HueBleLight class
Class representing Hue BLE Lights
- class HueBLE.HueBleLight(ble_device: BLEDevice)
Philips Hue BLE Light object.
- __init__(ble_device: BLEDevice)
Initialise light object. Does not connect automatically.
- add_callback_on_state_changed(function: Callable[[], None]) None
Register a callback to be run on light state changes. Triggers include changes to power, brightness, temp, colour, and connection status. These triggers are not dependant on the request being made by this program. (e.g If a ZigBee switch or Hue app commands the light off the callback will still be run)
- remove_callback(function: Callable[[], None]) None
Remove a registered state change callback. Raises ValueError if does not exist.
- async reconnect(reconnect_delay: int = 3)
Disconnects then reconnects to the device. Simply calls disconnect then calls connect.
- async connect(max_attempts: int = 3, connection_timeout: int = 30, wait_timeout: int = 120, run_callbacks: bool = True) None
Connects to the light using bluetooth. This can be manually called but it will also be run automatically if the light is not connected when the light is polled or set.
On connection it will attempt to pair to the light if not already paired but this only seems to work on Linux, so you might need to pair using your OS.
Connecting will NOT automatically cause all values to be polled and put in the internal state.
Connection timeout is the maximum time for a connection attempt once a lock has been acquired.
Wait timeout is the maximum amount of time that the method will wait to acquire a lock to attempt to perform a connection.
Registered callbacks will be run if a connection is achieved unless disabled.
This function raises ConnectionError on failure.
- async pair()
Pair to light if not paired and raise PairingError on failure.
- async disconnect() None
Disconnects the program from the light. Callbacks are not triggered.
- async poll_state(timeout=45, run_callbacks_if_changed=True) bool
Updates the local state with values from the light using polling. This will only populate the fields that the light supports (i.e it should not error out if your light does not support colour). A lock is used to only allow one state update at a time with a timeout. Any callbacks are run outside of the state lock but within the timeout lock. asyncio.TimeoutError raised on timeout. Returns true/false if the state changed. Passes through any raised exceptions.
- async poll_manufacturer(write_state: bool = True) str
Returns the manufacturer of the light.
- async poll_model(write_state: bool = True) str
Returns the model of the light.
- async poll_firmware(write_state: bool = True) str
Returns the firmware version of the light.
- async poll_zigbee_address(write_state: bool = True) str
Returns the Zigbee address of the light.
- async poll_light_name(write_state: bool = True) str
Returns the name of the light as shown in the Hue app. This may differ from the light objects name property.
- async poll_power_state(write_state: bool = True) bool
Gets the current power state of the light.
- async poll_brightness(write_state: bool = True) int
Gets the current brightness as an integer between 0 and 255.
- async poll_colour_temp(write_state: bool = True) int
Gets the current colour temperature as an integer between 153 and 500. Uses mireds.
- async poll_colour_xy(write_state: bool = True) tuple[float, float]
Gets the XY colour coordinates as floats between 0.0 and 1.0.
- async poll_effects(write_state: bool = True) tuple[EffectType, int]
Gets the effect type and effect speed as enum and int between 0 and 255.
- async set_light_name(name: str)
Sets the name of the light. Not tested, use at own risk.
- async set_power(on: bool)
Sets the power state of the light.
- async set_brightness(brightness: int)
Sets the brightness from an integer between 0 and 255
- async set_colour_temp(colour_temp: int)
Sets the temperature from an int between 153 and 500. Uses mireds.
- async set_colour_xy(x: float, y: float)
Sets the XY colour coordinates from floats between 0.0 and 1.0.
- async set_colour_effect(x: float, y: float, brightness: int, effect: EffectType, effect_speed: int)
Sets XY colour, brightness, effect and effect speed.
- Parameters:
x – X colour coordinate as float between 0.0 and 1.0
y – Y colour coordinate as float between 0.0 and 1.0
brightness – brightness as an integer between 0 and 255
effect – Effect of Type EffectType (can be EffectType.NONE for plain colour)
effect_speed – speed of the effect between 0 and 255
- async set_temperature_effect(colour_temp: int, brightness: int, effect: EffectType, effect_speed: int)
Sets colour temperature, brightness, effect and effect speed.
- Parameters:
colour_temp – colour temperature between 153 and 500
brightness – brightness as an integer between 0 and 255
effect – Effect of Type EffectType (can be EffectType.NONE for plain colour)
effect_speed – speed of the effect between 0 and 255
- property connected: bool
Returns true if the client is connected to a light. This does not however mean that we are able to send and receive commands. Use the “available” property for that.
- property authenticated: bool | None
Returns true if the light is paired. This only works on Linux. Returns None if unable to determine if device is authenticated.
- property available: bool
Is the light connected and authenticated. Meaning are we able to send/receive commands to/from the light. On non-Linux systems it is assumed we are authenticated!.
- property address: str
MAC address of the light.
- property manufacturer: str | None
Manufacturer of the light.
- property model: str | None
Model of the light.
- property firmware: str | None
Firmware of the light.
- property zigbee_address: str | None
Zigbee address of the light.
- property name: str
Bluetooth name of the light. Should not but may differ from value from poll_light_name().
- property name_in_app: str | None
Name of light in Hue app. Should not but may differ from the name (bluetooth) property.
- property power_state: bool | None
Is the light running?, you better go catch it.
- property brightness: int | None
Brightness of the light. Int 0-255. Returns None if the feature is not supported by the light.
- property colour_temp: int | None
Colour temperature of the light in mireds. Int 153-500. Returns None if the feature is not supported by the light.
- property minimum_mireds: int | None
Minimum mireds colour temperature supported. Returns None if the feature is not supported by the light. This value is assumed and not actually polled from the light.
- property maximum_mireds: int | None
Maximum mireds colour temperature supported. Returns None if the feature is not supported by the light. This value is assumed and not actually polled from the light.
- property colour_xy: tuple[float, float] | None
Colour in XY coordinates. (0.0, 0.0) - (1.0, 1.0). Returns None if the feature is not supported by the light.
- property colour_temp_mode: bool | None
True if the light is in colour temperature mode, else false. Returns None if the feature is not supported by the light.
- property effect: tuple[EffectType, int] | None
Effect as tuple of EffectType enum and effect speed. Returns None if the feature is not supported by the light.
- property supports_on_off: bool
Does the light support turning on and off. Yes I know it’s silly but its for forwards compatibility in case a bluetooth sensor is ever released.
- property supports_brightness: bool
Does the light support brightness control.
- property supports_colour_temp: bool
Does the light support colour temperature control.
- property supports_colour_xy: bool
Does the light support XY (RGB) colour control.
- property supports_effects: bool
Does the light support effect control.