API

AquaiPy provides an API for the AquaIllumination range of lights.

aquaipy.aquaipy module

Module for working with the AquaIllumination range of lights.

class aquaipy.aquaipy.AquaIPy(name=None, session=None, loop=None)[source]

Bases: object

A class that exposes the AquaIllumination Lights API.

async_connect(host, check_firmware_support=True)[source]

Connect AquaIPy instance to a specified AI light.

Also verifies connectivity and firmware version support.

Parameters:
  • host – Hostname/IP of AI light, for paired lights this should be the parent light.
  • check_firmware_support (bool) – Set to False to skip the firmware check

Note

It is NOT recommended to set check_firmware_support=False. Do so at your own risk!

Raises:
  • FirmwareError – If the firmware version is unsupported.
  • ConnError – If unable to connect to specified AI light.
  • MustBeParentError – the specified host must be the parent light, if there are multiple lights linked.
Example:
>>> from aquaipy import AquaIPy
>>> ai = AquaIPy()
>>> await ai.async_connect("192.168.1.1")
async_get_colors()[source]

Get the list of valid colors to pass to other colors methods.

Returns:list of valid colors or None if there’s an error
Return type:list( color_1..color_n ) or None
Raises:ConnError – if there is no valid connection to a device, usually because a previous call to async_connect() has failed
async_get_colors_brightness()[source]

Get the current brightness of all color channels.

Returns:dictionary of color and brightness percentages, or None if there’s an error
Return type:dict( color_1=percentage_1..color_n=percentage_n ) or None
Raises:ConnError – if there is no valid connection to a device, usually because a previous call to connect() has failed
async_get_schedule_state()[source]

Check if light schedule is enabled/disabled.

Returns:Schedule Enabled (True) / Schedule Disabled (False) or None if there’s an error
Return type:bool
Raises:ConnError – if there is no valid connection to a device, usually because a previous call to connect() has failed
async_patch_colors_brightness(colors)[source]

Set specified colors to the given percentage brightness.

Parameters:colors (dict( color_1=percentage_1..color_n=percentage_n )) – Specify just the colors that should be updated
Returns:Response.Success if it works, or a value indicating the error, if there is an issue.
Return type:Response
Raises:ConnError – if there is no valid connection to a device, usually because a previous call to connect() has failed
async_set_colors_brightness(colors)[source]

Set all colors to the specified color percentage.

Note

All colors returned by get_colors() must be specified.

Parameters:colors (dict( color_1=percentage_1..color_n=percentage_n )) – dictionary of colors and percentage values
Returns:Response.Success if it works, or a value indicating the error, if there is an issue.
Return type:Response
Raises:ConnError – if there is no valid connection to a device, usually because a previous call to connect() has failed
async_set_schedule_state(enable)[source]

Enable/disable the light schedule.

Parameters:enable (bool) – Schedule Enable (True) / Schedule Disable (False)
Returns:Response.Success if it works, or a value indicating the error, if there is an issue.
Return type:Response
Raises:ConnError – if there is no valid connection to a device, usually because a previous call to connect() has failed
async_update_color_brightness(color, value)[source]

Update a given color by the specified brightness percentage.

Parameters:
  • color (str) – color to change
  • value (float) – value to change percentage by
Returns:

Response.Success if it works, or a value indicating the error, if there is an issue.
Return type:

Response
Raises:

ConnError – if there is no valid connection to a device, usually because a previous call to connect() has failed.
base_path

Get base path of the AI API.

Returns:base path
Return type:str
close()[source]

Clean-up and close the underlying async dependancies..

Note

There is no async method, as it is assumed if you are using async functions, you will use your own event loop and aiohttp.ClientSession and pass them in. This will close the client session and event loop, if they were created by this object, when it was initialised.

connect(host, check_firmware_support=True)[source]

Connect AquaIPy instance to a specifed AI light, synchronously.

Parameters:
  • host – Hostname/IP of AI light, for paired lights this should be the parent light.
  • check_firmware_support (bool) – Set to False to skip the firmware check

Note

It is NOT recommended to set check_firmware_support=False. Do so at your own risk!

Raises:
  • FirmwareError – If the firmware version is unsupported.
  • ConnError – If unable to connect to specified AI light.
  • MustBeParentError – the specified host must be the parent light, if there are multiple lights linked.
Example:
>>> from aquaipy import AquaIPy
>>> ai = AquaIPy()
>>> ai.connect("192.168.1.1")
firmware_version

Get firmware version.

Returns:firmware version
Return type:str
get_colors()[source]

Get the list of valid colors for other methods, synchronously.

Returns:list of valid colors or None if there’s an error
Return type:list( color_1..color_n ) or None
Raises:ConnError – if there is no valid connection to a device, usually because a previous call to connect() has failed
get_colors_brightness()[source]

Get the current brightness of all color channels, synchronously.

Returns:dictionary of color and brightness percentages, or None if there’s an error
Return type:dict( color_1=percentage_1..color_n=percentage_n ) or None
Raises:ConnError – if there is no valid connection to a device, usually because a previous call to connect() has failed
get_schedule_state()[source]

Check if light schedule is enabled/disabled, synchronously.

Returns:Schedule Enabled (True) / Schedule Disabled (False) or None if there’s an error
Return type:bool
Raises:ConnError – if there is no valid connection to a device, usually because a previous call to connect() has failed
mac_addr

Get connected devices Mac Address/Serial Number.

Returns:device mac address/serial number
Return type:str
name

Get device name.

Returns:device name
Return type:str
patch_colors_brightness(colors)[source]

Set specified colors to the given percentage values, sychronously.

Parameters:colors (dict( color_1=percentage_1..color_n=percentage_n )) – Specify just the colors that should be updated
Returns:Response.Success if it works, or a value indicating the error, if there is an issue.
Return type:Response
Raises:ConnError – if there is no valid connection to a device, usually because a previous call to connect() has failed
product_type

Get product type.

Returns:product type
Return type:str
set_colors_brightness(colors)[source]

Set all colors to the specified color percentage, synchronously.

Parameters:colors (dict( color_1=percentage_1..color_n=percentage_n )) – dictionary of colors and percentage values
Returns:Response.Success if it works, or a value indicating the error, if there is an issue.
Return type:Response
Raises:ConnError – if there is no valid connection to a device, usually because a previous call to connect() has failed
set_schedule_state(enable)[source]

Enable/Disable the light schedule, synchronously.

Parameters:enable (bool) – Schedule Enable (True) / Schedule Disable (False)
Returns:Response.Success if it works, or a value indicating the error, if there is an issue.
Return type:Response
Raises:ConnError – if there is no valid connection to a device, usually because a previous call to connect() has failed
supported_firmware

Check if current firmware is supported.

Returns:status of firmware support
Return type:bool
update_color_brightness(color, value)[source]

Update a given color by the specified brightness, synchronously.

Parameters:
  • color (str) – color to change
  • value (float) – value to change percentage by
Returns:

Response.Success if it works, or a value indicating the error, if there is an issue.
Return type:

Response
Raises:

ConnError – if there is no valid connection to a device, usually because a previous call to connect() has failed.
class aquaipy.aquaipy.HDDevice(raw_data, primary_mac_address=None)[source]

Bases: object

A class for handling the conversion of data for a device.

convert_to_intensity(color, percentage)[source]

Convert a percentage to the native AI API intensity value.

The conversion is different for every color and model of light. The intensity to be returned will be bewtween 0-1000 for non-HD values and between 1000-2000 for HD (over 100%) values.

Parameters:
  • color (str) – the specified color to convert
  • percentage (float) – the percentage to convert
Returns:

intensity value (0-2000)
Return type:

int
convert_to_mw(color, intensity)[source]

Convert a given AI API native intensity value to the mWatt value.

An input intesnity (0-2000), is converted to the equivalent mWatt value for that color channel, on the specified device. This will differ for each color channel and device type.

Parameters:
  • color (str) – the specified color to convert
  • intensity (int) – the specified color intensity (0-2000)
Returns:

the resulting mWatt value, for the given intensity
Return type:

float
convert_to_percentage(color, intensity)[source]

Convert the native AI API intensity value to a percentage.

The conversion of the intensity value (0 - 2000) will be different for every color and light model.

Parameters:
  • color (str) – the specified color to convert
  • intensity (int) – the specified color intensity (0-2000)
Returns:

the resulting percentage
Return type:

float
is_primary

Check is HDDevice object represents a parent light.

Returns:true if parent, false if not
Return type:bool
mac_address

Get devices MAC address/serial number.

Returns:MAC address of device
Return type:str
max_mw

Get the max mWatts supported power level for the device.

Returns:max mWatts
Return type:int
class aquaipy.aquaipy.Response[source]

Bases: enum.Enum

Response codes, for the AquaIPy methods.

AllColorsMustBeSpecified = 5
Error = 1
InvalidBrightnessValue = 3
InvalidData = 6
NoSuchColour = 2
PowerLimitExceeded = 4
Success = 0

aquaipy.error module

This modules contains all the errors that are part of AquaIPy.

exception aquaipy.error.ConnError(message, host)[source]

Bases: aquaipy.error.Error

Raised when there is a connection error for an AI light.

Variables:
  • message – error message
  • host – host
exception aquaipy.error.Error[source]

Bases: Exception

Base class for exceptions in this class.

exception aquaipy.error.FirmwareError(message, firmware_version)[source]

Bases: aquaipy.error.Error

Raised when connecting to a device that has unsupported firmware.

Variables:
  • message – error message
  • firmware_version – unsupported version of firmware
exception aquaipy.error.MustBeParentError(message, parent_identifier)[source]

Bases: aquaipy.error.Error

Raised when connecting to a light that isn’t the parent.

The AquaIPy library only supports connecting to a parent light. There is support for paired devices, as long as the parent is the device that is connected to.

Variables:
  • message – error message
  • parent_identifier – an identifier for the parent device