diff --git a/bundles/org.openhab.binding.adorne/README.md b/bundles/org.openhab.binding.adorne/README.md index 48d70e5cee7..944e1ce90fe 100644 --- a/bundles/org.openhab.binding.adorne/README.md +++ b/bundles/org.openhab.binding.adorne/README.md @@ -1,4 +1,4 @@ -# Adorne Binding +# Adorne Binding The Adorne Binding integrates [Adorne Wi-Fi ready devices](https://www.legrand.us/adorne/products/wireless-whole-house-lighting-controls.aspx) (switches, dimmers, outlets) from [Legrand](https://legrand.com/). @@ -20,8 +20,8 @@ This binding's implementation of the REST API is motivated by the great work of ## Discovery -Auto-discovery is supported as long as the hub can be discovered using the default host and port. -If the hub requires custom host and/or port configuration manual setup is required. +Auto-discovery is supported as long as the hub can be discovered using the default host and port. +If the hub requires custom host and/or port configuration manual setup is required. Background discovery is not supported. @@ -44,7 +44,7 @@ All devices share one required paramenter: Legrand does not provide an easy way to look up a zone ID for a device. However, zone IDs are simply assigned sequentially starting with 0 in the order devices are added to the hub. -So the first device will have zone ID 0, the next 1 and so on. +So the first device will have zone ID 0, the next 1 and so on. ## Channels @@ -60,10 +60,10 @@ Also, if a dimmer is turned off (via the power channel) and the brightness is up Once the dimmer is turned on it will turn on with the updated brightness setting. Consequently when a dimmer is turned on it always returns to the most recent brightness setting. In other words power and brightness states are controlled independently. -This matches how power and brightness are managed on the physical dimmer itself. +This matches how power and brightness are managed on the physical dimmer itself. To avoid confusion for the user any UI must ensure that only values from 1 to 100 are passed to the brightness channel. -A default slider allows a 0 value and should not be used since there will be no response when the user selects 0. +A default slider allows a 0 value and should not be used since there will be no response when the user selects 0. Common UI choices are Sliders or Setpoints with a minimum value of 1 and a maximum value of 100 (min/max values in Sliders are only supported as of openHAB 2.5). ## Example @@ -71,21 +71,21 @@ Common UI choices are Sliders or Setpoints with a minimum value of 1 and a maxim This is a simple example that uses an Adorne switch and two dimmers. Remember that the host and port parameter are not needed in most cases. As discussed above care is taken that the brightness channel only allows values from 1 to 100 by specifying a min and max value in the sitemap for the dimmers. -For this example to run on an openHAB version older than 2.5 Bedroom 1's Slider must be removed in the sitemap since older versions don't support the min/max setting. +For this example to run on an openHAB version older than 2.5 Bedroom 1's Slider must be removed in the sitemap since older versions don't support the min/max setting. ## demo.things -``` +```java Bridge adorne:hub:home "Adorne Hub" [host="192.160.1.111", port=2113] { - switch bathroom "Bathroom" [zoneId=0] - dimmer bedroom1 "Bedroom1" [zoneId=1] - dimmer bedroom2 "Bedroom2" [zoneId=2] + switch bathroom "Bathroom" [zoneId=0] + dimmer bedroom1 "Bedroom1" [zoneId=1] + dimmer bedroom2 "Bedroom2" [zoneId=2] } ``` ## demo.items -``` +```java Switch LightBathroom {channel="adorne:switch:home:bathroom:power"} Switch LightBedroomSwitch1 {channel="adorne:dimmer:home:bedroom1:power"} Dimmer LightBedroomDimmer1 {channel="adorne:dimmer:home:bedroom1:brightness"} @@ -95,19 +95,19 @@ Dimmer LightBedroomDimmer2 {channel="adorne:dimmer:home:bedroom2:brightness"} ## demo.sitemap -``` +```perl sitemap demo label="Adorne Binding Demo" { - Frame label="Adorne Switch" { - Switch item=LightBathroom label="Bathroom" mappings=["ON"="On", "OFF"="Off"] icon="light-on" - } - Frame label="Adorne Dimmer using Slider" { - Switch item=LightBedroomSwitch1 label="Bedroom 1" mappings=["ON"="On", "OFF"="Off"] icon="light-on" - Slider item=LightBedroomDimmer1 label="Bedroom 1" icon="light-on" minValue=1 maxValue=100 step=1 - } - Frame label="Adorne Dimmer using Setpoint" { - Switch item=LightBedroomSwitch2 label="Bedroom 2" mappings=["ON"="On", "OFF"="Off"] icon="light-on" - Setpoint item=LightBedroomDimmer2 label="Bedroom 2" icon="light-on" minValue=1 maxValue=100 step=5 - } + Frame label="Adorne Switch" { + Switch item=LightBathroom label="Bathroom" mappings=["ON"="On", "OFF"="Off"] icon="light-on" + } + Frame label="Adorne Dimmer using Slider" { + Switch item=LightBedroomSwitch1 label="Bedroom 1" mappings=["ON"="On", "OFF"="Off"] icon="light-on" + Slider item=LightBedroomDimmer1 label="Bedroom 1" icon="light-on" minValue=1 maxValue=100 step=1 + } + Frame label="Adorne Dimmer using Setpoint" { + Switch item=LightBedroomSwitch2 label="Bedroom 2" mappings=["ON"="On", "OFF"="Off"] icon="light-on" + Setpoint item=LightBedroomDimmer2 label="Bedroom 2" icon="light-on" minValue=1 maxValue=100 step=5 + } } ``` diff --git a/bundles/org.openhab.binding.ahawastecollection/README.md b/bundles/org.openhab.binding.ahawastecollection/README.md index 504884a6682..89f44ff3872 100644 --- a/bundles/org.openhab.binding.ahawastecollection/README.md +++ b/bundles/org.openhab.binding.ahawastecollection/README.md @@ -4,7 +4,7 @@ This binding provides information about the upcoming waste collection dates for ## Supported Things -- **collectionSchedule:** Represents the connection to the **aha Waste Collection Schedule** with four channels for the different waste types. +- **collectionSchedule:** Represents the connection to the **aha Waste Collection Schedule** with four channels for the different waste types. ## Discovery @@ -14,21 +14,20 @@ Discovery is not possible, due some form input values from the website above are For configuration of the **collectionSchedule** thing, you need the form inputs from the aha collections schedule web page. Follow the steps below to get the required configuration parameters from the form input values. - 1. Open [aha Abfuhrkalender](https://www.aha-region.de/abholtermine/abfuhrkalender) in your favorite brower with developer-console. -2. Open the developer console and switch to network tab (for example press F12 in chrome / edge / firefox). -3. Fill in the form: Select your commune, Street and house number and hit "Suchen". -4. Select the first request to https://www.aha-region.de/abholtermine/abfuhrkalender (see first screenshot below) -5. Check the form data at the end of the request for the form values (see second screenshot below) -5. Fill in the values from the form input in thing configuration (see examples below) +1. Open the developer console and switch to network tab (for example press F12 in chrome / edge / firefox). +1. Fill in the form: Select your commune, Street and house number and hit "Suchen". +1. Select the first request to [https://www.aha-region.de/abholtermine/abfuhrkalender](https://www.aha-region.de/abholtermine/abfuhrkalender) (see first screenshot below) +1. Check the form data at the end of the request for the form values (see second screenshot below) +1. Fill in the values from the form input in thing configuration (see examples below) ![Chrome Developer Console Top](doc/images/ChromeDevconsoleTop.png "Chrome Developer Console showing request URL") -*Check if you've selected the correct request, that contains the form data* +Check if you've selected the correct request, that contains the form data ![Chrome Developer Console Bottom](doc/images/ChromeDevconsoleBottom.png "Chrome Developer Console showing form inputs") -*Grab the values for the configuration parameters from the form data section at the end of the request* +Grab the values for the configuration parameters from the form data section at the end of the request **collectionSchedule** parameters: @@ -44,7 +43,6 @@ For configuration of the **collectionSchedule** thing, you need the form inputs The thing **aha Waste Collection Schedule** provides four channels for the upcoming day of waste collection for the different waste types. - | channel | type | description | |----------|--------|------------------------------| | generalWaste | DateTime | Next collection day for general waste | @@ -52,28 +50,26 @@ The thing **aha Waste Collection Schedule** provides four channels for the upcom | bioWaste | DateTime | Next collection day for bio waste | | paper | DateTime | Next collection day for paper | - ## Full Example wasteCollection.things -``` +```java Thing ahawastecollection:collectionSchedule:wasteCollectionSchedule "aha Abfuhrkalender" [ commune="Isernhagen", street="67269@Rosmarinweg+/+Kirchhorst@Kirchhorst", houseNumber="10", houseNumberAddon="", collectionPlace="67269-0010+" ] ``` wasteCollection.items -``` +```java DateTime collectionDay_generalWaste "Next general waste collection" {channel="ahawastecollection:collectionSchedule:wasteCollectionSchedule:generalWaste"} DateTime collectionDay_leightweightPackaging "Next lightweight packaging collection" {channel="ahawastecollection:collectionSchedule:wasteCollectionSchedule:leightweightPackaging"} DateTime collectionDay_bioWaste "Next bio waste collection" {channel="ahawastecollection:collectionSchedule:wasteCollectionSchedule:bioWaste"} DateTime collectionDay_paper "Next paper collection" {channel="ahawastecollection:collectionSchedule:wasteCollectionSchedule:paper"} ``` - Example for rule that sends a notification with collected waste types on day before collection -``` +```yaml triggers: - id: "1" configuration: diff --git a/bundles/org.openhab.binding.airq/README.md b/bundles/org.openhab.binding.airq/README.md index dd581d8146d..060b3398e1a 100644 --- a/bundles/org.openhab.binding.airq/README.md +++ b/bundles/org.openhab.binding.airq/README.md @@ -120,13 +120,13 @@ The rw column is empty if the channel is only readable, w if the channel can be ### air-Q.things -``` +```java Thing airq:airq:1 "air-Q" [ ipAddress="192.168.0.68", password="myAirQPassword" ] ``` ### air-Q.items -``` +```java String airQ_status "Status of Sensors" {channel="airq:airq:1:status"} Number:Length airQ_avgFineDustSize "Average Size of Fine Dust" {channel="airq:airq:1:avgFineDustSize"} Number:Dimensionless airQ_fineDustCnt00_3 "Fine Dust >0,3 µm" {channel="airq:airq:1:fineDustCnt00_3"} diff --git a/bundles/org.openhab.binding.airquality/README.md b/bundles/org.openhab.binding.airquality/README.md index 44195ac6ad5..9c47d92c682 100644 --- a/bundles/org.openhab.binding.airquality/README.md +++ b/bundles/org.openhab.binding.airquality/README.md @@ -24,13 +24,12 @@ You will created a Bridge with your apiKey. ## Bridge Configuration -The bridge configuration only holds the api key : +The bridge configuration only holds the api key : | Parameter | Description | |-----------|-------------------------------------------------------------------------| | apiKey | Data-platform token to access the AQIcn.org service. Mandatory. | - ## Thing Configuration The 'Station' thing has a few configuration parameters: @@ -51,7 +50,7 @@ For the location parameter, the following syntax is allowed (comma separated lat If you always want to receive data from specific station and you know its unique ID, you can enter it instead of the coordinates. This `stationId` can be found by using the following link: -https://api.waqi.info/search/?token=TOKEN&keyword=NAME, replacing TOKEN by your apiKey and NAME by the station you are looking for. +`https://api.waqi.info/search/?token=TOKEN&keyword=NAME`, replacing TOKEN by your apiKey and NAME by the station you are looking for. ### Thing properties @@ -61,7 +60,6 @@ Once created, at first execution, the station's properties will be filled with i - Measuring station ID - Latitude/longitude of measuring station - ## Channels The AirQuality information that is retrieved for a given is available as these channels: @@ -98,8 +96,7 @@ you will be provided with the following informations | index | Number | AQI Index of the single pollutant | | alert-level | Number | Alert level associate to the index | - -(*) The alert level is described by a color : +(*) The alert level is described by a color : | Code | Color | Description | |------|--------|--------------------------------| @@ -110,10 +107,8 @@ you will be provided with the following informations | 4 | Purple | Very Unhealthy | | 5 | Maroon | Hazardous | - ## Full Example - airquality.things: ```java diff --git a/bundles/org.openhab.binding.airvisualnode/README.md b/bundles/org.openhab.binding.airvisualnode/README.md index b8b750ddecf..4b51ce47aba 100644 --- a/bundles/org.openhab.binding.airvisualnode/README.md +++ b/bundles/org.openhab.binding.airvisualnode/README.md @@ -8,7 +8,7 @@ There is one supported Thing, the "avnode". ## Discovery -Binding will do autodiscovery for AirVisual Node by searching for a host advertised with the NetBIOS name 'AVISUAL-'. +Binding will do autodiscovery for AirVisual Node by searching for a host advertised with the NetBIOS name `AVISUAL-`. All discovered devices will be added to the inbox. Please note you will need to set the Node username and password in the configuration of the newly discovered thing before a connection can be made. @@ -56,7 +56,7 @@ The Node updates measurements data every 5 minutes in active mode and every 15 m The preferred way to add AirVisual Node to the openHAB installation is autodiscovery, but the AirVisual Node also can be configured using `.things` file: -``` +```java airvisualnode:avnode:1a2b3c4 [ address="192.168.1.32", username="airvisual", password="12345", share="airvisual", refresh=60 ] ``` @@ -64,7 +64,7 @@ airvisualnode:avnode:1a2b3c4 [ address="192.168.1.32", username="airvisual", pas Here is an example of items for the AirVisual Node: -``` +```java Number:Temperature Livingroom_Temperature "Temperature [%.1f %unit%]" {channel="airvisualnode:avnode:1a2b3c4:temperature"} Number:Dimensionless Livingroom_Humidity "Humidity [%d %unit%]" {channel="airvisualnode:avnode:1a2b3c4:humidity"} Number:Dimensionless Livingroom_CO2_Level "CO₂" {channel="airvisualnode:avnode:1a2b3c4:co2"} @@ -77,7 +77,7 @@ DateTime Livingroom_Aqi_Timestamp "AQI Timestamp [%1$tH:%1$tM]" { channel="airvi Example rules: -``` +```java rule "AirVisual Node Temperature Rule" when Item Livingroom_Temperature changed @@ -119,7 +119,7 @@ end Example sitemap: -``` +```perl sitemap home label="Home" { Frame label="Living Room" { Text item=Livingroom_Temperature diff --git a/bundles/org.openhab.binding.alarmdecoder/README.md b/bundles/org.openhab.binding.alarmdecoder/README.md index b899e0e6aeb..30d1aaf90d1 100644 --- a/bundles/org.openhab.binding.alarmdecoder/README.md +++ b/bundles/org.openhab.binding.alarmdecoder/README.md @@ -5,9 +5,9 @@ It acts essentially like a keypad, reading and writing messages on the serial bu There are several versions of the adapter available: -* *AD2PI* or *AD2PHAT* - A board that plugs into a Raspberry Pi and offers network-based TCP connectivity -* *AD2SERIAL* - Attaches to a host via a serial port -* *AD2USB* - Attaches to a host via USB +- _AD2PI_ or _AD2PHAT_ - A board that plugs into a Raspberry Pi and offers network-based TCP connectivity +- _AD2SERIAL_ - Attaches to a host via a serial port +- _AD2USB_ - Attaches to a host via USB This binding allows openHAB to access the state of wired or wireless contacts and motion detectors connected to supported alarm panels, as well as the state of attached keypads and the messages send to attached LRR devices. Support is also available for sending keypad commands, including special/programmable keys supported by your panel. @@ -16,19 +16,19 @@ Support is also available for sending keypad commands, including special/program The binding supports the following thing types: -* `ipbridge` - Supports TCP connection to the AD. -* `serialbridge` - Supports serial/USB connection to the AD. -* `keypad` - Reports keypad status and optionally sends keypad messages. -* `zone` - Reports status from zone expanders and relay expanders, and also from built-in zones via emulation. -* `rfzone` - Reports status from RF zones. -* `vzone` - Sends commands to virtual zones. -* `lrr` - Reports messages sent from the panel to a Long Range Radio (LRR) or emulated LRR device. +- `ipbridge` - Supports TCP connection to the AD. +- `serialbridge` - Supports serial/USB connection to the AD. +- `keypad` - Reports keypad status and optionally sends keypad messages. +- `zone` - Reports status from zone expanders and relay expanders, and also from built-in zones via emulation. +- `rfzone` - Reports status from RF zones. +- `vzone` - Sends commands to virtual zones. +- `lrr` - Reports messages sent from the panel to a Long Range Radio (LRR) or emulated LRR device. ## Discovery Background discovery is currently supported for `zone` and `rfzone` things. -If the bridge `discovery` parameter is set to *true*, the first time a status message is seen from each zone or RF zone a corresponding thing will appear in the inbox. -Leaving the `discovery` parameter set to *false* during normal operation is recommended, as it will slightly reduce resource consumption by the binding. +If the bridge `discovery` parameter is set to _true_, the first time a status message is seen from each zone or RF zone a corresponding thing will appear in the inbox. +Leaving the `discovery` parameter set to _false_ during normal operation is recommended, as it will slightly reduce resource consumption by the binding. ## Prerequisites @@ -45,21 +45,21 @@ Although not mentioned in the Quick Start guide, configuring virtual relay board Alarm Decoder things can be configured through openHAB's management UI, or manually via configuration files. When first configuring the binding it is probably easiest to configure it via the management UI, even if you plan to use configuration files later. -If you enable the *discovery* option on the bridge, as you fault zones (e.g. open doors and windows, trigger motion detectors, etc.) they should appear in the discovery inbox. +If you enable the _discovery_ option on the bridge, as you fault zones (e.g. open doors and windows, trigger motion detectors, etc.) they should appear in the discovery inbox. ### ipbridge -The `ipbridge` thing supports a TCP/IP connection to an Alarm Decoder device such as *AD2PI* or *AD2PHAT*. +The `ipbridge` thing supports a TCP/IP connection to an Alarm Decoder device such as _AD2PI_ or _AD2PHAT_. -* `hostname` (required) The hostname or IP address of the Alarm Decoder device -* `tcpPort` (default = 10000) TCP port number for the Alarm Decoder connection -* `discovery` (default = false) Enable automatic discovery of zones and RF zones -* `reconnect` (1-60, default = 2) The period in minutes that the handler will wait between connection checks and connection attempts -* `timeout` (0-60, default = 5) The period in minutes after which the connection will be reset if no valid messages have been received. Set to 0 to disable. +- `hostname` (required) The hostname or IP address of the Alarm Decoder device +- `tcpPort` (default = 10000) TCP port number for the Alarm Decoder connection +- `discovery` (default = false) Enable automatic discovery of zones and RF zones +- `reconnect` (1-60, default = 2) The period in minutes that the handler will wait between connection checks and connection attempts +- `timeout` (0-60, default = 5) The period in minutes after which the connection will be reset if no valid messages have been received. Set to 0 to disable. Thing config file example: -``` +```java Bridge alarmdecoder:ipbridge:ad1 [ hostname="cerberus.home", tcpPort=10000, discovery=true ] { Thing ... Thing ... @@ -68,17 +68,17 @@ Bridge alarmdecoder:ipbridge:ad1 [ hostname="cerberus.home", tcpPort=10000, disc ### serialbridge -The `serialbridge` thing supports a serial or USB connection to an Alarm Decoder device such as *AD2SERIAL* or *AD2USB*. +The `serialbridge` thing supports a serial or USB connection to an Alarm Decoder device such as _AD2SERIAL_ or _AD2USB_. Parameters: -* `serialPort` (required) The name of the serial port used to connect to the Alarm Decoder device -* `bitrate` Speed of the serial connection -* `discovery` (default=false) Enable automatic discovery of zones and RF zones +- `serialPort` (required) The name of the serial port used to connect to the Alarm Decoder device +- `bitrate` Speed of the serial connection +- `discovery` (default=false) Enable automatic discovery of zones and RF zones Thing config file example: -``` +```java Bridge alarmdecoder:serialbridge:ad1 [ serialPort="/dev/ttyS1", bitrate=115200, discovery=true ] { Thing ... Thing ... @@ -98,10 +98,10 @@ Command strings containing invalid characters will be ignored. Parameters: -* `addressMask` (default = 0) String containing the mask in hex of addresses for which the keypad thing will receive messages (0 = all addresses). -* `sendCommands` (default = false) Allow keypad commands to be sent to the alarm system from openHAB. Enabling this means the alarm system will be only as secure as your openHAB system. -* `sendStar` (default = false) When disarmed/faulted, automatically send the * character to obtain zone fault information. -* `commandMapping` (optional) Comma separated list of key/value pairs mapping integers to command strings for `intcommand` channel. +- `addressMask` (default = 0) String containing the mask in hex of addresses for which the keypad thing will receive messages (0 = all addresses). +- `sendCommands` (default = false) Allow keypad commands to be sent to the alarm system from openHAB. Enabling this means the alarm system will be only as secure as your openHAB system. +- `sendStar` (default = false) When disarmed/faulted, automatically send the * character to obtain zone fault information. +- `commandMapping` (optional) Comma separated list of key/value pairs mapping integers to command strings for `intcommand` channel. Address masks @@ -110,7 +110,7 @@ The first byte (left to right) represents devices 0-7, the second 8-15, the thir The mask itself is represented as a string containing a hexadecimal number. For example, a mask of 03000000 would indicate devices 0 and 1 as follows: -``` +```text Mask: 03000000 Bytes: 03 00 00 00 Bits: 00000011 00000000 00000000 00000000 @@ -121,7 +121,7 @@ Device# 111111 22221111 33222222 Thing config file example: -``` +```java Thing keypad keypad1 [ addressMask=0, sendCommands=true ] ``` @@ -131,12 +131,12 @@ The `zone` thing reports status from zone expanders and relay expanders, and als Parameters: -* `address` (required) Zone address -* `channel` (required) Zone channel +- `address` (required) Zone address +- `channel` (required) Zone channel Thing config file example: -``` +```java Thing zone frontdoor [ address=10, channel=1 ] ``` @@ -146,11 +146,11 @@ The `rfzone` thing reports status from wireless zones, such as 5800 series RF de Parameters: -* `serial` (required) Serial number of the RF zone +- `serial` (required) Serial number of the RF zone Thing config file example: -``` +```java Thing rfzone motion1 [ serial=0180010 ] ``` @@ -163,11 +163,11 @@ The `state` channel is a switch type channel that reflects the current state of Parameters: -* `address` (required) Virtual zone number (0-99) +- `address` (required) Virtual zone number (0-99) Thing config file example: -``` +```java Thing vzone watersensor [ address=41 ] ``` @@ -178,11 +178,11 @@ These are normally specifically formatted messages as described in the [SIA DC-0 They can also, depending on configuration, be other types of messages as described [here](https://www.alarmdecoder.com/wiki/index.php/LRR_Support). For panels that support multiple partitions, the partition for which a given lrr thing will receive messages can be defined. -* `partition` (default = 0) Partition for which to receive LRR events (0 = All) +- `partition` (default = 0) Partition for which to receive LRR events (0 = All) Thing config file example: -``` +```java Thing lrr lrr [ partition=0 ] ``` @@ -190,13 +190,13 @@ Thing config file example: The alarmdecoder things expose the following channels: -**zone** +### zone | channel | type |RO/RW| description | |--------------|---------|-----|------------------------------| | contact | Contact |RO |Zone contact state | -**rfzone** +### rfzone | channel | type |RO/RW| description | |--------------|---------|-----|------------------------------| @@ -207,14 +207,14 @@ The alarmdecoder things expose the following channels: | loop3 | Contact | RO |Loop 3 state | | loop4 | Contact | RO |Loop 4 state | -**vzone** +### vzone | channel | type |RO/RW| description | |--------------|---------|-----|------------------------------| | command | String | WO |"OPEN" or "CLOSED" command | | state | Switch | RW |Zone state (ON = closed) | -**keypad** +### keypad | channel | type |RO/RW| description | |--------------|---------|-----|------------------------------| @@ -239,11 +239,11 @@ The alarmdecoder things expose the following channels: | command | String | RW |Keypad command | | intcommand | Number | RW |Integer keypad command | -*Note* - The `intcommand` channel is provided for backward compatibility with the OH1 version of the binding. +_Note_ - The `intcommand` channel is provided for backward compatibility with the OH1 version of the binding. The integer to command string mappings are provided by the optional keypad `commandMapping` parameter. The default mapping is "0=0,1=1,2=2,3=3,4=4,5=5,6=6,7=7,8=8,9=9,10=*,11=#". -**lrr** +### lrr | channel | type |RO/RW| description | |--------------|---------|-----|------------------------------| @@ -256,7 +256,7 @@ The default mapping is "0=0,1=1,2=2,3=3,4=4,5=5,6=6,7=7,8=8,9=9,10=*,11=#". Example ad.things file: -``` +```java Bridge alarmdecoder:ipbridge:ad1 [ hostname="cerberus.home", tcpPort=10000, discovery=true ] { Thing zone frontdoor [ address=10, channel=1 ] Thing zone backdoor [ address=11, channel=1 ] @@ -269,7 +269,7 @@ Bridge alarmdecoder:ipbridge:ad1 [ hostname="cerberus.home", tcpPort=10000, disc Example ad.items file: -``` +```java Number KeypadZone "Zone [%d]" {channel="alarmdecoder:keypad:ad1:keypad1:zone"} String KeypadText "Message" {channel="alarmdecoder:keypad:ad1:keypad1:text"} Switch KeypadArmedAway "Armed Away" {channel="alarmdecoder:keypad:ad1:keypad1:armedaway"} @@ -295,18 +295,18 @@ String LrrMessage "CID Message" {channel="alarmdecoder:lrr:ad1:lrr:cidmessage"} String LrrReportCode "CID Report Code" {channel="alarmdecoder:lrr:ad1:lrr:reportcode"} ``` -*Note: For brevity, not every possible keypad channel is linked to an item in the above example.* +_Note: For brevity, not every possible keypad channel is linked to an item in the above example._ ## Thing Actions The `ipbridge` and `serialbridge` things expose the following action to the automation engine: -*reboot* - Send command to reboot the Alarm Decoder device. Accepts no parameters. +_reboot_ - Send command to reboot the Alarm Decoder device. Accepts no parameters. ## Quirks The alarmdecoder device cannot query the panel for the state of individual zones. -For this reason, the binding puts contacts into the "unknown" state (UNDEF), *until the panel goes into the READY state*. +For this reason, the binding puts contacts into the "unknown" state (UNDEF), _until the panel goes into the READY state_. At that point, all contacts for which no update messages have arrived are presumed to be in the CLOSED state. In other words: to get to a clean slate after an openHAB restart, close all doors/windows such that the panel is READY. diff --git a/bundles/org.openhab.binding.amazondashbutton/README.md b/bundles/org.openhab.binding.amazondashbutton/README.md index 163b9605f61..88955018dfd 100644 --- a/bundles/org.openhab.binding.amazondashbutton/README.md +++ b/bundles/org.openhab.binding.amazondashbutton/README.md @@ -8,7 +8,7 @@ The Binding code is inspired by [hortinstein/node-dash-button](https://github.co **Warning:** The Dash Button will try to contact the Amazon servers every time the button is pressed. This might not be in line with your privacy preferences but can be prevented. -Please refer to the ["Preventing Communication with Amazon Servers"](#no-phonehome) section for details. +Please refer to the ["Preventing Communication with Amazon Servers"](#preventing-communication-with-amazon-servers) section for details. **Response Time:** Please be aware, that due to the operation method of this binding, the response time for a button press can be rather high (up to five seconds). @@ -61,7 +61,7 @@ You need to restart openHAB for the capabilities change to take effect. On a Windows system there are two options to go with. 1. The preferred solution is [WinPcap](https://www.winpcap.org) if your network interface is supported. -2. An alternative option is [npcap](https://github.com/nmap/npcap) with the settings "WinPcap 4.1.3 compatibility" and "Raw 802.11 Packet Capture" +1. An alternative option is [npcap](https://github.com/nmap/npcap) with the settings "WinPcap 4.1.3 compatibility" and "Raw 802.11 Packet Capture" ### Installing libpcap on Other Operating Systems @@ -76,10 +76,9 @@ A few known operating systems are: ## Setup Dash Button Amazon itself doesn't support Dash Buttons anymore. -Instructions how to use them without having to rely on Amazon's servers can be found at https://blog.christophermullins.com/2019/12/20/rescue-your-amazon-dash-buttons/ - at least for some firmware versions. +Instructions how to use them without having to rely on Amazon's servers can be found at [https://blog.christophermullins.com/2019/12/20/rescue-your-amazon-dash-buttons/](https://blog.christophermullins.com/2019/12/20/rescue-your-amazon-dash-buttons/) - at least for some firmware versions. Take care to block internet access for the button or it will be bricked. -{: #no-phonehome} ## Preventing Communication with Amazon Servers Every time a Dash Button is pressed a request will be sent to the Amazon servers. @@ -116,11 +115,11 @@ You can ignore these devices in your Inbox. ### Amazon Dash Button -- `macAddress` - The MAC address of the Amazon Dash Button. +- `macAddress` - The MAC address of the Amazon Dash Button. -- `pcapNetworkInterfaceName` - The network interface which receives the packets of the Amazon Dash Button. +- `pcapNetworkInterfaceName` - The network interface which receives the packets of the Amazon Dash Button. -- `packetInterval` - Often a single button press is recognized multiple times. +- `packetInterval` - Often a single button press is recognized multiple times. You can specify how long any further detected button pressed should be ignored after one click was processed. The parameter is optional and 5000ms by default. diff --git a/bundles/org.openhab.binding.amazonechocontrol/README.md b/bundles/org.openhab.binding.amazonechocontrol/README.md index b817a02505a..a9cd5da40b6 100644 --- a/bundles/org.openhab.binding.amazonechocontrol/README.md +++ b/bundles/org.openhab.binding.amazonechocontrol/README.md @@ -76,10 +76,10 @@ The configuration of your amazon account must be done in the 'Amazon Account' de ## First Steps -1) Create an 'Amazon Account' thing -2) open the url YOUR_OPENHAB/amazonechocontrol in your browser (e.g. http://openhab:8080/amazonechocontrol/), click the link for your account thing and login. -3) You should see now a message that the login was successful -4) If you encounter redirect/page refresh issues, enable two-factor authentication (2FA) on your Amazon account. +1. Create an 'Amazon Account' thing +1. open the url YOUR_OPENHAB/amazonechocontrol in your browser (e.g. `http://openhab:8080/amazonechocontrol/`), click the link for your account thing and login. +1. You should see now a message that the login was successful +1. If you encounter redirect/page refresh issues, enable two-factor authentication (2FA) on your Amazon account. ## Discovery @@ -92,7 +92,7 @@ You will find the required serial number in settings of the device in the Alexa If you want to discover your smart home devices you need to activate it in the 'Amazon Account' thing. Devices from other skills can be discovered too. -See section *Smart Home Devices* below for more information. +See section _Smart Home Devices_ below for more information. ## Account @@ -139,7 +139,7 @@ The configuration of your Amazon account must be done in the 'Amazon Account' de |--------------------------|----------------------------------------------------| | serialNumber | Serial number of the Amazon Echo in the Alexa app | -You will find the serial number in the Alexa app or on the webpage YOUR_OPENHAB/amazonechocontrol/YOUR_ACCOUNT (e.g. http://openhab:8080/amazonechocontrol/account1). +You will find the serial number in the Alexa app or on the webpage YOUR_OPENHAB/amazonechocontrol/YOUR_ACCOUNT (e.g. `http://openhab:8080/amazonechocontrol/account1`). ### Flash Briefing Profile @@ -201,13 +201,13 @@ This can be used to call Alexa API from rules. E.g. to read out the history call from an installation on openhab:8080 with an account named account1: -http://openhab:8080/amazonechocontrol/account1/PROXY/api/activities?startTime=&size=50&offset=1 +`http://openhab:8080/amazonechocontrol/account1/PROXY/api/activities?startTime=&size=50&offset=1` ### Example #### echo.things -``` +```java Bridge amazonechocontrol:account:account1 "Amazon Account" @ "Accounts" [discoverSmartHome=2, pollingIntervalSmartHomeAlexa=30, pollingIntervalSmartSkills=120] { Thing echo echo1 "Alexa" @ "Living Room" [serialNumber="SERIAL_NUMBER"] @@ -222,7 +222,7 @@ Bridge amazonechocontrol:account:account1 "Amazon Account" @ "Accounts" [discove Sample for the Thing echo1 only. But it will work in the same way for the other things, only replace the thing name in the channel link. Take a look in the channel description above to know, which channels are supported by your thing type. -``` +```java // Account String Echo_Living_Room_SendMessage "SendMessage" {channel="amazonechocontrol:account:account1:sendMessage"} @@ -296,7 +296,7 @@ String FlashBriefing_LifeStyle_Play "Play (Write only)" #### echo.sitemap: -``` +```perl sitemap amazonechocontrol label="Echo Devices" { Frame label="Alexa" { @@ -349,13 +349,13 @@ sitemap amazonechocontrol label="Echo Devices" ## Flash Briefing -#### Supported Things +### Supported Things | Thing type id | Name | |----------------------|---------------------------------------| | flashbriefingprofile | Flash briefing profile | -#### Channels +### Channels The flashbriefingprofile thing has no configuration parameters. It will be configured at runtime by using the save channel to store the current flash briefing configuration which is set in the alexa app in the thing. Create a flashbriefingprofile Thing for each set you need. @@ -367,11 +367,11 @@ E.g. One Flashbriefing profile with technical news and wheater, one for playing | active | Switch | R/W | flashbriefingprofile | Active the profile | playOnDevice | String | W | flashbriefingprofile | Specify the echo serial number or name to start the flash briefing. -#### Example +### Example #### flashbriefings.things -``` +```java Bridge amazonechocontrol:account:account1 "Amazon Account" @ "Accounts" [discoverSmartHome=2] { Thing flashbriefingprofile flashbriefing1 "Flash Briefing Technical" @ "Flash Briefings" @@ -384,7 +384,7 @@ Bridge amazonechocontrol:account:account1 "Amazon Account" @ "Accounts" [discove Sample for the Thing echo1 only. But it will work in the same way for the other things, only replace the thing name in the channel link. Take a look in the channel description above to know, which channels are supported by your thing type. -``` +```java // Flashbriefings Switch FlashBriefing_Technical_Save "Save (Write only)" {channel="amazonechocontrol:flashbriefingprofile:account1:flashbriefing1:save"} Switch FlashBriefing_Technical_Active "Active" {channel="amazonechocontrol:flashbriefingprofile:account1:flashbriefing1:active"} @@ -397,7 +397,7 @@ String FlashBriefing_LifeStyle_Play "Play (Write only)" {channel="amazonechoco #### flashbriefings.sitemap: -``` +```perl sitemap flashbriefings label="Flash Briefings" { Frame label="Flash Briefing Technical" { @@ -419,15 +419,14 @@ sitemap flashbriefings label="Flash Briefings" Note: the channels of smartHomeDevices and smartHomeDeviceGroup will be created dynamically based on the capabilities reported by the amazon server. This can take a little bit of time. The polling interval configured in the Account Thing to get the state is specified in minutes and has a minimum of 10. This means it takes up to 10 minutes to see the state of a channel. The reason for this low interval is, that the polling causes a big server load for the Smart Home Skills. -#### Supported Things +### Supported Things | Thing type id | Name | |----------------------|---------------------------------------| | smartHomeDevice | Smart Home Device | | smartHomeDeviceGroup | Smart Home Device group | - -#### Thing configuration of smartHomeDevice, smartHomeDeviceGroup +### Thing configuration of smartHomeDevice, smartHomeDeviceGroup | Configuration name | Description | |--------------------------|---------------------------------------------------------------------------| @@ -435,7 +434,7 @@ The polling interval configured in the Account Thing to get the state is specifi The only possibility to find out the id is by using the discover function in the UI. You can use then the id, if you want define the Thing in a file. -#### Channels +### Channels The channels of the smarthome devices will be generated at runtime. Check in the UI thing configurations, which channels are created. @@ -464,7 +463,7 @@ The channels of the smarthome devices will be generated at runtime. Check in the #### smarthome.things -``` +```java Bridge amazonechocontrol:account:account1 "Amazon Account" @ "Accounts" [discoverSmartHome=2, pollingIntervalSmartHomeAlexa=30, pollingIntervalSmartSkills=120] { Thing smartHomeDevice smartHomeDevice1 "Smart Home Device 1" @ "Living Room" [id="ID"] @@ -479,7 +478,7 @@ Bridge amazonechocontrol:account:account1 "Amazon Account" @ "Accounts" [discove Sample for the Thing echo1 only. But it will work in the same way for the other things, only replace the thing name in the channel link. Take a look in the channel description above to know which channels are supported by your thing type. -``` +```java // Lights and lightgroups Switch Light_State "On/Off" {channel="amazonechocontrol:smartHomeDevice:account1:smartHomeDevice1:powerState"} Dimmer Light_Brightness "Brightness" {channel="amazonechocontrol:smartHomeDevice:account1:smartHomeDevice1:brightness"} @@ -501,7 +500,7 @@ The only possibility to find out the id for the smartHomeDevice and smartHomeDev #### smarthome.sitemap: -``` +```perl sitemap smarthome label="Smart Home Devices" { Frame label="Lights and light groups" { @@ -519,18 +518,18 @@ sitemap smarthome label="Smart Home Devices" ## How To Get IDs -1) Open the url YOUR_OPENHAB/amazonechocontrol in your browser (e.g. http://openhab:8080/amazonechocontrol/) -2) Click on the name of the account thing -3) Click on the name of the echo thing -4) Scroll to the channel and copy the required ID +1. Open the url YOUR_OPENHAB/amazonechocontrol in your browser (e.g. `http://openhab:8080/amazonechocontrol/`) +1. Click on the name of the account thing +1. Click on the name of the echo thing +1. Scroll to the channel and copy the required ID -## Advanced Feature Technically Experienced Users +### Advanced Feature Technically Experienced Users The url /amazonechocontrol//PROXY/ provides a proxy server with an authenticated connection to the amazon alexa server. This can be used to call alexa api from rules. E.g. to read out the history call from an installation on openhab:8080 with an account named account1: -http://openhab:8080/amazonechocontrol/account1/PROXY/api/activities?startTime=&size=50&offset=1 +`http://openhab:8080/amazonechocontrol/account1/PROXY/api/activities?startTime=&size=50&offset=1` ## Tutorials @@ -589,8 +588,7 @@ No specification uses the volume from the `textToSpeechVolume` channel. Note: If you turn off the sound and Alexa is playing music, it will anyway turn down the volume for a moment. This behavior can not be changed. - -```php +```java rule "Say welcome if the door opens" when Item Door_Contact changed to OPEN @@ -601,11 +599,11 @@ end ## Playing an alarm sound for 15 seconds with an openHAB rule if a door contact was opened: -1) Do get the ID of your sound, follow the steps in "How To Get IDs" -2) Write down the text in the square brackets. e.g. ECHO:system_alerts_repetitive01 for the nightstand sound -3) Create a rule for start playing the sound: +1. Do get the ID of your sound, follow the steps in "How To Get IDs" +1. Write down the text in the square brackets. e.g. ECHO:system_alerts_repetitive01 for the nightstand sound +1. Create a rule for start playing the sound: -```php +```java var Timer stopAlarmTimer = null rule "Turn on alarm sound for 15 seconds if door opens" @@ -631,11 +629,11 @@ Note 2: The rule have no effect for your default alarm sound used in the Alexa a ### Play a spotify playlist if a switch was changed to on: -1) Do get the ID of your sound, follow the steps in "How To Get IDs" -2) Write down the text in the square brackets. e.g. SPOTIFY for the spotify music provider -3) Create a rule for start playing a song or playlist: +1. Do get the ID of your sound, follow the steps in "How To Get IDs" +1. Write down the text in the square brackets. e.g. SPOTIFY for the spotify music provider +1. Create a rule for start playing a song or playlist: -```php +```java rule "Play a playlist on spotify if a switch was changed" when Item Spotify_Playlist_Switch changed to ON @@ -649,10 +647,10 @@ Note: It is recommended to test the command send to play music command first wit ### Start playing weather/traffic/etc: -1) Pick up one of the available commands: Weather, Traffic, GoodMorning, SingASong, TellStory, FlashBriefing -2) Create a rule for start playing the information where you provide the command as string: +1. Pick up one of the available commands: Weather, Traffic, GoodMorning, SingASong, TellStory, FlashBriefing +1. Create a rule for start playing the information where you provide the command as string: -```php +```java rule "Start wheater info" when Item Spotify_Start_Wheater_Switch changed to ON @@ -663,11 +661,11 @@ end ### Start playing a custom flashbriefing on a device: -1) Do get the ID of your sound, follow the steps in "How To Get IDs" -2) Write down the text in the square brackets. e.g. flashbriefing.flashbriefing1 -2) Create a rule for start playing the information where you provide the command as string: +1. Do get the ID of your sound, follow the steps in "How To Get IDs" +1. Write down the text in the square brackets. e.g. flashbriefing.flashbriefing1 +1. Create a rule for start playing the information where you provide the command as string: -```php +```java rule "Start wheater info" when Item Spotify_Start_Wheater_Switch changed to ON @@ -676,14 +674,14 @@ then end ``` -## Advanced Feature Technically Experienced Users +### Advanced Feature Technically Experienced Users The url /amazonechocontrol//PROXY/ provides a proxy server with an authenticated connection to the Amazon Alexa server. This can be used to call Alexa API from rules. E.g. to read out the history call from an installation on openhab:8080 with an account named account1: -http://openhab:8080/amazonechocontrol/account1/PROXY/api/activities?startTime=&size=50&offset=1 +`http://openhab:8080/amazonechocontrol/account1/PROXY/api/activities?startTime=&size=50&offset=1` To resolve login problems the connection settings of an `account` thing can be reset via the karaf console. The command `amazonechocontrol listAccounts` shows a list of all available `account` things. @@ -700,9 +698,9 @@ The binding is tested with amazon.de, amazon.fr, amazon.it, amazon.com and amazo ## Credits -The idea for writing this binding came from this blog: https://blog.loetzimmer.de/2017/10/amazon-alexa-hort-auf-die-shell-echo.html (German). +The idea for writing this binding came from this blog: [https://blog.loetzimmer.de/2017/10/amazon-alexa-hort-auf-die-shell-echo.html](https://blog.loetzimmer.de/2017/10/amazon-alexa-hort-auf-die-shell-echo.html) (German). Thank you Alex! -The technical information for the web socket connection to get live Alexa state updates cames from Ingo. He has done the Alexa ioBroker implementation https://github.com/Apollon77 +The technical information for the web socket connection to get live Alexa state updates cames from Ingo. He has done the Alexa ioBroker implementation [https://github.com/Apollon77](https://github.com/Apollon77) Thank you Ingo! ## Trademark Disclaimer diff --git a/bundles/org.openhab.binding.ambientweather/README.md b/bundles/org.openhab.binding.ambientweather/README.md index 557a8f300c2..00e23d3b4b9 100644 --- a/bundles/org.openhab.binding.ambientweather/README.md +++ b/bundles/org.openhab.binding.ambientweather/README.md @@ -7,7 +7,7 @@ The binding uses Ambient Weather's real-time API, so updates from weather statio The binding currently supports weather data from these weather stations. -| Thing | ID | +| Thing | ID | |--------------------------|-----------| | Account | bridge | | WS-0900-IP | ws0900ip | @@ -29,8 +29,8 @@ Automatic discovery is currently not supported due to the lack of weather statio | Parameter | Parameter ID | Required/Optional | Description | |------------------|-------------------|-------------------|-------------| -| API Key | apiKey | Required | Obtain the API key on the *My Account* page of your `ambientweather.net` dashboard. | -| Application Key | apiKey | Required | Obtain the Application key on the *My Account* page of your `ambientweather.net` dashboard. | +| API Key | apiKey | Required | Obtain the API key on the _My Account_ page of your `ambientweather.net` dashboard. | +| Application Key | apiKey | Required | Obtain the Application key on the _My Account_ page of your `ambientweather.net` dashboard. | ### Weather Station @@ -98,7 +98,7 @@ The following channels are supported by the binding. Note that specific weather ### Things -``` +```java Bridge ambientweather:bridge:account "Ambient Weather Account" [ applicationKey="bd7eb3fe87f74e9.....", apiKey="efe88d6202be43e6a40....." ] { Thing ws1400ip 1400 "Ambient Weather WS-1400-IP" [ macAddress="00:ab:cd:00:00:01" ] Thing ws8482 8482 "Ambient Weather WS-8482" [ macAddress="00:ab:cd:00:00:02" ] @@ -107,7 +107,7 @@ Bridge ambientweather:bridge:account "Ambient Weather Account" [ applicationKey= ### Items -``` +```java // WS-1400-IP Weather Station String WS1400IP_StationName "Station Name [%s]" { channel="ambientweather:ws1400ip:account:1400:station#name" } String WS1400IP_StationLocation "Station Location [%s]" { channel="ambientweather:ws1400ip:account:1400:station#location" } @@ -173,7 +173,7 @@ String WS8482_SoilSensorBattery "Remote Battery [MAP(ambient-battery.map):%s]" { #### File ambient-battery.map -``` +```text -=UNKNOWN NULL=UNKNOWN 1=GOOD @@ -182,7 +182,7 @@ NULL=UNKNOWN ### Sitemap -``` +```perl Text label="Weather Station" icon="sun_clouds" { Frame { Text item=WS1400IP_ObservationTime label="Observation Time [%1$tm/%1$td %1$tl:%1$tM %1$tp]" @@ -231,19 +231,19 @@ Text label="Weather Station" icon="sun_clouds" { Adding support for a new weather station type involves changes to the source code in just a few places. -#### Add a New Thing Type in AmbientWeatherBindingConstants.java +### Add a New Thing Type in AmbientWeatherBindingConstants.java Define a new `ThingTypeUID` for the new station and add it to the `SUPPORTED_THING_TYPES_UIDS` Collection. Add a channel group for the new station. -#### Create OH-INF/thing/\.xml +### Create OH-INF/thing/\.xml Add thing type and channel group specific to the data elements supported by this weather station. Modeling this after an existing thing type that shares many of the channels is the easiest starting point. You can determine the weather data elements returned for the weather station by putting the binding into debug mode and reviewing the JSON object returned by the Ambient Weather API. -#### Create Processor Class Processor +### Create Processor Class Processor Add a class in `org.openhab.binding.ambientweather.internal.processor` that defines the channels supported by this station type. @@ -251,14 +251,14 @@ Add the following two methods. Again, the easiest approach is to model this class after a class for a similar weather station type. -##### Method: processInfoUpdate +#### Method: processInfoUpdate Updates the channels for station name and location. -##### Method: processWeatherData +#### Method: processWeatherData Updates channels for weather data. -#### Update ProcessorFactory.java +### Update ProcessorFactory.java Add new Processor class definition to `ProcessorFactory.java`, and add a new case to the switch statement to return the new processor. diff --git a/bundles/org.openhab.binding.amplipi/README.md b/bundles/org.openhab.binding.amplipi/README.md index ed36308b3e7..ad4d28adf61 100644 --- a/bundles/org.openhab.binding.amplipi/README.md +++ b/bundles/org.openhab.binding.amplipi/README.md @@ -2,7 +2,6 @@ This binding supports the multi-room audio system [AmpliPi](http://www.amplipi.com/) from [MicroNova](http://www.micro-nova.com/). - ## Supported Things The AmpliPi itself is modeled as a Bridge of type `controller`. @@ -56,7 +55,7 @@ If no volume value is passed, the current volume of each zone is used, otherwise amplipi.things: -``` +```java Bridge amplipi:controller:1 "My AmpliPi" [ hostname="amplipi.local" ] { zone zone2 "Living Room" [ id=1 ] } @@ -64,7 +63,7 @@ Bridge amplipi:controller:1 "My AmpliPi" [ hostname="amplipi.local" ] { amplipi.items: -``` +```java Number Preset "Preset" { channel="amplipi:controller:1:preset" } String Input1 "Input 1" { channel="amplipi:controller:1:input1" } String Input2 "Input 2" { channel="amplipi:controller:1:input2" } @@ -78,7 +77,7 @@ Number SourceZ2 "Source Zone2" { channel="amplipi:zone:1:zone2: amplipi.sitemap: -``` +```perl sitemap amplipi label="Main Menu" { Frame label="AmpliPi" { diff --git a/bundles/org.openhab.binding.androiddebugbridge/README.md b/bundles/org.openhab.binding.androiddebugbridge/README.md index 42549a51825..18a378d4302 100644 --- a/bundles/org.openhab.binding.androiddebugbridge/README.md +++ b/bundles/org.openhab.binding.androiddebugbridge/README.md @@ -16,7 +16,7 @@ This binding was tested on : | Nexus5x | 8.1.0 | Everything works nice | | Freebox Pop Player | 9 | Everything works nice | -Please update this document if you tested it with other android versions to reflect the compatibility of the binding. +Please update this document if you tested it with other android versions to reflect the compatibility of the binding. ## Discovery @@ -60,10 +60,10 @@ You can configure different modes to detect when the device is playing media dep The available modes are: -* idle: assert not playing, avoid command execution. -* media_state: detect play status by dumping the media_session service. This is the default for not configured apps -* audio: detect play status by dumping the audio service. -* wake_lock: detect play status by comparing the power wake lock state with the values provided in 'wakeLockPlayStates' +- idle: assert not playing, avoid command execution. +- media_state: detect play status by dumping the media_session service. This is the default for not configured apps +- audio: detect play status by dumping the audio service. +- wake_lock: detect play status by comparing the power wake lock state with the values provided in 'wakeLockPlayStates' The configuration depends on the application, device and version used. @@ -73,14 +73,14 @@ This is a sample of the mediaStateJSONConfig thing configuration - the `label` i ## Record/Send input events -As the execution of key events takes a while, you can use input events as an alternative way to control your device. +As the execution of key events takes a while, you can use input events as an alternative way to control your device. They are pretty device specific, so you should use the record-input and recorded-input channels to store/send those events. An example of what you can do: -* You can send the command `UP` to the `record-input` channel the binding will then capture the events you send through your remote for the defined recordDuration config for the thing, so press once the UP key on your remote and wait a while. -* Now that you have recorded your input, you can send the `UP` command to the `recorded-input` event and it will send the recorded event to the android device. +- You can send the command `UP` to the `record-input` channel the binding will then capture the events you send through your remote for the defined recordDuration config for the thing, so press once the UP key on your remote and wait a while. +- Now that you have recorded your input, you can send the `UP` command to the `recorded-input` event and it will send the recorded event to the android device. Please note that events could fail if the input method is removed, for example it could fail if you clone the events of a bluetooth controller and the remote goes offline. This is happening for me when recording the Fire TV remote events but not for my Xiaomi TV which also has a bt remote controller. @@ -106,7 +106,7 @@ Please note that events could fail if the input method is removed, for example i | wake-lock | Number | Power wake lock value | | screen-state | Switch | Screen power state | -#### Start Intent +### Start Intent This channel allows to invoke the 'am start' command, the syntax for it is: ||<> ||... @@ -114,311 +114,311 @@ This channel allows to invoke the 'am start' command, the syntax for it is: This is a sample: com.netflix.ninja/.MainActivity||android.intent.action.VIEW||netflix://title/80025384||0x10000020||amzn_deeplink_data 80025384 -Not all the (arguments)[https://developer.android.com/studio/command-line/adb#IntentSpec] are supported. Please open an issue or pull request if you need more. +Not all the [arguments](https://developer.android.com/studio/command-line/adb#IntentSpec) are supported. Please open an issue or pull request if you need more. -#### Available key-event values: +### Available key-event values: -* KEYCODE_0 -* KEYCODE_1 -* KEYCODE_11 -* KEYCODE_12 -* KEYCODE_2 -* KEYCODE_3 -* KEYCODE_3D_MODE -* KEYCODE_4 -* KEYCODE_5 -* KEYCODE_6 -* KEYCODE_7 -* KEYCODE_8 -* KEYCODE_9 -* KEYCODE_A -* KEYCODE_ALL_APPS -* KEYCODE_ALT_LEFT -* KEYCODE_ALT_RIGHT -* KEYCODE_APOSTROPHE -* KEYCODE_APP_SWITCH -* KEYCODE_ASSIST -* KEYCODE_AT -* KEYCODE_AVR_INPUT -* KEYCODE_AVR_POWER -* KEYCODE_B -* KEYCODE_BACK -* KEYCODE_BACKSLASH -* KEYCODE_BOOKMARK -* KEYCODE_BREAK -* KEYCODE_BRIGHTNESS_DOWN -* KEYCODE_BRIGHTNESS_UP -* KEYCODE_BUTTON_1 -* KEYCODE_BUTTON_10 -* KEYCODE_BUTTON_11 -* KEYCODE_BUTTON_12 -* KEYCODE_BUTTON_13 -* KEYCODE_BUTTON_14 -* KEYCODE_BUTTON_15 -* KEYCODE_BUTTON_16 -* KEYCODE_BUTTON_2 -* KEYCODE_BUTTON_3 -* KEYCODE_BUTTON_4 -* KEYCODE_BUTTON_5 -* KEYCODE_BUTTON_6 -* KEYCODE_BUTTON_7 -* KEYCODE_BUTTON_8 -* KEYCODE_BUTTON_9 -* KEYCODE_BUTTON_A -* KEYCODE_BUTTON_B -* KEYCODE_BUTTON_C -* KEYCODE_BUTTON_L1 -* KEYCODE_BUTTON_L2 -* KEYCODE_BUTTON_MODE -* KEYCODE_BUTTON_R1 -* KEYCODE_BUTTON_R2 -* KEYCODE_BUTTON_SELECT -* KEYCODE_BUTTON_START -* KEYCODE_BUTTON_THUMBL -* KEYCODE_BUTTON_THUMBR -* KEYCODE_BUTTON_X -* KEYCODE_BUTTON_Y -* KEYCODE_BUTTON_Z -* KEYCODE_C -* KEYCODE_CALCULATOR -* KEYCODE_CALENDAR -* KEYCODE_CALL -* KEYCODE_CAMERA -* KEYCODE_CAPS_LOCK -* KEYCODE_CAPTIONS -* KEYCODE_CHANNEL_DOWN -* KEYCODE_CHANNEL_UP -* KEYCODE_CLEAR -* KEYCODE_COMMA -* KEYCODE_CONTACTS -* KEYCODE_COPY -* KEYCODE_CTRL_LEFT -* KEYCODE_CTRL_RIGHT -* KEYCODE_CUT -* KEYCODE_D -* KEYCODE_DEL -* KEYCODE_DPAD_CENTER -* KEYCODE_DPAD_DOWN -* KEYCODE_DPAD_DOWN_LEFT -* KEYCODE_DPAD_DOWN_RIGHT -* KEYCODE_DPAD_LEFT -* KEYCODE_DPAD_RIGHT -* KEYCODE_DPAD_UP -* KEYCODE_DPAD_UP_LEFT -* KEYCODE_DPAD_UP_RIGHT -* KEYCODE_DVR -* KEYCODE_E -* KEYCODE_EISU -* KEYCODE_ENDCALL -* KEYCODE_ENTER -* KEYCODE_ENVELOPE -* KEYCODE_EQUALS -* KEYCODE_ESCAPE -* KEYCODE_EXPLORER -* KEYCODE_F -* KEYCODE_F1 -* KEYCODE_F10 -* KEYCODE_F11 -* KEYCODE_F12 -* KEYCODE_F2 -* KEYCODE_F3 -* KEYCODE_F4 -* KEYCODE_F5 -* KEYCODE_F6 -* KEYCODE_F7 -* KEYCODE_F8 -* KEYCODE_F9 -* KEYCODE_FOCUS -* KEYCODE_FORWARD -* KEYCODE_FORWARD_DEL -* KEYCODE_FUNCTION -* KEYCODE_G -* KEYCODE_GRAVE -* KEYCODE_GUIDE -* KEYCODE_H -* KEYCODE_HEADSETHOOK -* KEYCODE_HELP -* KEYCODE_HENKAN -* KEYCODE_HOME -* KEYCODE_I -* KEYCODE_INFO -* KEYCODE_INSERT -* KEYCODE_J -* KEYCODE_K -* KEYCODE_KANA -* KEYCODE_KATAKANA_HIRAGANA -* KEYCODE_L -* KEYCODE_LANGUAGE_SWITCH -* KEYCODE_LAST_CHANNEL -* KEYCODE_LEFT_BRACKET -* KEYCODE_M -* KEYCODE_MANNER_MODE -* KEYCODE_MEDIA_AUDIO_TRACK -* KEYCODE_MEDIA_CLOSE -* KEYCODE_MEDIA_EJECT -* KEYCODE_MEDIA_FAST_FORWARD -* KEYCODE_MEDIA_NEXT -* KEYCODE_MEDIA_PAUSE -* KEYCODE_MEDIA_PLAY -* KEYCODE_MEDIA_PLAY_PAUSE -* KEYCODE_MEDIA_PREVIOUS -* KEYCODE_MEDIA_RECORD -* KEYCODE_MEDIA_REWIND -* KEYCODE_MEDIA_SKIP_BACKWARD -* KEYCODE_MEDIA_SKIP_FORWARD -* KEYCODE_MEDIA_STEP_BACKWARD -* KEYCODE_MEDIA_STEP_FORWARD -* KEYCODE_MEDIA_STOP -* KEYCODE_MEDIA_TOP_MENU -* KEYCODE_MENU -* KEYCODE_META_LEFT -* KEYCODE_META_RIGHT -* KEYCODE_MINUS -* KEYCODE_MOVE_END -* KEYCODE_MOVE_HOME -* KEYCODE_MUHENKAN -* KEYCODE_MUSIC -* KEYCODE_MUTE -* KEYCODE_N -* KEYCODE_NAVIGATE_IN -* KEYCODE_NAVIGATE_NEXT -* KEYCODE_NAVIGATE_OUT -* KEYCODE_NAVIGATE_PREVIOUS -* KEYCODE_NOTIFICATION -* KEYCODE_NUM -* KEYCODE_NUMPAD_0 -* KEYCODE_NUMPAD_1 -* KEYCODE_NUMPAD_2 -* KEYCODE_NUMPAD_3 -* KEYCODE_NUMPAD_4 -* KEYCODE_NUMPAD_5 -* KEYCODE_NUMPAD_6 -* KEYCODE_NUMPAD_7 -* KEYCODE_NUMPAD_8 -* KEYCODE_NUMPAD_9 -* KEYCODE_NUMPAD_ADD -* KEYCODE_NUMPAD_COMMA -* KEYCODE_NUMPAD_DIVIDE -* KEYCODE_NUMPAD_DOT -* KEYCODE_NUMPAD_ENTER -* KEYCODE_NUMPAD_EQUALS -* KEYCODE_NUMPAD_LEFT_PAREN -* KEYCODE_NUMPAD_MULTIPLY -* KEYCODE_NUMPAD_RIGHT_PAREN -* KEYCODE_NUMPAD_SUBTRACT -* KEYCODE_NUM_LOCK -* KEYCODE_O -* KEYCODE_P -* KEYCODE_PAGE_DOWN -* KEYCODE_PAGE_UP -* KEYCODE_PAIRING -* KEYCODE_PASTE -* KEYCODE_PERIOD -* KEYCODE_PICTSYMBOLS -* KEYCODE_PLUS -* KEYCODE_POUND -* KEYCODE_POWER -* KEYCODE_PROFILE_SWITCH -* KEYCODE_PROG_BLUE -* KEYCODE_PROG_GREEN -* KEYCODE_PROG_RED -* KEYCODE_PROG_YELLOW -* KEYCODE_Q -* KEYCODE_R -* KEYCODE_REFRESH -* KEYCODE_RIGHT_BRACKET -* KEYCODE_RO -* KEYCODE_S -* KEYCODE_SCROLL_LOCK -* KEYCODE_SEARCH -* KEYCODE_SEMICOLON -* KEYCODE_SETTINGS -* KEYCODE_SHIFT_LEFT -* KEYCODE_SHIFT_RIGHT -* KEYCODE_SLASH -* KEYCODE_SLEEP -* KEYCODE_SOFT_LEFT -* KEYCODE_SOFT_RIGHT -* KEYCODE_SOFT_SLEEP -* KEYCODE_SPACE -* KEYCODE_STAR -* KEYCODE_STB_INPUT -* KEYCODE_STB_POWER -* KEYCODE_STEM_1 -* KEYCODE_STEM_2 -* KEYCODE_STEM_3 -* KEYCODE_STEM_PRIMARY -* KEYCODE_SWITCH_CHARSET -* KEYCODE_SYM -* KEYCODE_SYSRQ -* KEYCODE_SYSTEM_NAVIGATION_DOWN -* KEYCODE_SYSTEM_NAVIGATION_LEFT -* KEYCODE_SYSTEM_NAVIGATION_RIGHT -* KEYCODE_SYSTEM_NAVIGATION_UP -* KEYCODE_T -* KEYCODE_TAB -* KEYCODE_THUMBS_DOWN -* KEYCODE_THUMBS_UP -* KEYCODE_TV -* KEYCODE_TV_ANTENNA_CABLE -* KEYCODE_TV_AUDIO_DESCRIPTION -* KEYCODE_TV_AUDIO_DESCRIPTION_MIX_DOWN -* KEYCODE_TV_AUDIO_DESCRIPTION_MIX_UP -* KEYCODE_TV_CONTENTS_MENU -* KEYCODE_TV_DATA_SERVICE -* KEYCODE_TV_INPUT -* KEYCODE_TV_INPUT_COMPONENT_1 -* KEYCODE_TV_INPUT_COMPONENT_2 -* KEYCODE_TV_INPUT_COMPOSITE_1 -* KEYCODE_TV_INPUT_COMPOSITE_2 -* KEYCODE_TV_INPUT_HDMI_1 -* KEYCODE_TV_INPUT_HDMI_2 -* KEYCODE_TV_INPUT_HDMI_3 -* KEYCODE_TV_INPUT_HDMI_4 -* KEYCODE_TV_INPUT_VGA_1 -* KEYCODE_TV_MEDIA_CONTEXT_MENU -* KEYCODE_TV_NETWORK -* KEYCODE_TV_NUMBER_ENTRY -* KEYCODE_TV_POWER -* KEYCODE_TV_RADIO_SERVICE -* KEYCODE_TV_SATELLITE -* KEYCODE_TV_SATELLITE_BS -* KEYCODE_TV_SATELLITE_CS -* KEYCODE_TV_SATELLITE_SERVICE -* KEYCODE_TV_TELETEXT -* KEYCODE_TV_TERRESTRIAL_ANALOG -* KEYCODE_TV_TERRESTRIAL_DIGITAL -* KEYCODE_TV_TIMER_PROGRAMMING -* KEYCODE_TV_ZOOM_MODE -* KEYCODE_U -* KEYCODE_UNKNOWN -* KEYCODE_V -* KEYCODE_VOICE_ASSIST -* KEYCODE_VOLUME_DOWN -* KEYCODE_VOLUME_MUTE -* KEYCODE_VOLUME_UP -* KEYCODE_W -* KEYCODE_WAKEUP -* KEYCODE_WINDOW -* KEYCODE_X -* KEYCODE_Y -* KEYCODE_YEN -* KEYCODE_Z -* KEYCODE_ZENKAKU_HANKAKU -* KEYCODE_ZOOM_IN -* KEYCODE_ZOOM_OUT +- KEYCODE_0 +- KEYCODE_1 +- KEYCODE_11 +- KEYCODE_12 +- KEYCODE_2 +- KEYCODE_3 +- KEYCODE_3D_MODE +- KEYCODE_4 +- KEYCODE_5 +- KEYCODE_6 +- KEYCODE_7 +- KEYCODE_8 +- KEYCODE_9 +- KEYCODE_A +- KEYCODE_ALL_APPS +- KEYCODE_ALT_LEFT +- KEYCODE_ALT_RIGHT +- KEYCODE_APOSTROPHE +- KEYCODE_APP_SWITCH +- KEYCODE_ASSIST +- KEYCODE_AT +- KEYCODE_AVR_INPUT +- KEYCODE_AVR_POWER +- KEYCODE_B +- KEYCODE_BACK +- KEYCODE_BACKSLASH +- KEYCODE_BOOKMARK +- KEYCODE_BREAK +- KEYCODE_BRIGHTNESS_DOWN +- KEYCODE_BRIGHTNESS_UP +- KEYCODE_BUTTON_1 +- KEYCODE_BUTTON_10 +- KEYCODE_BUTTON_11 +- KEYCODE_BUTTON_12 +- KEYCODE_BUTTON_13 +- KEYCODE_BUTTON_14 +- KEYCODE_BUTTON_15 +- KEYCODE_BUTTON_16 +- KEYCODE_BUTTON_2 +- KEYCODE_BUTTON_3 +- KEYCODE_BUTTON_4 +- KEYCODE_BUTTON_5 +- KEYCODE_BUTTON_6 +- KEYCODE_BUTTON_7 +- KEYCODE_BUTTON_8 +- KEYCODE_BUTTON_9 +- KEYCODE_BUTTON_A +- KEYCODE_BUTTON_B +- KEYCODE_BUTTON_C +- KEYCODE_BUTTON_L1 +- KEYCODE_BUTTON_L2 +- KEYCODE_BUTTON_MODE +- KEYCODE_BUTTON_R1 +- KEYCODE_BUTTON_R2 +- KEYCODE_BUTTON_SELECT +- KEYCODE_BUTTON_START +- KEYCODE_BUTTON_THUMBL +- KEYCODE_BUTTON_THUMBR +- KEYCODE_BUTTON_X +- KEYCODE_BUTTON_Y +- KEYCODE_BUTTON_Z +- KEYCODE_C +- KEYCODE_CALCULATOR +- KEYCODE_CALENDAR +- KEYCODE_CALL +- KEYCODE_CAMERA +- KEYCODE_CAPS_LOCK +- KEYCODE_CAPTIONS +- KEYCODE_CHANNEL_DOWN +- KEYCODE_CHANNEL_UP +- KEYCODE_CLEAR +- KEYCODE_COMMA +- KEYCODE_CONTACTS +- KEYCODE_COPY +- KEYCODE_CTRL_LEFT +- KEYCODE_CTRL_RIGHT +- KEYCODE_CUT +- KEYCODE_D +- KEYCODE_DEL +- KEYCODE_DPAD_CENTER +- KEYCODE_DPAD_DOWN +- KEYCODE_DPAD_DOWN_LEFT +- KEYCODE_DPAD_DOWN_RIGHT +- KEYCODE_DPAD_LEFT +- KEYCODE_DPAD_RIGHT +- KEYCODE_DPAD_UP +- KEYCODE_DPAD_UP_LEFT +- KEYCODE_DPAD_UP_RIGHT +- KEYCODE_DVR +- KEYCODE_E +- KEYCODE_EISU +- KEYCODE_ENDCALL +- KEYCODE_ENTER +- KEYCODE_ENVELOPE +- KEYCODE_EQUALS +- KEYCODE_ESCAPE +- KEYCODE_EXPLORER +- KEYCODE_F +- KEYCODE_F1 +- KEYCODE_F10 +- KEYCODE_F11 +- KEYCODE_F12 +- KEYCODE_F2 +- KEYCODE_F3 +- KEYCODE_F4 +- KEYCODE_F5 +- KEYCODE_F6 +- KEYCODE_F7 +- KEYCODE_F8 +- KEYCODE_F9 +- KEYCODE_FOCUS +- KEYCODE_FORWARD +- KEYCODE_FORWARD_DEL +- KEYCODE_FUNCTION +- KEYCODE_G +- KEYCODE_GRAVE +- KEYCODE_GUIDE +- KEYCODE_H +- KEYCODE_HEADSETHOOK +- KEYCODE_HELP +- KEYCODE_HENKAN +- KEYCODE_HOME +- KEYCODE_I +- KEYCODE_INFO +- KEYCODE_INSERT +- KEYCODE_J +- KEYCODE_K +- KEYCODE_KANA +- KEYCODE_KATAKANA_HIRAGANA +- KEYCODE_L +- KEYCODE_LANGUAGE_SWITCH +- KEYCODE_LAST_CHANNEL +- KEYCODE_LEFT_BRACKET +- KEYCODE_M +- KEYCODE_MANNER_MODE +- KEYCODE_MEDIA_AUDIO_TRACK +- KEYCODE_MEDIA_CLOSE +- KEYCODE_MEDIA_EJECT +- KEYCODE_MEDIA_FAST_FORWARD +- KEYCODE_MEDIA_NEXT +- KEYCODE_MEDIA_PAUSE +- KEYCODE_MEDIA_PLAY +- KEYCODE_MEDIA_PLAY_PAUSE +- KEYCODE_MEDIA_PREVIOUS +- KEYCODE_MEDIA_RECORD +- KEYCODE_MEDIA_REWIND +- KEYCODE_MEDIA_SKIP_BACKWARD +- KEYCODE_MEDIA_SKIP_FORWARD +- KEYCODE_MEDIA_STEP_BACKWARD +- KEYCODE_MEDIA_STEP_FORWARD +- KEYCODE_MEDIA_STOP +- KEYCODE_MEDIA_TOP_MENU +- KEYCODE_MENU +- KEYCODE_META_LEFT +- KEYCODE_META_RIGHT +- KEYCODE_MINUS +- KEYCODE_MOVE_END +- KEYCODE_MOVE_HOME +- KEYCODE_MUHENKAN +- KEYCODE_MUSIC +- KEYCODE_MUTE +- KEYCODE_N +- KEYCODE_NAVIGATE_IN +- KEYCODE_NAVIGATE_NEXT +- KEYCODE_NAVIGATE_OUT +- KEYCODE_NAVIGATE_PREVIOUS +- KEYCODE_NOTIFICATION +- KEYCODE_NUM +- KEYCODE_NUMPAD_0 +- KEYCODE_NUMPAD_1 +- KEYCODE_NUMPAD_2 +- KEYCODE_NUMPAD_3 +- KEYCODE_NUMPAD_4 +- KEYCODE_NUMPAD_5 +- KEYCODE_NUMPAD_6 +- KEYCODE_NUMPAD_7 +- KEYCODE_NUMPAD_8 +- KEYCODE_NUMPAD_9 +- KEYCODE_NUMPAD_ADD +- KEYCODE_NUMPAD_COMMA +- KEYCODE_NUMPAD_DIVIDE +- KEYCODE_NUMPAD_DOT +- KEYCODE_NUMPAD_ENTER +- KEYCODE_NUMPAD_EQUALS +- KEYCODE_NUMPAD_LEFT_PAREN +- KEYCODE_NUMPAD_MULTIPLY +- KEYCODE_NUMPAD_RIGHT_PAREN +- KEYCODE_NUMPAD_SUBTRACT +- KEYCODE_NUM_LOCK +- KEYCODE_O +- KEYCODE_P +- KEYCODE_PAGE_DOWN +- KEYCODE_PAGE_UP +- KEYCODE_PAIRING +- KEYCODE_PASTE +- KEYCODE_PERIOD +- KEYCODE_PICTSYMBOLS +- KEYCODE_PLUS +- KEYCODE_POUND +- KEYCODE_POWER +- KEYCODE_PROFILE_SWITCH +- KEYCODE_PROG_BLUE +- KEYCODE_PROG_GREEN +- KEYCODE_PROG_RED +- KEYCODE_PROG_YELLOW +- KEYCODE_Q +- KEYCODE_R +- KEYCODE_REFRESH +- KEYCODE_RIGHT_BRACKET +- KEYCODE_RO +- KEYCODE_S +- KEYCODE_SCROLL_LOCK +- KEYCODE_SEARCH +- KEYCODE_SEMICOLON +- KEYCODE_SETTINGS +- KEYCODE_SHIFT_LEFT +- KEYCODE_SHIFT_RIGHT +- KEYCODE_SLASH +- KEYCODE_SLEEP +- KEYCODE_SOFT_LEFT +- KEYCODE_SOFT_RIGHT +- KEYCODE_SOFT_SLEEP +- KEYCODE_SPACE +- KEYCODE_STAR +- KEYCODE_STB_INPUT +- KEYCODE_STB_POWER +- KEYCODE_STEM_1 +- KEYCODE_STEM_2 +- KEYCODE_STEM_3 +- KEYCODE_STEM_PRIMARY +- KEYCODE_SWITCH_CHARSET +- KEYCODE_SYM +- KEYCODE_SYSRQ +- KEYCODE_SYSTEM_NAVIGATION_DOWN +- KEYCODE_SYSTEM_NAVIGATION_LEFT +- KEYCODE_SYSTEM_NAVIGATION_RIGHT +- KEYCODE_SYSTEM_NAVIGATION_UP +- KEYCODE_T +- KEYCODE_TAB +- KEYCODE_THUMBS_DOWN +- KEYCODE_THUMBS_UP +- KEYCODE_TV +- KEYCODE_TV_ANTENNA_CABLE +- KEYCODE_TV_AUDIO_DESCRIPTION +- KEYCODE_TV_AUDIO_DESCRIPTION_MIX_DOWN +- KEYCODE_TV_AUDIO_DESCRIPTION_MIX_UP +- KEYCODE_TV_CONTENTS_MENU +- KEYCODE_TV_DATA_SERVICE +- KEYCODE_TV_INPUT +- KEYCODE_TV_INPUT_COMPONENT_1 +- KEYCODE_TV_INPUT_COMPONENT_2 +- KEYCODE_TV_INPUT_COMPOSITE_1 +- KEYCODE_TV_INPUT_COMPOSITE_2 +- KEYCODE_TV_INPUT_HDMI_1 +- KEYCODE_TV_INPUT_HDMI_2 +- KEYCODE_TV_INPUT_HDMI_3 +- KEYCODE_TV_INPUT_HDMI_4 +- KEYCODE_TV_INPUT_VGA_1 +- KEYCODE_TV_MEDIA_CONTEXT_MENU +- KEYCODE_TV_NETWORK +- KEYCODE_TV_NUMBER_ENTRY +- KEYCODE_TV_POWER +- KEYCODE_TV_RADIO_SERVICE +- KEYCODE_TV_SATELLITE +- KEYCODE_TV_SATELLITE_BS +- KEYCODE_TV_SATELLITE_CS +- KEYCODE_TV_SATELLITE_SERVICE +- KEYCODE_TV_TELETEXT +- KEYCODE_TV_TERRESTRIAL_ANALOG +- KEYCODE_TV_TERRESTRIAL_DIGITAL +- KEYCODE_TV_TIMER_PROGRAMMING +- KEYCODE_TV_ZOOM_MODE +- KEYCODE_U +- KEYCODE_UNKNOWN +- KEYCODE_V +- KEYCODE_VOICE_ASSIST +- KEYCODE_VOLUME_DOWN +- KEYCODE_VOLUME_MUTE +- KEYCODE_VOLUME_UP +- KEYCODE_W +- KEYCODE_WAKEUP +- KEYCODE_WINDOW +- KEYCODE_X +- KEYCODE_Y +- KEYCODE_YEN +- KEYCODE_Z +- KEYCODE_ZENKAKU_HANKAKU +- KEYCODE_ZOOM_IN +- KEYCODE_ZOOM_OUT ## Full Example ### Sample Thing -``` +```java Thing androiddebugbridge:android:xxxxxxxxxxxx "xxxxxxxxxxxx" [ ip="192.168.1.10", port=5555, refreshTime=30 ] ``` ### Sample Items -``` +```java Group androidDevice "Android TV" String device_SendKey "Send Key" (androidDevice) { channel="androiddebugbridge:android:xxxxxxxxxxxx:key-event" } String device_CurrentApp "Current App" (androidDevice) { channel="androiddebugbridge:android:xxxxxxxxxxxx:current-package" } diff --git a/bundles/org.openhab.binding.anel/README.md b/bundles/org.openhab.binding.anel/README.md index e2189cb5c8f..193e7077299 100644 --- a/bundles/org.openhab.binding.anel/README.md +++ b/bundles/org.openhab.binding.anel/README.md @@ -5,7 +5,6 @@ Monitor and control Anel NET-PwrCtrl devices. NET-PwrCtrl devices are power sockets / relays that can be configured via browser but they can also be controlled over the network, e.g. with an Android or iPhone app - and also with openHAB via this binding. Some NET-PwrCtrl devices also have 8 I/O ports which can either be used to directly switch the sockets / relays, or they can be used as general input / output switches in openHAB. - ## Supported Things There are three kinds of devices ([overview on manufacturer's homepage](https://en.anel.eu/?src=/produkte/produkte.htm)): @@ -16,29 +15,27 @@ There are three kinds of devices ([overview on manufacturer's homepage](https:// Thing type IDs: -* *home*: The smallest device, the _HOME_, is the only one with only three power sockets and only available in Germany. -* *simple-firmware*: The _PRO_ and _REDUNDANT_ have eight power sockets and a similar (simplified) firmware as the _HOME_. -* *advanced-firmware*: All others (_ADV_, _IO_, and the different _HUT_ variants) have eight power sockets / relays, eight IO ports, and an advanced firmware. +- _home_: The smallest device, the _HOME_, is the only one with only three power sockets and only available in Germany. +- _simple-firmware_: The _PRO_ and _REDUNDANT_ have eight power sockets and a similar (simplified) firmware as the _HOME_. +- _advanced-firmware_: All others (_ADV_, _IO_, and the different _HUT_ variants) have eight power sockets / relays, eight IO ports, and an advanced firmware. An [additional sensor](https://en.anel.eu/?src=/produkte/sensor_1/sensor_1.htm) may be used for monitoring temperature, humidity, and brightness. The sensor can be attached to a _HUT_ device via an Ethernet cable (max length is 50m). - ## Discovery Devices can be discovered automatically if their UDP ports are configured as follows: -* 75 / 77 (default) -* 750 / 770 -* 7500 / 7700 -* 7750 / 7770 +- 75 / 77 (default) +- 750 / 770 +- 7500 / 7700 +- 7750 / 7770 If a device is found for a specific port (excluding the default port), the subsequent port is also scanned, e.g. 7500/7700 → 7501/7701 → 7502/7702 → etc. Depending on the network switch and router devices, discovery may or may not work on wireless networks. It should work reliably though on local wired networks. - ## Thing Configuration Each Thing requires the following configuration parameters. @@ -56,14 +53,13 @@ Ports above 1024 are recommended because they are outside the range of system po Possible entries in your thing file could be (thing types _home_, _simple-firmware_, and _advanced-firmware_ are explained above in _Supported Things_): -``` +```java anel:home:mydevice1 [hostname="192.168.0.101", udpSendPort=7500, udpReceivePort=7700, user="user7", password="anel"] anel:simple-firmware:mydevice2 [hostname="192.168.0.102", udpSendPort=7501, udpReceivePort=7701, user="user7", password="anel"] anel:advanced-firmware:mydevice3 [hostname="192.168.0.103", udpSendPort=7502, udpReceivePort=7702, user="user7", password="anel"] anel:advanced-firmware:mydevice4 [hostname="192.168.0.104", udpSendPort=7503, udpReceivePort=7703, user="user7", password="anel"] ``` - ## Channels Depending on the thing type, the following channels are available. @@ -127,18 +123,17 @@ Depending on the thing type, the following channels are available. \* Relay / socket state is read-only if it is locked; otherwise it is changeable.
\** IO port state is read-only if its mode is _input_, it is changeable if its mode is _output_. - ## Full Example `.things` file: -``` +```java Thing anel:advanced-firmware:anel1 "Anel1" [hostname="192.168.0.100", udpSendPort=7500, udpReceivePort=7700, user="user7", password="anel"] ``` `.items` file: -``` +```java // device properties String anel1name "Anel1 Name" {channel="anel:advanced-firmware:anel1:prop#name"} Number:Temperature anel1temperature "Anel1 Temperature" {channel="anel:advanced-firmware:anel1:prop#temperature"} @@ -175,7 +170,7 @@ Switch anel1io8state "Reed Contact Door" {channel="anel:advanced-firmware:ane `.sitemap` file: -``` +```perl sitemap anel label="Anel NET-PwrCtrl" { Frame label="Device and Sensor" { Text item=anel1name label="Anel1 Name" @@ -214,7 +209,7 @@ The locked state / IO mode is also rarely relevant in practice, because it typic `.rules` file: -``` +```java rule "doorbell only at daytime" when Item anel1io6state changed then if (now.getHoursOfDay >= 6 && now.getHoursOfDay <= 22) { @@ -224,8 +219,6 @@ when Item anel1io6state changed then end ``` - ## Reference Documentation The UDP protocol of Anel devices is explained [here](https://forum.anel.eu/viewtopic.php?f=16&t=207). - diff --git a/bundles/org.openhab.binding.astro/README.md b/bundles/org.openhab.binding.astro/README.md index 0e692f42559..0ba39332f63 100644 --- a/bundles/org.openhab.binding.astro/README.md +++ b/bundles/org.openhab.binding.astro/README.md @@ -1,9 +1,9 @@ # Astro Binding -The Astro binding is used for calculating +The Astro binding is used for calculating -* many DateTime and positional values for sun and moon. -* Radiation levels (direct, diffuse and total) of the sun during the day +- many DateTime and positional values for sun and moon. +- Radiation levels (direct, diffuse and total) of the sun during the day ## Supported Things @@ -21,7 +21,7 @@ No binding configuration required. ## Thing Configuration -All Things require the parameter `geolocation` (as `,[,]`) for which the calculation is done. +All Things require the parameter `geolocation` (as `,[,]`) for which the calculation is done. The altitude segment is optional and sharpens results provided by the Radiation group. Optionally, a refresh `interval` (in seconds) can be defined to also calculate positional data like azimuth and elevation. @@ -30,88 +30,88 @@ This is done by setting `useMeteorologicalSeason` to true in the advanced settin ## Channels -* **thing** `sun` - * **group** `rise, set, noon, night, morningNight, astroDawn, nauticDawn, civilDawn, astroDusk, nauticDusk, civilDusk, eveningNight, daylight` - * **channel** - * `start, end` (DateTime) - * `duration` (Number:Time) - * **group** `position` - * **channel** - * `azimuth, elevation` (Number:Angle) - * `shadeLength` (Number) - * **group** `radiation` - * **channel** - * `direct, diffuse, total` (Number:Intensity) - * **group** `zodiac` - * **channel** - * `start, end` (DateTime) - * `sign` (String), values: `ARIES, TAURUS, GEMINI, CANCER, LEO, VIRGO, LIBRA, SCORPIO, SAGITTARIUS, CAPRICORN, AQUARIUS, PISCES` - * **group** `season` - * **channel**: - * `spring, summer, autumn, winter` (DateTime) - * `name`,`nextName` (String), values `SPRING, SUMMER, AUTUMN, WINTER` - * `timeLeft` (Number:Time) - * **group** `eclipse` - * **channel**: - * `total, partial, ring` (DateTime) - * `totalElevation, partialElevation, ringElevation` (Number:Angle) - * **group** `phase` - * **channel** - * `name` (String), values: `SUN_RISE, ASTRO_DAWN, NAUTIC_DAWN, CIVIL_DAWN, CIVIL_DUSK, NAUTIC_DUSK, ASTRO_DUSK, SUN_SET, DAYLIGHT, NIGHT` -* **thing** `moon` - * **group** `rise, set` - * **channel** - * `start, end` (DateTime) - * **group** `phase` - * **channel**: - * `firstQuarter, thirdQuarter, full, new` (DateTime) - * `age` (Number:Time) - * `ageDegree` (Number:Angle) - * `agePercent, illumination` (Number:Dimensionless) - * `name` (String), values: `NEW, WAXING_CRESCENT, FIRST_QUARTER, WAXING_GIBBOUS, FULL, WANING_GIBBOUS, THIRD_QUARTER, WANING_CRESCENT` - * **group** `eclipse` - * **channel**: - * `total, partial` (DateTime) - * `totalElevation, partialElevation` (Number:Angle) - * **group** `distance` - * **channel**: - * `date` (DateTime) - * `distance` (Number:Length) - * **group** `perigee` - * **channel**: - * `date` (DateTime), - * `distance` (Number:Length) - * **group** `apogee` - * **channel**: - * `date` (DateTime) - * `distance` (Number:Length) - * **group** `zodiac` - * **channel** - * `sign` (String), values: `ARIES, TAURUS, GEMINI, CANCER, LEO, VIRGO, LIBRA, SCORPIO, SAGITTARIUS, CAPRICORN, AQUARIUS, PISCES` - * **group** `position` - * **channel** - * `azimuth, elevation` (Number:Angle) +- **thing** `sun` + - **group** `rise, set, noon, night, morningNight, astroDawn, nauticDawn, civilDawn, astroDusk, nauticDusk, civilDusk, eveningNight, daylight` + - **channel** + - `start, end` (DateTime) + - `duration` (Number:Time) + - **group** `position` + - **channel** + - `azimuth, elevation` (Number:Angle) + - `shadeLength` (Number) + - **group** `radiation` + - **channel** + - `direct, diffuse, total` (Number:Intensity) + - **group** `zodiac` + - **channel** + - `start, end` (DateTime) + - `sign` (String), values: `ARIES, TAURUS, GEMINI, CANCER, LEO, VIRGO, LIBRA, SCORPIO, SAGITTARIUS, CAPRICORN, AQUARIUS, PISCES` + - **group** `season` + - **channel**: + - `spring, summer, autumn, winter` (DateTime) + - `name`,`nextName` (String), values `SPRING, SUMMER, AUTUMN, WINTER` + - `timeLeft` (Number:Time) + - **group** `eclipse` + - **channel**: + - `total, partial, ring` (DateTime) + - `totalElevation, partialElevation, ringElevation` (Number:Angle) + - **group** `phase` + - **channel** + - `name` (String), values: `SUN_RISE, ASTRO_DAWN, NAUTIC_DAWN, CIVIL_DAWN, CIVIL_DUSK, NAUTIC_DUSK, ASTRO_DUSK, SUN_SET, DAYLIGHT, NIGHT` +- **thing** `moon` + - **group** `rise, set` + - **channel** + - `start, end` (DateTime) + - **group** `phase` + - **channel**: + - `firstQuarter, thirdQuarter, full, new` (DateTime) + - `age` (Number:Time) + - `ageDegree` (Number:Angle) + - `agePercent, illumination` (Number:Dimensionless) + - `name` (String), values: `NEW, WAXING_CRESCENT, FIRST_QUARTER, WAXING_GIBBOUS, FULL, WANING_GIBBOUS, THIRD_QUARTER, WANING_CRESCENT` + - **group** `eclipse` + - **channel**: + - `total, partial` (DateTime) + - `totalElevation, partialElevation` (Number:Angle) + - **group** `distance` + - **channel**: + - `date` (DateTime) + - `distance` (Number:Length) + - **group** `perigee` + - **channel**: + - `date` (DateTime), + - `distance` (Number:Length) + - **group** `apogee` + - **channel**: + - `date` (DateTime) + - `distance` (Number:Length) + - **group** `zodiac` + - **channel** + - `sign` (String), values: `ARIES, TAURUS, GEMINI, CANCER, LEO, VIRGO, LIBRA, SCORPIO, SAGITTARIUS, CAPRICORN, AQUARIUS, PISCES` + - **group** `position` + - **channel** + - `azimuth, elevation` (Number:Angle) ### Trigger Channels -* **thing** `sun` - * **group** `rise, set, noon, night, morningNight, astroDawn, nauticDawn, civilDawn, astroDusk, nauticDusk, civilDusk, eveningNight, daylight` - * **event** `START, END` - * **group** `eclipse` - * **event**: `TOTAL, PARTIAL, RING` -* **thing** `moon` - * **group** `rise` - * **event** `START` - * **group** `set` - * **event** `END` - * **group** `phase` - * **event**: `FIRST_QUARTER, THIRD_QUARTER, FULL, NEW` - * **group** `eclipse` - * **event**: `TOTAL, PARTIAL` - * **group** `perigee` - * **event**: `PERIGEE` - * **group** `apogee` - * **event**: `APOGEE` +- **thing** `sun` + - **group** `rise, set, noon, night, morningNight, astroDawn, nauticDawn, civilDawn, astroDusk, nauticDusk, civilDusk, eveningNight, daylight` + - **event** `START, END` + - **group** `eclipse` + - **event**: `TOTAL, PARTIAL, RING` +- **thing** `moon` + - **group** `rise` + - **event** `START` + - **group** `set` + - **event** `END` + - **group** `phase` + - **event**: `FIRST_QUARTER, THIRD_QUARTER, FULL, NEW` + - **group** `eclipse` + - **event**: `TOTAL, PARTIAL` + - **group** `perigee` + - **event**: `PERIGEE` + - **group** `apogee` + - **event**: `APOGEE` ### Channel config @@ -134,14 +134,14 @@ sunset is 22:10 but `latest` is set to 20:00 so the event/datetime value is move Things: -``` +```java astro:sun:home [ geolocation="52.5200066,13.4049540,100", interval=60 ] astro:moon:home [ geolocation="52.5200066,13.4049540", interval=60 ] ``` or optionally with an event offset -``` +```java astro:sun:home [ geolocation="52.5200066,13.4049540,100", interval=60 ] { Channels: Type rangeEvent : rise#event [ @@ -153,7 +153,7 @@ astro:moon:home [ geolocation="52.5200066,13.4049540", interval=60 ] or a datetime offset -``` +```java astro:sun:home [ geolocation="52.5200066,13.4049540,100", interval=60 ] { Channels: Type start : rise#start [ @@ -167,7 +167,7 @@ astro:sun:home [ geolocation="52.5200066,13.4049540,100", interval=60 ] { or an offset and latest -``` +```java astro:sun:home [ geolocation="52.5200066,13.4049540,100", interval=60 ] { Channels: Type rangeEvent : rise#event [ @@ -179,7 +179,7 @@ astro:sun:home [ geolocation="52.5200066,13.4049540,100", interval=60 ] { Items: -``` +```java DateTime Sunrise_Time "Sunrise [%1$tH:%1$tM]" { channel="astro:sun:home:rise#start" } DateTime Sunset_Time "Sunset [%1$tH:%1$tM]" { channel="astro:sun:home:set#start" } Number:Angle Azimuth "Azimuth" { channel="astro:sun:home:position#azimuth" } @@ -192,7 +192,7 @@ Number:Intensity Diffuse_Radiation "Diffuse Radiation [%.2f %unit%]" { Events: -``` +```java rule "example trigger rule" when Channel 'astro:sun:home:rise#event' triggered START @@ -207,7 +207,7 @@ Multiple actions are supported by this binding. In classic rules these are acces Getting sunActions variable in scripts -``` +```java val sunActions = getActions("astro","astro:sun:local") if(null === sunActions) { logInfo("actions", "sunActions not found, check thing ID") @@ -222,15 +222,15 @@ Getting sunActions variable in scripts Retrieves date and time (ZonedDateTime) of the requested phase name. Thing method only applies to Sun thing type. -* `phaseName` (String), values: `SUN_RISE, ASTRO_DAWN, NAUTIC_DAWN, CIVIL_DAWN, CIVIL_DUSK, NAUTIC_DUSK, ASTRO_DUSK, SUN_SET, DAYLIGHT, NIGHT`. Mandatory. +- `phaseName` (String), values: `SUN_RISE, ASTRO_DAWN, NAUTIC_DAWN, CIVIL_DAWN, CIVIL_DUSK, NAUTIC_DUSK, ASTRO_DUSK, SUN_SET, DAYLIGHT, NIGHT`. Mandatory. -* `date` (ZonedDateTime), only the date part of this parameter will be considered - defaulted to now() if null. +- `date` (ZonedDateTime), only the date part of this parameter will be considered - defaulted to now() if null. -* `moment` (String), values: `START, END` - defaulted to `START` if null. +- `moment` (String), values: `START, END` - defaulted to `START` if null. Example : -``` +```java val sunEvent = "SUN_SET" val today = ZonedDateTime.now; val sunEventTime = sunActions.getEventTime(sunEvent,today,"START") @@ -242,25 +242,23 @@ Example : Retrieves the elevation (QuantityType) of the sun at the requested instant. Thing method applies to Sun and Moon. -* `timeStamp` (ZonedDateTime) - defaulted to now() if null. - +- `timeStamp` (ZonedDateTime) - defaulted to now() if null. ### getAzimuth(timeStamp) Retrieves the azimuth (QuantityType) of the sun at the requested instant. Thing method applies to Sun and Moon. -* `timeStamp` (ZonedDateTime) - defaulted to now() if null. +- `timeStamp` (ZonedDateTime) - defaulted to now() if null. Example : -``` +```java val azimuth = sunActions.getAzimuth(sunEventTime) val elevation = sunActions.getElevation(sunEventTime) logInfo("AstroActions", "{} will be positioned at elevation {} - azimuth {}",sunEvent, elevation.toString,azimuth.toString) ``` - ## Tips Do not worry if for example the "astro dawn" is undefined at your location. diff --git a/bundles/org.openhab.binding.atlona/README.md b/bundles/org.openhab.binding.atlona/README.md index 6bf50b568f1..374916422d2 100644 --- a/bundles/org.openhab.binding.atlona/README.md +++ b/bundles/org.openhab.binding.atlona/README.md @@ -1,7 +1,7 @@ # Atlona Binding This binding integrates Atlona AT-UHD-PRO3 HdBaseT matrix switches [Atlona AT-UHD-PRO3 HdBaseT matrix switches](https://www.atlona.com) into your openHAB installation. -The older HD model 6x6 matrix [AT-PRO3HD66M] (https://atlona.com/product/at-pro3hd66m/) is also supported. +The older HD model 6x6 matrix [AT-PRO3HD66M](https://atlona.com/product/at-pro3hd66m/) is also supported. ## Supported Things @@ -190,14 +190,14 @@ The # of presets allowed depends on the firmware you are using (5 presets up to As of firmware 1.6.03 (rev 13), there are three issues on Atlona firmware (I have notified them on these issues): -- clearX command does not work. The TCP/IP command "ClearX" as specified in Atlona's protocol will ALWAYS return a "Command Failed". Please avoid this channel until atlona releases a new firmware. +- clearX command does not work. The TCP/IP command "ClearX" as specified in Atlona's protocol will ALWAYS return a "Command Failed". Please avoid this channel until atlona releases a new firmware. -- There is no way to query what the current status is of: panellock, and irenable. This add-on simply assumes that panellock is off and irenable is on at startup. +- There is no way to query what the current status is of: panellock, and irenable. This add-on simply assumes that panellock is off and irenable is on at startup. -- If you make a change in the switches UI that requires a reboot (mainly changing any of the settings on the "Network" tab in the switch configuration UI), this add-on's connection will be inconsistently closed at different times. +- If you make a change in the switches UI that requires a reboot (mainly changing any of the settings on the "Network" tab in the switch configuration UI), this add-on's connection will be inconsistently closed at different times. The thing will go OFFLINE and then back ONLINE when the reconnect attempt is made - and then it starts all over again. Please make sure you reboot as soon as possible when the switch UI notifies you. -- a bug in the firmware will sometimes cause memory presets to disappear after a reboot +- a bug in the firmware will sometimes cause memory presets to disappear after a reboot As of firmware 1.6.8 (rev 14), @@ -211,19 +211,19 @@ As of firmware 1.6.8 (rev 14), Here is an example with minimal configuration parameters (using default values with no telnet login): -``` +```java atlona:pro3-88m:home [ ipAddress="192.168.1.30" ] ``` Here is another example with minimal configuration parameters (using default values with telnet login): -``` +```java atlona:pro3-88m:home [ ipAddress="192.168.1.30", userName="me", password="12345" ] ``` Here is a full configuration example: -``` +```java atlona:pro3-88m:home [ ipAddress="192.168.1.30", userName="me", password="12345", polling=600, ping=30, retryPolling=10 ] ``` @@ -231,7 +231,7 @@ atlona:pro3-88m:home [ ipAddress="192.168.1.30", userName="me", password="12345" Here is an example of items for the AT-UHD-PRO33-88M: -``` +```java Switch Atlona_Power "Power" { channel = "atlona:pro3-88m:home:primary#power" } Switch Atlona_PanelLock "Panel Lock" { channel = "atlona:pro3-88m:home:primary#panellock" } Switch Atlona_Presets "Preset Command" { channel = "atlona:pro3-88m:home:primary#presetcmd" } @@ -274,7 +274,7 @@ Switch Atlona_VolumeMute6 "Mute 6" { channel = "atlona:pro3-88m:home:volume1#vol ### SiteMap -``` +```perl sitemap demo label="Main Menu" { Frame label="Atlona" { Text label="Device" { @@ -332,7 +332,7 @@ Be sure they are in sync with the mappings above. ### atlonainputports.map -``` +```text 1=CableBox 2=BluRay Player 3=Roku @@ -347,7 +347,7 @@ NULL=- ### atlonaoutputports.map -``` +```text 1=Living Room 2=Master Bed 3=Kitchen diff --git a/bundles/org.openhab.binding.autelis/README.md b/bundles/org.openhab.binding.autelis/README.md index 6b002dfcfd5..8d28ea6828e 100644 --- a/bundles/org.openhab.binding.autelis/README.md +++ b/bundles/org.openhab.binding.autelis/README.md @@ -5,10 +5,9 @@ See [the Autelis website](https://www.autelis.com) and the [Autelis Command Prot This binding supports: -* Jandy and Pentair models -* Read circuit, auxiliary, temperature, pump, chemistry and system values -* Control circuit, auxiliary lighting scenes, and temperature set points - +- Jandy and Pentair models +- Read circuit, auxiliary, temperature, pump, chemistry and system values +- Control circuit, auxiliary lighting scenes, and temperature set points ## Auto Discovery @@ -25,13 +24,13 @@ The Autelis binding requires the host, port, username and password In the thing file, this looks e.g. like -``` +```java Thing autelis:pentair:myPool [ host="192.168.1.10", port="80", user="admin", password="admin"] ``` or -``` +```java Thing autelis:jandy:myPool [ host="192.168.1.10", port="80", user="admin", password="admin"] ``` diff --git a/bundles/org.openhab.binding.automower/README.md b/bundles/org.openhab.binding.automower/README.md index e39532316a4..d5daa4af06a 100644 --- a/bundles/org.openhab.binding.automower/README.md +++ b/bundles/org.openhab.binding.automower/README.md @@ -11,7 +11,6 @@ This binding allows you to integrate, view and control Automower lawn mowers in All Husqvarna Automower models with "Automower Connect" should be supported. It was tested only with a Husqvarna Automower 430X and 450X. - ## Discovery Once the bridge is created and configured, OpenHab will automatically discover all Automowers registered on your account. @@ -125,7 +124,6 @@ Channel `last-position` is always identical with channel `position01` and thus p | position50 | Location | R | GPS Position 50 | | last-position | Location | R | Last GPS Position (identical with positions#position01) | - ## Actions The following actions are available for `automower`things: @@ -139,44 +137,44 @@ The following actions are available for `automower`things: | park | duration (int) | Parks the automower for the given duration (minutes), overriding the schedule | | resumeSchedule | - | Resumes the schedule for the automower | - ## Full Example ### automower.thing - Bridge automower:bridge:mybridge [ appKey="", userName="", password="" ] { - Thing automower myAutomower [ mowerId="", pollingInterval=3600] { - } - } - +```java +Bridge automower:bridge:mybridge [ appKey="", userName="", password="" ] { + Thing automower myAutomower [ mowerId="", pollingInterval=3600] { + } +} +``` ### automower.items - String Automower_Mode "Mode [%s]" { channel="automower:automower:mybridge:myAutomower:mode" } - String Automower_Activity "Activity [%s]" { channel="automower:automower:mybridge:myAutomower:activity" } - String Automower_State "State [%s]" { channel="automower:automower:mybridge:myAutomower:state" } - DateTime Automower_Last_Update "Last Update" { channel="automower:automower:mybridge:myAutomower:last-update" } - Number Automower_Battery "Battery [%d %%]" { channel="automower:automower:mybridge:myAutomower:battery" } - Number Automower_Error_Code "Error Code [%d]" { channel="automower:automower:mybridge:myAutomower:error-code" } - DateTime Automower_Error_Time "Error Time" { channel="automower:automower:mybridge:myAutomower:error-timestamp" } - String Automower_Override_Action "Override Action [%s]" { channel="automower:automower:mybridge:myAutomower:planner-override-action" } - DateTime Automower_Next_Start_Time "Next Start Time" { channel="automower:automower:mybridge:myAutomower:planner-next-start" } - String Automower_Calendar_Tasks "Planned Tasks [%s]" { channel="automower:automower:mybridge:myAutomower:calendar-tasks" } +```java +String Automower_Mode "Mode [%s]" { channel="automower:automower:mybridge:myAutomower:mode" } +String Automower_Activity "Activity [%s]" { channel="automower:automower:mybridge:myAutomower:activity" } +String Automower_State "State [%s]" { channel="automower:automower:mybridge:myAutomower:state" } +DateTime Automower_Last_Update "Last Update" { channel="automower:automower:mybridge:myAutomower:last-update" } +Number Automower_Battery "Battery [%d %%]" { channel="automower:automower:mybridge:myAutomower:battery" } +Number Automower_Error_Code "Error Code [%d]" { channel="automower:automower:mybridge:myAutomower:error-code" } +DateTime Automower_Error_Time "Error Time" { channel="automower:automower:mybridge:myAutomower:error-timestamp" } +String Automower_Override_Action "Override Action [%s]" { channel="automower:automower:mybridge:myAutomower:planner-override-action" } +DateTime Automower_Next_Start_Time "Next Start Time" { channel="automower:automower:mybridge:myAutomower:planner-next-start" } +String Automower_Calendar_Tasks "Planned Tasks [%s]" { channel="automower:automower:mybridge:myAutomower:calendar-tasks" } - Number Automower_Command_Start "Start mowing for duration [%d min]" { channel="automower:automower:mybridge:myAutomower:start" } - Switch Automower_Command_Resume "Resume the schedule" { channel="automower:automower:mybridge:myAutomower:resume_schedule" } - Switch Automower_Command_Pause "Pause the automower" { channel="automower:automower:mybridge:myAutomower:pause" } - Number Automower_Command_Park "Park for duration [%d min]" { channel="automower:automower:mybridge:myAutomower:park" } - Switch Automower_Command_Park_Next_Schedule "Park until next schedule" { channel="automower:automower:mybridge:myAutomower:park_until_next_schedule" } - Switch Automower_Command_Park_Notice "Park until further notice" { channel="automower:automower:mybridge:myAutomower:park_until_further_notice" } +Number Automower_Command_Start "Start mowing for duration [%d min]" { channel="automower:automower:mybridge:myAutomower:start" } +Switch Automower_Command_Resume "Resume the schedule" { channel="automower:automower:mybridge:myAutomower:resume_schedule" } +Switch Automower_Command_Pause "Pause the automower" { channel="automower:automower:mybridge:myAutomower:pause" } +Number Automower_Command_Park "Park for duration [%d min]" { channel="automower:automower:mybridge:myAutomower:park" } +Switch Automower_Command_Park_Next_Schedule "Park until next schedule" { channel="automower:automower:mybridge:myAutomower:park_until_next_schedule" } +Switch Automower_Command_Park_Notice "Park until further notice" { channel="automower:automower:mybridge:myAutomower:park_until_further_notice" } - Location Automower_Last_Position "Last Position" { channel="automower:automower:mybridge:myAutomower:last-position" } - +Location Automower_Last_Position "Last Position" { channel="automower:automower:mybridge:myAutomower:last-position" } +``` ### automower.sitemap - -``` +```perl sitemap demo label="Automower" { Frame { @@ -198,7 +196,7 @@ sitemap demo label="Automower" Example rule that triggers an automower action -``` +```java rule "AutomowerParkUntilFurtherNotice" when Item Some_Item changed to ON diff --git a/bundles/org.openhab.binding.avmfritz/README.md b/bundles/org.openhab.binding.avmfritz/README.md index d0421234a9f..e16cb272e68 100644 --- a/bundles/org.openhab.binding.avmfritz/README.md +++ b/bundles/org.openhab.binding.avmfritz/README.md @@ -15,13 +15,13 @@ This procedure opens TCP/IP port 1012 on your FRITZ!Box. (It can be deactivated again by dialing `#96*4*`.) You can test if everything is working with the Telnet program from your openHAB server: -``` +```shell telnet fritz.box 1012 ``` If you see an output like this: -``` +```shell Trying 192.168.178.1... Connected to fritz.box. Escape character is '^]'. @@ -65,7 +65,7 @@ The FRITZ!Box has to run at least on firmware FRITZ!OS 6.35. The [FRITZ!DECT 400](https://avm.de/produkte/fritzdect/fritzdect-400/) and [FRITZ!DECT 440](https://avm.de/produkte/fritzdect/fritzdect-440/) are buttons for convenient operation of FRITZ! Smart Home devices (FRITZ!OS 7.08 or higher for FRITZ!DECT 400, 7.20 or higher for FRITZ!DECT 440). The FRITZ!DECT 400 supports a configurable button to trigger short or long press events. Beside four customizable buttons the FRITZ!DECT 440 supports temperature readings. -** NOTE: ** FRITZ!DECT 440 now uses Channel Groups to group its Channels like `device#battery_level`, `device#battery_low` for device information, `sensors#temperature` for sensor data and `top-left`, `bottom-left`, `top-right` and `bottom-right` combined with `press` and `last_change` (see [Full Example](#full-example)) +**NOTE:** FRITZ!DECT 440 now uses Channel Groups to group its Channels like `device#battery_level`, `device#battery_low` for device information, `sensors#temperature` for sensor data and `top-left`, `bottom-left`, `top-right` and `bottom-right` combined with `press` and `last_change` (see [Full Example](#full-example)) ### FRITZ!DECT 500 @@ -99,7 +99,7 @@ The use of other Sensors should be possible, if these are compatible with DECT-U The FRITZ!Box has to run at least on firmware FRITZ!OS 7. -### FRITZ! Groups +### FRITZ! Groups The FRITZ!OS supports two different types of groups. On the one hand there are groups for heating thermostats on the other hand there are groups for switchable outlets and power meters. @@ -126,7 +126,7 @@ To do so Auto-discovery is enabled by default. To disable it, you can add the following line to `/services/runtime.cfg`: -``` +```text discovery.avmfritz:background=false ``` @@ -217,13 +217,13 @@ The trigger channel `press` for a FRITZ!DECT 400 device is of type `system.butto With the new [templates feature](https://en.avm.de/guide/smart-home/meet-the-smart-home-templates-from-fritz/) in FRITZ!OS 7, you can now save the settings of your Smart Home devices and groups as a template for certain occasions e.g. holidays or vacation. Unfortunately it is not that simple to find out the unique identifier (AIN) for a template needed for sending it as command to the `apply_template` channel. Here is a work-around: -To retrieve the list of AINs assigned by FRITZ! for your templates, go to the FRITZ!Box' Support page at http://fritz.box/html/support.html within your local network and login. +To retrieve the list of AINs assigned by FRITZ! for your templates, go to the FRITZ!Box' Support page at [http://fritz.box/html/support.html](http://fritz.box/html/support.html) within your local network and login. Then in the section "Support Data" ("Support-Daten") press the button "Create Support Data" ("Support-Daten erstellen") and save the generated text file. Open the file in a text editor and search for the term "avm_home_device_type_template". You will find entries like the attached one. The `identifyer 'tmpFC0F2C-3960B7EE6'` contains the templates AINs you need for using them in rules. -``` +```text Name 'Demo Template', identifyer 'tmpFC0F2C-3960B7EE6', firmware version '0.1' [aktive] ID 60013, emc 0x0, model 0x0, grouphash=0x0, devicetype 'avm_home_device_type_template', functionbitmask 0x4000, sortid 0, batt perc 255 low 255, pollinterval 0, polltimeout 0, validchangetime: 0 -------------------- @@ -245,8 +245,7 @@ end For heating devices and heating groups there are two actions available to set Boost or Window Open mode for a given duration: `setBoostMode(long)` and `setWindowOpenMode(long)`. The duration has to be given in seconds, min. 1, max. 86400, 0 for deactivation. - -``` +```java val actions = getActions("avmfritz","avmfritz:Comet_DECT:1:aaaaaabbbbbb") // set Boost mode for 5 min diff --git a/bundles/org.openhab.binding.awattar/README.md b/bundles/org.openhab.binding.awattar/README.md index 51798f2a7e5..ffa74f8528a 100644 --- a/bundles/org.openhab.binding.awattar/README.md +++ b/bundles/org.openhab.binding.awattar/README.md @@ -2,7 +2,6 @@ This binding provides access to the hourly prices for electricity for the German and Austrian provider aWATTar. - ## Supported Things There are three supported things. @@ -13,7 +12,7 @@ The `bridge` reads price data from the aWATTar API and stores the (optional) con ### Prices Thing -The `prices` Thing provides todays and (after 14:00) tomorrows net and gross prices. +The `prices` Thing provides todays and (after 14:00) tomorrows net and gross prices. ### Bestprice Thing @@ -27,7 +26,6 @@ Auto discovery is not supported. ### aWATTar Bridge - | Parameter | Description | |-------------|-------------------------------------------------------------------------------------------------------------------------------| | vatPercent | Percentage of the value added tax to apply to net prices. Optional, defaults to 19. | @@ -60,7 +58,7 @@ Also, due to the time the aWATTar API delivers the data for the next day, it doe ### Prices Thing For every hour, the `prices` thing provides the following prices: - + | channel | type | description | |----------|--------|------------------------------| | market-net | Number | This net market price per kWh. This is directly taken from the price the aWATTar API delivers. | @@ -68,17 +66,14 @@ For every hour, the `prices` thing provides the following prices: | total-net | Number | Sum of net market price and configured base price | | total-gross | Number | Sum of market and base price with VAT applied. Most probably this is the final price you will have to pay for one kWh in a certain hour | - All prices are available in each of the following channel groups: - | channel group | description | |----------|--------------------------------| | current | The prices for the current hour | | today00, today01, today02 ... today23 | Hourly prices for today. `today00` provides the price from 0:00 to 1:00, `today01` from 1:00 to 02:00 and so on. As long as the API is working, this data should always be available | | tomorrow00, tomorrow01, ... tomorrow23 | Hourly prices for the next day. They should be available starting at 14:00. | - ### Bestprice Thing | channel | type | description | @@ -90,24 +85,21 @@ All prices are available in each of the following channel groups: | remaining | Number:Time | The time in minutes until end of the bestprice range. If start time passed. the channel will be set to `UNDEFINED` until the values for the next day are available. | | hours | String | A comma separated list of hours this bestprice period contains. | - - - ## Full Example ### Things awattar.things: -``` +```java Bridge awattar:bridge:bridge1 "aWATTar Bridge" [ country="DE", vatPercent="19", basePrice="17.22"] { - Thing prices price1 "aWATTar Price" [] + Thing prices price1 "aWATTar Price" [] // The car should be loaded for 4 hours during the night - Thing bestprice carloader "Car Loader" [ rangeStart="22", rangeDuration="8", length="4", consecutive="true" ] + Thing bestprice carloader "Car Loader" [ rangeStart="22", rangeDuration="8", length="4", consecutive="true" ] // In the cheapest hour of the night the garden should be watered - Thing bestprice water "Water timer" [ rangeStart="19", rangeDuration="12", length="1" ] + Thing bestprice water "Water timer" [ rangeStart="19", rangeDuration="12", length="1" ] // The heatpump should run the 12 cheapest hours per day - Thing bestprice heatpump "Heat pump" [ length="12", consecutive="false" ] + Thing bestprice heatpump "Heat pump" [ length="12", consecutive="false" ] } ``` @@ -115,7 +107,7 @@ Bridge awattar:bridge:bridge1 "aWATTar Bridge" [ country="DE", vatPercent="19", awattar.items: -``` +```java Number:Dimensionless currentnet "Current price [%2.2f ct/kWh]" { channel="awattar:prices:bridge1:price1:current#market-net" } Number:Dimensionless currentgross "Current price [%2.2f ct/kWh]" { channel="awattar:prices:bridge1:price1:current#market-gross" } Number:Dimensionless totalnet "Current price [%2.2f ct/kWh]" { channel="awattar:prices:bridge1:price1:current#total-net" } @@ -184,74 +176,74 @@ Switch HeatpumpActive { channel="awattar:bestprice:bridge1:heatpump:active" } ### Sitemap -``` +```perl sitemap default label="aWATTar Sitemap" { - Frame label="Car Loader" { - Switch item=CarActive - Text item=CarCountdown - Text item=CarStart - Text item=CarEnd - Text item=CarHours - } - Frame label="Current Prices" { - Text label="Current Net" item=currentnet - Text label="Current Gross" item=currentgross - Text label="Total Net" item=totalnet - Text label="Total Gross" item=totalgross - } - Frame label="Todays Prices (total gross)" { - Text item=today00 - Text item=today01 - Text item=today02 - Text item=today03 - Text item=today04 - Text item=today05 - Text item=today06 - Text item=today07 - Text item=today08 - Text item=today09 - Text item=today10 - Text item=today11 - Text item=today12 - Text item=today13 - Text item=today14 - Text item=today15 - Text item=today16 - Text item=today17 - Text item=today18 - Text item=today19 - Text item=today20 - Text item=today21 - Text item=today22 - Text item=today23 - } - Frame label="Tomorrows Prices (total gross)" { - Text item=tomorrow00 - Text item=tomorrow01 - Text item=tomorrow02 - Text item=tomorrow03 - Text item=tomorrow04 - Text item=tomorrow05 - Text item=tomorrow06 - Text item=tomorrow07 - Text item=tomorrow08 - Text item=tomorrow09 - Text item=tomorrow10 - Text item=tomorrow11 - Text item=tomorrow12 - Text item=tomorrow13 - Text item=tomorrow14 - Text item=tomorrow15 - Text item=tomorrow16 - Text item=tomorrow17 - Text item=tomorrow18 - Text item=tomorrow19 - Text item=tomorrow20 - Text item=tomorrow21 - Text item=tomorrow22 - Text item=tomorrow23 - } + Frame label="Car Loader" { + Switch item=CarActive + Text item=CarCountdown + Text item=CarStart + Text item=CarEnd + Text item=CarHours + } + Frame label="Current Prices" { + Text label="Current Net" item=currentnet + Text label="Current Gross" item=currentgross + Text label="Total Net" item=totalnet + Text label="Total Gross" item=totalgross + } + Frame label="Todays Prices (total gross)" { + Text item=today00 + Text item=today01 + Text item=today02 + Text item=today03 + Text item=today04 + Text item=today05 + Text item=today06 + Text item=today07 + Text item=today08 + Text item=today09 + Text item=today10 + Text item=today11 + Text item=today12 + Text item=today13 + Text item=today14 + Text item=today15 + Text item=today16 + Text item=today17 + Text item=today18 + Text item=today19 + Text item=today20 + Text item=today21 + Text item=today22 + Text item=today23 + } + Frame label="Tomorrows Prices (total gross)" { + Text item=tomorrow00 + Text item=tomorrow01 + Text item=tomorrow02 + Text item=tomorrow03 + Text item=tomorrow04 + Text item=tomorrow05 + Text item=tomorrow06 + Text item=tomorrow07 + Text item=tomorrow08 + Text item=tomorrow09 + Text item=tomorrow10 + Text item=tomorrow11 + Text item=tomorrow12 + Text item=tomorrow13 + Text item=tomorrow14 + Text item=tomorrow15 + Text item=tomorrow16 + Text item=tomorrow17 + Text item=tomorrow18 + Text item=tomorrow19 + Text item=tomorrow20 + Text item=tomorrow21 + Text item=tomorrow22 + Text item=tomorrow23 + } } ``` diff --git a/bundles/org.openhab.binding.benqprojector/README.md b/bundles/org.openhab.binding.benqprojector/README.md index aae33af4d17..1cc8b1b58d9 100644 --- a/bundles/org.openhab.binding.benqprojector/README.md +++ b/bundles/org.openhab.binding.benqprojector/README.md @@ -38,39 +38,39 @@ The `projector-tcp` thing has the following configuration parameters: Some notes: -* If using a serial port connection, the baud rate in the projector OSD menu must be set to 9600 bps. -* The _source_, _picturemode_ and _aspectratio_ channels include a dropdown with the most commonly used settings. -* Not all pre-defined dropdown options will be usable if your particular projector does support a given option. -* If your projector has an option that is not in the dropdown, the string code to access that option will be displayed by the channel when that option is selected by the remote control. -* By using the sitemap mapping or a rule to send that code back to the channel, any options that are missing in the binding can be accessed. +- If using a serial port connection, the baud rate in the projector OSD menu must be set to 9600 bps. +- The _source_, _picturemode_ and _aspectratio_ channels include a dropdown with the most commonly used settings. +- Not all pre-defined dropdown options will be usable if your particular projector does support a given option. +- If your projector has an option that is not in the dropdown, the string code to access that option will be displayed by the channel when that option is selected by the remote control. +- By using the sitemap mapping or a rule to send that code back to the channel, any options that are missing in the binding can be accessed. -* On Linux, you may get an error stating the serial port cannot be opened when the benqprojector binding tries to load. -* You can get around this by adding the `openhab` user to the `dialout` group like this: `usermod -a -G dialout openhab`. -* Also on Linux you may have issues with the USB if using two serial USB devices e.g. benqprojector and RFXcom. See the [general documentation about serial port configuration](/docs/administration/serial.html) for more on symlinking the USB ports. -* Here is an example of ser2net.conf you can use to share your serial port /dev/ttyUSB0 on IP port 4444 using [ser2net Linux tool](https://sourceforge.net/projects/ser2net/) (take care, the baud rate is specific to the BenQ projector): +- On Linux, you may get an error stating the serial port cannot be opened when the benqprojector binding tries to load. +- You can get around this by adding the `openhab` user to the `dialout` group like this: `usermod -a -G dialout openhab`. +- Also on Linux you may have issues with the USB if using two serial USB devices e.g. benqprojector and RFXcom. See the [general documentation about serial port configuration](/docs/administration/serial.html) for more on symlinking the USB ports. +- Here is an example of ser2net.conf you can use to share your serial port /dev/ttyUSB0 on IP port 4444 using [ser2net Linux tool](https://sourceforge.net/projects/ser2net/) (take care, the baud rate is specific to the BenQ projector): -``` +```text 4444:raw:0:/dev/ttyUSB0:9600 8DATABITS NONE 1STOPBIT LOCAL ``` ## Channels -| Channel | Item Type | Purpose | Values | -| ------------------ | --------- | --------------------------------------------------- | --------- | -| power | Switch | Powers the projector on or off. | | -| source | String | Retrieve or set the input source. | See above | -| picturemode | String | Retrieve or set the picture mode. | See above | -| aspectratio | String | Retrieve or set the aspect ratio. | See above | -| freeze | Switch | Turn the freeze image mode on or off. | | -| blank | Switch | Turn the screen blank mode on or off. | | -| directcmd | String | Send a command directly to the projector. | Send only | -| lamptime | Number | Retrieves the lamp hours. | Read only | +| Channel | Item Type | Purpose | Values | +| ------------------ | --------- | --------------------------------------------------- | --------- | +| power | Switch | Powers the projector on or off. | | +| source | String | Retrieve or set the input source. | See above | +| picturemode | String | Retrieve or set the picture mode. | See above | +| aspectratio | String | Retrieve or set the aspect ratio. | See above | +| freeze | Switch | Turn the freeze image mode on or off. | | +| blank | Switch | Turn the screen blank mode on or off. | | +| directcmd | String | Send a command directly to the projector. | Send only | +| lamptime | Number | Retrieves the lamp hours. | Read only | ## Full Example things/benq.things: -``` +```java // serial port connection benqprojector:projector-serial:hometheater "Projector" [ serialPort="COM5", pollingInterval=10 ] @@ -81,7 +81,7 @@ benqprojector:projector-tcp:hometheater "Projector" [ host="192.168.0.10", port= items/benq.items -``` +```java Switch benqPower { channel="benqprojector:projector-serial:hometheater:power" } String benqSource "Source [%s]" { channel="benqprojector:projector-serial:hometheater:source" } String benqPictureMode "Picture Mode [%s]" { channel="benqprojector:projector-serial:hometheater:picturemode" } @@ -94,7 +94,7 @@ Number benqLampTime "Lamp Time [%d h]" { channel="benqprojector:p sitemaps/benq.sitemap -``` +```perl sitemap benq label="BenQ Projector" { Frame label="Controls" { Switch item=benqPower label="Power" diff --git a/bundles/org.openhab.binding.bigassfan/README.md b/bundles/org.openhab.binding.bigassfan/README.md index 63a43e1c6eb..26aac3dffe3 100644 --- a/bundles/org.openhab.binding.bigassfan/README.md +++ b/bundles/org.openhab.binding.bigassfan/README.md @@ -36,7 +36,7 @@ In the event that any of this information is changed on the device, the thing co ### Manual Thing Creation -Fan and light things can be manually created using the *UI*, or by placing a *.things* file in the *conf/things* directory. +Fan and light things can be manually created using the _UI_, or by placing a _.things_ file in the _conf/things_ directory. See example below. ## Device Discovery @@ -46,7 +46,7 @@ Once added as a thing, the user can control the fan and light, similarly to how Background discovery polls the network every few minutes for devices. Background discovery is **enabled** by default. -To **disable** background discovery, add the following line to the *conf/services/runtime.cfg* file: +To **disable** background discovery, add the following line to the _conf/services/runtime.cfg_ file: ```text discovery.bigassfan:background=false @@ -179,7 +179,7 @@ Frame label="Control My Light" { ### Manual Thing Creation -Place a file named *bigassfan.things* in the *conf/things* directory. +Place a file named _bigassfan.things_ in the _conf/things_ directory. The file should contain lines formatted like this. ```java diff --git a/bundles/org.openhab.binding.bluetooth.airthings/README.md b/bundles/org.openhab.binding.bluetooth.airthings/README.md index 1f85091762d..5a54bdf5700 100644 --- a/bundles/org.openhab.binding.bluetooth.airthings/README.md +++ b/bundles/org.openhab.binding.bluetooth.airthings/README.md @@ -1,6 +1,6 @@ # Airthings -This extension adds support for [Airthings](https://www.airthings.com) indoor air quality monitor sensors. +This extension adds support for [Airthings](https://www.airthings.com) indoor air quality monitor sensors. ## Supported Things @@ -14,7 +14,7 @@ Following thing types are supported by this extension: ## Discovery -As any other Bluetooth device, Airthings devices are discovered automatically by the corresponding bridge. +As any other Bluetooth device, Airthings devices are discovered automatically by the corresponding bridge. ## Thing Configuration @@ -59,13 +59,13 @@ Note: For the `Airthings Wave Gen 1`, only one channel can be updated at each re airthings.things (assuming you have a Bluetooth bridge with the ID `bluetooth:bluegiga:adapter1`: -``` +```java bluetooth:airthings_wave_plus:adapter1:sensor1 "Airthings Wave Plus Sensor 1" (bluetooth:bluegiga:adapter1) [ address="12:34:56:78:9A:BC", refreshInterval=300 ] ``` airthings.items: -``` +```java Number:Temperature temperature "Temperature [%.1f %unit%]" { channel="bluetooth:airthings_wave_plus:adapter1:sensor1:temperature" } Number:Dimensionless humidity "Humidity [%d %unit%]" { channel="bluetooth:airthings_wave_plus:adapter1:sensor1:humidity" } Number:Pressure pressure "Air Pressure [%d %unit%]" { channel="bluetooth:airthings_wave_plus:adapter1:sensor1:pressure" } diff --git a/bundles/org.openhab.binding.bluetooth.am43/README.md b/bundles/org.openhab.binding.bluetooth.am43/README.md index 8a57fa4a803..91d9313e6a5 100644 --- a/bundles/org.openhab.binding.bluetooth.am43/README.md +++ b/bundles/org.openhab.binding.bluetooth.am43/README.md @@ -10,7 +10,6 @@ Following thing types are supported by this extension: |---------------|-------------------------------| | am43 | AM43 Blind Drive Motor | - ## Discovery As any other Bluetooth device, AM43 Blind Drive Motors are discovered automatically by the corresponding bridge. @@ -48,13 +47,13 @@ Following channels are supported for `AM43 Blind Drive Motor` thing: am43.things (assuming you have a Bluetooth bridge with the ID `bluetooth:bluegiga:adapter1`: -``` +```java bluetooth:am43:adapter1:motor1 "AM43 Blind Drive Motor 1" (bluetooth:bluegiga:adapter1) [ address="12:34:56:78:9A:BC", refreshInterval=300, invertPosition=false ] ``` am43.items: -``` +```java String direction "Direction [%s]" { channel="bluetooth:am43:adapter1:motor1:direction" } Switch topLimitSet "Top Limit Set" { channel="bluetooth:am43:adapter1:motor1:topLimitSet" } Switch bottomLimitSet "Bottom Limit Set" { channel="bluetooth:am43:adapter1:motor1:bottomLimitSet" } @@ -68,6 +67,3 @@ Number:Dimensionless type "Type [%.0f]" { channel="b Number:Dimensionless light_level "Light Level [%.0f]" { channel="bluetooth:am43:adapter1:motor1:lightLevel" } Number:Dimensionless battery_level "Battery Level [%.0f %%]" { channel="bluetooth:am43:adapter1:motor1:electric" } ``` - - - diff --git a/bundles/org.openhab.binding.bluetooth.bluegiga/README.md b/bundles/org.openhab.binding.bluetooth.bluegiga/README.md index 61a340bece3..de39f68b7d3 100644 --- a/bundles/org.openhab.binding.bluetooth.bluegiga/README.md +++ b/bundles/org.openhab.binding.bluetooth.bluegiga/README.md @@ -10,7 +10,6 @@ It defines the following bridge type: |----------------|---------------------------------------------------------------------------| | bluegiga | A BlueGiga USB dongle using a BLED112 chip | - ## Discovery The adapter cannot be discovered; its serial port must be manually configured. @@ -24,6 +23,6 @@ Additionally, the parameter `backgroundDiscovery` can be set to true/false. When This is how a BlueGiga adapter can be configured textually in a *.things file: -``` +```java Bridge bluetooth:bluegiga:1 [ port="/dev/ttyS0", backgroundDiscovery=false ] ``` diff --git a/bundles/org.openhab.binding.bluetooth.bluez/README.md b/bundles/org.openhab.binding.bluetooth.bluez/README.md index 8df6ce38e0c..1a11b16491d 100644 --- a/bundles/org.openhab.binding.bluetooth.bluez/README.md +++ b/bundles/org.openhab.binding.bluetooth.bluez/README.md @@ -30,7 +30,7 @@ sudo adduser openhab bluetooth Also, in case you don't want to manually enable your bluetooth adapters with `bluetoothctl`, ensure that it's automatically enabled by setting the option `AutoEnable` in your `/etc/bluetooth/main.conf` to `true`. Restart running services for changes to take effect. -``` +```shell systemctl restart dbus systemctl restart bluetooth systemctl restart openhab2 @@ -48,7 +48,6 @@ It defines the following bridge type: If BlueZ is enabled and can be accessed, all available adapters are automatically discovered. - ## Bridge Configuration The bluez bridge requires the configuration parameter `address`, which corresponds to the Bluetooth address of the adapter (in format "XX:XX:XX:XX:XX:XX"). @@ -59,6 +58,6 @@ Additionally, the parameter `backgroundDiscovery` can be set to true/false.When This is how a BlueZ adapter can be configured textually in a *.things file: -``` +```java Bridge bluetooth:bluez:hci0 [ address="12:34:56:78:90:AB", backgroundDiscovery=false ] ``` diff --git a/bundles/org.openhab.binding.bluetooth.blukii/README.md b/bundles/org.openhab.binding.bluetooth.blukii/README.md index 1d98626a230..52bf1b64048 100644 --- a/bundles/org.openhab.binding.bluetooth.blukii/README.md +++ b/bundles/org.openhab.binding.bluetooth.blukii/README.md @@ -1,6 +1,6 @@ # Blukii -This extension adds support for [Blukii](https://www.blukii.com/) Sensor Beacons. +This extension adds support for [Blukii](https://www.blukii.com/) Sensor Beacons. ## Supported Things @@ -12,7 +12,7 @@ Only a single thing type is added by this extension: ## Discovery -As any other Bluetooth device, Blukii Beacons are discovered automatically by the corresponding bridge. +As any other Bluetooth device, Blukii Beacons are discovered automatically by the corresponding bridge. ## Thing Configuration @@ -36,13 +36,13 @@ A Blukii Smart Beacon has the following channels: demo.things: -``` +```java bluetooth:blukii:hci0:beacon "Blukii Sensor Beacon" (bluetooth:bluez:hci0) [ address="12:34:56:78:9A:BC" ] ``` demo.items: -``` +```java Number:Temperature temperature "Room Temperature [%.1f %unit%]" { channel="bluetooth:blukii:hci0:beacon:temperature" } Number:Dimensionless humidity "Humidity [%.0f %unit%]" { channel="bluetooth:blukii:hci0:beacon:humidity" } Number:Pressure pressure "Air Pressure [%.0f %unit%]" { channel="bluetooth:blukii:hci0:beacon:pressure" } diff --git a/bundles/org.openhab.binding.bluetooth.daikinmadoka/README.md b/bundles/org.openhab.binding.bluetooth.daikinmadoka/README.md index 1f2e2461b78..4937eeca38f 100644 --- a/bundles/org.openhab.binding.bluetooth.daikinmadoka/README.md +++ b/bundles/org.openhab.binding.bluetooth.daikinmadoka/README.md @@ -7,34 +7,28 @@ The device uses an UART over BLE serial communication protocol over BLE WriteWit [BRC1H on Daikin website (EN)](https://www.daikin.eu/en_us/product-group/control-systems/BRC1H.html) - ## Supported Things - | Thing Type ID | Description | | ------------- | ----------- | | brc1h | BRC1H BLE Thermostat | - ## Discovery As a pairing of the Thermostat is necessary (Bluetooth), no automatic discovery is implemented. ## Thing Configuration -* address: The Bluetooth MAC Address of the BRC1H controller +- address: The Bluetooth MAC Address of the BRC1H controller Example with a DBusBlueZ Bluetooth Bridge: -``` - +```java Bridge bluetooth:dbusbluez:hci0 [ address="00:1A:7D:DA:71:13" ] Thing bluetooth:brc1h:hci0:salon (bluetooth:dbusbluez:hci0) [ address="00:CC:3F:B2:80:CA" ] - ``` - ## Channels _Here you should provide information about available channel types, what their meaning is and how they can be used._ @@ -64,8 +58,7 @@ _Note that it is planned to generate some part of this based on the XML files wi ### daikinmadoka.things: -``` - +```java Bridge bluetooth:dbusbluez:hci0 [ address="00:1A:7D:DA:71:13" ] Thing bluetooth:brc1h:hci0:salon (bluetooth:dbusbluez:hci0) [ address="00:CC:3F:B2:80:CA" ] @@ -74,8 +67,7 @@ Thing bluetooth:brc1h:hci0:salon (bluetooth:dbusbluez:hci0) [ address="00:CC ### daikinmadoka.items: -``` - +```java Group g_climSalon "Salon" [ "Thermostat" ] Switch climSalon_onOff "Climatisation Salon" (g_climSalon) { channel="bluetooth:brc1h:hci0:salon:onOffStatus" } @@ -104,12 +96,12 @@ This pairing process can be a bit challenging, as it seems the timing is very im We suggest that the Bluetooth adapter is not being used by another component during the pairing phase. As such, if you have other Bluetooth Things in your OpenHAB, it is suggested to stop the openHAB service before doing the pairing. - * Ensure that your BRC1H has Bluetooth enabled in the menu - * Open `bluetoothctl` on your openHAB server - preferably as `root` - * start scanning by typing `scan on` - * After few seconds, stop scanning `scan off` - * Start the pairing process by typing `pair ` - * On the BRC1H, confirm the pairing request, and quickly confirm as well on your server by typing `yes` +- Ensure that your BRC1H has Bluetooth enabled in the menu +- Open `bluetoothctl` on your openHAB server - preferably as `root` +- start scanning by typing `scan on` +- After few seconds, stop scanning `scan off` +- Start the pairing process by typing `pair ` +- On the BRC1H, confirm the pairing request, and quickly confirm as well on your server by typing `yes` A successful pairing ends with `pairing successful`. diff --git a/bundles/org.openhab.binding.bluetooth.enoceanble/README.md b/bundles/org.openhab.binding.bluetooth.enoceanble/README.md index 96998df8ff6..08c8717c011 100644 --- a/bundles/org.openhab.binding.bluetooth.enoceanble/README.md +++ b/bundles/org.openhab.binding.bluetooth.enoceanble/README.md @@ -16,7 +16,6 @@ Only a single thing type is added by this extension: | --------------- | ------------------------- | | ptm215b | The EnOcean PTM 215B Rocker | - These rockers are battery-less, the necessary energy for the BLE transmission is generated by the button click itself and completely depleted after 3 attempts of a "fire & forget" (unidirectional) BLE transmission. This means, the rockers are only "on" during the button click, so there is no possibility for openHAB to actively @@ -45,7 +44,7 @@ An EnOcean PTM 215B Rocker has the following channels: demo.things: -``` +```java Bridge bluetooth:bluegiga:bluegiga0 "Bluegiga Adapter" [ port="/dev/ttyBLUEGIGA", discovery=false ] { Thing ptm215b rocker_livingroom "Rocker Living Room" [ address = "E2:15:00:00:53:F9" ] Thing ptm215b rocker_kitchen "Rocker Kitchen" [ address = "E2:15:00:00:53:98" ] @@ -54,7 +53,7 @@ Bridge bluetooth:bluegiga:bluegiga0 "Bluegiga Adapter" [ port="/dev/ttyBLUEGIGA" demo.items: -``` +```java Dimmer Light_LivingRoom { channel="milight:rgbLed:milight2:4:ledbrightness", channel="bluetooth:ptm215b:bluegiga0:rocker_livingroom:rocker1" [profile="rawrocker-to-on-off"], channel="bluetooth:ptm215b:bluegiga0:rocker_kitchen:rocker1" [profile="rawrocker-to-on-off"] } // We have a combined kitchen / livingroom, so we control the living room lights with switches from the living room and from the kitchen Switch Light_Kitchen { channel="hue:group:1:kitchen-bulbs:switch", channel="bluetooth:ptm215b:bluegiga0:rocker_kitchen:rocker2" [profile="rawrocker-to-on-off"] } ``` diff --git a/bundles/org.openhab.binding.bluetooth.generic/README.md b/bundles/org.openhab.binding.bluetooth.generic/README.md index 4b6be9af5dd..4b2ffca709c 100644 --- a/bundles/org.openhab.binding.bluetooth.generic/README.md +++ b/bundles/org.openhab.binding.bluetooth.generic/README.md @@ -25,7 +25,7 @@ Generic bluetooth devices will be discovered for any connectable bluetooth devic ## Channels Channels will be dynamically created based on types of characteristics the device supports. -This binding contains a mostly complete database of standardized GATT services and characteristics +This binding contains a mostly complete database of standardized GATT services and characteristics that is used to map characteristics to one or multiple channels. Characteristics not in the database will be mapped to a single `String` channel labeled `Unknown`. diff --git a/bundles/org.openhab.binding.bluetooth.govee/README.md b/bundles/org.openhab.binding.bluetooth.govee/README.md index 6d9e1aeedba..425e968e851 100644 --- a/bundles/org.openhab.binding.bluetooth.govee/README.md +++ b/bundles/org.openhab.binding.bluetooth.govee/README.md @@ -1,6 +1,6 @@ # Govee -This extension adds support for [Govee](https://www.govee.com/) Bluetooth Devices. +This extension adds support for [Govee](https://www.govee.com/) Bluetooth Devices. ## Supported Things @@ -13,7 +13,7 @@ Only two thing types are supported by this extension at the moment. ## Discovery -As any other Bluetooth device, Govee devices are discovered automatically by the corresponding bridge. +As any other Bluetooth device, Govee devices are discovered automatically by the corresponding bridge. ## Thing Configuration @@ -24,7 +24,7 @@ Govee things have the following configuration parameters: | all | address | yes | | The Bluetooth address of the device (in format "XX:XX:XX:XX:XX:XX") | | all | refreshInterval | | 300 | How often, in seconds, the sensor data of the device should be refreshed | | goveeHygrometer1 | temperatureCalibration | no | | Offset to apply to temperature2 sensor readings | -| goveeHygrometer1 | humidityCalibration | no | | Offset to apply to humidity sensor readings | +| goveeHygrometer1 | humidityCalibration | no | | Offset to apply to humidity sensor readings | | goveeHygrometerMonitor | temperatureWarningAlarm | | false | Enables warning alarms to be broadcast when temperature is out of specified range | | goveeHygrometerMonitor | temperatureWarningMin | | 0 | The lower safe temperature2 threshold 3 | | goveeHygrometerMonitor | temperatureWarningMax | | 0 | The upper safe temperature2 threshold 3 | @@ -33,8 +33,8 @@ Govee things have the following configuration parameters: | goveeHygrometerMonitor | humidityWarningMax | | 0 | The upper safe humidity threshold 3 | 1. Available to both `goveeHygrometer` and `goveeHygrometerMonitor` thing types. -2. In °C -3. Only applies if alarm feature is enabled +1. In °C +1. Only applies if alarm feature is enabled ## Channels @@ -49,19 +49,19 @@ Govee things have the following channels in addition to the default bluetooth ch | goveeHygrometerMonitor | humidityAlarm | Switch | Indicates if current humidity is out of range. 2 | 1. Available to both `goveeHygrometer` and `goveeHygrometerMonitor` thing types. -2. Only applies if warning alarms are enabled in the configuration. +1. Only applies if warning alarms are enabled in the configuration. ## Example demo.things: -``` +```java bluetooth:goveeHygrometer:hci0:beacon "Govee Temperature Humidity Monitor" (bluetooth:bluez:hci0) [ address="12:34:56:78:9A:BC" ] ``` demo.items: -``` +```java Number:Temperature temperature "Room Temperature [%.1f %unit%]" { channel="bluetooth:goveeHygrometer:hci0:beacon:temperature" } Number:Dimensionless humidity "Humidity [%.0f %unit%]" { channel="bluetooth:goveeHygrometer:hci0:beacon:humidity" } Number:Dimensionless battery "Battery [%.0f %unit%]" { channel="bluetooth:goveeHygrometer:hci0:beacon:battery" } diff --git a/bundles/org.openhab.binding.bluetooth.roaming/README.md b/bundles/org.openhab.binding.bluetooth.roaming/README.md index 78808eaf22f..4e06a7fc924 100644 --- a/bundles/org.openhab.binding.bluetooth.roaming/README.md +++ b/bundles/org.openhab.binding.bluetooth.roaming/README.md @@ -29,7 +29,7 @@ The Roaming bridge has an optional parameter `groupUIDs` that configures which B `groupUIDs` must be formatted as a comma separated list of Bluetooth adapter thing UID values. If the `groupUIDs` parameter is not specified or left empty then the Roaming adapter will track devices across all other Bluetooth adapters. -Additionally, the Roaming bridge has the parameter `backgroundDiscovery` that can be set to `true` or `false`. +Additionally, the Roaming bridge has the parameter `backgroundDiscovery` that can be set to `true` or `false`. When set to `true`, a device discovered on any other adapter will have a corresponding `roaming` discovery. The `backgroundDiscovery` parameter is true by default. @@ -37,7 +37,7 @@ The `backgroundDiscovery` parameter is true by default. This is how a Roaming adapter can be configured textually in a *.things file: -``` +```java Bridge bluetooth:roaming:ctrl "BLE Roaming Adapter" [ backgroundDiscovery=true] Bridge bluetooth:roaming:other "BLE Roaming Adapter" [ backgroundDiscovery=true, groupUIDs="bluetooth:bluez:hci0,bluetooth:bluez:hci1"] ``` diff --git a/bundles/org.openhab.binding.bluetooth.ruuvitag/README.md b/bundles/org.openhab.binding.bluetooth.ruuvitag/README.md index 63c9c005918..5c0ccf4b932 100644 --- a/bundles/org.openhab.binding.bluetooth.ruuvitag/README.md +++ b/bundles/org.openhab.binding.bluetooth.ruuvitag/README.md @@ -1,6 +1,6 @@ # Ruuvi Tag -This extension adds support for [Ruuvi Tag](https://ruuvi.com/) Sensor Beacons. +This extension adds support for [Ruuvi Tag](https://ruuvi.com/) Sensor Beacons. ## Supported Things @@ -10,14 +10,13 @@ Only a single thing type is added by this extension: | --------------- | ------------------------- | | ruuvitag_beacon | A Ruuvi Tag Sensor Beacon | - Under normal conditions the ruuvitag should submit data every 10 seconds. However, if no data has been retrieved after 1 minute the ruuvitag is set to OFFLINE and the state of channels is set to UNDEF. When new data is retrieved when OFFLINE the ruuvtag is set ONLINE again. ## Discovery -As any other Bluetooth device, Ruuvi Tag Beacons are discovered automatically by the corresponding bridge. +As any other Bluetooth device, Ruuvi Tag Beacons are discovered automatically by the corresponding bridge. ## Thing Configuration @@ -47,13 +46,13 @@ Note: not all channels are always available. Available fields depends on [Ruuvi demo.things: -``` +```java bluetooth:ruuvitag:hci0:beacon "RuuviTag Sensor Beacon" (bluetooth:bluez:hci0) [ address="12:34:56:78:9A:BC" ] ``` demo.items: -``` +```java Number:Temperature temperature "Room Temperature [%.1f %unit%]" { channel="bluetooth:ruuvitag:hci0:beacon:temperature" } Number:Dimensionless humidity "Humidity [%.0f %unit%]" { channel="bluetooth:ruuvitag:hci0:beacon:humidity" } Number:Pressure pressure "Air Pressure [%.0f %unit%]" { channel="bluetooth:ruuvitag:hci0:beacon:pressure" } diff --git a/bundles/org.openhab.binding.bluetooth/CONTRIBUTE.md b/bundles/org.openhab.binding.bluetooth/CONTRIBUTE.md index 700b04af9ce..a5905e7bcf5 100644 --- a/bundles/org.openhab.binding.bluetooth/CONTRIBUTE.md +++ b/bundles/org.openhab.binding.bluetooth/CONTRIBUTE.md @@ -1,61 +1,62 @@ # Bluetooth Binding overview - + The Bluetooth binding is implemented to allow bundles to extend the main Bluetooth bundle (this one) in order to add new Bluetooth adapter as well as device support. This architecture means that such extension bundles must utilise the binding name `bluetooth`. A base class structure is defined in the `org.openhab.binding.bluetooth` bundle. This includes the main classes required to implement Bluetooth: - -* `BluetoothAdapter`. This interface defines the main functionality required to be implemented by a Bluetooth adapter, including device discovery. Typically, this interface is implemented by a BridgeHandler and then registered as an OSGi service -* `BluetoothDiscoveryParticipant`. An interface to be implemented by services that can identify specific Bluetooth devices. -* `BluetoothDevice`. This implements a Bluetooth device. It manages the notifications of device notifications, Bluetooth service and characteristic management, and provides the main interface to communicate to a Bluetooth device. -* `BluetoothService`. Implements the Bluetooth service. A service holds a number of characteristics. -* `BluetoothCharacteristic`. Implements the Bluetooth characteristic. This is the basic component for communicating data to and from a Bluetooth device. -* `BluetoothDescriptor`. Implements the Bluetooth descriptors for each characteristic. - + +- `BluetoothAdapter`. This interface defines the main functionality required to be implemented by a Bluetooth adapter, including device discovery. Typically, this interface is implemented by a BridgeHandler and then registered as an OSGi service +- `BluetoothDiscoveryParticipant`. An interface to be implemented by services that can identify specific Bluetooth devices. +- `BluetoothDevice`. This implements a Bluetooth device. It manages the notifications of device notifications, Bluetooth service and characteristic management, and provides the main interface to communicate to a Bluetooth device. +- `BluetoothService`. Implements the Bluetooth service. A service holds a number of characteristics. +- `BluetoothCharacteristic`. Implements the Bluetooth characteristic. This is the basic component for communicating data to and from a Bluetooth device. +- `BluetoothDescriptor`. Implements the Bluetooth descriptors for each characteristic. + ## Implementing a new Bluetooth Adapter bundle - + Bluetooth adapters are modelled as a bridge in openHAB. The bridge handler provides the link with the Bluetooth hardware (eg a dongle, or system Bluetooth API). An adapter bundle needs to implement two main classes: the `BridgeHandler` which should implement `BluetoothAdapter` (any be registered as a service), and a `ThingFactory`, which is required to instantiate the handler. - + The bridge handler must implement any functionality required to interface to the Bluetooth layer. It is responsible for managing the Bluetooth scanning, device discovery (i.e. the device interrogation to get the list of services and characteristics) and reading and writing of characteristics. The bridge needs to manage any interaction between the interface with any things it provides – this needs to account for any constraints that an interface may impose such that things do not need to worry about any peculiarities imposed by a specific interface. Classes such as `BluetoothCharacteristic` or `BluetoothService` may be extended to provide additional functionality to interface to a specific library if needed. - + ## Implementing specific Bluetooth device support - + A specific Bluetooth thing handler provides the functionality required to interact with a specific Bluetooth device. The new thing bundle needs to implement three main classes – a `BluetoothDiscoveryParticipant`, a `ThingHandler` and a `ThingFactory`, which is required to instantiate the handler. - + Two fundamental communications methods can be employed in Bluetooth: beacons and connected mode. A Bluetooth thing handler can implement one or both of these communications In practice, a connected mode Thing implementation would normally handle the beacons in order to provide as a minimum the RSSI data. ### Thing Naming -To avoid naming conflicts with different Bluetooth bundles a strict naming policy for things and thing xml files is proposed. +To avoid naming conflicts with different Bluetooth bundles a strict naming policy for things and thing xml files is proposed. This should use the bundle name and the thing name, separated with an underscore - e.g. for a Yeelight binding Blue2 thing, the thing type would be `yeelight_blue2`. - + ### Connected Mode Implementation - + The connected mode `BluetoothThingHandler` needs to handle the following functionality -* Extend the connected bluetooth thing handler. This holds the `adapter` through which all communication is done. -* Call the `adapter.getDevice()` method to get the `BluetoothDevice` class for the requested device. The `getDevice()` method will return a `BluetoothDevice` class even if the device is not currently known. -* Implement the `BluetoothDeviceListener` methods. These provide callbacks for various notifications regarding device updates – e.g. when the connection state of a device changes, when the device discovery is complete, when a read and write completes, and when beacon messages are received. -* The parent class calls the `device.connect()` method to connect to the device. Once the device is connected, the `BluetoothDeviceListener.onConnectionStateChange()` callback will be called. -* The parent class calls the `device.discoverServices()` method to discover all the BluetoothServices and `BluetoothCharacteristic`s implemented by the device. Once this is complete, the `BluetoothDeviceListener.onServicesDiscovered()` callback will be called. -* Call the `readCharacteristic` or `writeCharacteristic` methods to interact with the device. The `BluetoothDeviceListener.onCharacteristicReadComplete()` and `BluetoothDeviceListener.onCharacteristicWriteComplete()` methods will be called on completion. -* Implement the `BluetoothDeviceListener.onCharacteristicUpdate()` method to process any read responses or unsolicited updates of a characteristic value. - + +- Extend the connected bluetooth thing handler. This holds the `adapter` through which all communication is done. +- Call the `adapter.getDevice()` method to get the `BluetoothDevice` class for the requested device. The `getDevice()` method will return a `BluetoothDevice` class even if the device is not currently known. +- Implement the `BluetoothDeviceListener` methods. These provide callbacks for various notifications regarding device updates – e.g. when the connection state of a device changes, when the device discovery is complete, when a read and write completes, and when beacon messages are received. +- The parent class calls the `device.connect()` method to connect to the device. Once the device is connected, the `BluetoothDeviceListener.onConnectionStateChange()` callback will be called. +- The parent class calls the `device.discoverServices()` method to discover all the BluetoothServices and `BluetoothCharacteristic`s implemented by the device. Once this is complete, the `BluetoothDeviceListener.onServicesDiscovered()` callback will be called. +- Call the `readCharacteristic` or `writeCharacteristic` methods to interact with the device. The `BluetoothDeviceListener.onCharacteristicReadComplete()` and `BluetoothDeviceListener.onCharacteristicWriteComplete()` methods will be called on completion. +- Implement the `BluetoothDeviceListener.onCharacteristicUpdate()` method to process any read responses or unsolicited updates of a characteristic value. + ### Beacon Mode Implementation - + The beacon mode thing handler needs to handle the following functionality: -* Extend the beacon Bluetooth thing handler. This holds the `adapter` through which all communication is done. -* Call the `adapter.getDevice()` method to get the `BluetoothDevice` class for the requested device. The `getDevice()` method will return a `BluetoothDevice` class even if the device is not currently known. -* Implement the `BluetoothDeviceListener.onScanRecordReceived()` method to process the beacons. The notification will provide the current receive signal strength (RSSI), the raw beacon data, and various elements of generally useful beacon data is provided separately. +- Extend the beacon Bluetooth thing handler. This holds the `adapter` through which all communication is done. +- Call the `adapter.getDevice()` method to get the `BluetoothDevice` class for the requested device. The `getDevice()` method will return a `BluetoothDevice` class even if the device is not currently known. +- Implement the `BluetoothDeviceListener.onScanRecordReceived()` method to process the beacons. The notification will provide the current receive signal strength (RSSI), the raw beacon data, and various elements of generally useful beacon data is provided separately. ### Generic Bluetooth Device Support diff --git a/bundles/org.openhab.binding.bluetooth/README.md b/bundles/org.openhab.binding.bluetooth/README.md index 67733cc81f4..daf6019fce8 100644 --- a/bundles/org.openhab.binding.bluetooth/README.md +++ b/bundles/org.openhab.binding.bluetooth/README.md @@ -10,7 +10,7 @@ It has the following extensions: In order to function, this binding requires a Bluetooth adapter to be present, which handles the wireless communication. As there is no standard in Bluetooth for such dongles resp. chips, different adapters require a different implementation. -This is why the Bluetooth binding itself does not come with any bridge handlers for such adapters itself, but instead is extensible by additional bundles which can implement support for a specific adapter. +This is why the Bluetooth binding itself does not come with any bridge handlers for such adapters itself, but instead is extensible by additional bundles which can implement support for a specific adapter. For Linux, there exists a special bundle which provides a Bluetooth bridge that talks to BlueZ. This should be the best choice for any Linux-based single board computers like e.g. the Raspberry Pi. @@ -24,7 +24,6 @@ Additional thing types are available through bluetooth extensions. |---------------|---------------------------------------------------------------------------------------------------------| | beacon | A Bluetooth device that is not connected, but only broadcasts announcements. | - ## Discovery Discovery is performed through the Bluetooth bridge. @@ -36,7 +35,6 @@ As this might lead to a huge list of devices, bridges usually disable this behav All bluetooth thing types require a configuration parameter `address`, which corresponds to the Bluetooth address of the device (in format "XX:XX:XX:XX:XX:XX"). Other configuration parameters may be required depending on the bluetooth thing type, look at the documentation for that thing type for details. - ## Channels Every Bluetooth thing has the following channel: @@ -49,19 +47,19 @@ Every Bluetooth thing has the following channel: demo.things (assuming you have a Bluetooth bridge with the ID `bluetooth:bluez:hci0`): -``` +```java bluetooth:beacon:hci0:b1 "BLE Beacon" (bluetooth:bluez:hci0) [ address="68:64:4C:14:FC:C4" ] ``` demo.items: -``` +```java Number Beacon_RSSI "My Beacon [%.0f]" { channel="bluetooth:beacon:hci0:b1:rssi" } ``` demo.sitemap: -``` +```perl sitemap demo label="Main Menu" { Frame { diff --git a/bundles/org.openhab.binding.bondhome/README.md b/bundles/org.openhab.binding.bondhome/README.md index d136642a6c2..8695cccd61a 100644 --- a/bundles/org.openhab.binding.bondhome/README.md +++ b/bundles/org.openhab.binding.bondhome/README.md @@ -90,14 +90,14 @@ Available commands: ### `bond.things` File -``` +```java bondhome:bondBridge:BD123456 "Bond Bridge" [ ipAddress="192.168.0.10", localToken="abc123", serialNumber="BD123456" ] bondhome:bondFan:BD123456:0d11f00 "Living Room Fan" (bondhome:bondBridge:BD123456) [ deviceId="0d11f00" ] ``` ### `bond.items` File -``` +```java Switch GreatFan_Switch "Great Room Fan" { channel="bondhome:bondFan:BD123456:0d11f00:common#power" } Dimmer GreatFan_Dimmer "Great Room Fan" { channel="bondhome:bondFan:BD123456:0d11f00:fan#speed" } String GreatFan_Rotation "Great Room Fan Rotation" { channel="bondhome:bondFan:BD123456:0d11f00:fan#direction" } diff --git a/bundles/org.openhab.binding.boschindego/README.md b/bundles/org.openhab.binding.boschindego/README.md index 5feb093134a..f0bfa18c538 100644 --- a/bundles/org.openhab.binding.boschindego/README.md +++ b/bundles/org.openhab.binding.boschindego/README.md @@ -6,7 +6,7 @@ His [Java Library](https://github.com/zazaz-de/iot-device-bosch-indego-controlle ## Thing Configuration -Currently the binding supports ***indego*** mowers as a thing type with these configuration parameters: +Currently the binding supports _**indego**_ mowers as a thing type with these configuration parameters: | Parameter | Description | Default | |--------------------|-------------------------------------------------------------------|---------| @@ -79,13 +79,13 @@ Currently the binding supports ***indego*** mowers as a thing type with these ### `indego.things` File -``` +```java boschindego:indego:lawnmower [username="mail@example.com", password="idontneedtocutthelawnagain", refresh=120] ``` ### `indego.items` File -``` +```java Number Indego_State { channel="boschindego:indego:lawnmower:state" } Number Indego_ErrorCode { channel="boschindego:indego:lawnmower:errorcode" } Number Indego_StateCode { channel="boschindego:indego:lawnmower:statecode" } @@ -104,6 +104,6 @@ Image Indego_GardenMap { channel="boschindego:indego:lawnmower:gardenMap" } ### `indego.sitemap` File -``` +```perl Switch item=Indego_State mappings=[1="Mow", 2="Return",3="Pause"] ``` diff --git a/bundles/org.openhab.binding.boschshc/DEVELOPERS.md b/bundles/org.openhab.binding.boschshc/DEVELOPERS.md index 846d337aa3f..75a4c9561bf 100644 --- a/bundles/org.openhab.binding.boschshc/DEVELOPERS.md +++ b/bundles/org.openhab.binding.boschshc/DEVELOPERS.md @@ -4,11 +4,13 @@ To only build the Bosch Smart Home binding code execute - mvn -pl :org.openhab.binding.boschshc install +```shell +mvn -pl :org.openhab.binding.boschshc install +``` ## Execute -After compiling a new ``org.openhab.binding.boschshc.jar`` +After compiling a new ``org.openhab.binding.boschshc.jar`` copy it into the ``addons`` folder of your openHAB test instance. For the first time the jar is loaded automatically as a bundle. @@ -17,26 +19,37 @@ It should also be reloaded automatically when the jar changed. To reload the bundle manually you need to execute in the openhab console: - bundle:update "openHAB Add-ons :: Bundles :: Bosch Smart Home Binding" - +```shell +bundle:update "openHAB Add-ons :: Bundles :: Bosch Smart Home Binding" +``` + or get the ID and update the bundle using the ID: - bundle:list - -> Get ID for "openHAB Add-ons :: Bundles :: Bosch Smart Home Binding" - bundle:update - +```shell +bundle:list +``` + +-> Get ID for "openHAB Add-ons :: Bundles :: Bosch Smart Home Binding" + +```shell +bundle:update +``` ## Debugging To get debug output and traces of the Bosch Smart Home binding code -add the following lines into ``userdata/etc/log4j2.xml`` Loggers XML section. +add the following lines into ``userdata/etc/log4j2.xml`` Loggers XML section. - - +```xml + + +``` or use the openhab console to change the log level - log:set TRACE org.openhab.binding.boschshc +```shell +log:set TRACE org.openhab.binding.boschshc +``` ## Pairing and Certificates @@ -47,10 +60,10 @@ Read more about the pairing process in [register a new client to the bosch smart A precondition for the secured connection to the Bosch SHC is a self singed key + certificate. The key + certificate will be created and stored with the public Bosch SHC certificates in a Java Key store (jks). -The public certificates files are from https://github.com/BoschSmartHome/bosch-shc-api-docs/tree/master/best_practice. +The public certificates files are from . File copies stored in ``src/main/resource``. All three certificates and the key will be used for the HTTPS connection between this openHAB binding and the Bosch SHC. -During pairing the openHAB binding will exchange the self singed certificate with SHC. \ No newline at end of file +During pairing the openHAB binding will exchange the self singed certificate with SHC. diff --git a/bundles/org.openhab.binding.boschshc/README.md b/bundles/org.openhab.binding.boschshc/README.md index 774c54fe301..f93813689cf 100644 --- a/bundles/org.openhab.binding.boschshc/README.md +++ b/bundles/org.openhab.binding.boschshc/README.md @@ -7,7 +7,7 @@ Binding for the Bosch Smart Home. - [In-Wall Switch](#in-wall-switch) - [Compact Smart Plug](#compact-smart-plug) - [Twinguard Smoke Detector](#twinguard-smoke-detector) - - [Door/Window Contact](#door-window-contact) + - [Door/Window Contact](#doorwindow-contact) - [Motion Detector](#motion-detector) - [Shutter Control](#shutter-control) - [Thermostat](#thermostat) @@ -209,7 +209,7 @@ The system password is set by you during your initial registration steps in the A keystore file with a self-signed certificate is created automatically. This certificate is used for pairing between the Bridge and the Bosch Smart Home Controller. -*Press and hold the Bosch Smart Home Controller Bridge button until the LED starts blinking after you save your settings for pairing*. +_Press and hold the Bosch Smart Home Controller Bridge button until the LED starts blinking after you save your settings for pairing_. ## Getting the device IDs @@ -217,15 +217,15 @@ Bosch IDs for found devices are displayed in the openHAB log on bootup (`OPENHAB The log can also be called using the following command. -``` +```bash tail -f /var/log/openhab/openhab.log /var/log/openhab/events.log ``` -Alternatively, the log can be viewed using the OpenHab Log Viewer (frontail) via http://openhab:9001. +Alternatively, the log can be viewed using the OpenHab Log Viewer (frontail) via . Example: -``` +```bash 2020-08-11 12:42:49.490 [INFO ] [chshc.internal.BoschSHCBridgeHandler] - Found device: name=Heizung id=hdm:HomeMaticIP:3014F711A000XXXXXXXXXXXX 2020-08-11 12:42:49.495 [INFO ] [chshc.internal.BoschSHCBridgeHandler] - Found device: name=-RoomClimateControl- id=roomClimateControl_hz_1 2020-08-11 12:42:49.497 [INFO ] [chshc.internal.BoschSHCBridgeHandler] - Found device: name=-VentilationService- id=ventilationService @@ -245,7 +245,7 @@ Example: You define your Bosch devices by adding them either to a `.things` file in your `$OPENHAB_CONF/things` folder like this: -``` +```java Bridge boschshc:shc:1 [ ipAddress="192.168.x.y", password="XXXXXXXXXX" ] { Thing in-wall-switch bathroom "Bathroom" [ id="hdm:HomeMaticIP:3014F711A000XXXXXXXXXXXX" ] Thing in-wall-switch bedroom "Bedroom" [ id="hdm:HomeMaticIP:3014F711A000XXXXXXXXXXXX" ] @@ -269,7 +269,7 @@ Or by adding them via UI: Settings -> Things -> "+" -> Bosch Smart Home Binding. You define the items which should be linked to your Bosch devices via a `.items` file in your `$OPENHAB_CONF/items` folder like this: -``` +```java Switch Bosch_Bathroom "Bath Room" { channel="boschshc:in-wall-switch:1:bathroom:power-switch" } Switch Bosch_Bedroom "Bed Room" { channel="boschshc:in-wall-switch:1:bedroom:power-switch" } Switch Bosch_Kitchen "Kitchen" { channel="boschshc:in-wall-switch:1:kitchen:power-switch" } diff --git a/bundles/org.openhab.binding.bosesoundtouch/README.md b/bundles/org.openhab.binding.bosesoundtouch/README.md index b535ef2585f..c7ea3e8b503 100644 --- a/bundles/org.openhab.binding.bosesoundtouch/README.md +++ b/bundles/org.openhab.binding.bosesoundtouch/README.md @@ -3,7 +3,7 @@ This binding supports the Bose SoundTouch multiroom system. ## Supported Things - + The following Bose devices are supported: | Name | Thing Type | @@ -16,17 +16,17 @@ The following Bose devices are supported: | Bose SoundTouch Wireless Link Adapter | wirelessLinkAdapter | | Bose SoundTouch SA-5 Amplifier | sa5Amplifier | | Any other Bose SoundTouch device | device | - + ## Discovery - + Speakers are automatically discovered using mDNS in the local network. - + ## Binding Configuration - + The binding has no configuration options, all configuration is done at Thing level. - + ## Thing Configuration - + All thing types have the same configuration parameters: | Parameter Name | Type | Required | Description | @@ -39,7 +39,7 @@ The required properties are set when using discovery. For manual configuration, Note that the device might have two MAC addresses, one for ethernet and one for Wifi. The authorization key is used to identify the client application when using the Notification API. It must be requested from the developer portal. - + ## Channels All devices share the same set of channels, while some of them might not be available on all devices. @@ -48,7 +48,7 @@ All devices share the same set of channels, while some of them might not be avai |---------------------------|-----------|--------------------------------------------------------------| | keyCode | String | Simulates pushing a remote control button | | mute | Switch | Mutes the sound | -| notificationsound | String | Play a notification sound by a given URI | +| notificationsound | String | Play a notification sound by a given URI | | nowPlayingAlbum | String | Current playing album name | | nowPlayingArtist | String | Current playing artist name | | nowPlayingArtwork | Image | Artwork for the current playing song | @@ -68,29 +68,28 @@ All devices share the same set of channels, while some of them might not be avai | skipPreviousEnabled | Switch | Current source allows scrolling through tracks | | volume | Dimmer | Set or get the volume | | bass | Number | Bass (-9 minimum, 0 maximum) | - -The *notificationsound* channel has the following optional configuration parameters: +The _notificationsound_ channel has the following optional configuration parameters: + +- notificationVolume - Desired volume level while playing the notification, it must be between 10 and 70 (inclusive). A value outside this range will result in an error and not play the notification. +- notificationService - The service providing the notification +- notificationReason - The reason for the notification +- notificationMessage - Further details about the notification - - notificationVolume - Desired volume level while playing the notification, it must be between 10 and 70 (inclusive). A value outside this range will result in an error and not play the notification. - - notificationService - The service providing the notification - - notificationReason - The reason for the notification - - notificationMessage - Further details about the notification - The texts for the notification service, reason and message appear on the device display (when available) and the SoundTouch application screen. Upon completion of the notification, the speaker volume returns to its original value. If not present, the notification will play at the existing volume level. - + ## Full Example Things: -``` +```java bosesoundtouch:device:demo @ "Living" [ host="192.168.1.2", macAddress="123456789ABC" ] ``` Items: -``` +```java Switch Bose1_Power "Power: [%s]" { channel="bosesoundtouch:device:demo:power" } Dimmer Bose1_Volume "Volume: [%d %%]" { channel="bosesoundtouch:device:demo:volume" } Number Bose1_Bass "Bass: [%d %%]" { channel="bosesoundtouch:device:demo:bass" } @@ -116,27 +115,27 @@ String Bose1_nowPlayingTrack "Track: [%s]" { Sitemap: -``` +```perl sitemap demo label="Bose Test Items" { - Frame label="Bose 1" { + Frame label="Bose 1" { Switch item=Bose1_Power - Slider item=Bose1_Volume - Text item=Bose1_Bass - Switch item=Bose1_Mute - Text item=Bose1_OperationMode - Text item=Bose1_PlayerControl - Text item=Bose1_Preset - Text item=Bose1_SaveAsPreset - Text item=Bose1_KeyCode - Text item=Bose1_nowPlayingAlbum - Text item=Bose1_nowPlayingArtist - Text item=Bose1_nowPlayingArtwork - Text item=Bose1_nowPlayingDescription - Text item=Bose1_nowPlayingGenre - Text item=Bose1_nowPlayingItemName - Text item=Bose1_nowPlayingStationLocation - Text item=Bose1_nowPlayingTrack - } + Slider item=Bose1_Volume + Text item=Bose1_Bass + Switch item=Bose1_Mute + Text item=Bose1_OperationMode + Text item=Bose1_PlayerControl + Text item=Bose1_Preset + Text item=Bose1_SaveAsPreset + Text item=Bose1_KeyCode + Text item=Bose1_nowPlayingAlbum + Text item=Bose1_nowPlayingArtist + Text item=Bose1_nowPlayingArtwork + Text item=Bose1_nowPlayingDescription + Text item=Bose1_nowPlayingGenre + Text item=Bose1_nowPlayingItemName + Text item=Bose1_nowPlayingStationLocation + Text item=Bose1_nowPlayingTrack + } } ``` diff --git a/bundles/org.openhab.binding.broadlinkthermostat/README.md b/bundles/org.openhab.binding.broadlinkthermostat/README.md index 20ee445fa39..1e22b6d3ef0 100644 --- a/bundles/org.openhab.binding.broadlinkthermostat/README.md +++ b/bundles/org.openhab.binding.broadlinkthermostat/README.md @@ -5,7 +5,7 @@ As the binding uses the [broadlink-java-api](https://github.com/mob41/broadlink- ## Supported Things -*Note:* So far only the Floureon Thermostat and Rm Mini 3 devices has been tested! The other things are "best guess" implementations. +_Note:_ So far only the Floureon Thermostat and Rm Mini 3 devices has been tested! The other things are "best guess" implementations. | Things | Description | Thing Type | |-------------------------|---------------------------------------------------------------------|----------------------| @@ -56,13 +56,13 @@ The autodiscovery process finds both parts automatically. demo.things: -``` +```java Thing broadlinkthermostat:floureonthermostat:bathroomthermostat "Bathroom Thermostat" [ host="192.168.0.23", macAddress="00:10:FA:6E:38:4A"] ``` demo.items: -``` +```java Number:Temperature Bathroom_Thermostat_Temperature "Room temperature [%.1f %unit%]" { channel="broadlinkthermostat:floureonthermostat:bathroomthermostat:roomtemperature"} Number:Temperature Bathroom_Thermostat_Temperature_Ext "Room temperature (ext) [%.1f %unit%]" { channel="broadlinkthermostat:floureonthermostat:bathroomthermostat:roomtemperature"} Number:Temperature Bathroom_Thermostat_Setpoint "Setpoint [%.1f %unit%]" { channel="broadlinkthermostat:floureonthermostat:bathroomthermostat:setpoint"} diff --git a/bundles/org.openhab.binding.bsblan/README.md b/bundles/org.openhab.binding.bsblan/README.md index c9b48a222d0..8979023f7a4 100644 --- a/bundles/org.openhab.binding.bsblan/README.md +++ b/bundles/org.openhab.binding.bsblan/README.md @@ -60,7 +60,7 @@ Note: If you would also like to use the binding to set parameter values, ensure bsblan.things: -``` +```java Bridge bsblan:bridge:heating [host="192.168.1.100", refreshInterval=30, username="atari", password="800xl"] { Thing parameter p700 [id=700] Thing parameter p710 [id=710] @@ -70,7 +70,7 @@ Bridge bsblan:bridge:heating [host="192.168.1.100", refreshInterval=30, username bsblan.items: -``` +```java Number BsbParameter700NumberValue { channel="bsblan:parameter:heating:p700:number-value" } Number BsbParameter710NumberValue { channel="bsblan:parameter:heating:p710:number-value" } String BsbParameter8730Description { channel="bsblan:parameter:heating:p8730:description" } @@ -78,7 +78,7 @@ String BsbParameter8730Description { channel="bsblan:parameter:heating:p8730:des bsblan.sitemap: -``` +```perl sitemap bsblan label="BSB-LAN" { Selection item=BsbParameter700NumberValue label="Operating Mode" mappings=[0="Protection", 1="Automatic", 2="Reduced", 3="Comfort"] icon="heating" Setpoint item=BsbParameter710NumberValue label="Room Temperature Comfort Setpoint [%.1f °C]" icon="temperature" minValue=22.0 maxValue=25.0 step=0.5 diff --git a/bundles/org.openhab.binding.bticinosmarther/README.md b/bundles/org.openhab.binding.bticinosmarther/README.md index 3fd53d0611e..db239b07b44 100644 --- a/bundles/org.openhab.binding.bticinosmarther/README.md +++ b/bundles/org.openhab.binding.bticinosmarther/README.md @@ -8,8 +8,8 @@ Smarther chronothermostat is produced by [BTicino](https://www.bticino.com/produ All BTicino Smarther Chronothermostat device models should be discoverable through this binding: -* Flush mounting installation item (X8000) -* Wall installation item (X8000W) +- Flush mounting installation item (X8000) +- Wall installation item (X8000W) If you can control them from BTicino Thermostat mobile app on your iPhone/Android you should be able to add it as a thing. @@ -52,26 +52,26 @@ The following configuration options are available on the BTicino Smarther Chrono ### Account Creation -Follow the instructions in the tutorial [here](https://developer.legrand.com/tutorials/getting-started/), under: +Follow the instructions in the tutorial [here](https://developer.legrand.com/tutorials/getting-started/), under: -* Step 1 : Create an account -* Step 2 : Subscribe to a product and get subscription key +- Step 1 : Create an account +- Step 2 : Subscribe to a product and get subscription key There's also a Step 3 in this tutorial, you can skip it as not needed to complete this process. Simply write down your "Primary Key" as it will be needed later on in the bridge configuration phase. ### Application Creation -Follow the instructions in the tutorial [here](https://developer.legrand.com/tutorials/create-an-application/), under: +Follow the instructions in the tutorial [here](https://developer.legrand.com/tutorials/create-an-application/), under: -* Step 1 : Register your application -* Step 2 : Check scopes -* Step 3 : Getting application details +- Step 1 : Register your application +- Step 2 : Check scopes +- Step 3 : Getting application details When registering your new Legrand Application for openHAB BTicino Smarther Bridge you have to specify the allowed Reply URL, aka white-listed address. Here you have to specify the URL to the Bridge Authorization page on your server. -For example if you run your openHAB server on http://openhabianpi:8080 you should set `http://openhabianpi:8080/bticinosmarther/connectsmarther` as the "First Reply URL" required field in Step 1. +For example if you run your openHAB server on `http://openhabianpi:8080` you should set `http://openhabianpi:8080/bticinosmarther/connectsmarther` as the "First Reply URL" required field in Step 1. Other Reply URLs (second, third, etc.) you can leave them blank. This is **very important** since the authorize process with Legrand takes place using your client web browser and Legrand will have to know the right URL to your openHAB server for the authorization to be completed. @@ -92,19 +92,19 @@ If you want to later receive push notifications (device status) from Legrand for ### Bridge Configuration 1. Install the binding and make sure the _BTicino Smarther Binding_ is listed on your server, if you have not already done so. -2. Complete the [Account Creation](#account-creation) and [Application Creation](#application-creation) steps, if you have not already done so. -3. Make sure you have your Legrand account _Primary Key_ and your Legrand application _Client ID_ and _Client Secret_ identities available. -4. Go to your preferred openHAB admin UI and add a new Thing - select the **"BTicino Smarther Bridge"**. -5. Choose new Id for the bridge, unless you like the generated one. -6. Put in your _Primary Key_ (in _Subscription Key_ field), _Client ID_ and _Cliend Secret_ in their respective fields of the bridge configuration. -7. Set _Use Notifications_ to `ON` if your openHAB server is reachable from a public https URL (see [Note on notifications](#note-on-notifications)), set `OFF` otherwise. -8. You can leave the _Bridge Status Refresh Period_ as is. -9. Save the bridge. -10. The bridge thing will stay in state _INITIALIZING_ and eventually go _OFFLINE_ - this is fine, as you now have to authorize this bridge with Legrand. -11. Go to the authorization page of your server (see [Application Creation](#application-creation)) `http://:/bticinosmarther/connectsmarther`; your newly added bridge should be listed there (along with the available locations). -12. Press the _"Authorize Bridge"_ button; this will take you either to the login page of Legrand portal or directly to the authorization screen. -13. Login and/or authorize the application; if the Reply URL is correct you will be returned and the entry should show your bridge is authorized with your Client ID; otherwise, go back to your application configuration on Legrand portal and ensure you have set the right Reply URL (see [Troubleshooting](#troubleshooting) below). -14. The bridge will be updated with a refresh token and go _ONLINE_ (the refresh token is used to re-authorize the bridge with Legrand Smarther API whenever required). +1. Complete the [Account Creation](#account-creation) and [Application Creation](#application-creation) steps, if you have not already done so. +1. Make sure you have your Legrand account _Primary Key_ and your Legrand application _Client ID_ and _Client Secret_ identities available. +1. Go to your preferred openHAB admin UI and add a new Thing - select the **"BTicino Smarther Bridge"**. +1. Choose new Id for the bridge, unless you like the generated one. +1. Put in your _Primary Key_ (in _Subscription Key_ field), _Client ID_ and _Cliend Secret_ in their respective fields of the bridge configuration. +1. Set _Use Notifications_ to `ON` if your openHAB server is reachable from a public https URL (see [Note on notifications](#note-on-notifications)), set `OFF` otherwise. +1. You can leave the _Bridge Status Refresh Period_ as is. +1. Save the bridge. +1. The bridge thing will stay in state _INITIALIZING_ and eventually go _OFFLINE_ - this is fine, as you now have to authorize this bridge with Legrand. +1. Go to the authorization page of your server (see [Application Creation](#application-creation)) `http://:/bticinosmarther/connectsmarther`; your newly added bridge should be listed there (along with the available locations). +1. Press the _"Authorize Bridge"_ button; this will take you either to the login page of Legrand portal or directly to the authorization screen. +1. Login and/or authorize the application; if the Reply URL is correct you will be returned and the entry should show your bridge is authorized with your Client ID; otherwise, go back to your application configuration on Legrand portal and ensure you have set the right Reply URL (see [Troubleshooting](#troubleshooting) below). +1. The bridge will be updated with a refresh token and go _ONLINE_ (the refresh token is used to re-authorize the bridge with Legrand Smarther API whenever required). ![Tutorial 1](doc/images/tutorial-1.png) @@ -124,7 +124,7 @@ You can force reinitialization by authorizing again on the `/bticinosmarther/con When configuring the bridge (see step 13 [here](#thing-configuration)), you can receive the following error from Legrand portal: -``` +```json { "error": "invalid_request", "error_description": "The reply url host xxxxx doesn't match with the ones configured on the application" @@ -136,8 +136,8 @@ Please remember these two strings must match for authentication process to work. To solve the issue, either: -* Correct the address you're accessing the `/bticinosmarther/connectsmarther` page from, to match the "Reply URL" attribute registered in your application, or -* Should you have specified a wrong "Reply URL" attribute in your application, go to the Legrand portal and correct it accordingly then resubmit the application for approval. +- Correct the address you're accessing the `/bticinosmarther/connectsmarther` page from, to match the "Reply URL" attribute registered in your application, or +- Should you have specified a wrong "Reply URL" attribute in your application, go to the Legrand portal and correct it accordingly then resubmit the application for approval. ## Channels @@ -220,7 +220,7 @@ In this example there is a bridge configured with Thing ID **mybridge**: bticinosmarther.things: -``` +```java Bridge bticinosmarther:bridge:mybridge "BTicino Smarther Bridge" [subscriptionKey="" clientId="", clientSecret=""] { Thing module thermo1 "Thermo 1" [plantId="" moduleId=""] Thing module thermo2 "Thermo 2" [plantId="" moduleId=""] @@ -229,7 +229,7 @@ Bridge bticinosmarther:bridge:mybridge "BTicino Smarther Bridge" [subscriptionKe bticinosmarther.items: -``` +```java // Measures items Number:Temperature smaTemperature "In Temperature [%.1f %unit%]" { channel="bticinosmarther:module:mybridge:thermo1:measures#temperature" } Number:Dimensionless smaHumidity "In Humidity [%.1f %unit%]" { channel="bticinosmarther:module:mybridge:thermo1:measures#humidity" } @@ -257,7 +257,7 @@ Switch smaDisplayTime bticinosmarther.sitemap: -``` +```perl sitemap bticinosmarther label="BTicino Smarther Sitemap" { Frame label="Smarther Measures" { @@ -288,7 +288,7 @@ sitemap bticinosmarther label="BTicino Smarther Sitemap" { bticinosmarther.rules: -``` +```java rule "BTicino Smarther - Set time visibility flag" when Item smaSetMode received update or Item smaSetDate received update @@ -309,9 +309,9 @@ All devices (chronothermostats modules) currently associated with the user accou Legrand/BTicino Smarther topology considers the following dimensions: -* topology : is the whole network of devices associated with a user account -* plant : is the location where a module is installed (0..N plants per topology) -* module : is the chronothermostat installed in a location (0..N modules per location) +- topology : is the whole network of devices associated with a user account +- plant : is the location where a module is installed (0..N plants per topology) +- module : is the chronothermostat installed in a location (0..N modules per location) You can add multiple bridges to allow controlling devices in the context of multiple Legrand user accounts. diff --git a/bundles/org.openhab.binding.buienradar/README.md b/bundles/org.openhab.binding.buienradar/README.md index dc81d5880f4..25a7690f2b4 100644 --- a/bundles/org.openhab.binding.buienradar/README.md +++ b/bundles/org.openhab.binding.buienradar/README.md @@ -1,13 +1,12 @@ # Buienradar Binding -The Buienradar Binding periodically (5 minute intervals) retrieves rainfall predictions from the Dutch -[buienradar.nl webservice API.](https://www.buienradar.nl/overbuienradar/gratis-weerdata). +The Buienradar Binding periodically (5 minute intervals) retrieves rainfall predictions from the Dutch [buienradar.nl webservice API.](https://www.buienradar.nl/overbuienradar/gratis-weerdata). -Using the binding, we can +Using the binding, we can -* warn of upcoming rainfall when there are open windows or doors -* prevent watering the outside plants needlessly, -* warn when we are about to leave the house. +- warn of upcoming rainfall when there are open windows or doors +- prevent watering the outside plants needlessly, +- warn when we are about to leave the house. ## Supported Things @@ -21,13 +20,13 @@ No auto-discovery is currently possible. The configuration can be done by adding a Rain Forecast Thing using the UI, or by adding it to a `.things` file: -``` +```java Thing buienradar:rain_forecast:home [ location="52.198864211111925,5.4192629660193585" ] ``` and adding the relevant items as such in your `.items` file. Please note that the buienradar service only provides predictions in 5 minutes intervals with a maximum of two hours (120 minutes): -``` +```java Number RAIN_CURRENT "Current rain" (Rain) {channel="buienradar:rain_forecast:home:forecast_0" } Number RAIN_5MIN "Rain 5 min." (Rain) {channel="buienradar:rain_forecast:home:forecast_5" } Number RAIN_10MIN "Rain 10 min." (Rain) {channel="buienradar:rain_forecast:home:forecast_10" } @@ -63,12 +62,10 @@ In this example we use the 'Discrete' plugin of Grafana to visualize the predict The mappings are as follows: -* 0 – 0.01: None (rgba(204, 204, 204, 0)) -* 0.01 – 1: Very light (#badff4) -* 1 – 5: Light (#6ed0e0) -* 5 – 20: Medium (#1f78c1) -* 20 – 50: Heavy (#ef843c) -* 50 – 80: Very heavy (#e24d42) -* 80 – 100: Extremely heavy (#890f02) - - +- 0 – 0.01: None (rgba(204, 204, 204, 0)) +- 0.01 – 1: Very light (#badff4) +- 1 – 5: Light (#6ed0e0) +- 5 – 20: Medium (#1f78c1) +- 20 – 50: Heavy (#ef843c) +- 50 – 80: Very heavy (#e24d42) +- 80 – 100: Extremely heavy (#890f02) diff --git a/bundles/org.openhab.binding.caddx/README.md b/bundles/org.openhab.binding.caddx/README.md index e59408a1df3..0d7d1db1558 100644 --- a/bundles/org.openhab.binding.caddx/README.md +++ b/bundles/org.openhab.binding.caddx/README.md @@ -26,7 +26,7 @@ There is no support to discover the available keypads. ## Prerequisites -For the binding to work the panel has also to be programmed appropriately. +For the binding to work the panel has also to be programmed appropriately. ### Programming locations for the NX-8E control panel @@ -281,7 +281,7 @@ The binding supports the following actions on the respective things. The following is an example of a things file (caddx.things): -``` +```java Bridge caddx:bridge:thebridge "Bridge" [ protocol="Binary", serialPort="/dev/ttyUSB0", baud=38400, maxZoneNumber=18 ] { Thing partition partition1 "Groundfloor alarm" [ partitionNumber=1 ] Thing zone zone1 "Livingroom motion sensor" [ zoneNumber=1 ] @@ -295,7 +295,7 @@ Bridge caddx:bridge:thebridge "Bridge" [ protocol="Binary", s The following is an example of an items file (caddx.items): -``` +```java Group:Contact:OR(OPEN,CLOSED) MotionSensors "Motion Sensors [%s]" Group:Contact:OR(OPEN,CLOSED) Windows "Windows open [%s]" @@ -312,7 +312,7 @@ Switch Partition1_EntryGuard "Entry Guard [%s]" { channe The following is an example of a sitemap file (home.sitemap): -``` +```perl sitemap home label="Home" { Frame label="Ground floor" { Text item=Partition1_Armed @@ -337,7 +337,7 @@ sitemap home label="Home" { The following is a rule example with calling of an action on the binding -``` +```java rule "Zone Bypass on Chime Off" when Item caddx_partition_thebridge_partition1_partition_chime_mode_on changed from ON to OFF diff --git a/bundles/org.openhab.binding.cbus/README.md b/bundles/org.openhab.binding.cbus/README.md index b4154cee4c3..37dccfeff9b 100644 --- a/bundles/org.openhab.binding.cbus/README.md +++ b/bundles/org.openhab.binding.cbus/README.md @@ -15,7 +15,6 @@ Without that they will remain on the last value set and wont match what is shown First the CGate Connection bridge needs to be configured with the ip address of the computer running the C-Gate software. After this a Bridge is creaed for each network configured on the CBus Network. The CBus Project Name and the network Id for that network - ## Supported Things This binding support 6 different things types @@ -31,7 +30,7 @@ This binding support 6 different things types When a discovery scan is started in the UI, Things are discovered for the groups that are found on the CBus network. -##Channels +## Channels At startup the binding will scan the network for the values of all the groups and set those on the appropriate channels. It is not possible to fetch the value of a Trigger Group so those values will only be updated when a trigger is set on the CBus network. @@ -40,32 +39,32 @@ It is not possible to fetch the value of a Trigger Group so those values will on Light things have 2 channels which show the current state of the group on the cbus network and can also set the state of the group:- -* **state** - On/Off state of the light -* **level** - The level of the channel between 0 and 100 +- **state** - On/Off state of the light +- **level** - The level of the channel between 0 and 100 ### Temperature Temperature things have 1 channel which shows the current value. This is read-only and will not set the value on the CBus Network. -* **temp** - Temperature value +- **temp** - Temperature value ### Trigger Trigger things have 1 channel which shows the current trigger value on the cbus network and can be used to set a trigger value on the CBus Network. -* **value** - CBus Trigger value +- **value** - CBus Trigger value ### Dali Dali things have 1 channel which shows the current value on the cbus network and can be used to set a value on the CBus Network. -* **level** - Value from the DALI node +- **level** - Value from the DALI node ## Example ### cbus.things -``` +```java /* Need a cgate bridge to connect to cgate and then 1 network bridge for each network on that system */ Bridge cbus:cgate:cgatenetwork "file - cgate" [ ipAddress="127.0.0.1"] { @@ -84,7 +83,7 @@ Thing cbus:dali:cgatenetwork:cbusnetwork:dali3 "dali 3 value" (cbus:network:cgat ### cbus.items -``` +```java Dimmer light31Dimmer { channel="cbus:light:cgatenetwork:cbusnetwork:light31:level"} Switch light31Switch { channel="cbus:light:cgatenetwork:cbusnetwork:light31:state"} Number trigger1Value { channel="cbus:trigger:cgatenetwork:cbusnetwork:trigger1:value"} @@ -94,7 +93,7 @@ Dimmer dali3 { channel="cbus:dali:cgatenetwork:cbusnetwork:dali3:level"} ### cbusdemo.sitemap -``` +```perl sitemap cbusdemo label="CBus Binding Demo" { Frame label="light" { diff --git a/bundles/org.openhab.binding.chromecast/README.md b/bundles/org.openhab.binding.chromecast/README.md index 11392107216..c6f64b2a367 100644 --- a/bundles/org.openhab.binding.chromecast/README.md +++ b/bundles/org.openhab.binding.chromecast/README.md @@ -15,8 +15,8 @@ This can be configured on the binding level: Configure a Callback URL when the Chromecast cannot connect using the Primary Address or Port, e.g. when: -* proxying HTTP (port 80/443) using Apache/NGINX to openHAB (port 8080) -* openHAB is running inside a Docker container that has its own IP Address +- proxying HTTP (port 80/443) using Apache/NGINX to openHAB (port 8080) +- openHAB is running inside a Docker container that has its own IP Address ## Supported Things @@ -33,7 +33,7 @@ No authentication is required for accessing the devices on the network. Auto-discovery is enabled by default. To disable it, you can add the following line to `/services/runtime.cfg`: -``` +```shell discovery.chromecast:background=false ``` @@ -155,14 +155,13 @@ sitemap chromecast label="Chromecasts" { This binding includes rule actions for casting media. -* `playURL(String url)` -* `playURL(String url, String mimeType)` +- `playURL(String url)` +- `playURL(String url, String mimeType)` Examples: -``` +```java val castActions = getActions("chromecast","chromecast:chromecast:29fcf535da") val success = castActions.playURL("http://192.168.1.160:81/mjpg/front1/video.mjpg") val success2 = castActions.playURL("http://192.168.1.160:81/mjpg/front1/video.mjpg", "image/jpeg") - ``` diff --git a/bundles/org.openhab.binding.cm11a/README.md b/bundles/org.openhab.binding.cm11a/README.md index 298836421e1..55ad9f054ff 100644 --- a/bundles/org.openhab.binding.cm11a/README.md +++ b/bundles/org.openhab.binding.cm11a/README.md @@ -64,9 +64,9 @@ Each attached thing must specify the `houseUnitCode` set in the device (i.e. A1) | switch | switchState | Switch | An On/Off switch | | dimmer | lightDimmer | Dimmer | A dimmable device | -**Example** +### Example -### Things +#### Things ```perl Bridge cm11a:cm11a:MyCm11a [ serialPort="COM3" ] { @@ -75,7 +75,7 @@ Bridge cm11a:cm11a:MyCm11a [ serialPort="COM3" ] { } ``` -### Items +#### Items ```java SwitchA1 "Kitchen Plug" (someGroup) { channel="cm11a:switch:MyCm11a:SwitchA1:switchstatus" } @@ -84,11 +84,11 @@ DimmerA2 "Porch lights" (someGroup) { channel="cm11a:dimmer:MyCm11a ## Known issues -1. When openHAB starts up it doesn't restore the last state of each module. And, the cm11a does not provide a discovery service. Therefore it assumes everything off. -2. The dimmer slider can get out of sync with the actual light because of the way X10 works. On some switches if you turn them on they will go to full bright and some switches will return to the previous dim level. +1. When openHAB starts up it doesn't restore the last state of each module. And, the cm11a does not provide a discovery service. Therefore it assumes everything off. +1. The dimmer slider can get out of sync with the actual light because of the way X10 works. On some switches if you turn them on they will go to full bright and some switches will return to the previous dim level. ## References 1. [CM11A (X10) Protocol Document](https://wanderingsamurai.net/electronics/cm11a-x10-protocol-document) -2. [Heyu - control software for the cm11a](https://www.heyu.org/) -3. cm11a Controllers are available for purchase from several sites on the internet +1. [Heyu - control software for the cm11a](https://www.heyu.org/) +1. cm11a Controllers are available for purchase from several sites on the internet diff --git a/bundles/org.openhab.binding.comfoair/README.md b/bundles/org.openhab.binding.comfoair/README.md index 0965ddcb9eb..2baa6b2ac59 100644 --- a/bundles/org.openhab.binding.comfoair/README.md +++ b/bundles/org.openhab.binding.comfoair/README.md @@ -6,30 +6,30 @@ It was also successfully tested on a Wernig G90-160. **NOTE:** This binding does not work with the ComfoAir Q-series (e.g. Q350 or Q450). These ventilation units use a CAN bus for communication and a different protocol. -### Limitations +## Limitations -* Either the ComfoAir binding or the CCEase Comfocontrol can be active, but not together. -* You must implement auto mode by yourself with rules, but it is more powerful. +- Either the ComfoAir binding or the CCEase Comfocontrol can be active, but not together. +- You must implement auto mode by yourself with rules, but it is more powerful. -### Prerequisites +## Prerequisites Computer communication between ComfoAir device and openHAB via RS232 connection has to be set up. The connection should be made with a 3-wire cable connecting pins: GND, TX, RX of RS232 sockets, but RX and TX pins should be crossed (TX of ComfoAir to RX of PC, RX of ComfoAir to TX of PC). -### Serial Port Access Rights +## Serial Port Access Rights -* Take care that the user that runs openHAB has rights to access the serial port -* On Ubuntu/Debian based systems (incl. openHABian) that usually means adding the user (e.g. openhab) to the group "dialout", i.e. +- Take care that the user that runs openHAB has rights to access the serial port +- On Ubuntu/Debian based systems (incl. openHABian) that usually means adding the user (e.g. openhab) to the group "dialout", i.e. -``` +```shell sudo usermod -a -G dialout openhab ``` ## Supported Things The binding supports thing types for different device types. -They only differ in the available channels, where the generic *comfoair* thing type supports all available channels. -If there is no thing type that matches your specific device you can safely choose the *comfoair* type. +They only differ in the available channels, where the generic _comfoair_ thing type supports all available channels. +If there is no thing type that matches your specific device you can safely choose the _comfoair_ type. |Thing Type ID |Description | |--------------|-----------------------------------------------------------------------------| @@ -200,78 +200,78 @@ The ComfoAir binding supports the following channels. `.things` file: -``` +```java Thing comfoair:comfoair:myComfoAir "ComfoAir" [serialPort="/dev/ttyUSB0", refreshInterval="60"] ``` `.items` file: -``` -Switch comfoairControl "Activate" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:bindingControl#activate"} -Number comfoairFanLevel "Ventilation level [%d]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:ventilation#fanLevel"} -Number comfoairErrorReset "Error reset" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:resets#errorReset"} -Number comfoairFilterReset "Filter reset" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:resets#filterReset"} -Number comfoairFilterPeriod "Filter period [%d weeks]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:menuP2#filterWeeks"} +```java +Switch comfoairControl "Activate" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:bindingControl#activate"} +Number comfoairFanLevel "Ventilation level [%d]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:ventilation#fanLevel"} +Number comfoairErrorReset "Error reset" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:resets#errorReset"} +Number comfoairFilterReset "Filter reset" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:resets#filterReset"} +Number comfoairFilterPeriod "Filter period [%d weeks]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:menuP2#filterWeeks"} // Messages -String comfoairError "Error: [%s]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:errors#errorsCurrent"} -Number:Time comfoairFilterRuntime "Filter runtime [%.0f h]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:times#filterHours"} +String comfoairError "Error: [%s]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:errors#errorsCurrent"} +Number:Time comfoairFilterRuntime "Filter runtime [%.0f h]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:times#filterHours"} // State -Number:Temperature comfoairTargetTemperature "Comfort temperature [%.1f °C]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:temperatures#targetTemperature"} -Number:Temperature comfoairOutdoorIncomingTemperature "Inlet air temperature [%.1f °C]" (ComfoAir, comfoairTemps_Chart) {channel="comfoair:comfoair:myComfoAir:temperatures#outdoorTemperatureIn"} -Number:Temperature comfoairIndoorIncomingTemperature "Supply air temperature [%.1f °C]" (ComfoAir, comfoairTemps_Chart) {channel="comfoair:comfoair:myComfoAir:temperatures#indoorTemperatureIn"} -Number:Temperature comfoairIndoorOutgoingTemperature "Return air temperature [%.1f °C]" (ComfoAir, comfoairTemps_Chart) {channel="comfoair:comfoair:myComfoAir:temperatures#indoorTemperatureOut"} -Number:Temperature comfoairOutdoorOutgoingTemperature "Exhaust air temperature [%.1f °C]" (ComfoAir, comfoairTemps_Chart) {channel="comfoair:comfoair:myComfoAir:temperatures#outdoorTemperatureOut"} -Number comfoairIncomingFan "Supply capacity [%d %%]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:ventilation#fanInPercent"} -Number comfoairOutgoingFan "Exhaust capacity [%d %%]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:ventilation#fanOutPercent"} -Number comfoairFanIn0 "Supply capacity - level 0 [%d %%]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:ventilation#fanIn0"} -Number comfoairFanOut0 "Exhaust capacity - level 0 [%d %%]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:ventilation#fanOut0"} -Switch comfoairBypassMode "Bypass [MAP(comfoair_bypass.map):%s]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:menuP9#bypassState"} -Switch comfoairGHXMode "GHX [MAP(comfoair_on-off.map):%s]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:menuP9#ewtState"} -Switch comfoairChimneyMode "Fire programme [MAP(comfoair_on-off.map):%s]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:menuP9#chimneyState"} -Switch comfoairHeaterMode "Heater [MAP(comfoair_on-off.map):%s]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:menuP9#heaterState"} -Switch comfoairCookerHoodMode "Extractor hood [MAP(comfoair_on-off.map):%s]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:menuP9#cookerhoodState"} -Switch comfoairEnthalpyMode "Enthalpy [MAP(comfoair_on-off.map):%s]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:menuP9#enthalpyState"} -Switch comfoairFreezeMode "Freeze [MAP(comfoair_freeze.map):%s]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:menuP9#frostState"} +Number:Temperature comfoairTargetTemperature "Comfort temperature [%.1f °C]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:temperatures#targetTemperature"} +Number:Temperature comfoairOutdoorIncomingTemperature "Inlet air temperature [%.1f °C]" (ComfoAir, comfoairTemps_Chart) {channel="comfoair:comfoair:myComfoAir:temperatures#outdoorTemperatureIn"} +Number:Temperature comfoairIndoorIncomingTemperature "Supply air temperature [%.1f °C]" (ComfoAir, comfoairTemps_Chart) {channel="comfoair:comfoair:myComfoAir:temperatures#indoorTemperatureIn"} +Number:Temperature comfoairIndoorOutgoingTemperature "Return air temperature [%.1f °C]" (ComfoAir, comfoairTemps_Chart) {channel="comfoair:comfoair:myComfoAir:temperatures#indoorTemperatureOut"} +Number:Temperature comfoairOutdoorOutgoingTemperature "Exhaust air temperature [%.1f °C]" (ComfoAir, comfoairTemps_Chart) {channel="comfoair:comfoair:myComfoAir:temperatures#outdoorTemperatureOut"} +Number comfoairIncomingFan "Supply capacity [%d %%]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:ventilation#fanInPercent"} +Number comfoairOutgoingFan "Exhaust capacity [%d %%]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:ventilation#fanOutPercent"} +Number comfoairFanIn0 "Supply capacity - level 0 [%d %%]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:ventilation#fanIn0"} +Number comfoairFanOut0 "Exhaust capacity - level 0 [%d %%]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:ventilation#fanOut0"} +Switch comfoairBypassMode "Bypass [MAP(comfoair_bypass.map):%s]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:menuP9#bypassState"} +Switch comfoairGHXMode "GHX [MAP(comfoair_on-off.map):%s]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:menuP9#ewtState"} +Switch comfoairChimneyMode "Fire programme [MAP(comfoair_on-off.map):%s]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:menuP9#chimneyState"} +Switch comfoairHeaterMode "Heater [MAP(comfoair_on-off.map):%s]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:menuP9#heaterState"} +Switch comfoairCookerHoodMode "Extractor hood [MAP(comfoair_on-off.map):%s]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:menuP9#cookerhoodState"} +Switch comfoairEnthalpyMode "Enthalpy [MAP(comfoair_on-off.map):%s]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:menuP9#enthalpyState"} +Switch comfoairFreezeMode "Freeze [MAP(comfoair_freeze.map):%s]" (ComfoAir) {channel="comfoair:comfoair:myComfoAir:menuP9#frostState"} ``` `.sitemap` file: -``` +```perl sitemap comfoair label="ComfoAir" { - Frame label="Main" { - Text item=comfoairError labelcolor=[!="No Errors"="red"] valuecolor=[!="No Errors"="red"] - Switch item=comfoairControl mappings=[OFF="CCEase", ON="Computer"] - Switch item=comfoairErrorReset mappings=[1="Reset"] - Switch item=comfoairFilterReset mappings=[1="Reset"] - } - Frame label="Control" { - Selection item=comfoairFanLevel - Setpoint item=comfoairTargetTemperature step=0.5 minValue=15 maxValue=28 valuecolor=["black"] - } - Frame label="State" { - Text item=comfoairOutdoorIncomingTemperature valuecolor=["black"] - Text item=comfoairOutdoorOutgoingTemperature valuecolor=["black"] - Text item=comfoairIndoorIncomingTemperature valuecolor=["black"] - Text item=comfoairIndoorOutgoingTemperature valuecolor=["black"] - } - Frame { - Text item=comfoairIncomingFan valuecolor=["black"] - Text item=comfoairBypassMode valuecolor=["black"] - Text item=comfoairOutgoingFan valuecolor=["black"] - Text item=comfoairGHXMode valuecolor=[OFF="silver", ON="black"] - Text item=comfoairEfficiency valuecolor=["black"] - Text item=comfoairFreezeMode valuecolor=[OFF="black", ON="red"] - Text item=comfoairFilterRuntime_Message valuecolor=["black"] - Text item=comfoairChimneyMode valuecolor=[OFF="silver", ON="black"] - } + Frame label="Main" { + Text item=comfoairError labelcolor=[!="No Errors"="red"] valuecolor=[!="No Errors"="red"] + Switch item=comfoairControl mappings=[OFF="CCEase", ON="Computer"] + Switch item=comfoairErrorReset mappings=[1="Reset"] + Switch item=comfoairFilterReset mappings=[1="Reset"] + } + Frame label="Control" { + Selection item=comfoairFanLevel + Setpoint item=comfoairTargetTemperature step=0.5 minValue=15 maxValue=28 valuecolor=["black"] + } + Frame label="State" { + Text item=comfoairOutdoorIncomingTemperature valuecolor=["black"] + Text item=comfoairOutdoorOutgoingTemperature valuecolor=["black"] + Text item=comfoairIndoorIncomingTemperature valuecolor=["black"] + Text item=comfoairIndoorOutgoingTemperature valuecolor=["black"] + } + Frame { + Text item=comfoairIncomingFan valuecolor=["black"] + Text item=comfoairBypassMode valuecolor=["black"] + Text item=comfoairOutgoingFan valuecolor=["black"] + Text item=comfoairGHXMode valuecolor=[OFF="silver", ON="black"] + Text item=comfoairEfficiency valuecolor=["black"] + Text item=comfoairFreezeMode valuecolor=[OFF="black", ON="red"] + Text item=comfoairFilterRuntime_Message valuecolor=["black"] + Text item=comfoairChimneyMode valuecolor=[OFF="silver", ON="black"] + } } ``` `comfoair_bypass.map` file: -``` +```text ON=Opened OFF=Closed undefined=unknown @@ -280,7 +280,7 @@ undefined=unknown `comfoair_on-off.map` file: -``` +```text ON=active OFF=inactive undefined=unknown @@ -289,7 +289,7 @@ undefined=unknown `comfoair_freeze.map` file: -``` +```text ON=frozen OFF=OK undefined=unknown diff --git a/bundles/org.openhab.binding.coronastats/README.md b/bundles/org.openhab.binding.coronastats/README.md index 0249aca3cba..39738d1f671 100644 --- a/bundles/org.openhab.binding.coronastats/README.md +++ b/bundles/org.openhab.binding.coronastats/README.md @@ -1,7 +1,6 @@ # CoronaStats Binding -This binding provides the statistic about cases of COVID-19 from the website https://corona-stats.online/. - +This binding provides the statistic about cases of COVID-19 from the website [https://corona-stats.online/](https://corona-stats.online/). ## Supported Things @@ -10,7 +9,7 @@ The `country` thing, representing the statistics for a specified country. ## Discovery -This binding adds a default `world` thing to the Inbox. +This binding adds a default `world` thing to the Inbox. This can be used as bridge for country things you may add manually. ## Thing Configuration @@ -27,7 +26,7 @@ This can be used as bridge for country things you may add manually. | ------------- | :-----: | :------: | ------------------------------------------------- | | `countryCode` | - | yes | 2-letter code for the country you want to display | -For the correct 2-letter country code have a look at the website https://corona-stats.online/ +For the correct 2-letter country code have a look at the website [https://corona-stats.online/](https://corona-stats.online/) ## Channels @@ -49,7 +48,7 @@ For the correct 2-letter country code have a look at the website https://corona- ### Things -``` +```java Bridge coronastats:world:stats "Corona Stats World" @ "Corona" [refresh=15] { Thing country usa "Corona Stats USA" @ "Corona" [countryCode="US"] Thing country germany "Corona Stats Germany" @ "Corona" [countryCode="DE"] @@ -62,7 +61,7 @@ Bridge coronastats:world:stats "Corona Stats World" @ "Corona" [refresh=15] { ### Items -``` +```java Number:Dimensionless coronaCasesWorld "Total Cases World [%,d]" {channel="coronastats:world:stats:cases"} @@ -102,7 +101,7 @@ DateTime coronaUpdatedUSA "Updated USA [%1$tA, %1$td.%1$tm.%1$tY %1$tH:%1$tM]" ### Sitemap -``` +```perl Text label="Corona" { Frame label="World" { Text item=coronaCasesWorld diff --git a/bundles/org.openhab.binding.daikin/README.md b/bundles/org.openhab.binding.daikin/README.md index 839f354fca9..02dccd4088b 100644 --- a/bundles/org.openhab.binding.daikin/README.md +++ b/bundles/org.openhab.binding.daikin/README.md @@ -15,7 +15,7 @@ You can also manually add a new item if you know the IP address. Background discovery polls the network every minute for devices. Background discovery is **enabled** by default. -To **disable** background discovery, add the following line to the *conf/services/runtime.cfg* file: +To **disable** background discovery, add the following line to the _conf/services/runtime.cfg_ file: ```text discovery.daikin:background=false @@ -27,14 +27,14 @@ A BRP072C42 adapter requires a registered UUID to authenticate. Upon discovery, ## Thing Configuration -* `host` - The hostname of the Daikin air conditioner. Typically you'd use an IP address such as `192.168.0.5` for this field. -* `refresh` - The frequency with which to refresh information from the Daikin air conditioner specified in seconds. Defaults to 60 seconds. +- `host` - The hostname of the Daikin air conditioner. Typically you'd use an IP address such as `192.168.0.5` for this field. +- `refresh` - The frequency with which to refresh information from the Daikin air conditioner specified in seconds. Defaults to 60 seconds. ### Additional Thing configurations for BRP072C42 adapter -* `secure` - Must be set to true for BRP072C42 to access it through https. -* `uuid` - A UUID used to access the BRP072C42 adapter. A handy UUID generator can be found at . -* `key` - The 13-digit key from the Daikin adapter. +- `secure` - Must be set to true for BRP072C42 to access it through https. +- `uuid` - A UUID used to access the BRP072C42 adapter. A handy UUID generator can be found at . +- `key` - The 13-digit key from the Daikin adapter. ## Channels @@ -110,7 +110,7 @@ For the BRP15B61: daikin.things: -``` +```java // for BRP069B41 or BRP072A42 daikin:ac_unit:living_room_ac [ host="192.168.0.5" ] // for BRP072C42 @@ -121,7 +121,7 @@ daikin:airbase_ac_unit:living_room_ac [ host="192.168.0.5" ] daikin.items: -``` +```java // for BRP069B41, BRP072A42 or BRP072C42 Switch DaikinACUnit_Power { channel="daikin:ac_unit:living_room_ac:power" } Number:Temperature DaikinACUnit_SetPoint { channel="daikin:ac_unit:living_room_ac:settemp" } @@ -154,7 +154,7 @@ Switch DaikinACUnit_Zone8 { channel="daikin:airbase_ac_unit:living_room_ac:zone8 daikin.sitemap: -``` +```perl // for BRP069B41, BRP072A42 or BRP072C42 Switch item=DaikinACUnit_Power Setpoint item=DaikinACUnit_SetPoint visibility=[DaikinACUnit_Power==ON] diff --git a/bundles/org.openhab.binding.dali/README.md b/bundles/org.openhab.binding.dali/README.md index ebbd159ece1..2549b5d90e1 100644 --- a/bundles/org.openhab.binding.dali/README.md +++ b/bundles/org.openhab.binding.dali/README.md @@ -9,13 +9,13 @@ As it only provides a thin multiplexer for the USB interface, the DALI messages Currently, these things are supported: - - daliserver (bridge) - - device (single device/ballast on the DALI bus) - - group (group of DALI devices) - - rgb (virtual device consisting of three directly addressed devices that represent r/g/b (LED) color channels) - - device-dt8 (single device/ballast supporting DT8 (single-channel RGB & color temperature control)) - - group-dt8 (group of DALI devices supporting DT8) - +- daliserver (bridge) +- device (single device/ballast on the DALI bus) +- group (group of DALI devices) +- rgb (virtual device consisting of three directly addressed devices that represent r/g/b (LED) color channels) +- device-dt8 (single device/ballast supporting DT8 (single-channel RGB & color temperature control)) +- group-dt8 (group of DALI devices supporting DT8) + This binding was tested on a DALI 1 bus with daliserver 0.2. ## Discovery @@ -69,7 +69,7 @@ Automatic device discovery is not yet implemented. .things file -``` +```java Bridge dali:daliserver:237dbae7 "Daliserver" [ host="localhost", port=55825] { Thing rgb 87bf0403-a45d-4037-b874-28f4ece30004 "RGB Lights" [ targetIdR=0, targetIdG=1, targetIdB=2 ] Thing device 995e16ca-07c4-4111-9cda-504cb5120f82 "Warm White" [ targetId=3 ] @@ -77,10 +77,9 @@ Bridge dali:daliserver:237dbae7 "Daliserver" [ host="localhost", port=55825] { } ``` - .items file -``` +```java Dimmer WarmWhiteLivingRoom "Warm White Living Room" {channel="dali:device:237dbae7:995e16ca-07c4-4111-9cda-504cb5120f82:dimImmediately"} Color ColorLivingRoom "Light Color Living Room" {channel="dali:device:237dbae7:87bf0403-a45d-4037-b874-28f4ece30004:color"} Switch LightsLivingRoom "Lights Living Room On/Off" {channel="dali:device:237dbae7:31da8dac-8e09-455a-bc7a-6ed70f740001:dimImmediately"} diff --git a/bundles/org.openhab.binding.danfossairunit/README.md b/bundles/org.openhab.binding.danfossairunit/README.md index d6833f916c7..49d7d3a6e97 100644 --- a/bundles/org.openhab.binding.danfossairunit/README.md +++ b/bundles/org.openhab.binding.danfossairunit/README.md @@ -1,22 +1,22 @@ # DanfossAirUnit Binding This binding supports controlling and monitoring [Danfoss air units](https://www.danfoss.com/en/products/energy-recovery-devices/dhs/heat-recovery-ventilation/air-units/) via Ethernet connection. - + ## Supported Things -This binding has been tested/reported to work with the Danfoss Air w2 / a2 / a3 devices. +This binding has been tested/reported to work with the Danfoss Air w2 / a2 / a3 devices. ## Discovery -Air units in the LAN are automatically discovered via broadcast and added to the Inbox. +Air units in the LAN are automatically discovered via broadcast and added to the Inbox. ## Thing Configuration These are the available configuration parameters: - `host` Hostname/IP of the air unit (automatically set by discovery service) -- `refreshInterval` Time (in seconds) between monitoring requests to the air unit. Smaller values mean more network load, typically set between a few seconds and a minute. Defaults to 10 seconds. -- `updateUnchangedValuesEveryMillis` Minimum time between state updates sent to the event bus for a particular channel when the state of the channel didn't change. This should avoid spamming the event bus with unnecessary updates. When set to 0, all channel state are updated every time the air unit requests are sent (see refresh interval). When set to a non zero value, unchanged values are only reported after the configured timespan has passed. Changed values are always sent to the event bus. Defaults to 60.000 (one minute), so updates are sent every minute or if the state of the channel changes. +- `refreshInterval` Time (in seconds) between monitoring requests to the air unit. Smaller values mean more network load, typically set between a few seconds and a minute. Defaults to 10 seconds. +- `updateUnchangedValuesEveryMillis` Minimum time between state updates sent to the event bus for a particular channel when the state of the channel didn't change. This should avoid spamming the event bus with unnecessary updates. When set to 0, all channel state are updated every time the air unit requests are sent (see refresh interval). When set to a non zero value, unchanged values are only reported after the configured timespan has passed. Changed values are always sent to the event bus. Defaults to 60.000 (one minute), so updates are sent every minute or if the state of the channel changes. ## Channels @@ -43,7 +43,6 @@ These are the available configuration parameters: | filter_life | service | Number | RO | Remaining life of filter until exchange is necessary (percentage) | | filter_period | service | Number | RW | Number of months between filter replacements (between 3 and 12). This value affects calculation of filter_life by the unit, and might get overwritten by Air Dial or Link CC Controller. | - ## Full Example ### Things @@ -55,7 +54,7 @@ You can also manually configure your air unit in case you don't want to use auto (e. g. if you want to have a portable configuration): Create a new file, e. g. `danfoss.things`, in your _things_ configuration folder: -``` +```java Thing danfossairunit:airunit:myairunit [host="192.168.0.7", refreshInterval=5, updateUnchangedValuesEveryMillis=30000] @@ -63,7 +62,7 @@ updateUnchangedValuesEveryMillis=30000] ### Items -``` +```java Dimmer DanfossHRV_ManualFanStep "Manual Fan Step [%s]" {channel = "danfossairunit:airunit:myairunit:main#manual_fan_step"} Number DanfossHRV_SupplyFanSpeed "Supply Fan Speed" {channel = "danfossairunit:airunit:myairunit:main#supply_fan_speed"} Number DanfossHRV_ExtractFanSpeed "Extract Fan Speed" {channel = "danfossairunit:airunit:myairunit:main#extract_fan_speed"} @@ -82,7 +81,7 @@ Number DanfossHRV_FilterPeriod "Filter period" { channel = "danfossairunit:airun ### Sitemap -``` +```perl sitemap danfoss label="Danfoss" { Frame label="Control" { Selection item=DanfossHRV_Mode mappings=[DEMAND="Demand", OFF="Off", PROGRAM="Program", MANUAL="Manual"] diff --git a/bundles/org.openhab.binding.dbquery/README.md b/bundles/org.openhab.binding.dbquery/README.md index f39cd1aa1b5..1c9c21d6515 100644 --- a/bundles/org.openhab.binding.dbquery/README.md +++ b/bundles/org.openhab.binding.dbquery/README.md @@ -8,7 +8,7 @@ The source of the query can be any supported database, and doesn't need to be th Some use cases can be: - Integrate a device that stores its data in a database -- Query derived data from you openHAB persistence, for example with Influx2 tasks you can process your data to create a new one +- Query derived data from you openHAB persistence, for example with Influx2 tasks you can process your data to create a new one - Bypass limitations of current openHAB persistence queries ## Supported Things @@ -35,7 +35,7 @@ Defines a connection to an Influx2 database and allows creating queries on it. ### query -The `Query` thing defines a native query that provides several channels that you can bind to items. +The `Query` thing defines a native query that provides several channels that you can bind to items. #### Query parameters @@ -45,7 +45,7 @@ The query items support the following parameters: |--------------|----------|----------|-----------------------------------------------------------------------| | query | true | | Query string in native syntax | | interval | false | 0 | Interval in seconds in which the query is automatically executed | -| hasParameters| false | false | True if the query has parameters, false otherwise | +| hasParameters| false | false | True if the query has parameters, false otherwise | | timeout | false | 0 | Query execution timeout in seconds | | scalarResult | false | true | If query always returns a single value or not | | scalarColumn | false | | In case of multiple columns, it indicates which to use for scalarResult| @@ -56,25 +56,25 @@ These are described further in the following subsections. The query the items represents in the native language of your database: - - Flux for `influxdb2` - +- Flux for `influxdb2` + #### hasParameters If `hasParameters=true` you can use parameters in the query string that can be dynamically set with the `setQueryParameters` action. - + For InfluxDB use the `${paramName}` syntax for each parameter, and keep in mind that the values from that parameters must be from a trusted source as current parameter substitution is subject to query injection attacks. - + #### timeout A time-out in seconds to wait for the query result, if it's exceeded, the result will be discarded and the addon will do its best to cancel the query. Currently it's ignored and it will be implemented in a future version. -#### scalarResult +#### scalarResult If `true` the query is expected to return a single scalar value that will be available to `result` channels as string, number, boolean,... If the query can return several rows and/or several columns per row then it needs to be set to `false` and the result can be retrieved in `resultString` -channel as JSON or using the `getLastQueryResult` action. +channel as JSON or using the `getLastQueryResult` action. #### scalarColumn @@ -100,18 +100,20 @@ last previous executed query. The `resultString` channel is the only valid one if `scalarResult=false`, and in that case it contains the query result serialized to JSON in that format: - { - correct : true, - data : [ - { - column1 : value, - column2 : value - }, - { ... }, //row2 - { ... } //row3 - ] - } - +```json +{ + correct : true, + data : [ + { + column1 : value, + column2 : value + }, + { ... }, //row2 + { ... } //row3 + ] +} +``` + ### Channel Triggers #### calculateParameters @@ -119,14 +121,14 @@ The `resultString` channel is the only valid one if `scalarResult=false`, and in Triggers when there's a need to calculate parameters before query execution. When a query has `hasParameters=true` it fires the `calculateParameters` channel trigger and pauses the execution until `setQueryParameters` action is call in that query. - + In the case a query has parameters, it's expected that there is a rule that catches the `calculateParameters` trigger, calculate the parameters with the corresponding logic and then calls the `setQueryParameters` action, after that the query will be executed. - + ## Actions ### For DatabaseBridge -#### executeQuery +#### executeQuery It allows executing a query synchronously from a script/rule without defining it in a Thing. @@ -143,16 +145,16 @@ And it returns an `ActionQueryResult` that has the following properties: - isScalarResult: It returns if the result is scalar one (only one row with one column) - resultAsScalar: It returns the result as a scalar if possible, if not returns null - Example (using Jython script): - from core.log import logging, LOG_PREFIX - log = logging.getLogger("{}.action_example".format(LOG_PREFIX)) - map = {"time" : "-2h"} - influxdb = actions.get("dbquery","dbquery:influxdb2:sampleQuery") //Get bridge thing - result = influxdb.executeQuery("from(bucket: \"default\") |> range(start:-2h) |> filter(fn: (r) => r[\"_measurement\"] == \"go_memstats_frees_total\") |> filter(fn: (r) => r[\"_field\"] == \"counter\") |> mean()",{},5) - log.info("execute query result is "+str(result.data)) - +```python +from core.log import logging, LOG_PREFIX +log = logging.getLogger("{}.action_example".format(LOG_PREFIX)) +map = {"time" : "-2h"} +influxdb = actions.get("dbquery","dbquery:influxdb2:sampleQuery") //Get bridge thing +result = influxdb.executeQuery("from(bucket: \"default\") |> range(start:-2h) |> filter(fn: (r) => r[\"_measurement\"] == \"go_memstats_frees_total\") |> filter(fn: (r) => r[\"_field\"] == \"counter\") |> mean()",{},5) +log.info("execute query result is "+str(result.data)) +``` Use this action with care, because as the query is executed synchronously, it is not good to execute long-running queries that can block script execution. @@ -165,9 +167,11 @@ To execute the action you need to pass the parameters as a Map. Example (using Jython script): - params = {"time" : "-2h"} - dbquery = actions.get("dbquery","dbquery:query:queryWithParams") //Get query thing - dbquery.setQueryParameters(params) +```python +params = {"time" : "-2h"} +dbquery = actions.get("dbquery","dbquery:query:queryWithParams") //Get query thing +dbquery.setQueryParameters(params) +``` #### getLastQueryResult @@ -176,35 +180,40 @@ It doesn't have any parameters and returns an `ActionQueryResult` as defined in Example (using Jython script): - dbquery = actions.get("dbquery","dbquery:query:queryWithParams") //Get query thing - result = dbquery.getLastQueryResult() - +```python +dbquery = actions.get("dbquery","dbquery:query:queryWithParams") //Get query thing +result = dbquery.getLastQueryResult() +``` ## Examples -### The Simplest case +### The Simplest case Define an InfluxDB2 database thing and a query with an interval execution. That executes the query every 15 seconds and punts the result in `myItem`. - # Bridge Thing definition - Bridge dbquery:influxdb2:mydatabase "InfluxDB2 Bridge" [ bucket="default", user="admin", url="http://localhost:8086", organization="openhab", token="*******" ] - - # Query Thing definition - Thing dbquery:query:myquery "My Query" [ interval=15, hasParameters=false, scalarResult=true, timeout=0, query="from(bucket: \"default\") |> range(start:-1h) |> filter(fn: (r) => r[\"_measurement\"] == \"go_memstats_frees_total\") |> filter(fn: (r) => r[\"_field\"] == \"counter\") |> mean()", scalarColumn="_value" ] - - # Item definition - Number myItem "QueryResult" {channel="dbquery:query:myquery:resultNumber"} +```java +# Bridge Thing definition +Bridge dbquery:influxdb2:mydatabase "InfluxDB2 Bridge" [ bucket="default", user="admin", url="http://localhost:8086", organization="openhab", token="*******" ] + +# Query Thing definition +Thing dbquery:query:myquery "My Query" [ interval=15, hasParameters=false, scalarResult=true, timeout=0, query="from(bucket: \"default\") |> range(start:-1h) |> filter(fn: (r) => r[\"_measurement\"] == \"go_memstats_frees_total\") |> filter(fn: (r) => r[\"_field\"] == \"counter\") |> mean()", scalarColumn="_value" ] + +# Item definition +Number myItem "QueryResult" {channel="dbquery:query:myquery:resultNumber"} +``` ### A query with parameters Using the previous example you change the `range(start:-1h)` for `range(start:${time})` -Create a rule that is fired +Create a rule that is fired - - **When** `calculateParameters` is triggered in `myquery` - - **Then** executes the following script action (in that example Jython): - - map = {"time" : "-2h"} - dbquery = actions.get("dbquery","dbquery:query:myquery") - dbquery.setQueryParameters(map) +- **When** `calculateParameters` is triggered in `myquery` +- **Then** executes the following script action (in that example Jython): + +```text +map = {"time" : "-2h"} +dbquery = actions.get("dbquery","dbquery:query:myquery") +dbquery.setQueryParameters(map) +``` diff --git a/bundles/org.openhab.binding.deconz/README.md b/bundles/org.openhab.binding.deconz/README.md index 0619a08b362..ea5759edbbe 100644 --- a/bundles/org.openhab.binding.deconz/README.md +++ b/bundles/org.openhab.binding.deconz/README.md @@ -29,7 +29,6 @@ These sensors are supported: | Air quality Sensor | ZHAAirQuality | `airqualitysensor` | | Color Controller | ZBT-Remote-ALL-RGBW | `colorcontrol` | - Additionally lights, window coverings (blinds), door locks and thermostats are supported: | Device type | Resource Type | Thing type | @@ -78,7 +77,7 @@ For this process the deCONZ bridge must be unlocked in the deCONZ software so th ### Things All non-bridge things share the mandatory `id` parameter, an integer assigned to the device while pairing to deconz. -Auto-discovered things do not need to be configured. +Auto-discovered things do not need to be configured. All sensor-things have an additional `lastSeenPolling` parameter. Due to limitations in the API of deCONZ, the `lastSeen` channel (available some sensors) is only available when using polling. @@ -98,7 +97,7 @@ If this fails, the advanced `colormode` parameter can be set to `xy` or `hs`. If you use the textual configuration, the thing file without an API key will look like this, for example: -``` +```java Bridge deconz:deconz:homeserver [ host="192.168.0.10" ] ``` @@ -107,13 +106,13 @@ Please note that the generated key cannot be written automatically to the `.thin The generated key can be queried from the configuration using the openHAB console. To do this log into the [console](https://www.openhab.org/docs/administration/console.html) and use the command `things show` to display the configuration parameters, e.g: -``` +```shell things show deconz:deconz:homeserver ``` Afterwards the API key has to be inserted in the `.thing` file as `apikey` configuration value, e.g.: -``` +```java Bridge deconz:deconz:homeserver [ host="192.168.0.10", apikey="ABCDEFGHIJ" ] ``` @@ -166,13 +165,13 @@ Other devices support | Channel Type ID | Item Type | Access Mode | Description | Thing types | |-------------------|--------------------------|:-----------:|---------------------------------------|-------------------------------------------------| -| brightness | Dimmer | R/W | Brightness of the light | `dimmablelight`, `colortemperaturelight` | +| brightness | Dimmer | R/W | Brightness of the light | `dimmablelight`, `colortemperaturelight` | | switch | Switch | R/W | State of an ON/OFF device | `onofflight` | | color | Color | R/W | Color of an multi-color light | `colorlight`, `extendedcolorlight`, `lightgroup`| | color_temperature | Number | R/W | Color temperature in Kelvin. The value range is determined by each individual light | `colortemperaturelight`, `extendedcolorlight`, `lightgroup` | | effect | String | R/W | Effect selection. Allowed commands are set dynamically | `colorlight` | | effectSpeed | Number | W | Effect Speed | `colorlight` | -| lock | Switch | R/W | Lock (ON) or unlock (OFF) the doorlock| `doorlock` | +| lock | Switch | R/W | Lock (ON) or unlock (OFF) the doorlock| `doorlock` | | ontime | Number:Time | W | Timespan for which the light is turned on | all lights | | position | Rollershutter | R/W | Position of the blind | `windowcovering` | | heatsetpoint | Number:Temperature | R/W | Target Temperature in °C | `thermostat` | @@ -182,7 +181,7 @@ Other devices support | alert | String | W | Turn alerts on. Allowed commands are `none`, `select` (short blinking), `lselect` (long blinking) | `warningdevice`, `lightgroup`, `dimmablelight`, `colorlight`, `extendedcolorlight`, `colortemperaturelight` | | all_on | Switch | R | All lights in group are on | `lightgroup` | | any_on | Switch | R | Any light in group is on | `lightgroup` | -| scene | String | W | Recall a scene. Allowed commands are set dynamically | `lightgroup` | +| scene | String | W | Recall a scene. Allowed commands are set dynamically | `lightgroup` | **NOTE:** For groups `color` and `color_temperature` are used for sending commands to the group. Their state represents the last command send to the group, not necessarily the actual state of the group. @@ -214,9 +213,9 @@ Both will be added during runtime if supported by the switch. ## Full Example -### Things file ### +### Things file -``` +```java Bridge deconz:deconz:homeserver [ host="192.168.0.10", apikey="ABCDEFGHIJ" ] { presencesensor livingroom-presence "Livingroom Presence" [ id="1" ] temperaturesensor livingroom-temperature "Livingroom Temperature" [ id="2" ] @@ -233,9 +232,9 @@ Bridge deconz:deconz:homeserver [ host="192.168.0.10", apikey="ABCDEFGHIJ" ] { } ``` -### Items file ### +### Items file -``` +```java Switch Livingroom_Presence "Presence Livingroom [%s]" { channel="deconz:presencesensor:homeserver:livingroom-presence:presence" } Number:Temperature Livingroom_Temperature "Temperature Livingroom [%.1f °C]" { channel="deconz:temperaturesensor:homeserver:livingroom-temperature:temperature" } Number:Dimensionless Livingroom_Humidity "Humidity Livingroom [%.1f %%]" { channel="deconz:humiditysensor:homeserver:livingroom-humidity:humidity" } @@ -252,7 +251,7 @@ Switch Entrance_Door "Doorlock" ### Events -```php +```java rule "example trigger rule" when Channel "deconz:switch:homeserver:livingroom-hue-tap:buttonevent" triggered 34 // Hue Tap Button 1 pressed diff --git a/bundles/org.openhab.binding.denonmarantz/README.md b/bundles/org.openhab.binding.denonmarantz/README.md index e5ea081d2e4..e814b750af9 100644 --- a/bundles/org.openhab.binding.denonmarantz/README.md +++ b/bundles/org.openhab.binding.denonmarantz/README.md @@ -42,32 +42,32 @@ The DenonMarantz AVR supports the following channels (some channels are model sp | Channel Type ID | Item Type | Description | |-------------------------|--------------|--------------| -| *General* | | +| _General_ | | | general#power | Switch (RW) | Power on/off | general#surroundProgram | String (R) | current surround program (e.g. STEREO) | general#artist | String (R) | artist of current track | general#album | String (R) | album of current track | general#track | String (R) | title of current track | general#command | String (W) | Command to send to the AVR (for use in Rules) -| *Main zone* | | +| _Main zone_ | | | mainZone#power | Switch (RW) | Main zone power on/off | mainZone#volume | Dimmer (RW) | Main zone volume | mainZone#volumeDB | Number (RW) | Main zone volume in dB (-80 offset) | mainZone#mute | Switch (RW) | Main zone mute | mainZone#input | String (RW) | Main zone input (e.g. TV, TUNER, ..) -| *Zone 2* | | +| _Zone 2_ | | | zone2#power | Switch (RW) | Zone 2 power on/off | zone2#volume | Dimmer (RW) | Zone 2 volume | zone2#volumeDB | Number (RW) | Zone 2 volume in dB (-80 offset) | zone2#mute | Switch (RW) | Zone 2 mute | zone2#input | String (RW) | Zone 2 input -| *Zone 3* | | +| _Zone 3_ | | | zone3#power | Switch (RW) | Zone 3 power on/off | zone3#volume | Dimmer (RW) | Zone 3 volume | zone3#volumeDB | Number (RW) | Zone 3 volume in dB (-80 offset) | zone3#mute | Switch (RW) | Zone 3 mute | zone3#input | String (RW) | Zone 3 input -| *Zone 4* | | +| _Zone 4_ | | | zone4#power | Switch (RW) | Zone 4 power on/off | zone4#volume | Dimmer (RW) | Zone 4 volume | zone4#volumeDB | Number (RW) | Zone 4 volume in dB (-80 offset) @@ -82,13 +82,13 @@ The DenonMarantz AVR supports the following channels (some channels are model sp `.things` file: -``` +```java Thing denonmarantz:avr:1 "Receiver" @ "Living room" [host="192.168.1.100"] ``` `.items` file: -``` +```java Switch marantz_power "Receiver" {channel="denonmarantz:avr:1:general#power"} Dimmer marantz_volume "Volume" {channel="denonmarantz:avr:1:mainZone#volume"} Number marantz_volumeDB "Volume [%.1f dB]" {channel="denonmarantz:avr:1:mainzone#volume"} @@ -101,7 +101,7 @@ String marantz_command {channel="denonmarantz:avr:1 `.sitemap` file: -``` +```perl ... Group item=marantz_input label="Receiver" icon="receiver" { Default item=marantz_power @@ -121,4 +121,4 @@ These resources can be useful to learn what to send using the `command`channel: - [AVR-X2000/E400](http://www2.aerne.com/Public/dok-sw.nsf/0c6187bc750a16fcc1256e3c005a9740/96a2ba120706d10dc1257bdd0033493f/$FILE/AVRX2000_E400_PROTOCOL(10.1.0)_V04.pdf) - [AVR-X4000](https://usa.denon.com/us/product/hometheater/receivers/avrx4000?docname=AVRX4000_PROTOCOL(10%203%200)_V03.pdf) - [AVR-3311CI/AVR-3311/AVR-991](https://www.awe-europe.com/documents/Control%20Docs/Denon/Archive/AVR3311CI_AVR3311_991_PROTOCOL_V7.1.0.pdf) -- [Denon/Marantz Control Protocol] (https://assets.eu.denon.com/DocumentMaster/DE/AVR1713_AVR1613_PROTOCOL_V8.6.0.pdf) +- [Denon/Marantz Control Protocol](https://assets.eu.denon.com/DocumentMaster/DE/AVR1713_AVR1613_PROTOCOL_V8.6.0.pdf) diff --git a/bundles/org.openhab.binding.deutschebahn/README.md b/bundles/org.openhab.binding.deutschebahn/README.md index 944c401b6d0..e71059b97f1 100644 --- a/bundles/org.openhab.binding.deutschebahn/README.md +++ b/bundles/org.openhab.binding.deutschebahn/README.md @@ -15,17 +15,17 @@ The information are requested from the timetable api of Deutsche Bahn developer To configure a timetable you first need to register at Deutsche Bahn developer portal and register for timetable API to get an access key. 1. Go to [DB API Marketplace](https://developers.deutschebahn.com/) -2. Register new account or login with an existing one -3. If no application is configured yet (check Tab "Anwendungen" at top) create a new application. Only the name is required, for example openHAB, any other fields can be left blank. -4. Remember the shown **Client ID** and **Client Secret**. -5. Go to **Katalog** and search for **Timetables** api. -6. Within **Zugehörige APIs** select the Timetables api. -7. Select **Abonnieren** at top left of the page. -8. Select the Nutzungsplan **Free** by clicking **Abonnieren**. -9. Select the previously created application. -10. Click **Next**. -11. Click **Fertig**. -12. Now you have successfully registered the api within an application. The **Client ID** and **Client Secret** can now be used during bridge configuration. +1. Register new account or login with an existing one +1. If no application is configured yet (check Tab "Anwendungen" at top) create a new application. Only the name is required, for example openHAB, any other fields can be left blank. +1. Remember the shown **Client ID** and **Client Secret**. +1. Go to **Katalog** and search for **Timetables** api. +1. Within **Zugehörige APIs** select the Timetables api. +1. Select **Abonnieren** at top left of the page. +1. Select the Nutzungsplan **Free** by clicking **Abonnieren**. +1. Select the previously created application. +1. Click **Next**. +1. Click **Fertig**. +1. Now you have successfully registered the api within an application. The **Client ID** and **Client Secret** can now be used during bridge configuration. ### Determine the EVA-No of your station @@ -47,13 +47,13 @@ In addition, you can configure if only arrivals, only departures or all trains s | `trainFilter` | | Yes | Selects the trains that will be displayed in the timetable. Either only arrivals, only departures or all trains can be displayed. | | `additionalFilter` | | No | Specifies additional filters for trains, that should be displayed within the timetable. | -** Additional filter ** +**Additional filter** If you only want to display certain trains within your timetable, you can specify an additional filter. This will be evaluated when loading trains, and only trains that matches the given filter will be contained within the timetable. To specify an advanced filter you can -- specify a filter for the value of a given channel. Therefore, you must specify the channel name (with channel group) and specify a compare value like this: +- specify a filter for the value of a given channel. Therefore, you must specify the channel name (with channel group) and specify a compare value like this: `departure#line="RE60"` this will select all trains with line RE60 - use regular expressions for expected channel values, for example: `departure#line="RE.*"`, this will match all lines starting with "RE". - combine multiple statements as "and" conjunction by using `&`. If used, both parts must match, for example: `departure#line="RE60" & trip#category="WFB"` @@ -83,23 +83,22 @@ train things, the channels of these trains will be undefined. |-|-|-|-| | `position` | | Yes | The position of the train within the timetable. | - ## Channels Each train has a set of channels, that provides access to any information served by the timetable API. A detailed description of the values and their meaning can be found within the [Timetables V1 API Description](https://developers.deutschebahn.com/db-api-marketplace/apis/product/timetables). The information are grouped into three channel-groups: The first channel group (trip) contains all information for the trip of the train, for example the category (like ICE, RE, S). -The second and third channel group contains information about the arrival and the departure of the train at the given station. +The second and third channel group contains information about the arrival and the departure of the train at the given station. Both of the groups may provide an 'UNDEF' channel value, when the train does not arrive / depart at this station -(due it starts or ends at the given station). If you have configured your timetable to contain only departures (with property trainFilter) the departure channel values will always be defined +(due it starts or ends at the given station). If you have configured your timetable to contain only departures (with property trainFilter) the departure channel values will always be defined and if you have selected only arrivals the arrival channel values will always be defined. Channels will have a 'NULL' channel value, when the corresponding attribute is not set. Basically most information are available as planned and changed value. This allows to easy display changed values (for example the delay or changed platform). +### Channels for trip information -**Channels for trip information** | channel | type | description | |----------|--------|------------------------------| | category | String | Provides the category of the trip, e.g. "ICE" or "RE". | @@ -108,8 +107,8 @@ Basically most information are available as planned and changed value. This allo | trip-type | String | Provides the type of the trip. | | owner | String | Provides the owner of the train. A unique short-form and only intended to map a trip to specific evu (EisenbahnVerkehrsUnternehmen). | +### Channels for arrival / departure -**Channels for arrival / departure** | channel | type | description | |----------|--------|------------------------------| | planned-path | String | Provides the planned path of a train. | @@ -138,7 +137,7 @@ Basically most information are available as planned and changed value. This allo timetable.things -``` +```java Bridge deutschebahn:timetable:timetableLehrte "Fahrplan Lehrte" [ accessToken="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", trainFilter="departures", evaNo="8000226" ] { Thing deutschebahn:train:timetableLehrte:lehrteZug1 "Zug 1" [ position="1" ] Thing deutschebahn:train:timetableLehrte:lehrteZug2 "Zug 2" [ position="2" ] @@ -147,7 +146,7 @@ Bridge deutschebahn:timetable:timetableLehrte "Fahrplan Lehrte" [ accessToken="X timetable.items -``` +```java // Groups Group zug1 "Zug 1" Group zug1Fahrt "Zug 1 Fahrt" (zug1) @@ -216,7 +215,7 @@ String Zug1_Departure_Wings "Wings" (zug1Abfahrt) {channel="deutschebahn:train:t Example widget for displaying train details -``` +```yaml uid: timetable_train_details tags: - card @@ -364,7 +363,6 @@ slots: text-align: right ``` - Using the widget for displaying the next four departures: ![Departures Hannover HBF](doc/Abfahrten_HannoverHBF.png "openHAB page with four widgets displaying the next departures at Hannover HBF") diff --git a/bundles/org.openhab.binding.digiplex/README.md b/bundles/org.openhab.binding.digiplex/README.md index 0c13d329b36..314ce2c47ff 100644 --- a/bundles/org.openhab.binding.digiplex/README.md +++ b/bundles/org.openhab.binding.digiplex/README.md @@ -14,7 +14,6 @@ Please refer to PRT3 module manual for instructions how to modify baudrate (defa Once `PRT3 Module` is added and communication with the alarm system confirmed by its `online` status, please start discovery process to automatically discover (and add as new Things) all zones and areas defined in the alarm system. - ## Binding Configuration There is no binding level configuration required. @@ -105,6 +104,6 @@ Message format is as follows: For example, the following sitemap item can be used to send commands to the area and receive response status as modified color of a label: -``` +```java Switch item=areaControl label="Actions[]" mappings=[QA="Regular Quick Arm",QS="Stay Quick Arm",D1111="Disarm"] labelcolor=[Ok="green",Fail="red"] ``` diff --git a/bundles/org.openhab.binding.digitalstrom/README.md b/bundles/org.openhab.binding.digitalstrom/README.md index db7f1dd21f8..4e35584c24a 100644 --- a/bundles/org.openhab.binding.digitalstrom/README.md +++ b/bundles/org.openhab.binding.digitalstrom/README.md @@ -12,15 +12,15 @@ The digitalSTROM-Server communicates through the digitalSTROM-Meters with the di ### digitalSTROM-Server -The digitalSTROM-Server is required for accessing any other digitalSTROM-Devices. It acts like a *"bridge"*. +The digitalSTROM-Server is required for accessing any other digitalSTROM-Devices. It acts like a _"bridge"_. ### digitalSTROM-Devices -At this point almost all available **GE**, **SW**, **GR** and **BL** digitalSTROM-Devices with a set output-mode, unequal *disabled*, are supported by this binding. +At this point almost all available **GE**, **SW**, **GR** and **BL** digitalSTROM-Devices with a set output-mode, unequal _disabled_, are supported by this binding. Furthermore sensor devices like the **dS-iSens200** and **SW-devices** with binary-inputs are supported. Last but not least the **circuit** (dS-Meter) is supported, too. They will provide the power consumption and electric meter as channels. -For that there are identically named thing types. Only the *GR* type has a channel (shade), which cannot be changed. +For that there are identically named thing types. Only the _GR_ type has a channel (shade), which cannot be changed. The other types add their channels dynamically affected by the set color-group and output-mode. They also automatically change or add the channels, if the color-group or output-mode has changed through the dSS-web-configuration or the configured sensor priorities of the thing has changed. @@ -56,44 +56,44 @@ The different scene thing types are listed in the following table. | zoneScene | Zone-Scene | Represents a digitalSTROM Zone-Scene. | | groupScene | Group-Scene | Represents a digitalSTROM Group-Scene. | | namedScene | Named-Scene | Represents a digitalSTROM Scene, which has a user-defined name. | - + ### digitalSTROM-Zone-Temperature-Control Last but not least, the digitalSTROM-Zone-Temperature-Control is also supported, if a zone-temerature-control is configured, as thing-type **zone_temperature_control**. -The difference between the digitalSTROM-heating-control-app is, that there are no operation-modes, like *comfort* or *eco*. -You can directly set the target temperature, in case *pid-control* is configured, otherwise you can set the value in percent of heating valves at the zone. -The needed channels will be added automatically, as it is also the case for the devices. +The difference between the digitalSTROM-heating-control-app is, that there are no operation-modes, like _comfort_ or _eco_. +You can directly set the target temperature, in case _pid-control_ is configured, otherwise you can set the value in percent of heating valves at the zone. +The needed channels will be added automatically, as it is also the case for the devices. ## Discovery -The digitalSTROM-Server is discovered by mDNS or *dss.local.* at the local network. +The digitalSTROM-Server is discovered by mDNS or _dss.local._ at the local network. Once the server is added as a thing, you have to set a user name and password or insert a valid application-token to authenticate with the server. -If the binding is authorized, it automatically reads all supported devices, the dS-Meters and temperature controlled configured zones, that are set up on the digitalSTROM-System, and puts them into the *inbox*. - +If the binding is authorized, it automatically reads all supported devices, the dS-Meters and temperature controlled configured zones, that are set up on the digitalSTROM-System, and puts them into the _inbox_. + digitalSTROM-Scenes can be discovered, too. The background scene-discovery is deactivated by default to not flood the inbox. Otherwise it will discover so many scenes, that it can be difficult to find the searched devices. - + Discoverable scenes are all user named scenes, group scenes that are reachable by local push-buttons, zone scenes and apartment scenes. The discovery also will discover all called scenes, if they aren't automatically discovered yet. -Temperature control scenes, like *eco* will be ignored, so they cannot be discovered. +Temperature control scenes, like _eco_ will be ignored, so they cannot be discovered. If you only want to discover one of the thing types, you can start a discovery scan on the thing type you want to have discovered. You can use the command line command, e.g.: ``openhab:discovery start digitalstrom:namedScene`` to start the scan. -Which thing types this binding supports, please have a look at **Supported Things**. +Which thing types this binding supports, please have a look at **Supported Things**. ## Thing Configuration and Properties ### digitalSTROM-Server -The digitalSTROM-Server thing has the following configuration parameter groups: *Connection configuration*, *Server information* and *General configurations*. +The digitalSTROM-Server thing has the following configuration parameter groups: _Connection configuration_, _Server information_ and _General configurations_. #### Connection configuration If the digitalSTROM-Server isn’t found automatically, e.g. because the server isn’t placed at the local network or the mDNS-service is deactivated, you have to insert the network address or URL and the authentication data manually through the graphical user interface or type it into the \*.thing with textual configuration. If you use your user name and password for authentication and there is already a token for this application, it will be automatically retrieved from the digitalSTROM-Server, otherwise a new application-token will be generated. -| Parameter Label | Parameter ID | Description | Required | Advanced +| Parameter Label | Parameter ID | Description | Required | Advanced |--------------|------------|--------------------------------|----------------- |------------- | | Network address | dSSAddress | Network address of the digitalSTROM-Server.| true | false | | User name | userName | Name of a registered user to authenticate to the digitalSTROM-Server.| user name and password or Application-Token | false | @@ -101,28 +101,27 @@ If you use your user name and password for authentication and there is already a | Application-Token | applicationToken | The Application-Token to authenticate to the digitalSTROM-Server. | user name and password or Application-Token| false | #### Server information - -The parameter group *Server information* only includes informative parameters, which have no special functionality. +The parameter group _Server information_ only includes informative parameters, which have no special functionality. -| Parameter Label | Parameter ID | Description | Required | Advanced +| Parameter Label | Parameter ID | Description | Required | Advanced |-----------------|-------------|--------------------------|---------- |------------- | -| dSID | dSID | The unique identifier of a digitalSTROM-server. | false| false | +| dSID | dSID | The unique identifier of a digitalSTROM-server. | false| false | #### General configuration: -Here you can set general binding configuration parameters, which are shown in following table: +Here you can set general binding configuration parameters, which are shown in following table: -| Parameter Label | Parameter ID| Description | Required | Advanced | default +| Parameter Label | Parameter ID| Description | Required | Advanced | default |-----------------|------------------|-----------------------------------------|---------------- |------------- | ----------------- | | Sensor update interval | sensorDataUpdateInterval | Sets the seconds after the digitalSTROM-Device sensor data will be updated. If the priority is higher than 'never'. | false | false | 60 | | Total power update interval | totalPowerUpdateInterval | Sets the interval in seconds, after the digitalSTROM total power consumption and total electric meter sensor data will be updated. | false | false | 30 | | Days to be slaked trash bin devices | defaultTrashBinDeleateTime| Sets the days after the temporary saved digitalSTROM-Device configuration from not reachable digitalSTROM-Devices get permanently deleted. | false | false | 7 | -| Wait time sensor reading | sensorWaitTime| Waiting time between the evaluation of the sensor values and the reading of the scenes in seconds. **ATTENTION:** digitalSTROM rule 8 and 9 require a waiting period of 1 minute. Values less than 60 seconds could affect the digitalSTROM system. | false | true | 60 | +| Wait time sensor reading | sensorWaitTime| Waiting time between the evaluation of the sensor values and the reading of the scenes in seconds. **ATTENTION:** digitalSTROM rule 8 and 9 require a waiting period of 1 minute. Values less than 60 seconds could affect the digitalSTROM system. | false | true | 60 | At the thing file, a manual configuration looks e.g. like -``` +```java Bridge digitalstrom:dssBridge:dssBridge1 [ dSSAddress="dss.local.", userName="dssadmin", password="dssadmin", sensorDataUpdateInterval=180] ``` @@ -141,19 +140,19 @@ In addition to the configuration the digitalSTROM-Server has the following prope | Serial | The digitalSTROM-Server hardware serial number. | | Ethernet | The digitalSTROM-Server IEEE mac address. | | MachineID | The digitalSTROM-Server unique id. | -| Kernel | The digitalSTROM-Server Linux kernel release string. | +| Kernel | The digitalSTROM-Server Linux kernel release string. | ### digitalSTROM-Devices -The digitalSTROM-Device things have the following configuration parameter groups *Device information* and *Sensor setup*. - +The digitalSTROM-Device things have the following configuration parameter groups _Device information_ and _Sensor setup_. + #### Device information Each digitalSTROM-Device needs the device ID named dSID as configuration parameter. The device ID is printed as serial number at the digitalSTROM-Device and can also be found within the web-interface of the digitalSTROM-Server. -The following table shows the parameter: +The following table shows the parameter: -| Parameter Label | Parameter ID| Description | Required | Advanced +| Parameter Label | Parameter ID| Description | Required | Advanced |-----------------|------------------------|--------------|----------------- |------------- | | ID | dSID| The unique identifier of a digitalSTORM-device. | true | false | @@ -171,12 +170,12 @@ So these devices have the following parameters to read them out. #### Properties Furthermore a supported digitalSTROM-Device has some informative properties. -The following table shows all informative properties: +The following table shows all informative properties: | Property-Name | Description | | ------------- | ------------------------------------- | -|dSUID | The unique identifier of a digitalSTORM-device with virtual devices. | -| deviceName | he name of a digitalSTROM-Device. | +|dSUID | The unique identifier of a digitalSTORM-device with virtual devices. | +| deviceName | he name of a digitalSTROM-Device. | | meterDSID | Identifier of the meter to which the device is connected. | | hwInfo | The hardware type from this digitalSTROM-Device. | | zoneID |The digitalSTROM-Device is part of this zone. | @@ -188,11 +187,11 @@ The device scene configurations will also be persisted in the properties. There | Property-Name | Description | | ------------- | ------------------------------------- | -| scene[sceneID] | {Scene: [sceneID], dontcare: [don't care flag], localPrio: [local prio flag], specialMode: [special mode flag]}(0..1), {sceneValue: [scene value], sceneAngle: [scene angle]}(0..1) | +| scene[sceneID] | {Scene: [sceneID], dontcare: [don't care flag], localPrio: [local prio flag], specialMode: [special mode flag]}(0..1), {sceneValue: [scene value], sceneAngle: [scene angle]}(0..1) | ### digitalSTROM-Meter -A digitalSTROM-Meter needs, like the digitalSTROM-Devices, only the unique digitalSTROM device ID named dSID as configuration parameter, which has the same parameters, so please have a look at the point *Device information*. +A digitalSTROM-Meter needs, like the digitalSTROM-Devices, only the unique digitalSTROM device ID named dSID as configuration parameter, which has the same parameters, so please have a look at the point _Device information_. #### Properties @@ -211,12 +210,12 @@ In contrast to the digitalSTROM-Device there are other informal properties. The ### digitalSTROM-Zone-Temperature-Control -The thing type of a digitalSTROM-Zone-Temperature-Control is **zone_temperature_control**. +The thing type of a digitalSTROM-Zone-Temperature-Control is **zone_temperature_control**. As configuration only the zone ID or the zone name, to identify the controlled zone, is needed. -| Parameter Label | Parameter ID| Description | Required | Advanced | +| Parameter Label | Parameter ID| Description | Required | Advanced | |-----------------|------------------------|----------------------------------|----------------- |------------- | -| Zone ID or name | zoneID | The zone id or zone name of the temperature controlled zone. | true | false | +| Zone ID or name | zoneID | The zone id or zone name of the temperature controlled zone. | true | false | #### Properties @@ -230,44 +229,43 @@ As configuration only the zone ID or the zone name, to identify the controlled z The digitalSTROM-Scenes can be defined with following parameters. -| Parameter Label | Parameter ID| Description | Required | Advanced | +| Parameter Label | Parameter ID| Description | Required | Advanced | |-----------------|------------------------|----------------------------------|----------------- |------------- | -| Zone ID or name | zoneID | The zone ID or zone name of the called scene. 0 or empty is broadcast to all. | false | false | -| Group ID or name | groupID | The group ID or group name of the called scene. 0 or empty is broadcast to all. | false | false | -| Scene ID or name | sceneID |The call scene ID or scene name, e.g. preset 1 for scene ID 5. Callable scenes are from 0 to 126. | false | false | - -The Scene-Thing-Type *Named-Scene* and *Group-Scene* have all parameters. -The *Apartment-Scene* only has the parameters *Scene name* and *Scene ID* an the *Zone-Scene* has all parameters without *Group ID or name*. +| Zone ID or name | zoneID | The zone ID or zone name of the called scene. 0 or empty is broadcast to all. | false | false | +| Group ID or name | groupID | The group ID or group name of the called scene. 0 or empty is broadcast to all. | false | false | +| Scene ID or name | sceneID |The call scene ID or scene name, e.g. preset 1 for scene ID 5. Callable scenes are from 0 to 126. | false | false | +The Scene-Thing-Type _Named-Scene_ and _Group-Scene_ have all parameters. +The _Apartment-Scene_ only has the parameters _Scene name_ and _Scene ID_ an the _Zone-Scene_ has all parameters without _Group ID or name_. ### Textual configuration examples Usually the discovery works reliable, so that a manual configuration is not needed. -However, at the thing file, a manual configuration looks e.g. like +However, at the thing file, a manual configuration looks e.g. like #### digitalSTROM-Devices -``` +```java Thing digitalstrom:GE:GE-KM200 (digitalstrom:dssBridge:myDssBridge) [ dSID="3504175fe0000000000043d4", activePowerRefreshPriority="low", electricMeterRefreshPriority=“medium", outputCurrentRefreshPriority="high"] Thing digitalstrom:GR:GR-KL200 (digitalstrom:dssBridge:myDssBridge) [ dSID="3504175fe0000000000043d5"] ``` #### digitalSTROM-Meters -``` +```java Thing digitalstrom:circuit:circuit (digitalstrom:dssBridge:myDssBridge) [ dSID="3504175fe0000000000043d5"] ``` #### digitalSTROM-Zone-Temperature-Control -``` +```java Thing digitalstrom:zone_temperature_control:zone_temperature_control3 (digitalstrom:dssBridge:myDssBridge) [ zoneID="3"] ``` #### digitalSTROM-Group-Scene -``` +```java Thing digitalstrom:groupScene:preset1 (digitalstrom:dssBridge:myDssBridge) [ zoneID="3", groupID="1", sceneID="5"] ``` @@ -281,25 +279,25 @@ digitalSTROM-Devices with an activated output mode. | Channel Type ID | Item Type | Description | supported device type | |-------|---------|------------------------------------|----------------- | -| light_dimmer | Dimmer | The *light_dimm* channel allows to dimm a light device. | GE, SW | -| light_switch | Switch | The *light_switch* channel allows to turn a light device on or off. | GE, SW | -| light_2_stage | String| The *light_2_stage* channel allows to turn both light devices on or off or switch only 1 of the both light device on or off. | SW-UMR200 | -| light_3_stage | String | The *light_3_stage* channel allows to turn both light devices on or off or switch both light devices separated from each other on or off. | SW-UMR200 | -| shade | Rollershutter | The *shade* channel allows to control shade device e.g. a roller shutter or awnings. | GR | -| shade_angle | Dimmer | The *shade_angle* channel allows to control the relative slat position in percent of blinds. | GR | -| general_dimmer | Dimmer | The *general_dimmer* channel allows to control the power of a device e.g. a ceiling fan. | SW | -| general_switch | Switch | The *general_switch* channel allows to turn a device on or off e.g. a HIFI-System. | SW | -| general_2_stage | String | The *general_2_stage* channel allows to turn both relais of the device on or off or switch only 1 of the both relais on or off. | SW-UMR200 | -| general_3_stage | String | The *general_3_stage* channel allows to turn both relais of the device on or off or switch both relais of the device separated from each other on or off. | SW-UMR200 | -| heating_switch | Switch | The *heating_switch* channel allows to turn a heating device on or off. | BL | -| heating_dimmer | Dimmer | The *heating_switch* channel allows to control the value in percent of heating valve. | BL | +| light_dimmer | Dimmer | The _light_dimm_ channel allows to dimm a light device. | GE, SW | +| light_switch | Switch | The _light_switch_ channel allows to turn a light device on or off. | GE, SW | +| light_2_stage | String| The _light_2_stage_ channel allows to turn both light devices on or off or switch only 1 of the both light device on or off. | SW-UMR200 | +| light_3_stage | String | The _light_3_stage_ channel allows to turn both light devices on or off or switch both light devices separated from each other on or off. | SW-UMR200 | +| shade | Rollershutter | The _shade_ channel allows to control shade device e.g. a roller shutter or awnings. | GR | +| shade_angle | Dimmer | The _shade_angle_ channel allows to control the relative slat position in percent of blinds. | GR | +| general_dimmer | Dimmer | The _general_dimmer_ channel allows to control the power of a device e.g. a ceiling fan. | SW | +| general_switch | Switch | The _general_switch_ channel allows to turn a device on or off e.g. a HIFI-System. | SW | +| general_2_stage | String | The _general_2_stage_ channel allows to turn both relais of the device on or off or switch only 1 of the both relais on or off. | SW-UMR200 | +| general_3_stage | String | The _general_3_stage_ channel allows to turn both relais of the device on or off or switch both relais of the device separated from each other on or off. | SW-UMR200 | +| heating_switch | Switch | The _heating_switch_ channel allows to turn a heating device on or off. | BL | +| heating_dimmer | Dimmer | The _heating_switch_ channel allows to control the value in percent of heating valve. | BL | digitalSTROM-Zone-Temperature-Controlled -| Channel Type ID | Item Type | Description | +| Channel Type ID | Item Type | Description | |-------|---------|------------------------------------| -| heating_temperature_controled | Number | The *heating_temperature_controled* channel allows to set a target temperature of a zone. | -| heating_dimmer | Dimmer | The *heating_switch* channel allows to control the value in percent of heating valve. | +| heating_temperature_controled | Number | The _heating_temperature_controled_ channel allows to set a target temperature of a zone. | +| heating_dimmer | Dimmer | The _heating_switch_ channel allows to control the value in percent of heating valve. | ### Sensor-Channels @@ -307,9 +305,9 @@ digitalSTROM-Devices which have sensors data. | Channel Type ID | Item Type | Description | supported device type | |-------|---------|------------------------------------|----------------- | -| active_power | Number | This channel indicates the current active power in watt (W) of the device." | GE, SW, BL | -| output_current | Number | This channel indicates the current output current in milliamper (mA) of the device." | GE, SW, BL | -| electric_meter | Number | This channel indicates the current electric meter value in killowatts hours (kWh) of the device. | GE, SW, BL | +| active_power | Number | This channel indicates the current active power in watt (W) of the device." | GE, SW, BL | +| output_current | Number | This channel indicates the current output current in milliamper (mA) of the device." | GE, SW, BL | +| electric_meter | Number | This channel indicates the current electric meter value in killowatts hours (kWh) of the device. | GE, SW, BL | | temperature_indoors | Number | This channel indicates the current temperature indoors in Celsius (°C) of the device. | dS-iSens200 | | temperature_outdoors | Number | This channel indicates the current temperature outdoors in Celsius (°C) of the device. | --- | | brightness_indoors | Number | This channel indicates the current brightness indoors in Lux (Lx) of the device. | --- | @@ -325,7 +323,7 @@ digitalSTROM-Devices which have sensors data. | room_temperation_set_point | Number | This channel indicates the current room temperation set point in Celsius (°C) of the device. | --- | | room_temperation_control_variable | Number | This channel indicates the current room temperation control variable in Celsius (°C) of the device. | --- | -*If no supported device type is at the table, digitalSTROM currently does not offer a device, which support this type of sensor. +*If no supported device type is at the table, digitalSTROM currently does not offer a device, which support this type of sensor. ### Binary-Input-Channels @@ -356,49 +354,49 @@ digitalSTROM-Devices which are able to set a binary-input sensor like SW-UMR200 ### Metering-Channels -The digitalSTROM-Meters +The digitalSTROM-Meters | Channel Type ID | Item Type | Description | supported device type | |-------|---------|------------------------------------|----------------- | -| consumption_Wh | Number | The *consumption_Wh* channel indicates the current power consumption in watt (W) of the circuit. | circuit | -| energy_Wh | Number | The *energy_Wh* channel indicates the current electric meter value in killowatt hours of the circuit. | circuit | +| consumption_Wh | Number | The _consumption_Wh_ channel indicates the current power consumption in watt (W) of the circuit. | circuit | +| energy_Wh | Number | The _energy_Wh_ channel indicates the current electric meter value in killowatt hours of the circuit. | circuit | -The digitalSTROM-Server +The digitalSTROM-Server | Channel Type ID | Item Type | Description | supported device type | |-------|---------|------------------------------------|----------------- | -| total_consumption_Wh | Number | The *total_consumption_Wh* channel indicates the current consumption power in watt (W) of all connected circuits to the digitalSTROM-System. | dssBridge | -| total_energy_Wh | Number | The *total_energy_Wh* channel indicates the current electric meter value in killowatt hours of all connected circuits to the digitalSTROM-System. | dssBridge | +| total_consumption_Wh | Number | The _total_consumption_Wh_ channel indicates the current consumption power in watt (W) of all connected circuits to the digitalSTROM-System. | dssBridge | +| total_energy_Wh | Number | The _total_energy_Wh_ channel indicates the current electric meter value in killowatt hours of all connected circuits to the digitalSTROM-System. | dssBridge | ### Scenes | Channel Type ID | Item Type | Description | supported device type | |-------|---------|------------------------------------|----------------- | -| scene | Switch | The scene channel allows to call or undo a scene from digitalSTROM. | all scene-types | +| scene | Switch | The scene channel allows to call or undo a scene from digitalSTROM. | all scene-types | -**Notes: ** +**Notes:** -*Generally:* +_Generally:_ -* The digitalSTROM-Server only informs the binding about scene-commands. So if you set the output value of devices e.g. through the dSS-App, the binding will not be informed about the changes and you have to send a "refresh-command" to update the channel. -* If you press a physical switch at your digitalSTROM-installation and the called scene-value is not red out yet, it can take a bit time to read it out and change the state of the channel. +- The digitalSTROM-Server only informs the binding about scene-commands. So if you set the output value of devices e.g. through the dSS-App, the binding will not be informed about the changes and you have to send a "refresh-command" to update the channel. +- If you press a physical switch at your digitalSTROM-installation and the called scene-value is not red out yet, it can take a bit time to read it out and change the state of the channel. It the scene-value is red out, the state will change immediately. -See also *General-Informations/digitalSTROM-Scenes*. +See also _General-Informations/digitalSTROM-Scenes_. -*Channels with accepted command type increase and decrease:* +_Channels with accepted command type increase and decrease:_ - * digitalSTROM will only evaluate increase and decrease commands, if a scene was called before which turn the device on. - -*Blinds:* +- digitalSTROM will only evaluate increase and decrease commands, if a scene was called before which turn the device on. - * Increase, decrease and up, down commands of the shade channel changes the angle in digitalSTROM, too. If you want to set only the position, you have to set the value directly. - * To protect the slats digitalSTROM changes the position by setting the angle, too, if the position is very high or low. So if you want to see the correct position, you have to send a refresh or stop command, if the blind is ready. +_Blinds:_ + +- Increase, decrease and up, down commands of the shade channel changes the angle in digitalSTROM, too. If you want to set only the position, you have to set the value directly. +- To protect the slats digitalSTROM changes the position by setting the angle, too, if the position is very high or low. So if you want to see the correct position, you have to send a refresh or stop command, if the blind is ready. ## Full Example ### demo.things: -``` +```java Bridge digitalstrom:dssBridge:dSS [ dSSAddress="urlOfMyDss", userName="dssadmin", password="mySecretPassword", sensorDataUpdateInterval=180] { GE GE-KM-200 [ dSID="3504175fe000000000010db9", activePowerRefreshPriority="low", electricMeterRefreshPriority="medium", outputCurrentRefreshPriority="high"] SW SW-ZWS-200 [ dSID="3504175fe0000000000651c0"] @@ -414,7 +412,7 @@ Bridge digitalstrom:dssBridge:dSS [ dSSAddress="urlOfMyDss", userName="dssadmin ### demo.items: -``` +```java //dSS Number TotalActivePower { channel="digitalstrom:dssBridge:dSS:total_consumption_wh" } Number TotalElectricMeter { channel="digitalstrom:dssBridge:dSS:total_energy_wh" } @@ -455,7 +453,7 @@ Number Temperature { channel="digitalstrom:zoneTemperatureControl:dSS:zoneTemper ### demo.sitemap: -``` +```perl sitemap demo label="Main Menu" { Frame label="System" { @@ -524,17 +522,17 @@ sitemap demo label="Main Menu" ### digitalSTROM-Scenes -The device scene configuration will be saved persistently to the thing properties, if the thing is not textual configured (because textual configured things will not be persisted), to update the device state faster. -For that each scene configuration of each device has to be read out first, because of the digitalSTROM-rule 9 that requires a waiting period of one minute, that take some time so that at the first start a scene call can be take some time to read it out and update the device state. -To read it out faster only the discovered or called scenes will be read out. - +The device scene configuration will be saved persistently to the thing properties, if the thing is not textual configured (because textual configured things will not be persisted), to update the device state faster. +For that each scene configuration of each device has to be read out first, because of the digitalSTROM-rule 9 that requires a waiting period of one minute, that take some time so that at the first start a scene call can be take some time to read it out and update the device state. +To read it out faster only the discovered or called scenes will be read out. + **Note:** Because the digitalSTROM-Server can't inform the binding about save scene events at this time, the persistently saved scene configurations can't be updated. The current troubleshooting to read out the new scene configuration after a save scene action at the digitalSTROM-Server is the following: 1. delete the thing to delete the persistently saved scene configuration -2. restart the server to delete the temporary saved scene configuration -3. add the thing again to read out the scene configuration again. +1. restart the server to delete the temporary saved scene configuration +1. add the thing again to read out the scene configuration again. ### Initial state of digitalSTROM-Scenes and devices @@ -542,17 +540,17 @@ To get the device and scene state after a server start or restart, the binding u Because of that there are two things to be observed: 1. If a device status has changed through a device scene or a directly set output value, the status is maybe not correct. -2. If the last called group scene was not read out yet, it can takes some time until the status will be updated. +1. If the last called group scene was not read out yet, it can takes some time until the status will be updated. ### Textual configuration notice -If you configure your system with textual configuration files, like *\*.thing*, there is one things you have to consider. +If you configure your system with textual configuration files, like _\*.thing_, there is one things you have to consider. -* The feature of the persisting of scene-configurations, to get the scene-configurations after a restart faster (see *digitalSTROM-Scenes* above), will not support textural configured things, because the properties cannot be persist in this case. +- The feature of the persisting of scene-configurations, to get the scene-configurations after a restart faster (see _digitalSTROM-Scenes_ above), will not support textural configured things, because the properties cannot be persist in this case. ### Rule specific notice If you want to create a rule, which uses things of the digitalSTROM-Binding, there are also two things you have to consider. 1. If the rule contains several digitalSTROM-Devices, which can be summarized in a digitalSTROM-Scene, e.g. some lights in a zone, please use an equivalent supported scene. That will significantly reduce the communication to the digitalSTROM-Server, increases performance and does not bypass the digitalSTROM state-machine. -2. If you implement your own temperature control algorithm for a zone/room, e.g. because you want to use other temperature sensors, and call more than one digitalSTROM-BL-KM200, please use the *zone_temperature_control* for valve value control. The *zone_temperature_control* for valve value control will call all digitalSTROM-BL-KM200 with one command and increases the performance. To get the needed channel at the *zone_temperature_control* you have to choose a control mode unequal to *pid-controlled* for the affected zone at the digitalSTROM-heating-control-app. +1. If you implement your own temperature control algorithm for a zone/room, e.g. because you want to use other temperature sensors, and call more than one digitalSTROM-BL-KM200, please use the _zone_temperature_control_ for valve value control. The _zone_temperature_control_ for valve value control will call all digitalSTROM-BL-KM200 with one command and increases the performance. To get the needed channel at the _zone_temperature_control_ you have to choose a control mode unequal to _pid-controlled_ for the affected zone at the digitalSTROM-heating-control-app. diff --git a/bundles/org.openhab.binding.dmx/README.md b/bundles/org.openhab.binding.dmx/README.md index 9cc9709f76a..3f0f09f2ea9 100644 --- a/bundles/org.openhab.binding.dmx/README.md +++ b/bundles/org.openhab.binding.dmx/README.md @@ -1,35 +1,35 @@ # DMX Binding -The DMX binding integrates DMX devices. There are different output devices supported as well as Dimmers and Chasers. +The DMX binding integrates DMX devices. There are different output devices supported as well as Dimmers and Chasers. -Each output device (bridges) is representing exactly one universe, each thing is bound to a bridge. -At least one bridge and one thing is needed for the binding to work properly. +Each output device (bridges) is representing exactly one universe, each thing is bound to a bridge. +At least one bridge and one thing is needed for the binding to work properly. ## Supported Things ### Bridges -Two DMX over Ethernet devices are supported as DMX output: ArtNet and sACN/E1.31. -The ArtNet bridge can only be operated in unicast mode (broadcast mode is not supported as the specification recommends using it if more than 40 nodes are connected, which is unlikely in the case of a smarthome). -The sACN bridge supports both, unicast and multicast. +Two DMX over Ethernet devices are supported as DMX output: ArtNet and sACN/E1.31. +The ArtNet bridge can only be operated in unicast mode (broadcast mode is not supported as the specification recommends using it if more than 40 nodes are connected, which is unlikely in the case of a smarthome). +The sACN bridge supports both, unicast and multicast. Additionally Lib485 devices are supported via the Lib485 bridge. ### Things -The most generic thing is a dimmer. -A dimmer can contain one or more DMX channels. -It can be bound to Switch and Dimmer items. -If more than one DMX channel is defined, the item will be updated according to the state of the first DMX channel. -There are two other things similar to the dimmer thing. -One is the color thing, it can be bound to Switch, Dimmer or Color Items and is best used for RGB lamps. +The most generic thing is a dimmer. +A dimmer can contain one or more DMX channels. +It can be bound to Switch and Dimmer items. +If more than one DMX channel is defined, the item will be updated according to the state of the first DMX channel. +There are two other things similar to the dimmer thing. +One is the color thing, it can be bound to Switch, Dimmer or Color Items and is best used for RGB lamps. The second one is the tunable white thing, it allows to control the color temperature of lamps with seperate DMX channels for cool white and warm white. -The last supported thing is a chaser. -It can contain one or more DMX channels and binds to Switch items only. -If the thing receives an ON command all running fades in all channels are either suspended (if resumeAfter is set to true) or cleared and replaced with the fades defined in this thing. -An OFF command stops the fades and either restores the previously suspended fades (if resumeAfter is set to true) or just holds the current values. -If any of the DMX channels in a chaser receives a command from another thing, the status of the chaser is updated to OFF. +The last supported thing is a chaser. +It can contain one or more DMX channels and binds to Switch items only. +If the thing receives an ON command all running fades in all channels are either suspended (if resumeAfter is set to true) or cleared and replaced with the fades defined in this thing. +An OFF command stops the fades and either restores the previously suspended fades (if resumeAfter is set to true) or just holds the current values. +If any of the DMX channels in a chaser receives a command from another thing, the status of the chaser is updated to OFF. Chaser things define a control channel that can be used to dynamically change the chasers fade configuration. ## Discovery @@ -39,27 +39,27 @@ You have to add all bridges and things manually. ## Thing Configuration -Since the brightness perception of the human eye is not linear, all bridges support `applycurve`, a list of channels `applycurve` that have a CIE 1931 lightness correction (cf. [Poynton, C.A.: “Gamma” and its Disguises: The Nonlinear Mappings of Intensity in Perception, CRTs, Film and Video, SMPTE Journal Dec. 1993, pp. 1099 - 1108](https://www.poynton.com/PDFs/SMPTE93_Gamma.pdf)) applied. -This list follows the format of the thing channel definition. +Since the brightness perception of the human eye is not linear, all bridges support `applycurve`, a list of channels `applycurve` that have a CIE 1931 lightness correction (cf. [Poynton, C.A.: “Gamma” and its Disguises: The Nonlinear Mappings of Intensity in Perception, CRTs, Film and Video, SMPTE Journal Dec. 1993, pp. 1099 - 1108](https://www.poynton.com/PDFs/SMPTE93_Gamma.pdf)) applied. +This list follows the format of the thing channel definition. This is used regardless of the thing(s) that are associated to the channel. -All bridges can make use of the `refreshrate` option. -It determines at what frequency the DMX output is refreshed. -The achievable refresh rate depends on the number of channels and the output type. +All bridges can make use of the `refreshrate` option. +It determines at what frequency the DMX output is refreshed. +The achievable refresh rate depends on the number of channels and the output type. A value of `0` disables the output, the default value is 30 Hz. ### ArtNet Bridge (`artnet-bridge`) -The ArtNet bridge has one mandatory configuration value: network address (`address`). +The ArtNet bridge has one mandatory configuration value: network address (`address`). The network address defines the IP address of the receiving node, it is also allowed to use a FQDN if DNS resolution is available. If necessary the default port 6454 can be changed by adding `:` to the address. Multiple receivers can be added, separated by a comma. -The universe (`universe`) can range from 0-32767, this value defaults to 0. +The universe (`universe`) can range from 0-32767, this value defaults to 0. -There are two more configuration values that usually don't need to be touched. -The address and port of the sender will be automatically selected by the kernel, if they need to be set to a fixed value, this can be done with `localaddress`. -The format is identical to the receiver address. +There are two more configuration values that usually don't need to be touched. +The address and port of the sender will be automatically selected by the kernel, if they need to be set to a fixed value, this can be done with `localaddress`. +The format is identical to the receiver address. Unlike DMX512-A (E1.11), the ArtNet standard allows to suppress repeated transmissions of unchanged universes for a certain time. This is enabled by default and will re-transmit unchanged data with a fixed refresh rate of 800ms. If for some reason continuous transmission is needed, the `refreshmode` can be set to `always`, opposed to the default `standard`. @@ -76,17 +76,17 @@ Multiple receivers can be added, separated by a comma. ### sACN/E1.31 Bridge (`sacn-bridge`) The sACN bridge has one mandatory configuration value: transmission mode (`mode`). -The transmission mode can be set to either `unicast` or `multicast`, where the later one is the default value. +The transmission mode can be set to either `unicast` or `multicast`, where the later one is the default value. If unicast mode is selected, it is mandatory to define the network address (`address`) of the receiving node. This can be an IP address but it is also allowed to use a FQDN if DNS resolution is available. If necessary the default port 5568 can be changed by adding `:` to the address. Multiple receivers can be added, separated by a comma. -The universe (`universe`) can range from 1-63999, this value defaults to 1. +The universe (`universe`) can range from 1-63999, this value defaults to 1. There are some more configuration values that usually don't need to be touched. The address and port of the sender will be automatically selected by the kernel, if they need to be set to a fixed value, this can be done with `localaddress`. -The format is identical to the receiver address. +The format is identical to the receiver address. Unlike DMX512-A (E1.11), the E1.31 standard allows to suppress repeated transmissions of unchanged universes for a certain time. This is enabled by default and will re-transmit unchanged data with a fixed refresh rate of 800ms. @@ -94,10 +94,10 @@ If for some reason continuous transmission is needed, the `refreshmode` can be s ### Chaser Thing (`chaser`) -There are two mandatory configuration values for a chaser thing: the `dmxid` and `steps`. +There are two mandatory configuration values for a chaser thing: the `dmxid` and `steps`. The `dmxid` is a list of DMX channels that are associated with this thing. -There are several possible formats: `channel,channel,channel,...` or `channel/width` or a combination of both. +There are several possible formats: `channel,channel,channel,...` or `channel/width` or a combination of both. The `steps` value is a list of steps that shall be run by the chaser. The format of a single step is `fadetime:value,value2, ...:holdtime`, two or more steps are concatenated by `step1|step2|...`. @@ -115,37 +115,37 @@ It defaults to false but if set to true, the original state of the channel (incl There is one mandatory configuration value for a dimmer thing. It is the `dmxid`, a list of DMX channels that are associated with this thing. -There are several possible formats: `channel1,channel2,channel3,...` or `channel/width` or a combination of both. +There are several possible formats: `channel1,channel2,channel3,...` or `channel/width` or a combination of both. The `fadetime` option allows a smooth transition from the current to the new value. The time unit is ms and the interval is for a fade from 0-100%. If the current value is 25% and the new value is 75% the time needed for this change is half of `fadetime`. -`fadetime`is used for absolute values or ON/OFF commands send to the `brightness` channel. +`fadetime`is used for absolute values or ON/OFF commands send to the `brightness` channel. Related is the `dimtime` option: it defines the time in ms from 0-100% if incremental dimming (`INCREASE`/`DECREASE`) is used. For convenient use `dimtime` usually is set to a larger value than `fadetime`. -Typical values are 500-1000 ms for `fadetime` and 2000-5000 ms for `dimtime`. +Typical values are 500-1000 ms for `fadetime` and 2000-5000 ms for `dimtime`. -Advanced options are the `turnonvalue`and the `turnoffvalue`. +Advanced options are the `turnonvalue`and the `turnoffvalue`. They default to 255 (equals 100%) and 0 (equals 0%) respectively. This value can be set individually for all DMX channels, the format is `value1,value2, ...` with values from 0 to 255. If less values than DMX channels are defined, the values will be re-used from the beginning (i.e. if two values are defined, value1 will be used for channel1, channel3, ... and value2 will be used for channel2, channel4, ...). -These values will be used if the thing receives an ON or OFF command. +These values will be used if the thing receives an ON or OFF command. The `dynamicturnonvalue` can be set to `true` or `false` (default). If enabled, thing overwrites the previous turn-on value with the current channel values. -The next `ON` command uses these values instead of the default (or configuration supplied) values. +The next `ON` command uses these values instead of the default (or configuration supplied) values. ### Color Thing (`color`) There is one mandatory configuration value for a dimmer thing. It is the `dmxid`, a list of DMX channels that are associated with this thing. There are several possible formats: `channel1,channel2,channel3,...` or `channel/width` or a combination of both. -The number of channels has to be a multiple of three. +The number of channels has to be a multiple of three. The `fadetime` option allows a smooth transition from the current to the new value. The time unit is ms and the interval is for a fade from 0-100%. If the current value is 25% and the new value is 75% the time needed for this change is half of `fadetime`. -`fadetime`is used for absolute values or ON/OFF commands send to the `brightness` channel. +`fadetime`is used for absolute values or ON/OFF commands send to the `brightness` channel. Related is the `dimtime` option: it defines the time in ms from 0-100% if incremental dimming (`INCREASE`/`DECREASE`) is used. For convenient use `dimtime` usually is set to a larger value than `fadetime`. Typical values are 500-1000 ms for `fadetime` and 2000-5000 ms for `dimtime`. @@ -155,24 +155,24 @@ They default to 255 (equals 100%) and 0 (equals 0%) respectively. This value can be set individually for all DMX channels, the format is `value1,value2, ...` with values from 0 to 255. If less values than DMX channels are defined, the values will be re-used from the beginning (i.e. if two values are defined, value1 will be used for channel1, channel3, ... and value2 will be used for channel2, channel4, ...). For color things the number of values has to be a multiple of three. -These values will be used if the thing receives an ON or OFF command. +These values will be used if the thing receives an ON or OFF command. The `dynamicturnonvalue` can be set to `true` or `false` (default). If enabled, thing overwrites the previous turn-on value with the current channel values. -The next `ON` command uses these values instead of the default (or configuration supplied) values. +The next `ON` command uses these values instead of the default (or configuration supplied) values. ### Tunable White Thing (`tunablewhite`) -There is one mandatory configuration value for a dimmer thing. +There is one mandatory configuration value for a dimmer thing. It is the `dmxid`, a list of DMX channels that are associated with this thing. There are several possible formats: `channel1,channel2,channel3,...` or `channel/width` or a combination of both. The number of channels has to be even. In the order "cool white, warm white". -Additionally a channel for cool and warm white brightness as well as color temperature (`0` being the coolest, `100` being the warmest) will be provided. +Additionally a channel for cool and warm white brightness as well as color temperature (`0` being the coolest, `100` being the warmest) will be provided. The `fadetime` option allows a smooth transition from the current to the new value. The time unit is ms and the interval is for a fade from 0-100%. If the current value is 25% and the new value is 75% the time needed for this change is half of `fadetime`. -`fadetime`is used for absolute values or ON/OFF commands send to the `brightness` channel. +`fadetime`is used for absolute values or ON/OFF commands send to the `brightness` channel. Related is the `dimtime` option: it defines the time in ms from 0-100% if incremental dimming (`INCREASE`/`DECREASE`) is used. For convenient use `dimtime` usually is set to a larger value than `fadetime`. Typical values are 500-1000 ms for `fadetime` and 2000-5000 ms for `dimtime`. @@ -180,15 +180,14 @@ Typical values are 500-1000 ms for `fadetime` and 2000-5000 ms for `dimtime`. Advanced options are the `turnonvalue`and the `turnoffvalue`. They default to 255 (equals 100%) and 0 (equals 0%) respectively. This value can be set individually for all DMX channels, the format is `value1,value2, ...` with values from 0 to 255. -If less values than DMX channels are defined, the values will be re-used from the beginning (i.e. if two values are defined, value1 will be used for channel1, channel3, ... and value2 will be used for channel2, channel4, ...). +If less values than DMX channels are defined, the values will be re-used from the beginning (i.e. if two values are defined, value1 will be used for channel1, channel3, ... and value2 will be used for channel2, channel4, ...). For tunable white things the number of values has to be a multiple of two. -These values will be used if the thing receives an ON or OFF command. - +These values will be used if the thing receives an ON or OFF command. + The `dynamicturnonvalue` can be set to `true` or `false` (default). If enabled, thing overwrites the previous turn-on value with the current channel values. -The next `ON` command uses these values instead of the default (or configuration supplied) values. - - +The next `ON` command uses these values instead of the default (or configuration supplied) values. + ## Channels | Type-ID | Thing | Item | Description | @@ -205,7 +204,7 @@ The next `ON` command uses these values instead of the default (or configuration |switch |chaser |Switch | turns the chaser ON or OFF | |mute |(all bridges) |Switch | mutes the DMX output of the bridge | -*Note:* the string send to the control channel of chaser things has to be formatted like the `steps` configuration of the chaser thing. +_Note:_ the string send to the control channel of chaser things has to be formatted like the `steps` configuration of the chaser thing. If the new string is invalid, the old configuration will be used. ## Rule Actions @@ -254,7 +253,7 @@ This example defines a sACN/E1.31 bridge in unicast mode which transmits univers ### demo.things: -``` +```java Bridge dmx:sacn-bridge:mybridge [ mode="unicast", address="192.168.0.60", universe=2 ] { color rgb [dmxid="5/3", fadetime=1000, dimtime=10000 ] dimmer single [dmxid="50", fadetime=1000, turnonvalue="230", turnoffvalue="25" ] @@ -264,7 +263,7 @@ Bridge dmx:sacn-bridge:mybridge [ mode="unicast", address="192.168.0.60", univer ### demo.items: -``` +```java Color MyColorItem "My Color Item" { channel="dmx:color:mybridge:rgb:color" } Dimmer MyDimmerItem "My Dimmer Item" { channel="dmx:dimmer:mybridge:single:brightness" } Switch MyChaserItem "My Chaser Item" { channel="dmx:chaser:mybridge:ampel:switch" } @@ -272,7 +271,7 @@ Switch MyChaserItem "My Chaser Item" { channel="dmx:chaser:mybridge:ampel:switch ### demo.sitemap: -``` +```perl sitemap demo label="Main Menu" { Frame { diff --git a/bundles/org.openhab.binding.dominoswiss/README.md b/bundles/org.openhab.binding.dominoswiss/README.md index fb2363d09ff..46a5d135fae 100644 --- a/bundles/org.openhab.binding.dominoswiss/README.md +++ b/bundles/org.openhab.binding.dominoswiss/README.md @@ -1,26 +1,22 @@ # Dominoswiss Binding -This binding allows the control of rollershutters, using an eGate as gateway and Dominoswiss radio receivers. -The eGate-gateway is connected via ethernet to openHAB and sends its commands via radio to all rollershutters. -See https://www.brelag.com/ for more information. - +This binding allows the control of rollershutters, using an eGate as gateway and Dominoswiss radio receivers. +The eGate-gateway is connected via ethernet to openHAB and sends its commands via radio to all rollershutters. +See for more information. ## Supported Things eGate: Dominoswiss eGate Server. The eGate is the gateway which sends the commands to the connected rollershutters. The bridge-type ID is egate. Blind: represents one rollershutter, that can be controlled via eGate. The thing-type ID is blind. - ## Discovery -Unfortunately no automatic discovery is possible due to protocol restrictions. +Unfortunately no automatic discovery is possible due to protocol restrictions. Every rollershutter must be known by eGate and can be called by it's number of storage-place on eGate gateway. - - ## Thing Configuration -The bridge "eGate" has one channel "getconfig" which returns the config of this bridge. +The bridge "eGate" has one channel "getconfig" which returns the config of this bridge. The eGate is configured with both an `ipAddress` and a port. |Property|Default|Required|Description| @@ -28,14 +24,13 @@ The eGate is configured with both an `ipAddress` and a port. |ipAddress|none|Yes|The IP or host name of the Dominoswiss EGate Serve| |port|1318|Yes|Port interface of the Dominoswiss EGate Server| -``` +```java Bridge dominoswiss:egate:myeGate "My eGate Server" @ "Home" [ ipAddres="localhost", port=5700 ] ``` - The thing blind represents one blind on the eGate. Each blind is represented by an id set on your eGate. -``` +```java Thing blind officeBlind "Office" @ "1stFloor" [ id="1"] ``` @@ -49,15 +44,15 @@ The blind-Thing has the following channels: |continuousDown|Rollershutter|send a continous down to this blind. The blind will automatically stop as it is fully down.| |stop|Rollershutter|stop the action of the blind. The command will be imadiatly sent to the blind.| |shutter|Rollershutter|this is used to bind the channel to the shutter item. There are no further rules needed this channel will handel the up/down/stop commands. See example for usage.| -|tilt|Rollershutter|same as shutter, this will handel all up/down/stop - tilt commands to be used with the shutter-item.| -|tiltUp|Rollershutter|sends 3 pulse-up commands to this blind to tilt the blind. If your blind needs more than 3 pulse-up, create a rule yourself with three pluse-up commands. Between each pulse-up you should wait 150ms to let the command be processed. +|tilt|Rollershutter|same as shutter, this will handel all up/down/stop - tilt commands to be used with the shutter-item.| +|tiltUp|Rollershutter|sends 3 pulse-up commands to this blind to tilt the blind. If your blind needs more than 3 pulse-up, create a rule yourself with three pluse-up commands. Between each pulse-up you should wait 150ms to let the command be processed. |tiltDown|Rollershutter|sends 3 pulse-down commands to this blind to tilt the blind. If your blind needs more than 3 pulse-down, create a rule yourself with three pluse-down commands. Between each pulse-down you should wait 150ms to let the command be processed. | ## Full Example Sample things file: -``` +```java Bridge dominoswiss:egate:myeGate "My eGate Server" @ "Home" [ ipAddres="localhost", port="5500" ] { Thing blind officeBlind "Office" @ "1stFloor" [ id="1"] @@ -68,7 +63,7 @@ Bridge dominoswiss:egate:myeGate "My eGate Server" @ "Home" [ ipAddres="localhos Sample items file: -``` +```java Rollershutter OfficeBlindShutter "Office blind" (g_blinds) { channel="dominoswiss:blind:myeGate:officeBlind:shutter"} Rollershutter OfficeBlindShutterTilt "Tilt Office" (g_blinds_tilt) { channel="dominoswiss:blind:meGgate:bueroBlind:tilt"} @@ -77,7 +72,7 @@ Rollershutter OfficeBlindShutterTilt "Tilt Office" (g_blinds_ti Sample sitemap file -``` +```perl Switch item=OfficeBlindShutter Switch item=OfficeBlindShutterTilt ``` @@ -86,7 +81,7 @@ Sample rule file This example moves the blind of the office up as the sun passed 110 azimuth (so the sun is no longer shining directly into the office). -``` +```java rule "OneSide up" when Item Azimuth changed diff --git a/bundles/org.openhab.binding.doorbird/README.md b/bundles/org.openhab.binding.doorbird/README.md index 52aa88eefa8..7cd48895859 100644 --- a/bundles/org.openhab.binding.doorbird/README.md +++ b/bundles/org.openhab.binding.doorbird/README.md @@ -80,17 +80,17 @@ The following channels are supported by the binding for the Doorbird A1081 Contr ## Profiles -Using the system default switch profile *rawbutton-on-off-switch* in a *doorbell* channel item definition will cause ON/OFF +Using the system default switch profile _rawbutton-on-off-switch_ in a _doorbell_ channel item definition will cause ON/OFF states to be set when the doorbell is pressed and released. -See *Items* example below. +See _Items_ example below. ## Rule Actions The binding supports the following actions. In classic rules these are accessible as shown in this example (adjust getActions with your ThingId): - + ### void restart() - + Restarts the Doorbird device. ### void sipHangup() @@ -115,7 +115,7 @@ Get the value of the SIP status parameter LASTERRORTEXT. Example -``` +```java val actions = getActions("doorbird","doorbird:d101:doorbell") if(actions === null) { logInfo("actions", "Actions not found, check thing ID") @@ -137,7 +137,7 @@ Either put the Doorbird and openHAB on the same subnet/VLAN, or set up your netw ### Things -``` +```java Thing doorbird:d101:doorbell "Doorbird D101 Doorbell" [doorbirdHost="192.168.1.100",userId="dtfubb0004",userPassword="HG7afc5TvN",imageRefreshRate=60,doorbellOffDelay=3,motionOffDelay=30,montageNumImages=3,montageScaleFactor=35] Thing doorbird:a1081:controller "Doorbird A1081 Controller" [doorbirdHost="192.168.1.100",userId="dtfubb0004",userPassword="HG7afc5TvN"] @@ -145,7 +145,7 @@ Thing doorbird:a1081:controller "Doorbird A1081 Controller" [doorbirdHost="192.1 ### Items -``` +```java Switch Doorbell_Pressed "Doorbell Pressed [%s]" ["Switch"] { channel="doorbird:d101:doorbell:doorbell" [profile="rawbutton-on-off-switch"] } DateTime Doorbell_PressedTimestamp "Doorbell Pressed Timestamp [%1$tA, %1$tm/%1$td/%1$tY %1$tl:%1$tM %1$tp]"