Skip to main content

Nanoleaf smart home integration, free and open source

Nanoleaf integration for Gladys Assistant

Nanoleaf panels on the local network: colors, whites, effects, touch gestures.

View on GitHubAll external integrations

Control your Nanoleaf light panels from Gladys Assistant, on the local network, through the Nanoleaf OpenAPI: on/off, brightness, color, white temperature, effects, and the touch gestures of the panels as scene triggers. No cloud, no account.

Developed without the hardware: feedback welcome. The integration is built and tested against the answers documented by Nanoleaf, not against real panels. Please report what works and what does not in the issues.

This integration is not affiliated with Nanoleaf.

Requirements​

  • Gladys Assistant 5.1.0 or later.
  • Panels with a Wi-Fi controller that speaks the Nanoleaf OpenAPI: Light Panels (Aurora), Canvas, Shapes (hexagons, triangles, mini triangles), Elements and Lines, on the same network as Gladys.
  • The panels set up in the Nanoleaf app first (Wi-Fi network).
  • Nanoleaf Essentials bulbs and strips (Matter / Thread) do not speak the OpenAPI: add them to Gladys through Matter instead.

Installation and pairing​

  1. In Gladys, open Integrations → Install from GitHub and enter https://github.com/guim31/gladys-nanoleaf (or install Nanoleaf from the catalog once it is listed).
  2. Open the Configuration tab of the integration. The panels on the same network as Gladys are found automatically (mDNS, and SSDP for the old Light Panels). If yours is not found, type its IP address in IP addresses of Nanoleaf controllers (several addresses: separate them with commas).
  3. On the panels, hold the power button 5 to 7 seconds until the lights flash, then click Pair in the Configuration tab within 30 seconds. The message under the button names the panels paired. To pair one address only, type it in the IP address (optional) field of the button.
  4. Open the Discovery tab and add the device.

Language of the device names: the language of the feature names of the new devices (French by default). Gladys keeps the names given when the device is added.

The pairing token is stored in the integration's /data volume, never in the configuration nor in the logs.

The device​

One device per controller (one set of panels), with these features:

FeatureWhat it does
LightOn / off.
Brightness0 to 100 %. 0 turns the panels off.
ColorAny color (hue and saturation). Not on Elements, which only show white.
Color temperatureThe white, in kelvins, within the range of the controller (1200-6500 K on most).
EffectThe effects of this controller, as in the Nanoleaf app. None: back to the plain color or white.
ConnectedRead only: the controller answers. Off at the wall, the panels are also shown off.

A brightness, a color or a white also turns the panels on, like the other Gladys lights. A change made in the Nanoleaf app, with the buttons or by a Nanoleaf schedule shows in Gladys within a second. A new effect created in the app joins the Effect list within a minute.

Widget​

Add the Nanoleaf widget to a dashboard and choose the panels in its settings. It shows:

  • the brightness, live;
  • Light (on or off), Effect (the effect running, the color or the white) and, on touch panels, Last gesture with the panel number;
  • up to four favorite effects as buttons (the running one carries a check mark). Type their names in Favorite effects, separated by commas; empty, the first three effects of the list are shown;
  • with three favorites or fewer, a Turn on / Turn off button.

Scene trigger​

Gesture on a Nanoleaf: a tap or a swipe on touch panels (Canvas, Shapes, Elements). Filters, all optional:

  • Nanoleaf: the panels; empty for any;
  • Gesture: Single tap, Double tap, Swipe up, Swipe down, Swipe left, Swipe right; empty for every gesture;
  • Panel number: for taps only (swipes cover the whole layout). Tap the panel, then read its number on the Last gesture line of the widget. The numbers are given by the controller: they change if the panels are rearranged.

The scene can use the gesture (single_tap, double_tap, swipe_up…) and the panel number as variables.

Scene actions​

  • Start a Nanoleaf effect: an effect by its name, as written in the Nanoleaf app (upper or lower case does not matter), with an optional brightness. The name of the effect started is available to the next actions. An unknown name fails the action and lists the effects.
  • Show a color on a Nanoleaf: a color from the list, or Other color in #RRGGBB form, for a number of seconds (1 to 3600), with an optional brightness; then the panels go back to what they showed before (effect, color or white, brightness, on or off). A command on the panels in the meantime cancels the return. Not on Elements.

On, off, brightness, color, white and the effect list are also available as the usual Gladys device actions.

Configuration buttons​

  • Pair: see Installation and pairing.
  • Search for Nanoleaf controllers: looks again and lists the paired controllers (answering or not) and those still to pair.

Scene examples​

  • Double tap to turn the living room off: trigger Gesture on a Nanoleaf, gesture Double tap; action: turn off the living room lights.
  • A panel as a doorbell light: when the doorbell rings, Show a color on a Nanoleaf, blue, 20 seconds, brightness 100 %.
  • Swipe for the evening mood: Gesture on a Nanoleaf, gesture Swipe down; actions: Start a Nanoleaf effect "Northern Lights" at 30 %, and dim the other lights.
  • Sunset: at sunset, Start a Nanoleaf effect "Sundown".

Refresh and network use​

  • Each controller keeps one connection open to the integration's event stream (Nanoleaf OpenAPI /events): changes and gestures arrive at once.
  • Each controller is also read once a minute (a few kilobytes), to follow the effect list and notice a controller that went away.
  • The network is searched every 15 minutes (through Gladys), to follow an address that changed.
  • Everything stays on the local network: port 16021 of the controllers, no cloud. The OpenAPI has no published quota; the integration stays far below what the Nanoleaf app does.

Troubleshooting​

  • "No Nanoleaf in pairing mode": hold the power button longer (5 to 7 seconds, until the lights flash), then click Pair right away: the pairing window lasts 30 seconds.
  • "No Nanoleaf found": check that the panels are on the same network as Gladys (not a guest network), then type their IP address (shown in the Nanoleaf app or in your router).
  • "A Nanoleaf refuses its access token": the controller was reset or its tokens were deleted. Pair it again: the device keeps its features and its history.
  • The device stays "not answering": the controller is off at the wall, or its address changed and the search did not find it. Click Search for Nanoleaf controllers, or type the new address.
  • A gesture does nothing: only Canvas, Shapes and Elements have touch; check that touch is not turned off in the Nanoleaf app, and that the device is chosen in the trigger (or left empty).
  • More detail in the integration logs with LOG_LEVEL=debug.

Limits​

  • Developed without the hardware: the answers of the controllers come from the Nanoleaf documentation.
  • The Nanoleaf Essentials (Matter / Thread), the 4D / Screen Mirror kit and the Skylight are not covered.
  • The Rhythm music mode, scenes and schedules of the Nanoleaf app, the layout and the per-panel colors are not available.
  • The touch of each panel (real-time stream) needs a UDP port the Gladys container cannot open: only the gestures are available.
  • Effects whose name starts or ends with a space are left out of the list.
  • The return after Show a color on a Nanoleaf does not survive a restart of the integration during the wait.

Configuration settings​

These are the settings Nanoleaf asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Pairing your NanoleafsectionNoNanoleaf panels on the same network as Gladys are found automatically. To pair one: hold its power button 5 to 7 seconds until the lights flash, then click "Pair" below within 30 seconds. Then add it from the Discovery tab.
IP addresses of Nanoleaf controllersstringNoOptional, separated by commas. Only needed for the controllers automatic discovery does not find.
Language of the device namesselectNoNames given to the features of new devices (Light, Brightness, Effect...).

How to install Nanoleaf in Gladys​

  1. In Gladys, open Integrations: Nanoleaf appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/guim31/gladys-nanoleaf:1.0.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/guim31/gladys-nanoleaf.

Nanoleaf requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

Nanoleaf is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on