diff --git a/bundles/org.openhab.binding.nanoleaf/README.md b/bundles/org.openhab.binding.nanoleaf/README.md index 788ae2c239b83..74ff0a7bd7643 100644 --- a/bundles/org.openhab.binding.nanoleaf/README.md +++ b/bundles/org.openhab.binding.nanoleaf/README.md @@ -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 @@ -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 | - | @@ -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". @@ -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. @@ -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. @@ -86,7 +85,7 @@ There is an alternative method for canvas that use square panels, you can reques then issue the following command: -``` +```shell openhab:nanoleaf layout [] ``` @@ -94,7 +93,7 @@ The `thingUID` is an optional parameter. If it is not provided, the command loop 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 @@ -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. @@ -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 | @@ -164,18 +161,18 @@ 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. @@ -183,7 +180,7 @@ Note that even gestures like up, down, left, right can be detected on the whole 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 @@ -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 ] @@ -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://
:16021/api/v1/new` @@ -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" } @@ -254,7 +251,7 @@ Switch NanoleafRainbowScene "Show Rainbow Scene" ### nanoleaf.sitemap -``` +```perl sitemap nanoleaf label="Nanoleaf" { Frame label="Controller" { @@ -286,7 +283,7 @@ sitemap nanoleaf label="Nanoleaf" ### nanoleaf.rules -``` +```java rule "UpdateHueAndSat" when Item NanoleafColor changed then @@ -417,10 +414,9 @@ then end ``` - ### nanoleaf.map -``` +```text ON = Yes OFF = No effects = Effect diff --git a/bundles/org.openhab.binding.neato/README.md b/bundles/org.openhab.binding.neato/README.md index 51668dbef6813..d17dc5ae0d4f6 100644 --- a/bundles/org.openhab.binding.neato/README.md +++ b/bundles/org.openhab.binding.neato/README.md @@ -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. @@ -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 . 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 | @@ -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 | @@ -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 %%]" (GNeato) { channel = "neato:vacuumcleaner:fanndamm:battery-level" } String FannDammState "Status [MAP(neato-sv.map):%s]" (GNeato) { channel = "neato:vacuumcleaner:fanndamm:state" } @@ -92,9 +92,9 @@ Number FannDammSpotHeight "SpotHeight [%.0f]" (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" @@ -106,8 +106,8 @@ Frame label="Neato BotVac Connected" { } ``` -**neato.things** +### neato.things -``` +```java neato:vacuumcleaner:fanndamm [ serial="vacuumcleaner-serial", secret="secret-string"] ``` diff --git a/bundles/org.openhab.binding.neeo/README.md b/bundles/org.openhab.binding.neeo/README.md index 5ce37a4bf9a34..e566e016983eb 100644 --- a/bundles/org.openhab.binding.neeo/README.md +++ b/bundles/org.openhab.binding.neeo/README.md @@ -8,8 +8,8 @@ More information can be found at [NEEO](neeo.com) or in the forums at [NEEO Plan Discovery occurs in three steps: 1. Discover your NEEO Brain. -2. Once you have added a NEEO Brain, each Room will be discovered (which will include all Recipes and Scenarios). -3. Once you have added a NEEO Room, each Device in the Room will be discovered (which will include all Macros for the Device). +1. Once you have added a NEEO Brain, each Room will be discovered (which will include all Recipes and Scenarios). +1. Once you have added a NEEO Room, each Device in the Room will be discovered (which will include all Macros for the Device). The Recipes/Scenarios can then be started or stopped from openHAB or from the remote. If a Recipe/Scenario is started on the Brain, the status of the Recipe/Scenario will change in openHAB as well. @@ -48,13 +48,13 @@ Actions can be triggered by sending ON to the channel ## Supported Things -* Bridge: NEEO Brain. +- Bridge: NEEO Brain. This bridge represents a physical NEEO Brain and will contain one to many Rooms within it. -* Bridge: NEEO Room. +- Bridge: NEEO Room. Represents a Room on the NEEO Brain. Only rooms that have atleast one device or one recipe (custom if no devices) will be shown unless the brain configuration option "discoverEmptyRooms" is set to true. -* Thing: NEEO Device. +- Thing: NEEO Device. Represents a Device within the NEEO Room. @@ -63,8 +63,8 @@ Represents a Device within the NEEO Room. NEEO Brains will be automatically discovered if mDNS/bonjour/zeroconf is installed on the local machine: 1. On Windows - installing iTunes will install bonjour. -2. On Linux - please install zeroconf (see vendor documentation on how to do that). -3. On Mac - should already be installed. +1. On Linux - please install zeroconf (see vendor documentation on how to do that). +1. On Mac - should already be installed. When you add the NEEO Brain, the Rooms on the Brain will then be auto discovered and placed in the inbox. When you add a Room, all Devices should be auto discovered and placed in the inbox. @@ -75,47 +75,47 @@ If you discovered the wired first but want to use the wireless (or in the revers If the Brain is not discovered, here is list of the most common issues: -1. You can generally trigger discovery by starting up the NEEO APP on your mobile device, press MENU->NEEO Brain->Change Brain. +1. You can generally trigger discovery by starting up the NEEO APP on your mobile device, press MENU->NEEO Brain->Change Brain. This will generally send out the necessary mDNS broadcast messages to discovery the Brain. -2. You did not wait long enough. +1. You did not wait long enough. I have noticed that it will take up to 5 minutes for the discovery to find the Brain. -3. Local firewall is blocking the mDNS broadcast messages. +1. Local firewall is blocking the mDNS broadcast messages. Modify the firewall to allow mDNS packets - typically port 5353 and/or IP address 224.0.0.251 -4. The Brain is on a different subnet. +1. The Brain is on a different subnet. Unless you have special routing rules, having the Brain on a different subnet than the openHAB instance will prevent discovery. Either add routing rules or move one of them to the same subnet. -5. Bug in the mDNS library. +1. Bug in the mDNS library. Occasionally a broadcast will be missed and a simple openHAB restart will fix the issue. -6. Brain isn't reachable. +1. Brain isn't reachable. Ping the Brain's address from the openHAB machine and see if it responds. If none of the above work, there are a few more things you can try: -1. Use your local dns-sd command to see if you find the instance ("dns-sd -B _neeo._tcp"). -2. Manually configure the Brain and specify its IP address. -3. Look in the issues forum on the NEEO SDK GitHub - specifically the [Brain Discovery not working](https://github.com/NEEOInc/neeo-sdk/issues/36). +1. Use your local dns-sd command to see if you find the instance ("dns-sd -B _neeo._tcp"). +1. Manually configure the Brain and specify its IP address. +1. Look in the issues forum on the NEEO SDK GitHub - specifically the [Brain Discovery not working](https://github.com/NEEOInc/neeo-sdk/issues/36). ## Forward Actions The NEEO Brain has the option to forward all actions performed on it to a specific address. The forward actions will be a JSON string representation: -``` +```json { "action": "xxx", "actionparameter": "xxx", "recipe": "xxx", "device": "xxx", "room": "xxx" } ``` All parameters are optional (based on what action has been taken) with atleast one of them filled in. If the Recipe "Watch TV" is launched, the forward action would be: -``` +```json { "action": "launch", "recipe": "Watch TV" } ``` The NEEO Brain bridge will register itself as the destination for actions and has a trigger channel defined to accept the results of any forward action. An example rule might look like (for a Brain with an ID of d487672e): -``` +```java rule "NEEO" when Channel 'neeo:Brain:d487672e:forwardActions' triggered @@ -139,7 +139,7 @@ end Since the NEEO Brain ONLY allows a single forward actions URL, the NEEO Brain Bridge can be configured to: 1. Whether to register for forward actions or not. -2. If forward actions has been registered, forward the action on to other URLs for processing. +1. If forward actions has been registered, forward the action on to other URLs for processing. This will allow you to use other devices that want to consume the forward actions (in addition to openHAB). @@ -157,8 +157,6 @@ The following are the configurations available to each of the bridges/things: | discoverEmptyRooms | boolean | No | false | Whether to discover Rooms with no Devices in them | | checkStatusInterval | number | No | 10 | The interval (in seconds) to check the status of the Brain. Specify <=0 to disable | - - ### NEEO Room | Name | Type | Required | Default | Description | @@ -173,7 +171,6 @@ The following are the configurations available to each of the bridges/things: |----------------------|---------|----------|---------|----------------------------------------------------------------------------------------------------------------| | deviceKey | string | Yes | (None) | The unique key identifying the Device on the NEEO Brain | - ## Channels ### NEEO Brain @@ -184,7 +181,6 @@ The NEEO Brain has the following channels: |--------------------|------------|--------------|--------------------------------------------------------------------------------------------| | forwardActions | R | Trigger | The forward actions channel | - The following properties are available at the time of this writing: | Name | Description | @@ -197,15 +193,14 @@ The following properties are available at the time of this writing: | Key | The unique identifier of the Brain | | Name | Internal name of the Brain | - ### NEEO Room The NEEO Room is dynamically generated from the Brain. Each Room will dynamically generate the following channel groups: -1) Each Room will have exactly one "room-state" representing the current state of the Room. -2) Each Room will have zero or more "room-recipe-xxx" (where xxx is the Recipe key) groups representing each Recipe in the Room. -3) Each Room will have zero or more "room-scenario-xxx" (where xxx is the Scenario key) groups representing each Scenario in the Room. +1. Each Room will have exactly one "room-state" representing the current state of the Room. +1. Each Room will have zero or more "room-recipe-xxx" (where xxx is the Recipe key) groups representing each Recipe in the Room. +1. Each Room will have zero or more "room-scenario-xxx" (where xxx is the Scenario key) groups representing each Scenario in the Room. #### Room State Group @@ -216,7 +211,7 @@ The following channels will be in the Room state group: | currentStep* | R | trigger | Displays the current step being executed | Current Step will ONLY be triggered if openHAB started the corresponding recipe (or scenario). -If the NEEO Remote or NEEO App starts the recipe or scenario, the currentStep will never be triggered. +If the NEEO Remote or NEEO App starts the recipe or scenario, the currentStep will never be triggered. The current step is ONLY communicated from the Brain to the device that started the Recipe/Scenario. If the remote started the Recipe/Scenario, it will show the current step but openHAB will not be notified. @@ -260,7 +255,7 @@ Each Device will have a single group (Macros) and that group will contain one or .things -``` +```java neeo:brain:home [ ipAddress="192.168.1.24" ] neeo:room:attic (neeo:brain:home) [ roomKey="6277847230179180544" ] neeo:device:tv (neeo:room:attic) [ deviceKey="6343464057630097408" ] @@ -268,7 +263,7 @@ neeo:device:tv (neeo:room:attic) [ deviceKey="6343464057630097408" ] .items -``` +```java String Attic_RecipeName "Recipe Name [%s]" { channel="neeo:room-6277847230179180544:attic:room:recipe#name-6277847545657950208" } Switch Attic_RecipeEnabled "Recipe Enabled" { channel="neeo:room-6277847230179180544:attic:room:recipe#enabled-6277847545657950208" } Switch Attic_RecipeStatus "Running" { channel="neeo:room-6277847230179180544:attic:room:recipe#status-6277847545657950208" } @@ -279,7 +274,7 @@ Switch Attic_TvInput1 "Input1" { channel="neeo:device:t .sitemap -``` +```perl sitemap demo label="NEEO" { Frame label="Attic" { Text item=Attic_RecipeName diff --git a/bundles/org.openhab.binding.neohub/README.md b/bundles/org.openhab.binding.neohub/README.md index 77d0e15e484f3..52857734296b6 100644 --- a/bundles/org.openhab.binding.neohub/README.md +++ b/bundles/org.openhab.binding.neohub/README.md @@ -23,7 +23,7 @@ The binding automatically searches for NeoHub devices, and puts them in the Main Alternatively you can manually create a (Bridge) Thing for the NeoHub. In either case you need to enter any missing Configuration Parameters (see Thing Configuration for NeoHub below). Once the Configuration Parameters are all valid, then the NeoHub Thing will automatically attempt to connect and sign on to the hub. -If the sign on succeeds, the Thing will indicate its status as Online, otherwise it will show an error status. +If the sign on succeeds, the Thing will indicate its status as Online, otherwise it will show an error status. Once the NeoHub Thing has been created and it has successfully signed on, it will automatically interrogate the HeoHub to discover all the respective Heatmiser device Things that are connected to it. If in the future, you add additional Heatmiser devices to your system, the binding will discover them too. @@ -56,7 +56,7 @@ But you can override this in special cases if you want to use (say) port forward ## Connection Refused Errors From early 2022 Heatmiser introduced NeoHub firmware that has the ability to enable / disable connecting to it via a TCP port. -If the TCP port is disabled the OpenHAB binding cannot connect and the binding will report a *"Connection Refused"* warning in the log. +If the TCP port is disabled the OpenHAB binding cannot connect and the binding will report a _"Connection Refused"_ warning in the log. In prior firmware versions the TCP port was always enabled. But in the new firmware the TCP port is initially enabled on power up but if no communication occurs for 48 hours it is automatically disabled. Alternatively the Heatmiser mobile app has a setting (Settings | System | API Access | Legacy API Enable | On) whereby the TCP port can be permanently enabled. @@ -66,7 +66,7 @@ Alternatively the Heatmiser mobile app has a setting (Settings | System | API Ac The NeoHub Thing connects to the hub (bridge) to communicate with any Heatmiser devices that are connected to it. Each such Heatmiser device is identified by means of a unique device name in the hub. The device name is automatically discovered by the NeoHub Thing, and it is also visible (and changeable) via the Heatmiser App. - + | Configuration Parameter | Description | |-------------------------|--------------------------------------------------------------------------------------| | deviceNameInHub | Device name that identifies the Heatmiser device in the NeoHub and the Heatmiser App | @@ -138,7 +138,7 @@ Note: if a drop out occurs, the Thing will always change its status to `OFFLINE` ### `demo.things` File -``` +```java Bridge neohub:neohub:myhubname "Heatmiser NeoHub" [ hostName="192.168.1.123", portNumber=4242, pollingInterval=60, socketTimeout=5, preferLegacyApi=true ] { Thing neoplug mydownstairs "Downstairs Plug" @ "Hall" [ deviceNameInHub="Hall Plug" ] Thing neostat myupstairs "Upstairs Thermostat" @ "Landing" [ deviceNameInHub="Landing Thermostat" ] @@ -149,7 +149,7 @@ Bridge neohub:neohub:myhubname "Heatmiser NeoHub" [ hostName="192.168.1.123", po ### `demo.items` File -``` +```java Number:Temperature Upstairs_RoomTemperature "Room Temperature" { channel="neohub:neostat:myhubname:myupstairs:roomTemperature" } Number:Temperature Upstairs_TargetTemperature "Target Temperature" { channel="neohub:neostat:myhubname:myupstairs:targetTemperature" } Number:Temperature Upstairs_FloorTemperature "Floor Temperature" { channel="neohub:neostat:myhubname:myupstairs:floorTemperature" } @@ -167,30 +167,29 @@ Number:Temperature Kitchen_Temperature "Kitchen Temperature" { channel="neohub:n ### `demo.sitemap` File -``` +```perl sitemap neohub label="Heatmiser NeoHub" { - Frame label="Thermostat" { - Text item=Upstairs_RoomTemperature - Setpoint item=Upstairs_TargetTemperature minValue=15 maxValue=30 step=1 - Text item=Upstairs_ThermostatOutputState - Switch item=Upstairs_OccupancyModePresent - Text item=Upstairs_FloorTemperature - } - - Frame label="Plug" { - Switch item=Downstairs_PlugOutputState - Switch item=Downstairs_PlugAutoMode - } - - Frame label="Contact" { - Contact item=Window_Contact_State - Switch item=Window_Contact_Battery_Low - } - - Frame label="Sensor" { - Text item=Kitchen_Temperature - } + Frame label="Thermostat" { + Text item=Upstairs_RoomTemperature + Setpoint item=Upstairs_TargetTemperature minValue=15 maxValue=30 step=1 + Text item=Upstairs_ThermostatOutputState + Switch item=Upstairs_OccupancyModePresent + Text item=Upstairs_FloorTemperature + } + + Frame label="Plug" { + Switch item=Downstairs_PlugOutputState + Switch item=Downstairs_PlugAutoMode + } + + Frame label="Contact" { + Contact item=Window_Contact_State + Switch item=Window_Contact_Battery_Low + } + + Frame label="Sensor" { + Text item=Kitchen_Temperature + } } ``` - diff --git a/bundles/org.openhab.binding.nest/README.md b/bundles/org.openhab.binding.nest/README.md index fb407b1c16781..148444082f02d 100644 --- a/bundles/org.openhab.binding.nest/README.md +++ b/bundles/org.openhab.binding.nest/README.md @@ -88,18 +88,18 @@ Finally, an SDM Account Thing can be created to access the SDM project using the 1. Copy/paste the saved OAuth 2.0 **Client Secret** to SDM group parameter (e.g. `726kcU-d1W4RXxEJA79oZ0oG`) 1. Create an authorization code for the binding: 1. Replace the **Project ID** and **Client ID** in the URL below with your SDM Project ID and SDM OAuth 2.0 Client ID and open the URL in a new browser tab: - + `https://nestservices.google.com/partnerconnections//auth?scope=https://www.googleapis.com/auth/sdm.service&access_type=offline&prompt=consent&include_granted_scopes=true&response_type=code&redirect_uri=https://www.google.com&client_id=` - + For the example values used so far this is: - + `https://nestservices.google.com/partnerconnections/585de72e-968c-435c-b16a-31d1d3f76833/auth?scope=https://www.googleapis.com/auth/sdm.service&access_type=offline&prompt=consent&include_granted_scopes=true&response_type=code&redirect_uri=https://www.google.com&client_id=1046297811237-3f5sj4ccfubit0fum027ral82jgffsd1.apps.googleusercontent.com` 1. Enable all the permissions you want to use with the binding and click "Next" to continue 1. Login using your Google account when prompted 1. On the "Google hasn't verified this app" page, click on "Advanced" 1. Then click on "Go to ... (advanced)" 1. Now "Allow" the SDM permissions and confirm your choices again by clicking "Allow" - 1. After your browser has been redirected to https://www.google.com, the **Authorization Code** will be set in the browser URL as value of the "code" URL query parameter + 1. After your browser has been redirected to , the **Authorization Code** will be set in the browser URL as value of the "code" URL query parameter 1. Copy/paste the **Authorization Code** to the SDM group parameter in the openHAB Nest SDM Account Thing configuration 1. All required SDM Account Thing configuration parameters have now been entered so create it by clicking "Create Thing" @@ -149,23 +149,23 @@ Finally, the existing SDM Account Thing can be updated so it can subscribe to SD 1. Open the configuration details of your existing "Nest SDM Account" Thing in openHAB 1. Copy/paste the saved GCP **Project ID** to Pub/Sub group parameter (e.g. `openhab-123`) 1. Enter a name in **Subscription ID** that uniquely identifies the Pub/Sub subscription used by the binding - + > Must be 3-255 characters, start with a letter, and contain only the following characters: letters, numbers, dashes (-), periods (.), underscores (_), tildes (~), percents (%) or plus signs (+). Cannot start with goog. 1. Copy/paste the saved OAuth 2.0 **Client ID** to Pub/Sub group parameter (e.g. `1046297811237-lg27h26kln6r1nbg54jpg6nfjg6h4b3n.apps.googleusercontent.com`) 1. Copy/paste the saved OAuth 2.0 **Client Secret** to Pub/Sub group parameter (e.g. `1-k78-XcHhp_gdZF-I6JaIHp`) 1. Create an authorization code for the binding: 1. Replace the **Client ID** in the URL below with your Pub/Sub OAuth 2.0 Client ID and open the URL in a new browser tab: - + `https://accounts.google.com/o/oauth2/v2/auth?scope=https://www.googleapis.com/auth/pubsub&access_type=offline&prompt=consent&include_granted_scopes=true&response_type=code&redirect_uri=https://www.google.com&client_id=` - + For the example client this is: - + `https://accounts.google.com/o/oauth2/v2/auth?scope=https://www.googleapis.com/auth/pubsub&access_type=offline&prompt=consent&include_granted_scopes=true&response_type=code&redirect_uri=https://www.google.com&client_id=1046297811237-lg27h26kln6r1nbg54jpg6nfjg6h4b3n.apps.googleusercontent.com` 1. Login using your Google account when prompted 1. On the "Google hasn't verified this app" page, click on "Advanced" 1. Then click on "Go to ... (advanced)" 1. Now "Allow" the Pub/Sub permissions and confirm your choices again by clicking "Allow" - 1. After your browser has been redirected to https://www.google.com, the **Authorization Code** will be set in the browser URL as value of the "code" URL query parameter + 1. After your browser has been redirected to , the **Authorization Code** will be set in the browser URL as value of the "code" URL query parameter 1. Copy/paste the **Authorization Code** to the Pub/Sub group parameter in the openHAB Nest SDM Account Thing configuration 1. All required Pub/Sub Account Thing configuration parameters have now been entered so click "Save" to update the SDM Account Thing configuration @@ -244,7 +244,7 @@ Similarly, when a DateTime command is sent to the `fan_timer_timeout` channel, t ### WWN Camera Channels -**Camera group channels** +#### Camera Group Channels Information about the camera. @@ -260,7 +260,7 @@ Information about the camera. | video_history_enabled | Switch | If the video history is currently enabled | R | | web_url | String | The web URL to see the camera | R | -**Last event group channels** +#### Last Event Group Channels Information about the last camera event (requires Nest Aware subscription). @@ -339,9 +339,9 @@ Information about the last camera event (requires Nest Aware subscription). Note that the Nest API rounds Thermostat values so they will differ from what shows up in the Nest App. The Nest API applies the following rounding: -* degrees Celsius to 0.5 degrees -* degrees Fahrenheit to whole degrees -* humidity to 5% +- degrees Celsius to 0.5 degrees +- degrees Fahrenheit to whole degrees +- humidity to 5% ## Example @@ -349,7 +349,7 @@ You can use the discovery functionality of the binding to obtain the deviceId an ### sdm-demo.things -``` +```java Bridge nest:sdm_account:demo_sdm_account [ sdmProjectId="585de72e-968c-435c-b16a-31d1d3f76833", sdmClientId="1046297811237-3f5sj4ccfubit0fum027ral82jgffsd1.apps.googleusercontent.com", sdmClientSecret="726kcU-d1W4RXxEJA79oZ0oG", sdmAuthorizationCode="xkkY3qYtfZCzaXCcPxpOELUW8EhgiSMD3n9jmzJ3m0yerkQpVRdj5vqWRjMSIG", pubsubProjectId="openhab-12345", pubsubSubscriptionId="nest-sdm-events", pubsubClientId="1046297811237-lg27h26kln6r1nbg54jpg6nfjg6h4b3n.apps.googleusercontent.com", pubsubClientSecret="1-k78-XcHhp_gdZF-I6JaIHp", pubsubAuthorizationCode="tASfQq7gn6sfbUSbwRufbMI0BYDzh1d7MBG2G7vdZpbhjmZfwDp5MkeaX0iMxn" ] { Thing sdm_camera fish_cam [ deviceId="AVPHwTQCAhersqmQ3IXwyqSX-XyuVZXoiNSNPeHdIMKgYpYZolNP4S9LS5QDF2LeuM3BQcpBh_fOEZYxkeH6eoQdWEELqi" ] { Channels: @@ -371,7 +371,7 @@ Bridge nest:sdm_account:demo_sdm_account [ sdmProjectId="585de72e-968c-435c-b16a ### sdm-demo.items -``` +```java /* SDM Doorbell */ Image Doorbell_Chime_Image "Chime Image" { channel="nest:sdm_doorbell:demo_sdm_account:front_door:chime_event#image" } DateTime Doorbell_Chime_Timestamp "Chime Timestamp [%1$tY-%1$tm-%1$td %1$tH:%1$tM:%1$tS]" { channel="nest:sdm_doorbell:demo_sdm_account:front_door:chime_event#timestamp" } @@ -403,7 +403,7 @@ Number:Temperature Thermostat_Temperature_Heat "Temperature Heat [%.1f %unit ### wwn-demo.things -``` +```java Bridge nest:wwn_account:demo_wwn_account [ productId="8fdf9885-ca07-4252-1aa3-f3d5ca9589e0", productSecret="QITLR3iyUlWaj9dbvCxsCKp4f", accessToken="c.6rse1xtRk2UANErcY0XazaqPHgbvSSB6owOrbZrZ6IXrmqhsr9QTmcfaiLX1l0ULvlI5xLp01xmKeiojHqozLQbNM8yfITj1LSdK28zsUft1aKKH2mDlOeoqZKBdVIsxyZk4orH0AvKEZ5aY" ] { Thing wwn_camera fish_cam [ deviceId="qw0NNE8ruxA9AGJkTaFH3KeUiJaONWKiH9Gh3RwwhHClonIexTtufQ" ] Thing wwn_smoke_detector hallway_smoke [ deviceId="Tzvibaa3lLKnHpvpi9OQeCI_z5rfkBAV" ] @@ -414,7 +414,7 @@ Bridge nest:wwn_account:demo_wwn_account [ productId="8fdf9885-ca07-4252-1aa3-f3 ### wwn-demo.items -``` +```java /* WWN Camera */ String Cam_App_URL "App URL [%s]" { channel="nest:wwn_camera:demo_wwn_account:fish_cam:camera#app_url" } Switch Cam_Audio_Input_Enabled "Audio Input Enabled" { channel="nest:wwn_camera:demo_wwn_account:fish_cam:camera#audio_input_enabled" } diff --git a/bundles/org.openhab.binding.netatmo/README.md b/bundles/org.openhab.binding.netatmo/README.md index f5a64dd4f67d6..2b52dbd637b95 100644 --- a/bundles/org.openhab.binding.netatmo/README.md +++ b/bundles/org.openhab.binding.netatmo/README.md @@ -2,16 +2,16 @@ The Netatmo binding integrates the following Netatmo products: -- *Personal Weather Station*. Reports temperature, humidity, air pressure, carbon dioxide concentration in the air, as well as the ambient noise level. -- *Thermostat*. Reports ambient temperature, allow to check target temperature, consult and change furnace heating status. -- *Indoor Camera / Welcome*. Reports last event and persons at home, consult picture and video from event/camera. -- *Siren* -- *Outdoor Camera / Presence*. Reports last event, consult picture and video from event/camera. -- *Doorbell* -- *Smoke Detector* -- *Smart Door Sensor* +- _Personal Weather Station_. Reports temperature, humidity, air pressure, carbon dioxide concentration in the air, as well as the ambient noise level. +- _Thermostat_. Reports ambient temperature, allow to check target temperature, consult and change furnace heating status. +- _Indoor Camera / Welcome_. Reports last event and persons at home, consult picture and video from event/camera. +- _Siren_ +- _Outdoor Camera / Presence_. Reports last event, consult picture and video from event/camera. +- _Doorbell_ +- _Smoke Detector_ +- _Smart Door Sensor_ -See https://www.netatmo.com/ for details on their product. +See for details on their product. ## Binding Configuration @@ -27,15 +27,14 @@ Follow instructions under: Variables needed for the setup of the binding are: -* `` Your client ID taken from your App at https://dev.netatmo.com/apps -* `` A token provided along with the ``. +- `` Your client ID taken from your App at +- `` A token provided along with the ``. The binding has the following configuration options: -| Parameter | Type | Description | -|--------------|---------------|--------------------------------------------------------------------------------------------| -| readFriends | Boolean | Enables or disables the discovery of guest weather stations. | - +| Parameter | Type | Description | +| ----------- | ------- | ------------------------------------------------------------ | +| readFriends | Boolean | Enables or disables the discovery of guest weather stations. | ## Netatmo Account (Bridge) Configuration @@ -44,8 +43,8 @@ You will have to create at first a bridge to handle communication with your Neta The Account bridge has the following configuration elements: | Parameter | Type | Required | Description | -|-------------------|--------|----------|------------------------------------------------------------------------------------------------------------------------| -| clientId | String | Yes | Client ID provided for the application you created on http://dev.netatmo.com/createapp | +| ----------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------- | +| clientId | String | Yes | Client ID provided for the application you created on | | clientSecret | String | Yes | Client Secret provided for the application you created | | webHookUrl | String | No | Protocol, public IP and port to access openHAB server from Internet | | reconnectInterval | Number | No | The reconnection interval to Netatmo API (in s) | @@ -56,10 +55,9 @@ The Account bridge has the following configuration elements: **Supported channels for the Account bridge thing:** | Channel Group | Channel Id | Item Type | Description | -|---------------|---------------|-----------|--------------------------------------------------------------------| +| ------------- | ------------- | --------- | ------------------------------------------------------------------ | | monitoring | request-count | Number | Number of requests transmitted to Netatmo API during the last hour | - ### Configure the Bridge 1. Complete the Netatmo Application Registration if you have not already done so, see above. @@ -67,38 +65,34 @@ The Account bridge has the following configuration elements: 1. Add a new **"Netatmo Account"** thing. Choose new Id for the account, unless you like the generated one, put in the _Client ID_ and _Client Secret_ from the Netatmo Connect Application registration in their respective fields of the bridge configuration. Save the bridge. 1. The bridge thing will go _OFFLINE_ / _CONFIGURATION_ERROR_ - this is fine. You have to authorize this bridge with Netatmo Connect. 1. Go to the authorization page of your server. `http://:8080/netatmo/connect/<_CLIENT_ID_>`. Your newly added bridge should be listed there (no need for you to expose your openHAB server outside your local network for this). -1. Press the _"Authorize Thing"_ button. This will take you either to the login page of Netatmo Connect or directly to the authorization screen. Login and/or authorize the application. You will be returned and the entry should go green. +1. Press the _"Authorize Thing"_ button. This will take you either to the login page of Netatmo Connect or directly to the authorization screen. Login and/or authorize the application. You will be returned and the entry should go green. 1. The bridge configuration will be updated with a refresh token and go _ONLINE_. The refresh token is used to re-authorize the bridge with Netatmo Connect Web API whenever required. So you can consult this token by opening the Thing page in MainUI, this is the value of the advanced parameter named “Refresh Token”. 1. If you're using file based .things config file, copy the provided refresh token in the **refreshToken** parameter of your thing definition (example below). Now that you have got your bridge _ONLINE_ you can now start a scan with the binding to auto discover your things. - ## List of supported things -| Thing Type | Type | Netatmo Object | Description | Thing Parameters | -|-----------------|--------|----------------|------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------| -| account | Bridge | N/A | This bridge represents an account, gateway to Netatmo API. | clientId, clientSecret, username, password, webHookUrl, reconnectInterval | -| home | Bridge | NAHome | A home hosting Security or Energy devices and modules. | id, refreshInterval | -| person | Thing | NAPerson | A person known by your Netatmo system. | id | -| welcome | Thing | NACamera | The Netatmo Smart Indoor Camera (Welcome). | id | -| presence | Thing | NOC | The Netatmo Smart Outdoor Camera (Presence) camera with or without siren. | id | -| siren | Thing | NIS | The Netatmo Smart Indoor Siren. | id | -| doorbell | Thing | NDB | The Netatmo Smart Video Doorbell device. | id | -| weather-station | Bridge | NAMain | Main indoor module reporting temperature, humidity, pressure, air quality and sound level. | id | -| outdoor | Thing | NAModule1 | Outdoor module reporting temperature and humidity. | id | -| wind | Thing | NAModule2 | Wind sensor reporting wind angle and strength. | id | -| rain | Thing | NAModule3 | Rain Gauge measuring precipitation. | id | -| indoor | Thing | NAModule4 | Additional indoor module reporting temperature, humidity and CO2 level. | id | -| home-coach | Thing | NHC | Healthy home coach reporting health-index, temperature, humidity, pressure, air quality, sound level.| id | -| plug | Thing | NAPlug | The relay connected to the boiler controlling a Thermostat and zero or more valves. | id | -| thermostat | Thing | NATherm1 | The Thermostat device placed in a given room. | id | -| room | Thing | NARoom | A room in your house. | id | -| valve | Thing | NRV | A valve controlling a radiator. | id | -| tag | Thing | NACamDoorTag | A door / window sensor | id | - - - +| Thing Type | Type | Netatmo Object | Description | Thing Parameters | +| --------------- | ------ | -------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | +| account | Bridge | N/A | This bridge represents an account, gateway to Netatmo API. | clientId, clientSecret, username, password, webHookUrl, reconnectInterval | +| home | Bridge | NAHome | A home hosting Security or Energy devices and modules. | id, refreshInterval | +| person | Thing | NAPerson | A person known by your Netatmo system. | id | +| welcome | Thing | NACamera | The Netatmo Smart Indoor Camera (Welcome). | id | +| presence | Thing | NOC | The Netatmo Smart Outdoor Camera (Presence) camera with or without siren. | id | +| siren | Thing | NIS | The Netatmo Smart Indoor Siren. | id | +| doorbell | Thing | NDB | The Netatmo Smart Video Doorbell device. | id | +| weather-station | Bridge | NAMain | Main indoor module reporting temperature, humidity, pressure, air quality and sound level. | id | +| outdoor | Thing | NAModule1 | Outdoor module reporting temperature and humidity. | id | +| wind | Thing | NAModule2 | Wind sensor reporting wind angle and strength. | id | +| rain | Thing | NAModule3 | Rain Gauge measuring precipitation. | id | +| indoor | Thing | NAModule4 | Additional indoor module reporting temperature, humidity and CO2 level. | id | +| home-coach | Thing | NHC | Healthy home coach reporting health-index, temperature, humidity, pressure, air quality, sound level. | id | +| plug | Thing | NAPlug | The relay connected to the boiler controlling a Thermostat and zero or more valves. | id | +| thermostat | Thing | NATherm1 | The Thermostat device placed in a given room. | id | +| room | Thing | NARoom | A room in your house. | id | +| valve | Thing | NRV | A valve controlling a radiator. | id | +| tag | Thing | NACamDoorTag | A door / window sensor | id | ### Webhook @@ -106,13 +100,13 @@ Netatmo servers can send push notifications to the Netatmo Binding by using a ca The webhook URL is setup at Netatmo Account level using "Webhook Address" parameter. You will define here public way to access your openHAB server: -``` +```text http(s)://xx.yy.zz.ww:443 ``` Your Netatmo App will be configured automatically by the bridge to the endpoint: -``` +```text http(s)://xx.yy.zz.ww:443/netatmo/webhook/<_CLIENT_ID_> ``` @@ -120,7 +114,6 @@ Please be aware of Netatmo own limits regarding webhook usage that lead to a 24h NB: Allowed ports for webhooks are 80, 88, 443 and 9443. - ### Configure Things The easiest way to retrieve the IDs for all the devices and modules is to use the console command `openhab:netatmo showIds`. @@ -134,7 +127,7 @@ First login with your user. Then some examples of the documentation contain the **real results** of your weather station. In order to try the examples, you need the `device_id` of your Netatmo station. You can find it in the configuration menu of the app (android or apple). -Get the IDs of your devices (indoor, outdoor, rain gauge) +Get the IDs of your devices (indoor, outdoor, rain gauge) [here](https://dev.netatmo.com/resources/technical/reference/weather/getstationsdata). `main_device` is the ID of the "main device", the indoor sensor. @@ -157,226 +150,213 @@ split the rest into three parts of two characters and append with a colon as del For example your serial number "h00bcdc" should end up as "02:00:00:00:bc:dc". - ## Discovery If you did not manually create things in the *.things file, the Netatmo Binding is able to discover automatically all depending modules and devices. - ## Channels - ### Weather Station Main Indoor Device Weather station does not need any refreshInterval setting. Based on a standard update period of 10mn by Netatmo systems - it will auto adapt to stick closest as possible to last data availability. - **Supported channels for the main indoor module:** -| Channel Group | Channel Id | Item Type | Description | -|---------------------|----------------------|----------------------|--------------------------------------------------| -| pressure | value | Number:Pressure | Current pressure | -| pressure | absolute | Number:Pressure | Pressure at sea level | -| pressure | trend | String | Pressure evolution trend over time | -| noise | value | Number:Dimensionless | Current noise level | -| humidity | value | Number:Dimensionless | Current humidity | -| humidity | humidex | Number | Computed Humidex index | -| humidity | humidex-scale | Number | Humidex index appreciation | -| temperature | value | Number:Temperature | Current temperature | -| temperature | min-today | Number:Temperature | Minimum temperature on current day | -| temperature | max-today | Number:Temperature | Maximum temperature on current day | -| temperature | min-time | DateTime | Moment of today's minimum temperature | -| temperature | max-time | DateTime | Moment of today's maximum temperature | -| temperature | trend | String | Temperature evolution trend over time | -| temperature | heat-index | Number:Temperature | Computed Heat Index | -| temperature | dewpoint | Number:Temperature | Computed dewpoint temperature | -| temperature | dewpoint-depression | Number:Temperature | Computed dewpoint depression | -| airquality | co2 | Number:Dimensionless | CO2 level in ppm | -| location | value | Location | Location of the device | -| timestamp | last-seen | DateTime | Last time the module reported its presence | -| timestamp | measures | DateTime | Moment of the last measures update | -| signal | strength | Number | Signal strength (0 for no signal, 1 for weak...) | -| signal | value | Number:Power | Signal strength in dBm | +| Channel Group | Channel Id | Item Type | Description | +| ------------- | ------------------- | -------------------- | ------------------------------------------------ | +| pressure | value | Number:Pressure | Current pressure | +| pressure | absolute | Number:Pressure | Pressure at sea level | +| pressure | trend | String | Pressure evolution trend over time | +| noise | value | Number:Dimensionless | Current noise level | +| humidity | value | Number:Dimensionless | Current humidity | +| humidity | humidex | Number | Computed Humidex index | +| humidity | humidex-scale | Number | Humidex index appreciation | +| temperature | value | Number:Temperature | Current temperature | +| temperature | min-today | Number:Temperature | Minimum temperature on current day | +| temperature | max-today | Number:Temperature | Maximum temperature on current day | +| temperature | min-time | DateTime | Moment of today's minimum temperature | +| temperature | max-time | DateTime | Moment of today's maximum temperature | +| temperature | trend | String | Temperature evolution trend over time | +| temperature | heat-index | Number:Temperature | Computed Heat Index | +| temperature | dewpoint | Number:Temperature | Computed dewpoint temperature | +| temperature | dewpoint-depression | Number:Temperature | Computed dewpoint depression | +| airquality | co2 | Number:Dimensionless | CO2 level in ppm | +| location | value | Location | Location of the device | +| timestamp | last-seen | DateTime | Last time the module reported its presence | +| timestamp | measures | DateTime | Moment of the last measures update | +| signal | strength | Number | Signal strength (0 for no signal, 1 for weak...) | +| signal | value | Number:Power | Signal strength in dBm | All these channels are read only. **Extensible channels for the main indoor module:** -| Channel Type | Item Type | Description | Channel parameters | -|----------------------|----------------------|-----------------------------------|----------------------------------| +| Channel Type | Item Type | Description | Channel parameters | +| -------------------- | -------------------- | --------------------------------- | -------------------------------------------------------------------- | | co2-measurement | Number:Dimensionless | CO2 measurement | limit (MIN, MAX), period (30min, 1hour, 3hours, 1day, 1week, 1month) | -| co2-timestamp | DateTime | CO2 measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | +| co2-timestamp | DateTime | CO2 measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | | hum-measurement | Number:Dimensionless | Humidity measurement | limit (MIN, MAX), period (30min, 1hour, 3hours, 1day, 1week, 1month) | -| hum-timestamp | DateTime | Humidity measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | +| hum-timestamp | DateTime | Humidity measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | | noise-measurement | Number:Dimensionless | Noise measurement | limit (MIN, MAX), period (30min, 1hour, 3hours, 1day, 1week, 1month) | -| noise-timestamp | DateTime | Noise measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | +| noise-timestamp | DateTime | Noise measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | | pressure-measurement | Number:Pressure | Pressure measurement | limit (MIN, MAX), period (30min, 1hour, 3hours, 1day, 1week, 1month) | -| pressure-timestamp | DateTime | Pressure measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | +| pressure-timestamp | DateTime | Pressure measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | | temp-measurement | Number:Temperature | Temperature measurement | limit (MIN, MAX), period (30min, 1hour, 3hours, 1day, 1week, 1month) | -| temp-timestamp | DateTime | Temperature measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | - +| temp-timestamp | DateTime | Temperature measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | ### Weather Station Outdoor module **Supported channels for the outdoor module:** -| Channel Group | Channel Id | Item Type | Description | -|---------------------|----------------------|----------------------|--------------------------------------------------| -| humidity | value | Number:Dimensionless | Current humidity | -| humidity | humidex | Number | Computed Humidex index | -| humidity | humidex-scale | Number | Humidex index appreciation | -| temperature | value | Number:Temperature | Current temperature | -| temperature | min-today | Number:Temperature | Minimum temperature on current day | -| temperature | max-today | Number:Temperature | Maximum temperature on current day | -| temperature | min-time | DateTime | Moment of today's minimum temperature | -| temperature | max-time | DateTime | Moment of today's maximum temperature | -| temperature | trend | String | Temperature evolution trend over time | -| temperature | heat-index | Number:Temperature | Computed Heat Index | -| temperature | dewpoint | Number:Temperature | Computed dewpoint temperature | -| temperature | dewpoint-depression | Number:Temperature | Computed dewpoint depression | -| timestamp | last-seen | DateTime | Last time the module reported its presence | -| timestamp | measures | DateTime | Moment of the last measures update | -| signal | strength | Number | Signal strength (0 for no signal, 1 for weak...) | -| signal | value | Number:Power | Signal strength in dBm | -| battery | value | Number | Battery level | -| battery | low-battery | Switch | Low battery | +| Channel Group | Channel Id | Item Type | Description | +| ------------- | ------------------- | -------------------- | ------------------------------------------------ | +| humidity | value | Number:Dimensionless | Current humidity | +| humidity | humidex | Number | Computed Humidex index | +| humidity | humidex-scale | Number | Humidex index appreciation | +| temperature | value | Number:Temperature | Current temperature | +| temperature | min-today | Number:Temperature | Minimum temperature on current day | +| temperature | max-today | Number:Temperature | Maximum temperature on current day | +| temperature | min-time | DateTime | Moment of today's minimum temperature | +| temperature | max-time | DateTime | Moment of today's maximum temperature | +| temperature | trend | String | Temperature evolution trend over time | +| temperature | heat-index | Number:Temperature | Computed Heat Index | +| temperature | dewpoint | Number:Temperature | Computed dewpoint temperature | +| temperature | dewpoint-depression | Number:Temperature | Computed dewpoint depression | +| timestamp | last-seen | DateTime | Last time the module reported its presence | +| timestamp | measures | DateTime | Moment of the last measures update | +| signal | strength | Number | Signal strength (0 for no signal, 1 for weak...) | +| signal | value | Number:Power | Signal strength in dBm | +| battery | value | Number | Battery level | +| battery | low-battery | Switch | Low battery | All these channels are read only. **Extensible channels for the outdoor module:** -| Channel Type | Item Type | Description | Channel parameters | -|----------------------|----------------------|-----------------------------------|----------------------------------| -| hum-measurement | Number:Dimensionless | Humidity measurement | limit (MIN, MAX), period (30min, 1hour, 3hours, 1day, 1week, 1month) | -| hum-timestamp | DateTime | Humidity measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | -| temp-measurement | Number:Temperature | Temperature measurement | limit (MIN, MAX), period (30min, 1hour, 3hours, 1day, 1week, 1month) | -| temp-timestamp | DateTime | Temperature measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | - +| Channel Type | Item Type | Description | Channel parameters | +| ---------------- | -------------------- | --------------------------------- | -------------------------------------------------------------------- | +| hum-measurement | Number:Dimensionless | Humidity measurement | limit (MIN, MAX), period (30min, 1hour, 3hours, 1day, 1week, 1month) | +| hum-timestamp | DateTime | Humidity measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | +| temp-measurement | Number:Temperature | Temperature measurement | limit (MIN, MAX), period (30min, 1hour, 3hours, 1day, 1week, 1month) | +| temp-timestamp | DateTime | Temperature measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | ### Weather Station Additional Indoor module - **Supported channels for the additional indoor module:** -| Channel Group | Channel Id | Item Type | Description | -|---------------------|----------------------|----------------------|--------------------------------------------------| -| humidity | value | Number:Dimensionless | Current humidity | -| humidity | humidex | Number | Computed Humidex index | -| humidity | humidex-scale | Number | Humidex index appreciation | -| temperature | value | Number:Temperature | Current temperature | -| temperature | min-today | Number:Temperature | Minimum temperature on current day | -| temperature | max-today | Number:Temperature | Maximum temperature on current day | -| temperature | min-time | DateTime | Moment of today's minimum temperature | -| temperature | max-time | DateTime | Moment of today's maximum temperature | -| temperature | trend | String | Temperature evolution trend over time | -| temperature | heat-index | Number:Temperature | Computed Heat Index | -| temperature | dewpoint | Number:Temperature | Computed dewpoint temperature | -| temperature | dewpoint-depression | Number:Temperature | Computed dewpoint depression | -| airquality | co2 | Number:Dimensionless | Air quality | -| timestamp | last-seen | DateTime | Last time the module reported its presence | -| timestamp | measures | DateTime | Moment of the last measures update | -| signal | strength | Number | Signal strength (0 for no signal, 1 for weak...) | -| signal | value | Number:Power | Signal strength in dBm | -| battery | value | Number | Battery level | -| battery | low-battery | Switch | Low battery | +| Channel Group | Channel Id | Item Type | Description | +| ------------- | ------------------- | -------------------- | ------------------------------------------------ | +| humidity | value | Number:Dimensionless | Current humidity | +| humidity | humidex | Number | Computed Humidex index | +| humidity | humidex-scale | Number | Humidex index appreciation | +| temperature | value | Number:Temperature | Current temperature | +| temperature | min-today | Number:Temperature | Minimum temperature on current day | +| temperature | max-today | Number:Temperature | Maximum temperature on current day | +| temperature | min-time | DateTime | Moment of today's minimum temperature | +| temperature | max-time | DateTime | Moment of today's maximum temperature | +| temperature | trend | String | Temperature evolution trend over time | +| temperature | heat-index | Number:Temperature | Computed Heat Index | +| temperature | dewpoint | Number:Temperature | Computed dewpoint temperature | +| temperature | dewpoint-depression | Number:Temperature | Computed dewpoint depression | +| airquality | co2 | Number:Dimensionless | Air quality | +| timestamp | last-seen | DateTime | Last time the module reported its presence | +| timestamp | measures | DateTime | Moment of the last measures update | +| signal | strength | Number | Signal strength (0 for no signal, 1 for weak...) | +| signal | value | Number:Power | Signal strength in dBm | +| battery | value | Number | Battery level | +| battery | low-battery | Switch | Low battery | All these channels are read only. **Extensible channels for the additional indoor module:** -| Channel Type | Item Type | Description | Channel parameters | -|----------------------|----------------------|-----------------------------------|----------------------------------| -| co2-measurement | Number:Dimensionless | CO2 measurement | limit (MIN, MAX), period (30min, 1hour, 3hours, 1day, 1week, 1month) | -| co2-timestamp | DateTime | CO2 measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | -| hum-measurement | Number:Dimensionless | Humidity measurement | limit (MIN, MAX), period (30min, 1hour, 3hours, 1day, 1week, 1month) | -| hum-timestamp | DateTime | Humidity measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | -| temp-measurement | Number:Temperature | Temperature measurement | limit (MIN, MAX), period (30min, 1hour, 3hours, 1day, 1week, 1month) | -| temp-timestamp | DateTime | Temperature measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | - +| Channel Type | Item Type | Description | Channel parameters | +| ---------------- | -------------------- | --------------------------------- | -------------------------------------------------------------------- | +| co2-measurement | Number:Dimensionless | CO2 measurement | limit (MIN, MAX), period (30min, 1hour, 3hours, 1day, 1week, 1month) | +| co2-timestamp | DateTime | CO2 measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | +| hum-measurement | Number:Dimensionless | Humidity measurement | limit (MIN, MAX), period (30min, 1hour, 3hours, 1day, 1week, 1month) | +| hum-timestamp | DateTime | Humidity measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | +| temp-measurement | Number:Temperature | Temperature measurement | limit (MIN, MAX), period (30min, 1hour, 3hours, 1day, 1week, 1month) | +| temp-timestamp | DateTime | Temperature measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | ### Rain Gauge - **Supported channels for the rain guage:** -| Channel Group | Channel Id | Item Type | Description | -|---------------------|----------------------|----------------------|--------------------------------------------------| -| rain | value | Number:Speed | Current precipitation intensity | -| rain | sum-1 | Number:Length | Quantity of water over last hour | -| rain | sum-24 | Number:Length | Quantity of water during the current day | -| timestamp | last-seen | DateTime | Last time the module reported its presence | -| timestamp | measures | DateTime | Moment of the last measures update | -| signal | strength | Number | Signal strength (0 for no signal, 1 for weak...) | -| signal | value | Number:Power | Signal strength in dBm | -| battery | value | Number | Battery level | -| battery | low-battery | Switch | Low battery | +| Channel Group | Channel Id | Item Type | Description | +| ------------- | ----------- | ------------- | ------------------------------------------------ | +| rain | value | Number:Speed | Current precipitation intensity | +| rain | sum-1 | Number:Length | Quantity of water over last hour | +| rain | sum-24 | Number:Length | Quantity of water during the current day | +| timestamp | last-seen | DateTime | Last time the module reported its presence | +| timestamp | measures | DateTime | Moment of the last measures update | +| signal | strength | Number | Signal strength (0 for no signal, 1 for weak...) | +| signal | value | Number:Power | Signal strength in dBm | +| battery | value | Number | Battery level | +| battery | low-battery | Switch | Low battery | All these channels are read only. **Extensible channels for the rain guage:** -| Channel Type | Item Type | Description | Channel parameters | -|----------------------|----------------------|-----------------------------------|----------------------------------------------------| -| sum_rain-measurement | Number:Length | Summing rain measurement | period (30min, 1hour, 3hours, 1day, 1week, 1month) | - +| Channel Type | Item Type | Description | Channel parameters | +| -------------------- | ------------- | ------------------------ | -------------------------------------------------- | +| sum_rain-measurement | Number:Length | Summing rain measurement | period (30min, 1hour, 3hours, 1day, 1week, 1month) | ### Weather Station Wind module - **Supported channels for the wind module:** -| Channel Group | Channel Id | Item Type | Description | -|---------------------|----------------------|----------------------|--------------------------------------------------| -| wind | angle | Number:Angle | Current 5 minutes average wind direction | -| wind | strength | Number:Speed | Current 5 minutes average wind speed | -| wind | max-strength | Number:Speed | Maximum wind strength recorded | -| wind | max-strength-date | DateTime | Moment when MaxWindStrength was recorded | -| wind | gust-angle | Number:Angle | Direction of the last 5 minutes highest gust | -| wind | gust-strength | Number:Speed | Speed of the last 5 minutes highest gust wind | -| timestamp | last-seen | DateTime | Last time the module reported its presence | -| timestamp | measures | DateTime | Moment of the last measures update | -| signal | strength | Number | Signal strength (0 for no signal, 1 for weak...) | -| signal | value | Number:Power | Signal strength in dBm | -| battery | value | Number | Battery level | -| battery | low-battery | Switch | Low battery | +| Channel Group | Channel Id | Item Type | Description | +| ------------- | ----------------- | ------------ | ------------------------------------------------ | +| wind | angle | Number:Angle | Current 5 minutes average wind direction | +| wind | strength | Number:Speed | Current 5 minutes average wind speed | +| wind | max-strength | Number:Speed | Maximum wind strength recorded | +| wind | max-strength-date | DateTime | Moment when MaxWindStrength was recorded | +| wind | gust-angle | Number:Angle | Direction of the last 5 minutes highest gust | +| wind | gust-strength | Number:Speed | Speed of the last 5 minutes highest gust wind | +| timestamp | last-seen | DateTime | Last time the module reported its presence | +| timestamp | measures | DateTime | Moment of the last measures update | +| signal | strength | Number | Signal strength (0 for no signal, 1 for weak...) | +| signal | value | Number:Power | Signal strength in dBm | +| battery | value | Number | Battery level | +| battery | low-battery | Switch | Low battery | All these channels are read only. - ### Healthy Home Coach Device - **Supported channels for the healthy home coach device:** -| Channel Group | Channel Id | Item Type | Description | -|---------------------|----------------------|----------------------|--------------------------------------------------| -| noise | value | Number:Dimensionless | Current noise level | -| humidity | value | Number:Dimensionless | Current humidity | -| humidity | humidex | Number | Computed Humidex index | -| humidity | humidex-scale | Number | Humidex index appreciation | -| pressure | value | Number:Pressure | Current pressure | -| pressure | absolute | Number:Pressure | Pressure at sea level | -| temperature | value | Number:Temperature | Current temperature | -| temperature | min-today | Number:Temperature | Minimum temperature on current day | -| temperature | max-today | Number:Temperature | Maximum temperature on current day | -| temperature | min-time | DateTime | Moment of today's minimum temperature | -| temperature | max-time | DateTime | Moment of today's maximum temperature | -| temperature | heat-index | Number:Temperature | Computed Heat Index | -| temperature | dewpoint | Number:Temperature | Computed dewpoint temperature | -| temperature | dewpoint-depression | Number:Temperature | Computed dewpoint depression | -| airquality | health-index | Number | Health index (*) | -| airquality | co2 | Number:Dimensionless | Air quality | -| timestamp | last-seen | DateTime | Last time the module reported its presence | -| timestamp | measures | DateTime | Moment of the last measures update | -| signal | strength | Number | Signal strength (0 for no signal, 1 for weak...) | -| signal | value | Number:Power | Signal strength in dBm | - -(*) Health index values : - -- 0 : healthy -- 1 : fine -- 2 : fair +| Channel Group | Channel Id | Item Type | Description | +| ------------- | ------------------- | -------------------- | ------------------------------------------------ | +| noise | value | Number:Dimensionless | Current noise level | +| humidity | value | Number:Dimensionless | Current humidity | +| humidity | humidex | Number | Computed Humidex index | +| humidity | humidex-scale | Number | Humidex index appreciation | +| pressure | value | Number:Pressure | Current pressure | +| pressure | absolute | Number:Pressure | Pressure at sea level | +| temperature | value | Number:Temperature | Current temperature | +| temperature | min-today | Number:Temperature | Minimum temperature on current day | +| temperature | max-today | Number:Temperature | Maximum temperature on current day | +| temperature | min-time | DateTime | Moment of today's minimum temperature | +| temperature | max-time | DateTime | Moment of today's maximum temperature | +| temperature | heat-index | Number:Temperature | Computed Heat Index | +| temperature | dewpoint | Number:Temperature | Computed dewpoint temperature | +| temperature | dewpoint-depression | Number:Temperature | Computed dewpoint depression | +| airquality | health-index | Number | Health index (*) | +| airquality | co2 | Number:Dimensionless | Air quality | +| timestamp | last-seen | DateTime | Last time the module reported its presence | +| timestamp | measures | DateTime | Moment of the last measures update | +| signal | strength | Number | Signal strength (0 for no signal, 1 for weak...) | +| signal | value | Number:Power | Signal strength in dBm | + +(*) Health index values : + +- 0 : healthy +- 1 : fine +- 2 : fair - 3 : poor - 4 : unhealthy @@ -384,49 +364,45 @@ All these channels are read only. **Extensible channels for the healthy home coach device:** -| Channel Type | Item Type | Description | Channel parameters | -|----------------------|----------------------|-----------------------------------|----------------------------------| +| Channel Type | Item Type | Description | Channel parameters | +| -------------------- | -------------------- | --------------------------------- | -------------------------------------------------------------------- | | hum-measurement | Number:Dimensionless | Humidity measurement | limit (MIN, MAX), period (30min, 1hour, 3hours, 1day, 1week, 1month) | -| hum-timestamp | DateTime | Humidity measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | +| hum-timestamp | DateTime | Humidity measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | | noise-measurement | Number:Dimensionless | Noise measurement | limit (MIN, MAX), period (30min, 1hour, 3hours, 1day, 1week, 1month) | -| noise-timestamp | DateTime | Noise measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | +| noise-timestamp | DateTime | Noise measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | | pressure-measurement | Number:Pressure | Pressure measurement | limit (MIN, MAX), period (30min, 1hour, 3hours, 1day, 1week, 1month) | -| pressure-timestamp | DateTime | Pressure measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | +| pressure-timestamp | DateTime | Pressure measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | | temp-measurement | Number:Temperature | Temperature measurement | limit (MIN, MAX), period (30min, 1hour, 3hours, 1day, 1week, 1month) | -| temp-timestamp | DateTime | Temperature measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | - - +| temp-timestamp | DateTime | Temperature measurement timestamp | limit (DATE_MIN, DATE_MAX), period (1week, 1month) | ### Thermostat Relay Device **Supported channels for the thermostat relay device:** -| Channel Group | Channel Id | Item Type | Description | -|---------------------|--------------------|----------------------|--------------------------------------------------| -| signal | strength | Number | Signal strength (0 for no signal, 1 for weak...) | -| signal | value | Number:Power | Signal strength in dBm | +| Channel Group | Channel Id | Item Type | Description | +| ------------- | ---------- | ------------ | ------------------------------------------------ | +| signal | strength | Number | Signal strength (0 for no signal, 1 for weak...) | +| signal | value | Number:Power | Signal strength in dBm | All these channels are read only. - ### Thermostat Plug **Supported channels for the thermostat plug device:** -| Channel Group | Channel Id | Item Type | Description | -|---------------------|--------------------|----------------------|--------------------------------------------------| -| signal | strength | Number | Signal strength (0 for no signal, 1 for weak...) | -| signal | value | Number:Power | Signal strength in dBm | +| Channel Group | Channel Id | Item Type | Description | +| ------------- | ---------- | ------------ | ------------------------------------------------ | +| signal | strength | Number | Signal strength (0 for no signal, 1 for weak...) | +| signal | value | Number:Power | Signal strength in dBm | All these channels are read only. - ### Room **Supported channels for the Room thing:** | Channel Group | Channel Id | Item Type | Description | -|---------------|-----------------------|----------------------|---------------------------------------------------------| +| ------------- | --------------------- | -------------------- | ------------------------------------------------------- | | temperature | value | Number:Temperature | Current temperature in the room | | properties | window-open | Contact | Windows of the room are opened | | properties | anticipating | Switch | Anticipates next scheduled setpoint | @@ -438,13 +414,12 @@ All these channels are read only. All these channels except setpoint and setpoint-mode are read only. - ### Thermostat Module **Supported channels for the thermostat module:** | Channel Group | Channel Id | Item Type | Description | -|---------------|-------------|--------------|--------------------------------------------------| +| ------------- | ----------- | ------------ | ------------------------------------------------ | | properties | relay | Contact | Indicates if the boiler is currently heating | | signal | strength | Number | Signal strength (0 for no signal, 1 for weak...) | | signal | value | Number:Power | Signal strength in dBm | @@ -454,19 +429,17 @@ All these channels except setpoint and setpoint-mode are read only. (*) Can be UNDEF on some modules - ### Valve Module **Supported channels for the Valve module:** -| Channel Group | Channel Id | Item Type | Description | -|---------------------|--------------------|----------------------|--------------------------------------------------| -| signal | strength | Number | Signal strength (0 for no signal, 1 for weak...) | -| signal | value | Number:Power | Signal strength in dBm | -| battery | value | Number | Battery level | -| battery | low-battery | Switch | Low battery | -| battery | status | String | Description of the battery status (*) | - +| Channel Group | Channel Id | Item Type | Description | +| ------------- | ----------- | ------------ | ------------------------------------------------ | +| signal | strength | Number | Signal strength (0 for no signal, 1 for weak...) | +| signal | value | Number:Power | Signal strength in dBm | +| battery | value | Number | Battery level | +| battery | low-battery | Switch | Low battery | +| battery | status | String | Description of the battery status (*) | ### Welcome Home @@ -474,44 +447,43 @@ All these channels are read only. **Supported channels for the Home thing:** -| Channel Group | Channel Id | Item Type | Description | -|---------------------|------------------------|------------------|--------------------------------------------------| -| security | person-count | Number | Total number of persons that are at home | -| security | unknown-person-count | Number | Total number of unknown persons that are at home | -| security | unknown-person-picture | Image | Snapshot of unknown person that is at home | +| Channel Group | Channel Id | Item Type | Description | +| ------------- | ---------------------- | --------- | ------------------------------------------------ | +| security | person-count | Number | Total number of persons that are at home | +| security | unknown-person-count | Number | Total number of unknown persons that are at home | +| security | unknown-person-picture | Image | Snapshot of unknown person that is at home | All these channels are read only. - **Supported trigger channels for the Home thing:** -| Channel Type ID | Options | Description | -|------------------|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| cameraEvent | | A camera event is triggered with a short delay but without requiring a webhook. The information of the event can get retrieved from the other "welcomeEvent" home thing channels | -| | HUMAN | Triggered when a human (or person) was detected | -| | ANIMAL | Triggered when an animal was detected | -| | MOVEMENT | Triggered when an unspecified movement was detected | -| | VEHICLE | Triggered when a vehicle was detected | -| welcomeHomeEvent | | A welcome home event is triggered directly via a configured webhook | -| | PERSON | Triggered when a concrete person was detected | -| | PERSON_AWAY | Triggered when a concrete person leaves | -| | MOVEMENT | Triggered when a movement was detected | -| | CONNECTION | Triggered when a camera connection gets created | -| | DISCONNECTION | Triggered when a camera connection got lost | -| | ON | Triggered when camera monitoring is switched on | -| | OFF | Triggered when camera monitoring is switched off | -| | BOOT | Triggered when a camera is booting | -| | SD | Triggered when a camera SD card status was changed | -| | ALIM | Triggered when a power supply status was changed | -| | NEW_MODULE | Triggered when a new module was discovered | -| | MODULE_CONNECT | Triggered when a module gets connected | -| | MODULE_DISCONNECT | Triggered when a module gets disconnected | -| | MODULE_LOW_BATTERY | Triggered when the battery of a module gets low | -| | MODULE_END_UPDATE | Triggered when a firmware update of a module is done | -| | TAG_BIG_MOVE | Triggered when a big movement of a tag was detected | -| | TAG_SMALL_MOVE | Triggered when a small movement of a tag was detected | -| | TAG_UNINSTALLED | Triggered when a tag gets uninstalled | -| | TAG_OPEN | Triggered when an open event of a tag was detected | +| Channel Type ID | Options | Description | +| ---------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| cameraEvent | | A camera event is triggered with a short delay but without requiring a webhook. The information of the event can get retrieved from the other "welcomeEvent" home thing channels | +| | HUMAN | Triggered when a human (or person) was detected | +| | ANIMAL | Triggered when an animal was detected | +| | MOVEMENT | Triggered when an unspecified movement was detected | +| | VEHICLE | Triggered when a vehicle was detected | +| welcomeHomeEvent | | A welcome home event is triggered directly via a configured webhook | +| | PERSON | Triggered when a concrete person was detected | +| | PERSON_AWAY | Triggered when a concrete person leaves | +| | MOVEMENT | Triggered when a movement was detected | +| | CONNECTION | Triggered when a camera connection gets created | +| | DISCONNECTION | Triggered when a camera connection got lost | +| | ON | Triggered when camera monitoring is switched on | +| | OFF | Triggered when camera monitoring is switched off | +| | BOOT | Triggered when a camera is booting | +| | SD | Triggered when a camera SD card status was changed | +| | ALIM | Triggered when a power supply status was changed | +| | NEW_MODULE | Triggered when a new module was discovered | +| | MODULE_CONNECT | Triggered when a module gets connected | +| | MODULE_DISCONNECT | Triggered when a module gets disconnected | +| | MODULE_LOW_BATTERY | Triggered when the battery of a module gets low | +| | MODULE_END_UPDATE | Triggered when a firmware update of a module is done | +| | TAG_BIG_MOVE | Triggered when a big movement of a tag was detected | +| | TAG_SMALL_MOVE | Triggered when a small movement of a tag was detected | +| | TAG_UNINSTALLED | Triggered when a tag gets uninstalled | +| | TAG_OPEN | Triggered when an open event of a tag was detected | ### Welcome, Presence and Doorbell Cameras @@ -522,28 +494,28 @@ Warnings: **Supported channels for the Welcome Camera thing:** -| Channel Group | Channel ID | Item Type | Read/Write | Description | -|----------------|----------------------|--------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------| -| status | monitoring | Switch | Read-write | State of the camera (video surveillance on/off) | -| status | sd-card | String | Read-only | State of the SD card | -| status | alim | String | Read-only | State of the power connector | -| live | picture | Image | Read-only | Camera Live Snapshot | -| live | local-picture-url | String | Read-only | Local Url of the live snapshot for this camera | -| live | vpn-picture-url | String | Read-only | Url of the live snapshot for this camera through Netatmo VPN. | -| live | local-stream-url (*) | String | Read-only | Local Url of the live stream for this camera (accessible if openhab server and camera are located on the same lan. | -| live | vpn-stream-url (*) | String | Read-only | Url of the live stream for this camera through Netatmo VPN. | -| signal | strength | Number | Read-only | Signal strength (0 for no signal, 1 for weak...) | -| signal | value | Number:Power | Read-only | Signal strength in dBm | -| last-event | type | String | Read-only | Type of event | -| last-event | subtype | String | Read-only | Sub-type of event | -| last-event | time | DateTime | Read-only | Time of occurrence of event | -| last-event | message | String | Read-only | Message sent by Netatmo corresponding to given event | -| last-event | snapshot | Image | Read-only | picture of the last event, if it applies | -| last-event | snapshot-url | String | Read-only | If the last event (depending upon event type) in the home lead a snapshot picture, the picture URL will be available here | -| last-event | local-video-url | String | Read-only | If the last event (depending upon event type) in the home lead a snapshot picture, the corresponding local video URL will be available here | -| last-event | vpn-video-url | String | Read-only | If the last event (depending upon event type) in the home lead a snapshot picture, the corresponding VPN video URL will be available here | -| last-event | video-status | String | Read-only | Status of the video (recording, deleted or available) | -| last-event | person-id | String | Read-only | Id of the person the event is about (if any) | +| Channel Group | Channel ID | Item Type | Read/Write | Description | +| ------------- | -------------------- | ------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| status | monitoring | Switch | Read-write | State of the camera (video surveillance on/off) | +| status | sd-card | String | Read-only | State of the SD card | +| status | alim | String | Read-only | State of the power connector | +| live | picture | Image | Read-only | Camera Live Snapshot | +| live | local-picture-url | String | Read-only | Local Url of the live snapshot for this camera | +| live | vpn-picture-url | String | Read-only | Url of the live snapshot for this camera through Netatmo VPN. | +| live | local-stream-url (*) | String | Read-only | Local Url of the live stream for this camera (accessible if openhab server and camera are located on the same lan. | +| live | vpn-stream-url (*) | String | Read-only | Url of the live stream for this camera through Netatmo VPN. | +| signal | strength | Number | Read-only | Signal strength (0 for no signal, 1 for weak...) | +| signal | value | Number:Power | Read-only | Signal strength in dBm | +| last-event | type | String | Read-only | Type of event | +| last-event | subtype | String | Read-only | Sub-type of event | +| last-event | time | DateTime | Read-only | Time of occurrence of event | +| last-event | message | String | Read-only | Message sent by Netatmo corresponding to given event | +| last-event | snapshot | Image | Read-only | picture of the last event, if it applies | +| last-event | snapshot-url | String | Read-only | If the last event (depending upon event type) in the home lead a snapshot picture, the picture URL will be available here | +| last-event | local-video-url | String | Read-only | If the last event (depending upon event type) in the home lead a snapshot picture, the corresponding local video URL will be available here | +| last-event | vpn-video-url | String | Read-only | If the last event (depending upon event type) in the home lead a snapshot picture, the corresponding VPN video URL will be available here | +| last-event | video-status | String | Read-only | Status of the video (recording, deleted or available) | +| last-event | person-id | String | Read-only | Id of the person the event is about (if any) | (*) This channel is configurable : low, poor, high. @@ -553,35 +525,35 @@ Warnings: - The floodlight auto-mode (auto-mode) isn't updated it is changed by another application. Therefore the binding handles its own state of the auto-mode. This has the advantage that the user can define its own floodlight switch off behaviour. -| Channel Group | Channel ID | Item Type | Read/Write | Description | -|----------------|----------------------|--------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------| -| status | monitoring | Switch | Read-write | State of the camera (video surveillance on/off) | -| status | sd-card | String | Read-only | State of the SD card | -| status | alim | String | Read-only | State of the power connector | -| live | picture | Image | Read-only | Camera Live Snapshot | -| live | picture-url | String | Read-only | Url of the live snapshot for this camera | -| live | local-stream-url (*) | String | Read-only | Local Url of the live stream for this camera (accessible if openhab server and camera are located on the same lan. | -| live | vpn-stream-url (*) | String | Read-only | Url of the live stream for this camera through Netatmo VPN. | -| signal | strength | Number | Read-only | Signal strength (0 for no signal, 1 for weak...) | -| signal | value | Number:Power | Read-only | Signal strength in dBm | -| presence | floodlight | Switch | Read-write | Sets the floodlight to ON/OFF/AUTO | -| last-event | type | String | Read-only | Type of event | -| last-event | subtype | String | Read-only | Sub-type of event | -| last-event | time | DateTime | Read-only | Time of occurrence of event | -| last-event | message | String | Read-only | Message sent by Netatmo corresponding to given event | -| last-event | snapshot | Image | Read-only | picture of the last event, if it applies | -| last-event | snapshot-url | String | Read-only | if the last event (depending upon event type) in the home lead a snapshot picture, the picture URL will be available here | -| last-event | local-video-url | String | Read-only | If the last event (depending upon event type) in the home lead a snapshot picture, the corresponding local video URL will be available here | -| last-event | vpn-video-url | String | Read-only | If the last event (depending upon event type) in the home lead a snapshot picture, the corresponding VPN video URL will be available here | -| last-event | video-status | String | Read-only | Status of the video (recording, deleted or available) | -| last-event | person-id | String | Read-only | Id of the person the event is about (if any) | +| Channel Group | Channel ID | Item Type | Read/Write | Description | +| ------------- | -------------------- | ------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| status | monitoring | Switch | Read-write | State of the camera (video surveillance on/off) | +| status | sd-card | String | Read-only | State of the SD card | +| status | alim | String | Read-only | State of the power connector | +| live | picture | Image | Read-only | Camera Live Snapshot | +| live | picture-url | String | Read-only | Url of the live snapshot for this camera | +| live | local-stream-url (*) | String | Read-only | Local Url of the live stream for this camera (accessible if openhab server and camera are located on the same lan. | +| live | vpn-stream-url (*) | String | Read-only | Url of the live stream for this camera through Netatmo VPN. | +| signal | strength | Number | Read-only | Signal strength (0 for no signal, 1 for weak...) | +| signal | value | Number:Power | Read-only | Signal strength in dBm | +| presence | floodlight | Switch | Read-write | Sets the floodlight to ON/OFF/AUTO | +| last-event | type | String | Read-only | Type of event | +| last-event | subtype | String | Read-only | Sub-type of event | +| last-event | time | DateTime | Read-only | Time of occurrence of event | +| last-event | message | String | Read-only | Message sent by Netatmo corresponding to given event | +| last-event | snapshot | Image | Read-only | picture of the last event, if it applies | +| last-event | snapshot-url | String | Read-only | if the last event (depending upon event type) in the home lead a snapshot picture, the picture URL will be available here | +| last-event | local-video-url | String | Read-only | If the last event (depending upon event type) in the home lead a snapshot picture, the corresponding local video URL will be available here | +| last-event | vpn-video-url | String | Read-only | If the last event (depending upon event type) in the home lead a snapshot picture, the corresponding VPN video URL will be available here | +| last-event | video-status | String | Read-only | Status of the video (recording, deleted or available) | +| last-event | person-id | String | Read-only | Id of the person the event is about (if any) | (*) This channel is configurable : low, poor, high. **Supported channels for the Doorbell thing:** | Channel Group | Channel ID | Item Type | Read/Write | Description | -|---------------|-------------------|--------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------| +| ------------- | ----------------- | ------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | status | sd-card | String | Read-only | State of the SD card | | status | alim | String | Read-only | State of the power connector | | live | picture | Image | Read-only | Camera Live Snapshot | @@ -602,46 +574,44 @@ Warnings: | sub-event | snapshot | Image | Read-only | picture of the snapshot | | sub-event | vignet | Image | Read-only | picture of the vignette | - Note: live feeds either locally or via VPN are not available in Netatmo API. **Supported channels for the Siren thing:** -| Channel Group | Channel ID | Item Type | Read/Write | Description | -|---------------|-------------------|--------------|------------|------------------------------------------------------| -| siren | status | String | Read-only | Status of the siren, if silent or emitting an alarm | -| siren | monitoring | Switch | Read-only | State of the siren device | -| signal | strength | Number | Read-only | Signal strength (0 for no signal, 1 for weak...) | -| signal | value | Number:Power | Read-only | Signal strength in dBm | -| timestamp | last-seen | DateTime | Read-only | Last time the module reported its presence | -| battery | value | Number | Read-only | Battery level | -| battery | low-battery | Switch | Read-only | Low battery | - +| Channel Group | Channel ID | Item Type | Read/Write | Description | +| ------------- | ----------- | ------------ | ---------- | --------------------------------------------------- | +| siren | status | String | Read-only | Status of the siren, if silent or emitting an alarm | +| siren | monitoring | Switch | Read-only | State of the siren device | +| signal | strength | Number | Read-only | Signal strength (0 for no signal, 1 for weak...) | +| signal | value | Number:Power | Read-only | Signal strength in dBm | +| timestamp | last-seen | DateTime | Read-only | Last time the module reported its presence | +| battery | value | Number | Read-only | Battery level | +| battery | low-battery | Switch | Read-only | Low battery | **Supported channels for the Door Tag thing:** -| Channel Group | Channel ID | Item Type | Read/Write | Description | -|---------------|-------------------|--------------|------------|------------------------------------------------------| -| tag | status | Contact | Read-only | Status of tag (OPEN,CLOSED) | -| signal | strength | Number | Read-only | Signal strength (0 for no signal, 1 for weak...) | -| signal | value | Number:Power | Read-only | Signal strength in dBm | -| timestamp | last-seen | DateTime | Read-only | Last time the module reported its presence | -| battery | value | Number | Read-only | Battery level | -| battery | low-battery | Switch | Read-only | Low battery | +| Channel Group | Channel ID | Item Type | Read/Write | Description | +| ------------- | ----------- | ------------ | ---------- | ------------------------------------------------ | +| tag | status | Contact | Read-only | Status of tag (OPEN,CLOSED) | +| signal | strength | Number | Read-only | Signal strength (0 for no signal, 1 for weak...) | +| signal | value | Number:Power | Read-only | Signal strength in dBm | +| timestamp | last-seen | DateTime | Read-only | Last time the module reported its presence | +| battery | value | Number | Read-only | Battery level | +| battery | low-battery | Switch | Read-only | Low battery | ### Welcome Person Netatmo API distinguishes two kinds of persons: -* Known persons : have been identified by the camera and you have defined a name for those. -* Unknown persons : identified by the camera, but no name defined. +- Known persons : have been identified by the camera and you have defined a name for those. +- Unknown persons : identified by the camera, but no name defined. Person things are automatically created in discovery process for all known persons. **Supported channels for the Person thing:** | Channel Group | Channel ID | Item Type | Description | -|---------------|--------------|-----------|--------------------------------------------------------| +| ------------- | ------------ | --------- | ------------------------------------------------------ | | person | avatar-url | String | URL for the avatar of this person | | person | avatar | Image | Avatar of this person | | person | at-home | Switch | Indicates if this person is known to be at home or not | @@ -655,29 +625,27 @@ Person things are automatically created in discovery process for all known perso All these channels except at-home are read only. - ### Netatmo Smart Smoke Detector All these channels are read only. **Supported channels for the Smoke Detector thing:** -| Channel Group | Channel Id | Item Type | Description | -|---------------|--------------|--------------|--------------------------------------------------| -| signal | strength | Number | Signal strength (0 for no signal, 1 for weak...) | -| signal | value | Number:Power | Signal strength in dBm | -| timestamp | last-seen | DateTime | Last time the module reported its presence | -| last-event | type | String | Type of event | -| last-event | time | DateTime | Moment of the last event for this person | -| last-event | subtype | String | Sub-type of event | -| last-event | message | String | Last event message from this person | +| Channel Group | Channel Id | Item Type | Description | +| ------------- | ---------- | ------------ | ------------------------------------------------ | +| signal | strength | Number | Signal strength (0 for no signal, 1 for weak...) | +| signal | value | Number:Power | Signal strength in dBm | +| timestamp | last-seen | DateTime | Last time the module reported its presence | +| last-event | type | String | Type of event | +| last-event | time | DateTime | Moment of the last event for this person | +| last-event | subtype | String | Sub-type of event | +| last-event | message | String | Last event message from this person | ## Configuration Examples - ### things/netatmo.things -``` +```java Bridge netatmo:account:myaccount "Netatmo Account" [clientId="xxxxx", clientSecret="yyyy", refreshToken="zzzzz"] { Bridge weather-station inside "Inside Weather Station" [id="70:ee:aa:aa:aa:aa"] { outdoor outside "Outside Module" [id="02:00:00:aa:aa:aa"] { @@ -707,10 +675,9 @@ Bridge netatmo:account:myaccount "Netatmo Account" [clientId="xxxxx", clientSecr } ``` - ### items/netatmo.items -``` +```java // Indoor Module Number:Temperature Indoor_Temp "Temperature [%.1f %unit%]" { channel = "netatmo:weather-station:myaccount:inside:temperature#value" } Number:Temperature Indoor_Min_Temp "Min Temperature Today [%.1f %unit%]" { channel = "netatmo:weather-station:myaccount:inside:temperature#min-today" } @@ -766,7 +733,7 @@ String CameraEventPersonId "Person Id [%s]" ### sitemaps/netatmo.sitemap -``` +```perl sitemap netatmo label="Netatmo" { Frame label="Indoor" { Text item=Indoor_Temp @@ -845,7 +812,7 @@ Multiple actions are supported by this binding. In classic rules these are acces Example -``` +```java val actions = getActions("netatmo","netatmo:room:myaccount:myhome:livingroom") if(null === actions) { logInfo("actions", "Actions not found, check thing ID") @@ -859,14 +826,14 @@ Sends a temperature setpoint (and switch to manual mode) to the thermostat for a Parameters: -| Name | Description | -|---------|----------------------------------------------------------------------| -| temp | The temperature setpoint. | -| endtime | Time the setpoint should end (Local Unix time in seconds). | +| Name | Description | +| ------- | ---------------------------------------------------------- | +| temp | The temperature setpoint. | +| endtime | Time the setpoint should end (Local Unix time in seconds). | Example: -``` +```java actions.setThermRoomTempSetpoint(19.0, 1654387205) ``` @@ -876,14 +843,14 @@ Sends a mode to the thermostat for a room with an optional end time. Parameters: -| Name | Description | -|---------|----------------------------------------------------------------------| -| mode | The mode to set: MANUAL, MAX or HOME. | -| endtime | Time the setpoint should end (Local Unix time in seconds). | +| Name | Description | +| ------- | ---------------------------------------------------------- | +| mode | The mode to set: MANUAL, MAX or HOME. | +| endtime | Time the setpoint should end (Local Unix time in seconds). | Example: -``` +```java actions.setThermRoomModeSetpoint("MANUAL", 1654387205) actions.setThermRoomModeSetpoint("HOME", null) ``` @@ -893,42 +860,35 @@ actions.setThermRoomModeSetpoint("HOME", null) If you want to evaluate this binding but have not got a Netatmo station yourself yet, you can search on the web for a publicly shared weather station. - ## Icons The following icons are used by original Netatmo web app: - ### Modules -- https://my.netatmo.com/images/my/app/module_int.png -- https://my.netatmo.com/images/my/app/module_ext.png -- https://my.netatmo.com/images/my/app/module_rain.png - +- `https://my.netatmo.com/images/my/app/module_int.png` +- `https://my.netatmo.com/images/my/app/module_ext.png` +- `https://my.netatmo.com/images/my/app/module_rain.png` ### Battery status -- https://my.netatmo.com/images/my/app/battery_verylow.png -- https://my.netatmo.com/images/my/app/battery_low.png -- https://my.netatmo.com/images/my/app/battery_medium.png -- https://my.netatmo.com/images/my/app/battery_high.png -- https://my.netatmo.com/images/my/app/battery_full.png - +- `https://my.netatmo.com/images/my/app/battery_verylow.png` +- `https://my.netatmo.com/images/my/app/battery_low.png` +- `https://my.netatmo.com/images/my/app/battery_medium.png` +- `https://my.netatmo.com/images/my/app/battery_high.png` +- `https://my.netatmo.com/images/my/app/battery_full.png` ### Signal status -- https://my.netatmo.com/images/my/app/signal_verylow.png -- https://my.netatmo.com/images/my/app/signal_low.png -- https://my.netatmo.com/images/my/app/signal_medium.png -- https://my.netatmo.com/images/my/app/signal_high.png -- https://my.netatmo.com/images/my/app/signal_full.png - +- `https://my.netatmo.com/images/my/app/signal_verylow.png` +- `https://my.netatmo.com/images/my/app/signal_low.png` +- `https://my.netatmo.com/images/my/app/signal_medium.png` +- `https://my.netatmo.com/images/my/app/signal_high.png` +- `https://my.netatmo.com/images/my/app/signal_full.png` ### Wifi status -- https://my.netatmo.com/images/my/app/wifi_low.png -- https://my.netatmo.com/images/my/app/wifi_medium.png -- https://my.netatmo.com/images/my/app/wifi_high.png -- https://my.netatmo.com/images/my/app/wifi_full.png - - +- `https://my.netatmo.com/images/my/app/wifi_low.png` +- `https://my.netatmo.com/images/my/app/wifi_medium.png` +- `https://my.netatmo.com/images/my/app/wifi_high.png` +- `https://my.netatmo.com/images/my/app/wifi_full.png` diff --git a/bundles/org.openhab.binding.network/README.md b/bundles/org.openhab.binding.network/README.md index 71c6ac9c998dc..7598735f98bbd 100644 --- a/bundles/org.openhab.binding.network/README.md +++ b/bundles/org.openhab.binding.network/README.md @@ -9,15 +9,15 @@ It is also capable to perform bandwidth speed tests. The binding has the following configuration options: -- **allowSystemPings:** Use the external ICMP ping program of the operating system instead of the Java ping. Useful if the devices cannot be reached by Java ping. Default is true. -- **allowDHCPlisten:** If devices leave and reenter a network, they usually request their last IPv4 address by using DHCP requests. By listening for those messages, the status update can be more "real-time" without having to wait for the next refresh cycle. Default is true. -- **arpPingToolPath:** If the arp ping tool is not called `arping` and cannot be found in the PATH environment variable, the absolute path can be configured here. Default is `arping`. -- **cacheDeviceStateTimeInMS:** The result of a device presence detection is cached for a small amount of time. Set this time here in milliseconds. Be aware that no new pings will be issued within this time frame, even if explicitly requested. Default is 2000. -- **preferResponseTimeAsLatency:** If enabled, an attempt will be made to extract the latency from the output of the ping command. If no such latency value is found in the ping command output, the time to execute the ping command is used as fallback latency. If disabled, the time to execute the ping command is always used as latency value. This is disabled by default to be backwards-compatible and to not break statistics and monitoring which existed before this feature. +- **allowSystemPings:** Use the external ICMP ping program of the operating system instead of the Java ping. Useful if the devices cannot be reached by Java ping. Default is true. +- **allowDHCPlisten:** If devices leave and reenter a network, they usually request their last IPv4 address by using DHCP requests. By listening for those messages, the status update can be more "real-time" without having to wait for the next refresh cycle. Default is true. +- **arpPingToolPath:** If the arp ping tool is not called `arping` and cannot be found in the PATH environment variable, the absolute path can be configured here. Default is `arping`. +- **cacheDeviceStateTimeInMS:** The result of a device presence detection is cached for a small amount of time. Set this time here in milliseconds. Be aware that no new pings will be issued within this time frame, even if explicitly requested. Default is 2000. +- **preferResponseTimeAsLatency:** If enabled, an attempt will be made to extract the latency from the output of the ping command. If no such latency value is found in the ping command output, the time to execute the ping command is used as fallback latency. If disabled, the time to execute the ping command is always used as latency value. This is disabled by default to be backwards-compatible and to not break statistics and monitoring which existed before this feature. Create a `/services/network.cfg` file and use the above options like this: -``` +```text binding.network:allowSystemPings=true binding.network:allowDHCPlisten=false binding.network:arpPingToolPath=arping @@ -26,9 +26,9 @@ binding.network:cacheDeviceStateTimeInMS=2000 ## Supported Things -- **pingdevice:** Detects device presence by using ICMP pings, arp pings and dhcp packet sniffing. -- **servicedevice:** Detects device presence by scanning for a specific open tcp port. -- **speedtest:** Monitors available bandwidth for upload and download. +- **pingdevice:** Detects device presence by using ICMP pings, arp pings and dhcp packet sniffing. +- **servicedevice:** Detects device presence by scanning for a specific open tcp port. +- **speedtest:** Monitors available bandwidth for upload and download. ## Discovery @@ -39,7 +39,7 @@ Please note: things discovered by the network binding will be provided with a ti ## Thing Configuration -``` +```java network:pingdevice:one_device [ hostname="192.168.0.64" ] network:pingdevice:second_device [ hostname="192.168.0.65", macAddress="6f:70:65:6e:48:41", retry=1, timeout=5000, refreshInterval=60000 ] network:servicedevice:important_server [ hostname="192.168.0.62", port=1234 ] @@ -48,24 +48,24 @@ network:speedtest:local "SpeedTest 50Mo" @ "Internet" [refreshInterval=20, uploa Use the following options for a **network:pingdevice**: -- **hostname:** IP address or hostname of the device. -- **macAddress:** MAC address used for waking the device by the Wake-on-LAN action. -- **retry:** After how many refresh interval cycles the device will be assumed to be offline. Default: `1`. -- **timeout:** How long the ping will wait for an answer, in milliseconds. Default: `5000` (5 seconds). -- **refreshInterval:** How often the device will be checked, in milliseconds. Default: `60000` (one minute). +- **hostname:** IP address or hostname of the device. +- **macAddress:** MAC address used for waking the device by the Wake-on-LAN action. +- **retry:** After how many refresh interval cycles the device will be assumed to be offline. Default: `1`. +- **timeout:** How long the ping will wait for an answer, in milliseconds. Default: `5000` (5 seconds). +- **refreshInterval:** How often the device will be checked, in milliseconds. Default: `60000` (one minute). Use the following additional options for a **network:servicedevice**: -- **port:** Must not be 0. The destination port needs to be a TCP service. +- **port:** Must not be 0. The destination port needs to be a TCP service. Use the following options for a **network:speedtest**: -- **refreshInterval:** Interval between each test execution, in minutes. Default: `20`. -- **uploadSize:** Size of the file to be uploaded in bytes. Default: `1000000`. -- **url:** Url of the speed test server. -- **fileName:** Name of the file to download from test server. -- **initialDelay:** Delay (in minutes) before starting the first speed test (can help avoid flooding your server at startup). Default: `5`. -- **maxTimeout:** Number of timeout events that can happend (resetted at success) before setting the thing offline. Default: `3`. +- **refreshInterval:** Interval between each test execution, in minutes. Default: `20`. +- **uploadSize:** Size of the file to be uploaded in bytes. Default: `1000000`. +- **url:** Url of the speed test server. +- **fileName:** Name of the file to download from test server. +- **initialDelay:** Delay (in minutes) before starting the first speed test (can help avoid flooding your server at startup). Default: `5`. +- **maxTimeout:** Number of timeout events that can happend (resetted at success) before setting the thing offline. Default: `3`. ## Presence detection - Configure target device @@ -89,15 +89,15 @@ Use DHCP listen for an almost immediate presence detection for phones and tablet Apple iOS devices are usually in a deep sleep mode and do not respond to ARP pings under all conditions, but to Bonjour service discovery messages (UDP port 5353). Therefore first a Bonjour message is sent, before the ARP presence detection is performed. The binding automatically figures out if the target device is an iOS device. -To check if the binding has correctly recognised a device, have a look at the *uses_ios_wakeup* property of the THING. +To check if the binding has correctly recognised a device, have a look at the _uses_ios_wakeup_ property of the THING. ### Use open TCP ports Many devices provide services on TCP ports (web-frontends, streaming servers, etc.), which can be used to confirm their presence in the network. Most operating systems have options to list open ports. -On a Linux-based system, *nmap* may be used to discover all open TCP ports on the device with the specified IP address: +On a Linux-based system, _nmap_ may be used to discover all open TCP ports on the device with the specified IP address: -``` +```shell $ sudo nmap -Pn -sT -p- 192.168.0.42 Starting Nmap 6.47 ( http://nmap.org ) at 2016-07-31 20:00 CEST @@ -128,10 +128,10 @@ Because external tools are used for some of the presence detection mechanism or For arp pings to work, a separate tool called "arping" is used. Linux has three different tools: -* arp-scan (not yet supported by this binding) -* arping of the ip-utils (Ubuntu/Debian: `apt-get install iputils-arping`) -* arping by Thomas Habets (Ubuntu/Debian: `apt-get install arping`) -* arp-ping by Eli Fulkerson (Windows: https://www.elifulkerson.com/projects/arp-ping.php) +- arp-scan (not yet supported by this binding) +- arping of the ip-utils (Ubuntu/Debian: `apt-get install iputils-arping`) +- arping by Thomas Habets (Ubuntu/Debian: `apt-get install arping`) +- arp-ping by Eli Fulkerson (Windows: ) arping by Thomas Habets runs on Windows and macOS as well. @@ -144,7 +144,7 @@ Just test the executable on the command line; if `sudo` is required, grant eleva Some operating systems such as Linux restrict applications to only use ports >= 1024 without elevated privileges. If the binding is not able to use port 67 (DHCP) because of such a restriction, or because the same system is used as a DHCP server, port 6767 will be used instead. -Check the property *dhcp_state* on the THING for such a hint. In this case, establish port forwarding: +Check the property _dhcp_state_ on the THING for such a hint. In this case, establish port forwarding: ```shell sysctl -w net.ipv4.ip_forward=1 @@ -159,7 +159,7 @@ iptables -A PREROUTING -t mangle -p udp ! -s 127.0.0.1 --dport 67 -j TEE --gatew iptables -A OUTPUT -t nat -p udp -s 127.0.0.1/32 --dport 67 -j DNAT --to 127.0.0.1:6767 ``` -Above iptables solutions to check *dhcp_state* are not working when openHAB is started in Docker. Use another workaround +Above iptables solutions to check _dhcp_state_ are not working when openHAB is started in Docker. Use another workaround ```shell iptables -I PREROUTING -t nat -p udp --src 0.0.0.0 --dport 67 -j DNAT --to 0.0.0.0:6767 @@ -185,14 +185,14 @@ Things support the following channels: demo.things: -```xtend +```java Thing network:pingdevice:devicename [ hostname="192.168.0.42", macAddress="6f:70:65:6e:48:41" ] Thing network:speedtest:local "SpeedTest 50Mo" @ "Internet" [url="https://bouygues.testdebit.info/", fileName="50M.iso"] ``` demo.items: -```xtend +```java Switch MyDevice { channel="network:pingdevice:devicename:online" } Number:Time MyDeviceResponseTime { channel="network:pingdevice:devicename:latency" } @@ -207,13 +207,14 @@ DateTime Speedtest_LUD "Timestamp [%1$tH:%1$tM]"