Skip to content

Commit

Permalink
[Documentation] Markdown improvements n to s (openhab#13948)
Browse files Browse the repository at this point in the history 
Signed-off-by: Jerome Luckenbach <[email protected]>
Signed-off-by: Andras Uhrin <[email protected]>
  • Loading branch information
@Confectrician @andrasU
Confectrician authored and andrasU committed Jan 5, 2024
1 parent 78a3ca7 commit eb4fd44
Show file tree
Hide file tree
Showing 32 changed files with 2,272 additions and 2,835 deletions.
50 changes: 23 additions & 27 deletions bundles/org.openhab.binding.nanoleaf/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ This binding integrates the [Nanoleaf Light Panels](https://nanoleaf.me/en/consu
It enables you to authenticate, control, and obtain information of a Light Panel's device.
The binding uses the [Nanoleaf OpenAPI](https://forum.nanoleaf.me/docs/openapi), which requires firmware version [1.5.0](https://helpdesk.nanoleaf.me/hc/en-us/articles/214006129-Light-Panels-Firmware-Release-Notes) or higher.

![Image](doc/LightPanels2_small.jpg) ![Image](doc/the-worm-small.png) ![Image](doc/NanoCanvas_small.jpg)
![Image](doc/LightPanels2_small.jpg) ![Image](doc/the-worm-small.png) ![Image](doc/NanoCanvas_small.jpg)

## Supported Things

Expand All @@ -24,7 +24,6 @@ The lightpanel (singular) thing controls one of the individual panels/canvas tha
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 or Shapes you can even detect single / double **touch events** related to an individual panel or **swipe events** on the whole device 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 | - |
Expand All @@ -41,7 +40,7 @@ You can set the **color** for each panel and in the case of a Nanoleaf Canvas or

## Discovery

**Adding the Controller as a Thing**
### Adding the Controller as a Thing

To add a nanoleaf controller, go to your inbox and start a scan.
Then choose "Nanoleaf Binding".
Expand All @@ -53,13 +52,13 @@ 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.
1. 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**
### 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.
Expand All @@ -74,8 +73,8 @@ In this case:

### Panel Layout

If you want to program individual panels, it can be hard to figure out which panel has which ID. To make this easier, there is Layout channel on the Nanoleaf controller thing in openHAB.
The easiest way to visualize the layout of the individual panels is to open the controller thing in the openHAB UI, go to Channels and add a new item to the Layout channel.
If you want to program individual panels, it can be hard to figure out which panel has which ID. To make this easier, there is Layout channel on the Nanoleaf controller thing in openHAB.
The easiest way to visualize the layout of the individual panels is to open the controller thing in the openHAB UI, go to Channels and add a new item to the Layout channel.
Clicking on that image or adding it to a dashboard will show a picture of your canvas with the individual thing ID in the picture.

If your canvas has elements we dont know how to draw a layout for yet, please reach out, and we will ask for some information and will try to add support for your elements.
Expand All @@ -86,15 +85,15 @@ There is an alternative method for canvas that use square panels, you can reques

then issue the following command:

```
```shell
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

```
```text
31413 9162 13276
55836 56093 48111 38724 17870 5164 64279
Expand All @@ -108,7 +107,7 @@ Compare the following output with the right picture at the beginning of the arti
## State

The state channel shows an image of the panels on the wall.
You have to configure things for each panel to get the correct color.
You have to configure things for each panel to get the correct color.
Since the colors of the panels can make it difficult to see the panel ids, please use the layout channel where the background color is always white to identify them.
For state to work, you need to set static colors to your panel.
This is because Nanoleaf does not return updates on colors for dynamic effects and animations.
Expand Down Expand Up @@ -154,8 +153,6 @@ The controller bridge has the following channels:
| state | Image | Shows the current state of your panels with colors. | Yes |
| swipe | Trigger | [Canvas / Shapes Only] Detects Swipes over the panel.LEFT, RIGHT, UP, DOWN events are supported. | Yes |



A lightpanel thing has the following channels:

| Channel | Type | Description | Read Only |
Expand All @@ -164,26 +161,26 @@ A lightpanel thing has the following channels:
| tap | Trigger | [Canvas / Shapes Only] Sends events of gestures. SHORT_PRESSED, LONG_PRESSED and DOUBLE_PRESSED events are supported. | 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*.
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:**
### 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.
- 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**
### 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 can be detected on the whole set of panels though not on an individual panel.
The four swipe gestures are supported by the binding.
See below for an example on how to use it.

To detect single and double taps the panel provides a *tap* channel while the controller provides a *swipe* channel to detect swipes.
To detect single and double taps the panel provides a _tap_ channel while the controller provides a _swipe_ channel to detect swipes.

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
Expand All @@ -201,7 +198,7 @@ The following files provide a full example for a configuration (using a things f

### nanoleaf.things

```
```java
Bridge nanoleaf:controller:MyLightPanels @ "mylocation" [ address="192.168.1.100", port=16021, authToken="AbcDefGhiJk879LmNopqRstUv1234WxyZ", refreshInterval=60 ] {
Thing lightpanel 135 [ id=135 ]
Thing lightpanel 158 [ id=158 ]
Expand All @@ -210,15 +207,15 @@ Bridge nanoleaf:controller:MyLightPanels @ "mylocation" [ address="192.168.1.100

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
- 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:
- 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:

`http://<address>:16021/api/v1/new`

Expand All @@ -231,7 +228,7 @@ 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.

```
```java
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" }
Expand All @@ -254,7 +251,7 @@ Switch NanoleafRainbowScene "Show Rainbow Scene"

### nanoleaf.sitemap

```
```perl
sitemap nanoleaf label="Nanoleaf"
{
Frame label="Controller" {
Expand Down Expand Up @@ -286,7 +283,7 @@ sitemap nanoleaf label="Nanoleaf"

### nanoleaf.rules

```
```java
rule "UpdateHueAndSat"
when Item NanoleafColor changed
then
Expand Down Expand Up @@ -417,10 +414,9 @@ then
end
```


### nanoleaf.map

```
```text
ON = Yes
OFF = No
effects = Effect
Expand Down
Loading

0 comments on commit eb4fd44

Please sign in to comment.