API reference

The public API is exposed from the top-level avea package.

avea

A python library to control Elgato’s Avea Bulb.

Bulb

class avea.Bulb(address)[source]

Bases: object

Represent and control a single Elgato Avea bulb.

The class exposes a synchronous public API while using asyncio and bleak internally for Bluetooth Low Energy communication. Methods that read or write bulb state open a connection on demand when the bulb is not already connected and close it again afterwards.

Parameters:: address (str) – Bluetooth device address of the Avea bulb.

close()[source]

Close the BLE connection and stop the internal event loop.

Calling this method is safe even when the bulb is already closed. Use it when the object is no longer needed to release Bluetooth and thread resources explicitly.

Return type:: None

connect()[source]

Connect to the bulb over Bluetooth Low Energy.

Returns:: True if a connection is available, otherwise False.
Return type:: bool

disconnect()[source]

Disconnect from the bulb if currently connected.

Return type:: None

get_brightness()[source]

Read the current bulb brightness.

Returns:: Brightness value from 0 to 4095. If the bulb cannot be reached, the last cached value is returned.

get_color()[source]

Read the current 12-bit white, red, green and blue channel values.

Returns:: Tuple (white, red, green, blue) with values from 0 to 4095. If the bulb cannot be reached, the last cached values are returned.

get_fw_version()[source]

Read the bulb firmware version.

Returns:: Firmware version as a formatted string, or an empty string when it cannot be read.
Return type:: str

get_hardware_revision()[source]

Read the bulb hardware revision.

Returns:: Hardware revision reported by the bulb, or an empty string when it cannot be read.
Return type:: str

get_manufacturer_name()[source]

Read the bulb manufacturer name.

Returns:: Manufacturer name reported by the bulb, or an empty string when it cannot be read.
Return type:: str

get_name()[source]

Read the bulb name.

Returns:: Name reported by the bulb. If the bulb cannot be reached, the last cached name is returned.

get_rgb()[source]

Read the current color as standard RGB values.

Returns:: Tuple (red, green, blue) with channel values from 0 to 255. If the bulb cannot be reached, the last cached values are returned.

get_serial_number()[source]

Read the bulb serial number.

Returns:: Serial number reported by the bulb, or an empty string when it cannot be read.
Return type:: str

process_notification(data)[source]

Update cached bulb state from a raw BLE notification payload.

Parameters:: data (bytes) – Notification bytes received from the Avea control characteristic.

set_brightness(brightness)[source]

Set the bulb brightness.

Parameters:: brightness – Brightness value from 0 to 4095. Values outside this range are clamped.

set_color(white, red, green, blue)[source]

Set the bulb color using 12-bit white, red, green and blue channels.

Parameters:

white – White channel value from 0 to 4095.
red – Red channel value from 0 to 4095.
green – Green channel value from 0 to 4095.
blue – Blue channel value from 0 to 4095.

Notes

Values outside the accepted range are clamped before being sent.

set_name(name)[source]

Set the bulb name.

Parameters:: name (str) – New UTF-8 encoded name to send to the bulb.

set_rgb(red, green, blue)[source]

Set the bulb color using standard RGB channel values.

Parameters:

red – Red channel value from 0 to 255.
green – Green channel value from 0 to 255.
blue – Blue channel value from 0 to 255.

Notes

RGB values are converted to the internal 12-bit channel scale.

set_smooth_transition(target_red, target_green, target_blue, duration=2, fps=60)[source]

Fade smoothly from the current color to a target RGB color.

Parameters:

target_red – Target red channel value from 0 to 255.
target_green – Target green channel value from 0 to 255.
target_blue – Target blue channel value from 0 to 255.
duration – Transition duration in seconds.
fps – Requested updates per second. The effective value is capped by the library to keep BLE communication stable.

subscribe_to_notification()[source]

Return whether notification handling is enabled.

Notifications are subscribed automatically during connection setup, so callers normally do not need to call this method directly.

Returns:: Always True.

Utility functions

avea.discover_avea_bulbs(timeout=4.0)[source]

Discover nearby Elgato Avea bulbs.

Parameters:: timeout (float) – Bluetooth scan duration in seconds.
Returns:: List of Bulb objects for discovered Avea devices.

Notes

Depending on the operating system, Bluetooth discovery may require additional permissions.

avea.compute_brightness(brightness)[source]

Build the BLE payload for a brightness command.

Parameters:: brightness – Brightness value from 0 to 4095. The value is expected to be clamped before calling this helper.
Returns:: Command payload bytes starting with 0x57.

avea.compute_color(w=2000, r=0, g=0, b=0)[source]

Build the BLE payload for a color command.

Parameters:

w – White channel value from 0 to 4095.
r – Red channel value from 0 to 4095.
g – Green channel value from 0 to 4095.
b – Blue channel value from 0 to 4095.

Returns:

Command payload bytes starting with 0x35.

avea.compute_transition_table(init, target, iterations)[source]

Compute eased intermediate values for a smooth color transition.

Parameters:

init – Initial channel value.
target – Target channel value.
iterations – Number of transition steps to generate.

Returns:

List of integer channel values, including the final target value.

avea.check_bounds(value)[source]

Clamp a numeric value to the Avea 12-bit channel range.

Parameters:: value – Value to convert to int and clamp.
Returns:: Integer between 0 and 4095. Non-numeric values return 0.