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]>
  • Loading branch information
@Confectrician @borazslo
Confectrician authored and borazslo committed Jan 8, 2023
1 parent 4bf8211 commit 33688b3
Show file tree
Hide file tree
Showing 106 changed files with 4,535 additions and 4,758 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
46 changes: 23 additions & 23 deletions bundles/org.openhab.binding.neato/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,16 @@

This binding is used to connect your openHAB system with Neato web (where you log in and find Your Neato's).
The binding supports discovery via configuring your login and password to a bridge.
From the binding, you will get status of your vacuum cleaners and also a command channel where you can control them. Since the binding uses a polling mechanism, there may be some latency depending on your setting regarding refresh time.
From the binding, you will get status of your vacuum cleaners and also a command channel where you can control them. Since the binding uses a polling mechanism, there may be some latency depending on your setting regarding refresh time.

For log in transaction, the binding uses Neato Beehive API and for status and control, the binding uses Nucleao API.
For log in transaction, the binding uses Neato Beehive API and for status and control, the binding uses Nucleao API.

## Supported Things

Supported thing types

* neatoaccount (bridge)
* vacuumcleaner
- neatoaccount (bridge)
- vacuumcleaner

A bridge is required to connect to your Neato Cloud account.

Expand All @@ -22,36 +22,36 @@ All "Connected" type vacuum cleaners should be supported by this binding since t
Discovery is used _after_ a bridge has been created and configured with your login information.

1. Add the binding
2. Add a new thing of type NeatoAccount and configure with username and password
3. Go to Inbox and start discovery of Vacuums using Neato Binding
4. Vacuums should appear in your inbox!
1. Add a new thing of type NeatoAccount and configure with username and password
1. Go to Inbox and start discovery of Vacuums using Neato Binding
1. Vacuums should appear in your inbox!

## Thing Configuration

In order to manually create a thing file and not use the discovery routine you will need to know the vacuums serial number as well as the secret used in web service calls.
This is a bit difficult to get.
The easiest way of getting this information is to use the third party python library that is available at https://github.com/stianaske/pybotvac.
The easiest way of getting this information is to use the third party python library that is available at <https://github.com/stianaske/pybotvac>.

Neato Account Config

| Config | Description |
|----------|------------------------------------ |
| -------- | ----------------------------------- |
| email | Email address tied to Neato Account |
| password | Password tied to Neato Account |

Vacuum Cleaner Config

| Config | Description |
|----------|-----------------------------------------|
| serial | Serial Number of your Neato Robot |
| secret | Secret for accessing Neato web services (see note above) |
| refresh | Refresh time interval in seconds for updates from the Neato Web Service. Defaults to 60 sec |
| Config | Description |
| ------- | -------------------------------------------------------------------------------------------- |
| serial | Serial Number of your Neato Robot |
| secret | Secret for accessing Neato web services (see note above) |
| refresh | Refresh time interval in seconds for updates from the Neato Web Service. Defaults to 60 sec |

## Channels

| Channel | Type | Label | Description | Read Only |
|---------------------|--------|----------------------------|-------------------------------------------------------------------------------------------|-----------|
| battery-level| Number | Battery Level | Battery Level of the vacuum cleaner. | True |
| ------------------- | ------ | -------------------------- | ----------------------------------------------------------------------------------------- | --------- |
| battery-level | Number | Battery Level | Battery Level of the vacuum cleaner. | True |
| state | String | Current State | Current state of the vacuum cleaner. | True |
| available-services | String | Current available services | List of services that are currently available for the vacuum cleaner | True |
| action | String | Current Action | Current action of the vacuum cleaner. | True |
Expand All @@ -61,7 +61,7 @@ Vacuum Cleaner Config
| is-charging | Switch | Is Charging | Is the vacuum cleaner currently charging? | True |
| available-commands | String | Available Commands | List of available commands. | True |
| error | String | Error | Current error message in system. | True |
| command | String | Send Command | Send Commands to Vacuum Cleaner. (clean with map, clean, pause, resume, stop, dock) | False |
| command | String | Send Command | Send Commands to Vacuum Cleaner. (clean with map, clean, pause, resume, stop, dock) | False |
| cleaning-category | String | Cleaning Category | Current or Last category of the cleaning. Manual, Normal House Cleaning or Spot Cleaning. | True |
| cleaning-mode | String | Cleaning Mode | Current or Last cleaning mode. Eco or Turbo. | True |
| cleaning-modifier | String | Cleaning Modifier | Modifier of current or last cleaning. Normal or Double. | True |
Expand All @@ -72,9 +72,9 @@ Vacuum Cleaner Config

Below you will find examples of the necessary files:

**neato.items**
### neato.items

```
```java
Group GNeato
Number FannDammBattery "Battery level [%.0f %%]" <battery> (GNeato) { channel = "neato:vacuumcleaner:fanndamm:battery-level" }
String FannDammState "Status [MAP(neato-sv.map):%s]" (GNeato) { channel = "neato:vacuumcleaner:fanndamm:state" }
Expand All @@ -92,9 +92,9 @@ Number FannDammSpotHeight "SpotHeight [%.0f]" <niveau> (GNeato) { channel = "n
String FannDammCommand "Send Command" { channel = "neato:vacuumcleaner:fanndamm:command" }
```

**sitemap**
### neato.sitemap

```
```perl
Frame label="Neato BotVac Connected" {
Switch item=FannDammCommand mappings=[cleanWithMap="cleanWithMap", clean="Clean",stop="Stop",pause="Pause",resume="Resume", dock="Send to dock"]
Text item=FannDammBattery label="Battery level"
Expand All @@ -106,8 +106,8 @@ Frame label="Neato BotVac Connected" {
}
```

**neato.things**
### neato.things

```
```java
neato:vacuumcleaner:fanndamm [ serial="vacuumcleaner-serial", secret="secret-string"]
```
Loading

0 comments on commit 33688b3

Please sign in to comment.