# Nanoleaf Binding

This binding integrates the Nanoleaf Light Panels (opens new window).


It enables you to authenticate, control, and obtain information of a Light Panel's device. The binding uses the Nanoleaf OpenAPI (opens new window), which requires firmware version 1.5.0 (opens new window) or higher.

Image Image

# Supported Things

Nanoleaf provides a bunch of devices of which some are connected to Wifi whereas other use the new Thread Technology. This binding only supports devices that are connected through Wifi.

Currently Nanoleaf's "Light Panels" and "Canvas" devices are supported.

The binding supports two thing types: controller and lightpanel.

The controller thing is the bridge for the individually attached panels/canvas and can be perceived as the Nanoleaf device at the wall as a whole (either called "light panels" or "canvas" by Nanoleaf). With the controller thing you can control channels which affect all panels, e.g. selecting effects or setting the brightness.

The lightpanel (singular) thing controls one of the individual panels/canvas that are connected to each other. Each individual panel has therefore its own id assigned to it. You can set the color for each panel and in the case of a Nanoleaf canvas you can even detect single and double touch events related to an individual panel which opens a whole new world of controlling any other device within your openHAB environment.

Nanoleaf Name Type Description supported touch support
Light Panels NL22 Triangles 1st Generation X (-)
Shapes Triangle NL42 Triangles 2nd Generation (rounded edges) X X
Shapes Hexagon NL42 Hexagons X X
Shapes Mini Triangles ?? Mini Triangles ? ?
Canvas NL29 Squares X X

x = Supported (x) = Supported but only tested by community (-) = unknown (no device available to test)

# Discovery

Adding the Controller as a Thing

To add a nanoleaf controller, go to your inbox and start a scan. Then choose "Nanoleaf Binding". A controller (bridge) device is discovered automatically using mDNS in your local network. Alternatively, you can also provide a things file (see below for more details). After the device is discovered and added as a thing, it needs a valid authentication token that must be obtained by pairing it with your openHAB instance. Without the token the light panels remain in status OFFLINE.

The binding supports pairing of the device with your openHAB instance as follows:

  1. Make sure that the authentication token field in your Nanoleaf controller thing configuration is left empty.
  2. Hold down the on-off button of the controller for 5-7 seconds until the LED starts flashing/cycling in a pattern, which turns the device in pairing mode, and openHAB will try to request an authentication token for it.

Once your openHAB instance successfully requested and stored the authentication token in the controller's thing configuration, the controller status changes to ONLINE, and you can start linking the channels to your items.

Tip: if you press (2) just before adding the item from the inbox it usually catches the auth token right away and if you are lucky it already automatically starts discovering the panels in one turn (see below).

Adding the invidual light panels as a thing

After you have added the controller as a thing and it has been successfully paired as described as above, the individual panels connected to it can be discovered by starting another scan for the Nanoleaf binding. All connected panels will be added as separate things to the inbox.

Troubleshooting: In seldom cases (in particular together with updating the binding) things or items do not work as expected, are offline or may not be detected. In this case:

  • remove the panels (maybe twice by force removing it)
  • remove the controller (maybe twice by force removing it)
  • stop and then start openHAB
  • Rediscover like described above

# Panel Layout

Unfortunately it is not easy to find out which panel gets which id, and this becomes pretty important if you have lots of them and want to assign rules.

For canvas that use square panels, you can request the layout through a console command:

openhab:nanoleaf layout [<thingUID>]

The thingUID is an optional parameter. If it is not provided, the command loops through all Nanoleaf controller things it can find and prints the layout for each of them.

Compare the following output with the right picture at the beginning of the article

            31413                    9162       13276     

55836       56093       48111       38724       17870        5164       64279

                        58086        8134                   39755             


# Thing Configuration

The controller thing has the following parameters:

Config Description
address IP address or hostname of the light panels controller (e.g.
port Port number of the light panels contoller. Default is 16021
authToken The authentication token received from the controller after successful pairing.
refreshInterval Interval in seconds to refresh the state of the light panels settings. Default is 60.
deviceType Defines the type lightpanels (triangle) or canvas (square or hexagon)

The lightpanel thing has the following parameters:

Config Description
id ID assigned by the controller to the individual panel (e.g. 158)

The IDs of the individual panels can be determined by starting another scan once the controller is configured and online. This discovers all connected panels with their IDs.

# Channels

The controller bridge has the following channels:

Channel Item Type Description Read Only
color Color Color, power and brightness of all light panels No
colorTemperature Dimmer Color temperature (in percent) of all light panels No
colorTemperatureAbs Number Color temperature (in Kelvin, 1200 to 6500) of all light panels No
colorMode String Color mode of the light panels Yes
effect String Selected effect of the light panels No
rhythmState Switch Connection state of the rhythm module Yes
rhythmActive Switch Activity state of the rhythm module Yes
rhythmMode Number Sound source for the rhythm module. 0=Microphone, 1=Aux cable No

A lightpanel thing has the following channels:

Channel Type Description Read Only
color Color Color of the individual light panel No
tap Trigger [Canvas Only] Sends events of gestures. Currently, these are SHORT_PRESSED and DOUBLE_PRESSED events. Yes

The color channels support full color control with hue, saturation and brightness values. For example, brightness of all panels at once can be controlled by defining a dimmer item for the color channel of the controller thing. The same applies to the color channel of an individual lightpanel.

Limitations assigning specific colors on individual panels:

  • Due to the way the API of the nanoleaf is designed, each time a color is assigned to a panel, it will be directly sent to that panel. The result is that if you send colors to several panels more or less at the same time, they will not be set at the same time but one after the other and rather appear like a sequence but as a one shot.
  • Another important limitation is that individual panels cannot be set while a dynamic effect is running on the panel which means that as soon as you set an individual panel the "static effect" is set, which disables the chosen dynamic effect. The nanoleaf app shows that a static effect is now running, too.
  • The colors of the current state cannot be retrieved due to the high frequency of color changes that cannot be read quickly enough from the canvas, so all panels go to OFF
  • The first panelColor command is applied to that panel (and of course then all subsequent commands)
  • The fact that it is called a static effect does not mean that you cannot create animations. The Rainbow rule below shows a good example for the whole canvas. Just replace the controller item with a panel item and you will get the rainbow effect with an individual panel.

Touch Support

Nanoleaf's Canvas introduces a whole new experience by supporting touch. This allows single and double taps on individual panels to be detected and processed via rules. Note that even gestures like up, down, left, right are sent but can only be detected on the whole set of panels and not on an individual panel. These four gestures are not yet supported by the binding but may be added in a later release.

To detect single and double taps the panels have been extended to have two additional channels named singleTap and doubleTap which act like switches that are turned on as soon as a tap type is detected. These switches then act as a pulse to further control anything else via rules.

Keep in mind that the double tap is used as an already built-in functionality by default when you buy the nanoleaf: it switches all panels (hence the controller) to on or off like a light switch for all the panels at once. To circumvent that

  • Within the nanoleaf app go to the dashboard and choose your device. Enter the settings for that device by clicking the cog icon in the upper right corner.
  • Enable "Touch Gesture" and assign the gestures you want to happen but set the double tap to unassigned.
  • To still have the possibility to switch on the whole canvas device with all its panels by double tapping a specific panel, you can easily write a rule that triggers on the tap channel of that panel and then sends an ON to the color channel of the controller. See the example below on Panel 1.

More details can be found in the full example below.

# Full Example

The following files provide a full example for a configuration (using a things file instead of automatic discovery):

# nanoleaf.things

Bridge nanoleaf:controller:MyLightPanels @ "mylocation" [ address="", port=16021, authToken="AbcDefGhiJk879LmNopqRstUv1234WxyZ", refreshInterval=60 ] {
    Thing lightpanel 135 [ id=135 ]
    Thing lightpanel 158 [ id=158 ]

If you define your device statically in the thing file, auto-discovery of the same thing is suppressed by using

  • the [address="..." ] of the controller
  • and the [id=123] of the lightpanel

in the bracket to identify the uniqueness of the discovered device. Therefore it is recommended to the give the controller a fixed ip address.

Note: To generate the authToken:

  • On the Nanoleaf controller, hold the on-off button for 5-7 seconds until the LED starts flashing.
  • Send a POST request to the authorization endpoint within 30 seconds of activating pairing, like this:


e.g. via command line curl --location --request POST 'http://<address>:16021/api/v1/new'

# nanoleaf.items

Note: If you auto-discovered your things and items:

  • A controller item looks like nanoleaf:controller:F0ED4F9351AF:power where F0ED4F9351AF is the id of the controller that has been automatically assigned by the binding.
  • A panel item looks like nanoleaf:lightpanel:F0ED4F9351AF:39755:singleTap where 39755 is the id of the panel that has been automatically assigned by the binding.
Switch NanoleafPower "Nanoleaf" { channel="nanoleaf:controller:MyLightPanels:color" }
Color NanoleafColor "Color" { channel="nanoleaf:controller:MyLightPanels:color" }
Dimmer NanoleafBrightness "Brightness [%.0f]" { channel="nanoleaf:controller:MyLightPanels:color" }
String NanoleafHue "Hue [%s]"
String NanoleafSaturation "Saturation [%s]"
Dimmer NanoleafColorTemp "Color temperature [%.0f]" { channel="nanoleaf:controller:MyLightPanels:colorTemperature" }
Number NanoleafColorTempAbs "Color temperature [%.000f]" { channel="nanoleaf:controller:MyLightPanels:colorTemperatureAbs" }
String NanoleafColorMode "Color mode [%s]" { channel="nanoleaf:controller:MyLightPanels:colorMode" }
String NanoleafEffect "Effect" { channel="nanoleaf:controller:MyLightPanels:effect" }
Switch NanoleafRhythmState "Rhythm connected [MAP(nanoleaf.map):%s]" { channel="nanoleaf:controller:MyLightPanels:rhythmState" }
Switch NanoleafRhythmActive "Rhythm active [MAP(nanoleaf.map):%s]" { channel="nanoleaf:controller:MyLightPanels:rhythmActive" }
Number NanoleafRhythmSource  "Rhythm source [%s]" { channel="nanoleaf:controller:MyLightPanels:rhythmMode" }

// note that the next to items use the exact same channel but the two different types Color and Dimmer to control different parameters
Color PanelColor "Panel 1" { channel="nanoleaf:lightpanel:MyLightPanels:135:color" }
Dimmer Panel1Brightness "Panel 1" { channel="nanoleaf:lightpanel:MyLightPanels:135:color" }
Switch Panel2Color "Panel 2" { channel="nanoleaf:lightpanel:MyLightPanels:158:color" }
Switch NanoleafRainbowScene "Show Rainbow Scene"

# nanoleaf.sitemap

sitemap nanoleaf label="Nanoleaf"
    Frame label="Controller" {
            Switch item=NanoleafPower
            Slider item=NanoleafBrightness
            Colorpicker item=NanoleafColor           
            Text item=NanoleafHue
            Text item=NanoleafSaturation
            Slider item=NanoleafColorTemp     
            Setpoint item=NanoleafColorTempAbs step=100 minValue=1200 maxValue=6500            
            Text item=NanoleafColorMode
            Selection item=NanoleafEffect
            Text item=NanoleafRhythmState
            Text item=NanoleafRhythmActive
            Selection item=NanoleafRhythmSource mappings=[0="Microphone", 1="Aux"]

    Frame label="Panels" {
        Colorpicker item=Panel1Color
        Slider item=Panel1Brightness
        Colorpicker item=Panel2Color

    Frame label="Scenes" {
        Switch item=NanoleafRainbowScene

# nanoleaf.rules

rule "UpdateHueAndSat"
when Item NanoleafColor changed
    val hsbValues = NanoleafColor.state as HSBType    

rule "ShowRainbowScene"
when Item NanoleafRainbowScene received command ON
    val saturation = new PercentType(75)
    val brightness = new PercentType(90)
    val long pause = 200

    var hue = 0
    var direction = 1

    while(NanoleafRainbowScene.state == ON) {        
        hue = hue + (5 * direction)
        if(hue >= 359) {
            hue = 359
            direction = direction * -1            
        else if (hue < 0) {
            hue = 0
            direction = direction * -1            
        // replace NanoleafColor with Panel1Color to run rainbow on a single panel
        NanoleafColor.sendCommand(new HSBType(new DecimalType(hue), saturation, brightness))

rule "Nanoleaf canvas touch detection Panel 2"
    Channel "nanoleaf:lightpanel:MyLightPanels:158:tap" triggered SHORT_PRESS
    logInfo("CanvasTouch", "Nanoleaf Canvas Panel 2 was touched once")

    if (My_Main_Light.state == OFF) {
    } else {

rule "Nanoleaf double tap toggles power of device"
    Channel "nanoleaf:lightpanel:MyLightPanels:135:tap" triggered DOUBLE_PRESS
    logInfo("CanvasTouch", "Nanoleaf Canvas Panel 1 was touched twice. Toggle Power of whole canvas.")

    if (NanoleafPower.state == OFF ) {
    } else {

# nanoleaf.map

ON = Yes
OFF = No
effects = Effect
hs = Hue/Saturation
ct = Color Temperature