Backend

All internal and external functions of the module

HueBleLight class

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.

_run_state_changed_callbacks() → None: Executes all registered callbacks for a state change. Exceptions are caught and re-raised.

_disconnect_callback(client: BaseBleakClient) → None: Private method. Updates program state and will attempt reconnect if the disconnect was unexpected.

async reconnect(reconnect_delay: int = 3): Disconnects then reconnects to the device. Simply calls disconnect then calls connect.

async _subscribe_to_light() → None: Subscribes to the state of the light. Automatically called on connect. :raises Exception: If unable to subscribe to supported features.

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 _pair_bluez(): Workaround for bluez authentication issues.

async _determine_services() → None: Determines what features the light supports. The data may then be retrieved via the supports properties. :raises BleakError: If unable to determine services offered.

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 _read_gatt(property: str, attempt_timeout: int = 20, max_attempts: int = 3) → bytearray: Reads a GATT attribute from the light. If there is an error an exception will be thrown.

async _write_gatt(property: str, data: bytes, attempt_timeout: int = 20, max_attempts: int = 3) → bytearray: Writes a GATT attribute to a light. Will attempt to connect if not already connected. Will throw an exception on error.

async print_services() → None: Prints all available GATT services in the debug log. See: original

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.

Static methods

HueBLE module.

async HueBLE.discover_lights(scanner: BleakScanner | None = None, timeout: int = 5) → list[BLEDevice]: Scanning feature Scans the BLE neighborhood for Hue BLE light(s) and returns a list of nearby lights based upon detection of a known UUID.

Module constants

HueBLE module.

HueBLE.UUID_MANUFACTURER = '00002a29-0000-1000-8000-00805f9b34fb': String containing manufacturer. Handle 15.

HueBLE.UUID_MODEL = '00002a24-0000-1000-8000-00805f9b34fb': String containing model number. Handle 17

HueBLE.UUID_FW_VERSION = '00002a28-0000-1000-8000-00805f9b34fb': String containing firmware version. Handle 19.

HueBLE.UUID_ZIGBEE_ADDRESS = '97fe6561-0001-4f62-86e9-b71ee2da3d22': String containing Zigbee address. Handle 22.

HueBLE.UUID_NAME = '97fe6561-0003-4f62-86e9-b71ee2da3d22': String containing light name. Handle 24

HueBLE.UUID_POWER = '932c32bd-0002-47a2-835a-a8d455b859dd': Power state of light. Is subscribable. x00 and x01. Handle 49.

HueBLE.UUID_BRIGHTNESS = '932c32bd-0003-47a2-835a-a8d455b859dd': Brightness of light. Int 0-255. Handle 52.

HueBLE.UUID_TEMPERATURE = '932c32bd-0004-47a2-835a-a8d455b859dd': Temperature of light. Int 153-500. 0xFFFF when colour enabled. Handle 55.

HueBLE.UUID_XY_COLOUR = '932c32bd-0005-47a2-835a-a8d455b859dd': XY colour of light. Two 16-bit ints. 0xFFFFFFFF when CW/WW. Handle 58.

HueBLE.UUID_EFFECTS = '932c32bd-0007-47a2-835a-a8d455b859dd': new colour change and effect enpoint

HueBLE.UUID_HUE_IDENTIFIER = '0000fe0f-0000-1000-8000-00805f9b34fb': This is a UUID that as far as I know only hue lights use and it shows up under BLE Device details and as such does not require connecting to check for. The UUID also has the following service data. I am not sure what it means but it is the same for both of my colour lights with model no LCA006. x02x10x0exbex02

HueBLE.MIN_MIREDS = 153: The assumed minimum colour temperature of the light in mireds. Constant as it us unknown if/where the light exposes this data.

HueBLE.MAX_MIREDS = 500: The assumed maximum colour temperature of the light in mireds. Constant as it us unknown if/where the light exposes this data.

HueBLE.DEFAULT_METADATA_STRING = 'Unknown': Default string of light metadata light address, model, and firmware.

HueBLE.DEFAULT_CONNECTION_ATTEMPTS_MAX = 3: Default max connection attempts in the connect function.

HueBLE.DEFAULT_CONNECTION_TIMEOUT = 30: Default max time for all connection attempts in connect function.

HueBLE.DEFAULT_CONNECTION_WAIT_TIMEOUT = 120: Default max time before a call to connect times out waiting for another call to connect to finish its attempt.

HueBLE.DEFAULT_POLL_STATE_TIMEOUT = 45: Default max time before a call to poll state times out.

HueBLE.DEFAULT_READ_GATT_TIMEOUT = 20: Default max time before a single read attempt to the light times out and it will try again. This must be large enough to allow for a connection attempt if the light is not already connected.

HueBLE.DEFAULT_READ_GATT_MAX_ATTEMPTS = 3: Default max light read attempts before raising an exception.

HueBLE.DEFAULT_WRITE_GATT_TIMEOUT = 20: Default max time before a single write attempt to the light times out and it will try again. This must be large enough to allow for a connection attempt if the light is not already connected.

HueBLE.DEFAULT_WRITE_GATT_MAX_ATTEMPTS = 3: Default max light write attempts before raising an exception.

HueBLE.DEFAULT_POLL_WRITES_STATE = True: Default of all polls to the light updating the light objects internal state.

HueBLE.DEFAULT_DISCOVER_TIME = 5: Default amount of time to scan for a light for in the discovery method.

Exceptions

HueBLE module.

exception HueBLE.HueBleError: Base exception of HueBLE.

exception HueBLE.ConnectionError: Exception raised when connecting to a device fails.

exception HueBLE.InitialConnectionError: Exception raised when the initial pre-pair pre-communication connect call fails.

exception HueBLE.PairingError: Exception raised when pairing to a device fails.

exception HueBLE.ReadWriteError: Exception raised when reading or writing a GATT attribute fails.

exception HueBLE.ServicesError: Exception raised when service discovery/subscription fails.

exception HueBLE.CallbackError: Exception raised when a callback raises an error.

Enums

HueBLE module.

class HueBLE.EffectType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

class HueBLE.EffectCommands(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)