DOCSEARCHbyAlgolia
Submit Docs

pywizlight Documentation

repository·master·Indexed 19 days ago

https://github.com/sbidy/pywizlight

A Python connector for WiZ smart lighting devices providing an asynchronous API and a command-line tool for device discovery and control. It includes classes for bulb management (wizlight, BulbRegistry, BulbLib), parameter configuration (PilotBuilder), and state parsing (PilotParser). The library supports Python >= 3.11 and features a UDP-based discovery mechanism via BroadcastProtocol, as well as tools for bulb simulation and testing.

Tokens
6.7K
Snippets
31
Records
49
Agent score
67%

What's inside pywizlight

  1. Overview of pywizlight core classes

    master

    The pywizlight library provides several key abstractions for interacting with WiZ light bulbs:

    • wizlight: The primary class used to create an instance of a WiZ Light Bulb.
    • BulbLib: Provides access to all existing bulb definitions.
    • DiscoveredBulb: Represents a bulb that has been found on the network.
    • BulbRegistry: Manages the registry of available bulb types.
    • BulbType: Defines the specific functions and features supported by a particular bulb model.
    • KelvinRange: Defines the supported color temperature (Kelvin) range for a bulb.
    • Features: Defines the set of supported features for a bulb.
    • BroadcastProtocol: Handles sending UDP broadcast messages used for bulb discovery.
    • PilotBuilder & PilotParser: Internal components used to build requests and interpret messages from the bulb.

    Error Handling:

    • WizLightError: General exception for the library.
    • WizLightConnectionError: Raised when a connection error occurs.
    • WizLightTimeOutError: Raised when a connection times out.
    • WizLightNotKnownBulb: Raised when the detected bulb type is not recognized by the library.

  2. Supported features in pywizlight

    master

    The Features class defines the capabilities supported by a Wiz light bulb. When initializing a Features object, you can specify which attributes are available for control. The supported attributes are:

    • color: RGB color control.
    • color_tmp: Color temperature control.
    • effect: Lighting effects.
    • brightness: Brightness level control.

  3. Configure bulb parameters with PilotBuilder

    master

    The PilotBuilder class is used to programmatically define the parameters for a turn_on command. Supported parameters include:

    • brightness: Integer (0-255).
    • rgb: Tuple of (r, g, b) integers (0-255).
    • warm_white: Integer (0-255).
    • cold_white: Integer (0-255).
    • scene: Integer (1-35) representing a predefined scene.
    • temp: Color temperature in Kelvins.
    from pywizlight import PilotBuilder

# Example: Set a specific scene and brightness
builder = PilotBuilder(scene=4, brightness=255)
await light.turn_on(builder)

  4. Use WizLightNotKnownBulb for unidentified bulbs

    master
    If pywizlight cannot identify the specific model or type of a Wiz bulb during discovery, it provides the WizLightNotKnownBulb class. This class allows you to interact with the bulb using standard Wiz Light commands even when the specific device capabilities cannot be fully mapped to a known model.

  5. How BroadcastProtocol works for bulb discovery

    master

    The BroadcastProtocol is an asyncio-based UDP protocol used to discover Wiz bulbs on a local network. It functions by sending UDP broadcast messages to a specified broadcast_address (typically 192.168.1.255) and listening for responses.

    When initialized, it sets up a registry to track discovered devices. The discovery process involves:

    1. Initialization: Setting up the loop, registry, and broadcast address.
    2. Connection: Establishing the socket transport via connection_made.
    3. Registration: Sending a broadcast registration request via broadcast_registration.
    4. Reception: Handling incoming UDP datagrams from bulbs via datagram_received to identify their IP addresses and details.
    5. Error Handling: Managing connection losses via connection_lost.

  6. Use BulbRegistry to manage Wiz bulbs

    master

    The BulbRegistry class serves as a central repository for managing discovered or manually added Wiz bulbs. You can use it to register individual bulb instances and retrieve the collection of all registered bulbs.

    Methods

    • __init__(): Initializes a new instance of the bulb registry.
    • register(bulb): Adds a new bulb instance to the registry.
    • bulbs: Returns a collection of all bulbs currently present in the registry.

  8. Use the pywizlight Python API

    master

    The pywizlight library provides an asynchronous API to control WiZ light bulbs. You can discover bulbs on your network, control their power, brightness, color temperature, and RGB values using the wizlight class and PilotBuilder for parameter configuration.

    Key workflow:

    1. Discovery: Use discovery.discover_lights() to find bulbs on the network.
    2. Initialization: Create a wizlight(ip) instance.
    3. Control: Use await light.turn_on(PilotBuilder(...)) to set states or await light.turn_off() to turn them off.
    4. State Retrieval: Call await light.updateState() to refresh the local state, then access properties via the light.state object (a PilotParser).
    import asyncio
from pywizlight import wizlight, PilotBuilder, discovery

async def main():
    # Discover bulbs
    bulbs = await discovery.discover_lights(broadcast_space="192.168.1.255")
    
    # Control a specific bulb
    light = wizlight("192.168.1.27")
    
    # Turn on with specific brightness and RGB color
    await light.turn_on(PilotBuilder(brightness=255, rgb=(0, 128, 255)))
    
    # Set warm white
    await light.turn_on(PilotBuilder(warm_white=255))
    
    # Get current state
    await light.updateState()
    print(f"Brightness: {light.state.get_brightness()}")
    print(f"RGB: {light.state.get_rgb()}")
    
    # Turn off
    await light.turn_off()

asyncio.run(main())

  10. Discover bulbs on the network

    master

    Discovery uses a UDP Broadcast request to find all WiZ bulbs in the local network. By default, it uses the broadcast address 192.168.1.255. You can specify a custom broadcast address if your network configuration differs.

    from pywizlight import discovery

# Discover using default or custom broadcast address
bulbs = await discovery.discover_lights(broadcast_space="192.168.1.255")