Detailed Documentation¶

Nanoleaf¶

nanoleafapi

This module is a Python 3 wrapper for the Nanoleaf OpenAPI. It provides an easy way to use many of the functions available in the API. It supports the Light Panels (previously Aurora), Canvas and Shapes (including Hexgaons).

class nanoleaf.Nanoleaf(ip: str, auth_token: str = None, print_errors: bool = False)¶

The Nanoleaf class for controlling the Light Panels and Canvas

Variables:	ip – IP of the Nanoleaf device url – The base URL for requests auth_token – The authentication token for the API print_errors – True for errors to be shown, otherwise False

check_connection() → None¶: Ensures there is a valid connection

create_auth_token() → Optional[str]¶

Creates or retrives the device authentication token

The power button on the device should be held for 5-7 seconds, then this method should be run. This will set both the auth_token and url instance variables, and save the token in a file for future instances of the Nanoleaf object.

Returns:	Token if successful, None if not.

delete_auth_token(auth_token: str) → bool¶

Deletes an authentication token

Deletes an authentication token and the .nanoleaf_token file if it contains the auth token to delete. This token can no longer be used as part of an API call to control the device. If required, generate a new one using create_auth_token().

Parameters:	auth_token – The authentication token to delete.
Returns:	True if successful, otherwise False

effect_exists(effect_name: str) → bool¶

Verifies whether an effect exists

Parameters:	effect_name – Name of the effect to verify
Returns:	True if effect exists, otherwise False

enable_extcontrol() → bool¶

Enables the extControl UDP streaming mode

Returns:	True if successful, otherwise False

flow(rgb_list: List[Tuple[int, int, int]], speed: float = 1) → bool¶

Displays a sequence of specified colours on the device.

Parameters:	rgb – A list of tuples containing RGB colours to flow between in the format (r, g, b). speed – The speed of the transition between colours in seconds, with a maximum of 1 decimal place.
Raises:	NanoleafEffectCreationError – When an invalid rgb_list is provided.
Returns:	True if the effect was created and displayed successfully, otherwise False

get_auth_token() → Optional[str]¶: Returns the current auth token or None

get_brightness() → int¶: Returns the current brightness value of the lights

get_color_mode() → str¶: Returns the colour mode of the lights

get_color_temp() → int¶: Returns the current colour temperature of the lights

get_current_effect() → str¶

Returns the currently selected effect

If the name of the effect isn’t available, this will return Solid, Dynamic or Static instead.

Returns:	Name of the effect or type if unavailable.

static get_custom_base_effect(anim_type: str = 'custom', loop: bool = True) → Dict[str, Any]¶: Returns base custom effect dictionary

get_hue() → int¶: Returns the current hue value of the lights

get_ids() → List[int]¶: Returns a list of all device ids

get_info() → Dict[str, Any]¶: Returns a dictionary of device information

get_layout() → Dict[str, Any]¶: Returns the device layout information

get_name() → str¶: Returns the name of the current device

get_power() → bool¶

Returns the power status of the lights

Returns:	True if on, False if off

get_saturation() → int¶: Returns the current saturation value of the lights

identify() → bool¶

Runs the identify sequence on the lights

Returns:	True if successful, otherwise False

increment_brightness(brightness: int) → bool¶

Increments the brightness of the lights

Parameters:	brightness – How much to increment the brightness, can also be negative
Returns:	True if successful, otherwise False

increment_color_temp(value: int) → bool¶

Sets the white colour temperature of the lights

Parameters:	value – How much to increment the colour temperature by, can also be negative.
Returns:	True if successful, otherwise False

increment_hue(value: int) → bool¶

Increments the hue of the lights

Parameters:	value – How much to increment the hue, can also be negative
Returns:	True if successful, otherwise False

increment_saturation(value: int) → bool¶

Increments the saturation of the lights

Parameters:	brightness – How much to increment the saturation, can also be negative.
Returns:	True if successful, otherwise False

list_effects() → List[str]¶: Returns a list of available effects

power_off() → bool¶

Powers off the lights

Returns:	True if successful, otherwise False

power_on() → bool¶

Powers on the lights

Returns:	True if successful, otherwise False

pulsate(rgb: Tuple[int, int, int], speed: float = 1) → bool¶

Displays a pulsating effect on the device with two colours

Parameters:	rgb – A tuple containing the RGB colour to pulsate in the format (r, g, b). speed – The speed of the transition between colours in seconds, with a maximum of 1 decimal place.
Raises:	NanoleafEffectCreationError – When an invalid rgb value is provided.
Returns:	True if the effect was created and displayed successfully, otherwise False

register_event(func: Callable[[Dict[str, Any]], Any], event_types: List[int]) → None¶

Starts a thread to register and listen for events

Creates an event listener. This method can only be called once per program run due to API limitations.

Parameters:	func – The function to run when an event is recieved (this should be defined by the user with one argument). This function will recieve the event as a dictionary. event_types – A list containing up to 4 numbers from 1-4 corresponding to the relevant events to be registered for. 1 = state (power/brightness), 2 = layout, 3 = effects, 4 = touch (Canvas only)

set_brightness(brightness: int, duration: int = 0) → bool¶

Sets the brightness of the lights

Parameters:	brightness – The required brightness (between 0 and 100) duration – The duration over which to change the brightness
Returns:	True if successful, otherwise False

set_color(rgb: Tuple[int, int, int]) → bool¶

Sets the colour of the lights

Parameters:	rgb – Tuple in the format (r, g, b)
Returns:	True if successful, otherwise False

set_color_temp(value: int) → bool¶

Sets the white colour temperature of the lights

Parameters:	value – The required colour temperature (between 0 and 100)
Returns:	True if successful, otherwise False

set_effect(effect_name: str) → bool¶

Sets the effect of the lights

Parameters:	effect_name – The name of the effect
Returns:	True if successful, otherwise False

set_hue(value: int) → bool¶

Sets the hue of the lights

Parameters:	value – The required hue (between 0 and 360)
Returns:	True if successful, otherwise False

set_saturation(value: int) → bool¶

Sets the saturation of the lights

Parameters:	value – The required saturation (between 0 and 100)
Returns:	True if successful, otherwise False

spectrum(speed: float = 1) → bool¶

Displays a spectrum cycling effect on the device

Parameters:	speed – The speed of the transition between colours in seconds, with a maximum of 1 decimal place.
Returns:	True if the effect was created and displayed successfully, otherwise False

toggle_power() → bool¶: Toggles the lights on/off

write_effect(effect_dict: Dict[str, Any]) → bool¶

Writes a user-defined effect to the panels

Parameters:	effect_dict – The effect dictionary in the format described here: https://forum.nanoleaf.me/docs/openapi#_u2t4jzmkp8nt
Raises:	NanoleafEffectCreationError – When invalid effect dictionary is provided.
Returns:	True if successful, otherwise False

exception nanoleaf.NanoleafConnectionError¶: Raised when the connection to the Nanoleaf device fails.

exception nanoleaf.NanoleafEffectCreationError¶: Raised when one of the custom effects creation has incorrect arguments.

exception nanoleaf.NanoleafRegistrationError¶: Raised when an issue during device registration.

Discovery¶

discovery

Module to aid with Nanoleaf discovery on a network.

discovery.discover_devices(timeout: int = 30, debug: bool = False) → Dict[Optional[str], str]¶

Discovers Nanoleaf devices on the network using SSDP

Parameters:	timeout – The timeout on the search in seconds (default 30) debug – Prints each device string for the SSDP discovery
Returns:	Dictionary of found devices in format {name: ip}

Digital Twin¶

NanoleafDigitalTwin

This module allows for the creation of a “digital twin”, allowing you to: make changes to individual panels and sync them to their real counterparts.

class digital_twin.NanoleafDigitalTwin(nl: nanoleafapi.nanoleaf.Nanoleaf)¶

Class for creating and modifying digital twins

Variables:	nanoleaf – The Nanoleaf object tile_dict – The dictionary of tiles and their associated colour

get_all_colors() → Dict[int, Tuple[int, int, int]]¶

Returns a dictionary of all panel IDs and associated colours.

Returns:	Dictionary with panel IDs as keys and RGB tuples as values.

get_color(panel_id: int) → Tuple[int, int, int]¶

Returns the colour of a specified panel.

Parameters:	panel_id – The panel to get the colour of.
Returns:	Returns the RGB tuple of the panel with ID panel_id.

get_ids() → List[int]¶

Returns a list of panel IDs.

Returns:	List of panel IDs.

set_all_colors(rgb: Tuple[int, int, int]) → None¶

Sets the colour of all the panels.

Parameters:	rgb – A tuple containing the RGB values of the colour to set

set_color(panel_id: int, rgb: Tuple[int, int, int]) → None¶

Sets the colour of an individual panel.

Parameters:	panel_id – The ID of the panel to change the colour of rgb – A tuple containing the RGB values of the colour to set

sync() → bool¶

Syncs the digital twin’s changes to the real Nanoleaf device.

Returns:	True if success, otherwise False