OpenHAB
/
openhab-docs
mirror of https://github.com/openhab/openhab-docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Introduced many custom containers. (#1117) 

* Refactored multiple 'Note:' occurances.

Signed-off-by: Jerome Luckenbach <github@luckenba.ch>

* Small fixes

Signed-off-by: Jerome Luckenbach <github@luckenba.ch>
pull/1120/head
Jerome Luckenbach 2019-12-27 16:18:48 +01:00 committed by GitHub
parent faf4bb1b51
commit d4cc7be27e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
21 changed files with 396 additions and 336 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
addons/actions.md
View File

@ -61,7 +61,7 @@ One can configure whether specific log entries are logged out and where they get
- `executeCommandLine(String commandLine, int timeout)`: Executes a command on the command and waits timeout milliseconds for the command to complete, returning the output from the command as a String
::: tip Note
Simple arguments that contain no spaces can be separated with spaces, for example `executeCommandLine("touch file.txt")`.
Simple arguments that contain no spaces can be separated with spaces, for example `executeCommandLine("touch file.txt")`.
When one or more arguments contain spaces, use `@@` instead of a space as the argument separator.
For example the bash command `touch -t 01010000 "some file with space.txt"` will have to be written as `touch@@-t@@01010000@@some file with space.txt`.
:::
@ -79,7 +79,9 @@ For example the bash command `touch -t 01010000 "some file with space.txt"` will
- `sendHttpDeleteRequest(String url)`: Sends a DELETE-HTTP request and returns the result as a String
- `sendHttpDeleteRequest(String url, Map<String, String> headers, int timeout)`: Sends a DELETE-HTTP request with the given request headers, and timeout in ms, and returns the result as a String
Note: All HTTP Actions can have a last `timeout` parameter added in ms. eg. `sendHttpPostRequest(String url, String contentType, String content, int timeout)`
::: tip Note
All HTTP Actions can have a last `timeout` parameter added in ms. eg. `sendHttpPostRequest(String url, String contentType, String content, int timeout)`
:::
For example:
```javascript

10
administration/console.md
View File

@ -33,9 +33,11 @@ To reach the console using SSH, use the following command to connect to the loca
ssh -p 8101 openhab@localhost
```
*Note:* By default, connection is only allowed from localhost, i.e. only from the machine running openHAB.
::: tip Note
By default, connection is only allowed from localhost, i.e. only from the machine running openHAB.
Connections are intentionally not allowed from remote hosts due to security concerns.
To change this, see [Bind Console to All Interfaces](#bind-console-to-all-interfaces).
:::
A security warning is expected upon the first connection:
@ -57,8 +59,10 @@ The default username/password is **openhab:habopen**, so enter `habopen` at the
The first successful connection triggers generation of the Karaf remote console key and will take a few seconds longer than subsequent attempts.
*Note:* On slower systems, such as Raspberry Pi or Pine64, this first SSH connection may even time out.
::: tip Note
On slower systems, such as Raspberry Pi or Pine64, this first SSH connection may even time out.
If this happens, simply try connecting again until successful.
:::
## Using the Console
@ -174,7 +178,7 @@ To enable binding to all interfaces, uncomment the line
```#org.apache.karaf.shell:sshHost = 0.0.0.0```
in `services/runtime.cfg`.
### Change the Port Number

14
administration/jsondb.md
View File

@ -7,13 +7,13 @@ title: JsonDB Storage
# JsonDB Storage
JsonDB provides a system database for storage of configuration data.
All configuration data stored into the system through the REST interface that is used by the user interfaces will be stored into the JsonDB.
JsonDB provides a system database for storage of configuration data.
All configuration data stored into the system through the REST interface that is used by the user interfaces will be stored into the JsonDB.
JsonDB provides a high performance, human readable data store that is primarily meant for system use but can be edited manually, or stored in a version control system such as Git.
## Technical Overview
The system stores different data into separate tables.
The system stores different data into separate tables.
JsonDB maps these tables into separate files - in this way each file contains a different type of data (eg. Things, Items, Links).
The system also keeps a number of backups in a ```backup``` folder.
Each time a file is updated, the current version will be moved to the ```backup``` folder and timestamped so that the system can retain the most recent files.
@ -48,7 +48,9 @@ openHAB stores configuration information in JSON (JavaScript Object Notation) fo
All configuration information regarding _**Items, Links, and Things**_ are defined via the User Interfaces (Paper UI, HABmin, REST) or via internal openHAB services.
Note: The JSON DB does NOT store information for manually configured _**Items, Links, or Things**_, since these are already stored in files within the `OPENHAB_CONF` sub-directories (e.g. `/etc/openhab2/items/`).
::: tip Note
The JSON DB does NOT store information for manually configured _**Items, Links, or Things**_, since these are already stored in files within the `OPENHAB_CONF` sub-directories (e.g. `/etc/openhab2/items/`).
:::
## Storage Purpose
@ -69,7 +71,7 @@ The parameters for the two mechanisms may be modified in Paper UI :arrow_right:
This can reduce the number of writes when many changes are being introduced within a short period, and
2. _Maximum write delay_ (defaults to 30000 ms): Sets the maximum period the service will wait to write data in cases where changes are happening continually.
The service keeps up to five backups of each table.
The service keeps up to five backups of each table.
The outdated file is copied to the backup folder and then that file is overwritten with the new content.
## Storage Location
@ -192,5 +194,5 @@ Step 3. Using Paper UI :arrow_right: Configuration :arrow_right: Things, edit th
and save:
![Edit_Thing_Paper_UI](./images/edit_thing_paper_ui.png)
Step 4. Check the configuration properties again in the `OPENHAB_USERDATA/jsondb/org.eclipse.smarthome.core.thing.Thing.json` file:
Step 4. Check the configuration properties again in the `OPENHAB_USERDATA/jsondb/org.eclipse.smarthome.core.thing.Thing.json` file:
![New_Json](./images/new_json_file.png)

4
administration/runtime.md
View File

@ -14,7 +14,9 @@ It is possible to query and even change the state of entities like items or thin
* TOC
{:toc}
**Please note: Some of the described commands are executed on the internal database and could break your installation. Please use this functionality only if you know what you are doing!**
::: tip Note
Some of the described commands are executed on the internal database and could break your installation. Please use this functionality only if you know what you are doing!
:::
## Examples

4
administration/serial.md
View File

@ -17,7 +17,9 @@ No special configuration is needed, you can use the COM port number (e.g. `COM4`
## Linux
**Note:** openHABian comes with a menu option to configure the serial ports automatically. So all the rest here is only relevant for non-openHABian users.
::: tip Note
openHABian comes with a menu option to configure the serial ports automatically. So all the rest here is only relevant for non-openHABian users.
:::
If you can see issues related to opening the serial port with Linux, and you are using **non standard serial ports** (e.g. `/dev/ttyAMA0`) you might have to configure openHAB to detect and access the port correctly:

2
configuration/eclipseiotmarket.md
View File

@ -34,7 +34,7 @@ This behavior will be changed in future.
## Configuration
The marketplace integration can be configured to only provide add-ons of certain types (Note: Currently only bindings are supported!) and of a certain maturity level.
The marketplace integration can be configured to only provide add-ons of certain types (*Note:* Currently only bindings are supported!) and of a certain maturity level.
To do so, you can add a configuration file `$OPENHAB_CONF/services/marketplace.cfg` with content like:

6
configuration/index.md
View File

@ -167,11 +167,13 @@ While it's technically possible to use both methods in parallel, we recommend to
It would work to mix but you may easily forget about what is your "source of truth" when you reconfigure Things or Items at a later stage.
:::
Configuration done in files will be used (and Things/Items become visible and even changeable in Paper UI) if no Thing/Item of the same name was already created in PaperUI, but you can NOT create a Thing or Item using files and then use Paper UI to **permanently** change it.
Configuration done in files will be used (and Things/Items become visible and even changeable in Paper UI) if no Thing/Item of the same name was already created in PaperUI, but you can NOT create a Thing or Item using files and then use Paper UI to **permanently** change it.
Configuration done in PaperUI will be used and permanently stored in the internal database if no Thing/Item of the same name already exists in files, but those additions or changes will not be copied back into any `.things` file.
openHAB settings as defined in `services/addons.cfg` and `services/runtime.cfg` will override any settings made in PaperUI's Configuration/System pane.
**Important note:** All text files must be created with UTF-8 encoding. When using Visual Studio Code, this encoding is already set by default.
::: warning Important
All text files must be created with UTF-8 encoding. When using Visual Studio Code, this encoding is already set by default.
:::
## Recommendations for New Users

90
configuration/jsr223-jython.md
View File

@ -9,11 +9,11 @@ title: JSR223 Jython Scripting
## Configuration
[Download](https://jython.github.io/index) the Jython 2.7.0 standalone or installer package, or install through a package repository.
Newer versions are not yet supported.
[Download](https://jython.github.io/index) the Jython 2.7.0 standalone or installer package, or install through a package repository.
Newer versions are not yet supported.
Install Jython on the local filesystem and make note of the installation directory location.
The Jython implementation will need to be added to openHAB's Java classpath.
The Jython implementation will need to be added to openHAB's Java classpath.
How this is done depends on the specific installation technique and operating system.
### Linux Package Installers
@ -24,23 +24,23 @@ Modify the `EXTRA_JAVA_OPTS` environment variable in `/etc/default/openhab2` to:
EXTRA_JAVA_OPTS="-Xbootclasspath/a:/etc/openhab2/automation/jython/jython-standalone-2.7.0.jar -Dpython.home=/etc/openhab2/automation/jython -Dpython.path=/etc/openhab2/automation/lib/python"
```
This will add the Jython library to the Java classpath,
set the Jython home directory and specify the initial Python path for the Jython runtime.
Python modules and packages can be installed into the `python.path` locations and imported from scripts.
This will add the Jython library to the Java classpath,
set the Jython home directory and specify the initial Python path for the Jython runtime.
Python modules and packages can be installed into the `python.path` locations and imported from scripts.
Note that library modules and packages are not automatically reloaded when they change.
### Mac and Windows or Manual Installation
Set the `EXTRA_JAVA_OPTS` environment variable to the value described in the Linux configuration.
Note that on Windows the environment variable value should be set as a single line
Set the `EXTRA_JAVA_OPTS` environment variable to the value described in the Linux configuration.
Note that on Windows the environment variable value should be set as a single line
(without backslashes to combine the line fragments).
## Configuration Testing
In the `automation/jsr223` directory create an empty file called `test.py`.
Watch the openHAB log file carefully ([Karaf logging]({{base}}/administration/logging.html)
or viewing the `openhab.log` file directly).
Watch the openHAB log file carefully ([Karaf logging]({{base}}/administration/logging.html)
or viewing the `openhab.log` file directly).
You should see a log line with information similar to:
```text
@ -50,11 +50,13 @@ You should see a log line with information similar to:
... [INFO ] [.a.m.s.r.i.l.ScriptFileWatcher:150 ] - Loading script 'test.py'
```
> NOTE: ECMAScript is Javascript
::: tip Note
ECMAScript is Javascript
:::
Look for any potentially related error messages.
To enable debug logging, use the [Karaf logging]({{base}}/administration/logging.html) commands to
To enable debug logging, use the [Karaf logging]({{base}}/administration/logging.html) commands to
enable debug logging for the automation functionality:
```text
@ -63,11 +65,11 @@ log:set DEBUG org.openhab.core.automation
## Script Examples
Jython scripts provide access to almost all the functionality in an openHAB runtime environment.
As a simple example, the following script logs "Hello, World!" into the openhab.log file.
Note that `print` will usually not work since the output has no terminal to display the text.
One exception is when the openHAB server is running from the Eclipse IDE.
The openHAB server uses the [SLFJ](https://www.slf4j.org/) library for logging.
Jython scripts provide access to almost all the functionality in an openHAB runtime environment.
As a simple example, the following script logs "Hello, World!" into the openhab.log file.
Note that `print` will usually not work since the output has no terminal to display the text.
One exception is when the openHAB server is running from the Eclipse IDE.
The openHAB server uses the [SLFJ](https://www.slf4j.org/) library for logging.
```python
from org.slf4j import LoggerFactory
@ -75,31 +77,33 @@ from org.slf4j import LoggerFactory
LoggerFactory.getLogger("org.openhab.core.automation.examples").info("Hello world!")
```
Jython can [import Java classes](http://www.jython.org/jythonbook/en/1.0/ModulesPackages.html).
Depending on the openHAB logging configuration,
you may need to prefix logger names with `org.openhab.core.automation`
Jython can [import Java classes](http://www.jython.org/jythonbook/en/1.0/ModulesPackages.html).
Depending on the openHAB logging configuration,
you may need to prefix logger names with `org.openhab.core.automation`
for them to show up in the log file (or you modify the logging configuration).
> NOTE: Be careful with using wildcards when importing Java packages (e.g., `import org.sl4j.*`).
> This will work in some cases, but it might not work in some situations.
> It's best to use explicit imports with Java packages.
> For more details, see the Jython documentation on
> [Java package scanning](http://www.jython.org/jythonbook/en/1.0/ModulesPackages.html#java-package-scanning).
::: tip Note
Be careful with using wildcards when importing Java packages (e.g., `import org.sl4j.*`).
This will work in some cases, but it might not work in some situations.
It's best to use explicit imports with Java packages.
For more details, see the Jython documentation on
[Java package scanning](http://www.jython.org/jythonbook/en/1.0/ModulesPackages.html#java-package-scanning).
:::
The script then uses the [LoggerFactory](https://www.slf4j.org/apidocs/org/slf4j/Logger.html)
The script then uses the [LoggerFactory](https://www.slf4j.org/apidocs/org/slf4j/Logger.html)
to obtain a named logger and then logs a message like:
```text
... [INFO ] [.openhab.core.automation.examples:-2 ] - Hello world!
```
Notice that no rules were required for this simple script.
Notice that no rules were required for this simple script.
This can be a useful way to experiment with simple Jython code before defining rules or other more advanced functionality.
If you want to respond to openHAB events you can create rules in the scripts.
The following script requires two string items, `TestString1` and `TestString2`.
The rule created in the script is triggered by an update to `TestString1` and,
when triggered, the rule updates `TestString2`.
If you want to respond to openHAB events you can create rules in the scripts.
The following script requires two string items, `TestString1` and `TestString2`.
The rule created in the script is triggered by an update to `TestString1` and,
when triggered, the rule updates `TestString2`.
```python
scriptExtension.importPreset("RuleSupport")
@ -116,32 +120,32 @@ class MyRule(SimpleRule):
"itemName": "TestString1"
})).build()
]
def execute(self, module, input):
events.postUpdate("TestString2", "some data")
automationManager.addRule(MyRule())
```
When a script is loaded, some names are already defined in the script *scope* (the local Jython namespace).
To define rules, you must include some additional [script *extensions*](jsr223.html#presets)
(implemented as "presets") that add more names to the script scope for specific purposes.
In this case, the `RuleSimple` extension is used to import the `SimpleRule` base class.
When a script is loaded, some names are already defined in the script *scope* (the local Jython namespace).
To define rules, you must include some additional [script *extensions*](jsr223.html#presets)
(implemented as "presets") that add more names to the script scope for specific purposes.
In this case, the `RuleSimple` extension is used to import the `SimpleRule` base class.
The `RuleSupport` extensions provides the `automationManager` that allows you to register rule instances with openHAB.
The Jython rule class uses the `SimpleRule` subclass to simplify some aspects of the openHAB interface for use with JSR223.
n the constructor, the triggers atribute is set to a list of [triggers](jsr223.html#trigger_types).
In this example, the trigger is a state update trigger.
The trigger name identifies the trigger and the configuration direction provides trigger-specific options.
The Jython rule class uses the `SimpleRule` subclass to simplify some aspects of the openHAB interface for use with JSR223.
n the constructor, the triggers atribute is set to a list of [triggers](jsr223.html#trigger_types).
In this example, the trigger is a state update trigger.
The trigger name identifies the trigger and the configuration direction provides trigger-specific options.
For the item update trigger, the configuration provides the item name of the monitored item.
The `execute` method is invoked when the rule is triggered.
The `module` and `input` arguments can be used in advanced rules.
The `execute` method is invoked when the rule is triggered.
The `module` and `input` arguments can be used in advanced rules.
The information provided varies by the trigger type.
### Resources
- [Scripted Rule Support](https://github.com/eclipse/smarthome/wiki/Scripted-Rule-Support)
Early documentation on JSR223 usage in openHAB 2. Includes IDE setup instructions.
- [openhab2-jython](https://github.com/steve-bate/openhab2-jython) (github)

36
configuration/jsr223.md
View File

@ -7,21 +7,23 @@ title: JSR223 Scripting
# JSR223 Scripting
> Note: This feature is for users who have or are willing to learn some programming skills
> and are comfortable working with the command line prompt of the operating system hosting openHAB.
> _The Experimental Rule Engine add-on must be installed to define rules._
::: tip Note
This feature is for users who have or are willing to learn some programming skills
and are comfortable working with the command line prompt of the operating system hosting openHAB.
_The Experimental Rule Engine add-on must be installed to define rules._
:::
## Overview
[JSR223](https://docs.oracle.com/javase/8/docs/technotes/guides/scripting/) ([spec](https://jcp.org/aboutJava/communityprocess/pr/jsr223/index.html)) is a standard scripting API for Java Virtual Machine (JVM) [languages](https://en.wikipedia.org/wiki/List_of_JVM_languages).
The JVM languages provide varying levels of support for the JSR223 API and interoperability with the Java runtime.
Currently the following languages are known to work well for openHAB scripting:
[**Jython**](https://jython.github.io/) (Python on the JVM),
[**Nashorn Javascript**](http://www.oracle.com/technetwork/articles/java/jf14-nashorn-2126515.html) (ECMAScript implementation included in JDK8 through 10, [deprecated in 11](https://openjdk.java.net/jeps/335)), and
[JSR223](https://docs.oracle.com/javase/8/docs/technotes/guides/scripting/) ([spec](https://jcp.org/aboutJava/communityprocess/pr/jsr223/index.html)) is a standard scripting API for Java Virtual Machine (JVM) [languages](https://en.wikipedia.org/wiki/List_of_JVM_languages).
The JVM languages provide varying levels of support for the JSR223 API and interoperability with the Java runtime.
Currently the following languages are known to work well for openHAB scripting:
[**Jython**](https://jython.github.io/) (Python on the JVM),
[**Nashorn Javascript**](http://www.oracle.com/technetwork/articles/java/jf14-nashorn-2126515.html) (ECMAScript implementation included in JDK8 through 10, [deprecated in 11](https://openjdk.java.net/jeps/335)), and
[**Apache Groovy**](http://www.groovy-lang.org/) (JVM scripting language).
Although JSR223 scripts can be used as a general-purpose extension language for openHAB, it is most commonly used for the creation of rules, and within scripted Actions or Conditions.
Currently, openHAB allows JSR223 scripting to access all packages, which may not be included in the official APIs.
Although JSR223 scripts can be used as a general-purpose extension language for openHAB, it is most commonly used for the creation of rules, and within scripted Actions or Conditions.
Currently, openHAB allows JSR223 scripting to access all packages, which may not be included in the official APIs.
This provides great flexibility for the users of JSR223, but is also *use at your own risk*, since changes outside of the offical APIs occur frequently, and are not considered to be *breaking changes*.
New APIs are planned to be implemented in the future, which will provide standardized interfaces for interacting with openHAB through scripted automation.
@ -202,7 +204,7 @@ The Default preset is preloaded, so it does not require importing.
| `StringType` | `org.eclipse.smarthome.core.library.types.StringType` |
| `StringListType` | `org.eclipse.smarthome.core.library.types.StringListType` |
| `RawType` | `org.eclipse.smarthome.core.library.types.RawType` |
| `items` | Instance of `java.util.Map&lt;String, State&gt;` |
| `items` | Instance of `java.util.Map&lt;String, State&gt;` |
| `itemRegistry` | Instance of `org.eclipse.smarthome.core.items.ItemRegistry` |
| `ir` | Alias for `itemRegistry` |
| `things` | Instance of `org.eclipse.smarthome.core.thing.ThingRegistry` |
@ -264,17 +266,17 @@ scriptExtension.importPreset("RuleSupport")
| Variable | Description |
|----------|-------------|
| automationManager | Instance for managing rules and other openHAB module instances. (e.g., `addRule`) |
| Configuration | `org.eclipse.smarthome.config.core.Configuration` |
| Action | `org.openhab.core.automation.Action` |
| Condition | `org.openhab.core.automation.Condition` |
| Configuration | `org.eclipse.smarthome.config.core.Configuration` |
| Action | `org.openhab.core.automation.Action` |
| Condition | `org.openhab.core.automation.Condition` |
| Trigger | `org.openhab.core.automation.Trigger` |
| Rule | `org.openhab.core.automation.Rule` (use `SimpleRule` for defining rules) |
| Rule | `org.openhab.core.automation.Rule` (use `SimpleRule` for defining rules) |
<a name="rulefactories_presets"></a>
#### `RuleFactories` Preset
> NOTE: Advanced usage
>Note: Advanced usage
```python
scriptExtension.importPreset("RuleFactories")
@ -365,5 +367,5 @@ Read the JSR223 language specific documentation for examples of using these `Tri
### Additional Information
- [Scripted Rule Support](https://github.com/eclipse/smarthome/wiki/Scripted-Rule-Support) -
- [Scripted Rule Support](https://github.com/eclipse/smarthome/wiki/Scripted-Rule-Support) -
Early documentation on JSR223 usage in openHAB 2, including IDE setup instructions

118
configuration/rules-dsl.md
View File

@ -36,8 +36,10 @@ This makes the creation of rules very easy!
### The Syntax
Note: The rule syntax is based on [Xbase](http://www.eclipse.org/Xtext/#xbase) and as a result it is sharing many details with [Xtend](http://www.eclipse.org/xtend/), which is built on top of Xbase as well.
::: tip Note
The rule syntax is based on [Xbase](http://www.eclipse.org/Xtext/#xbase) and as a result it is sharing many details with [Xtend](http://www.eclipse.org/xtend/), which is built on top of Xbase as well.
As a result, we will often point to the Xtend documentation for details.
:::
A rule file is a text file with the following structure:
@ -146,7 +148,7 @@ Member of <group> received update [<state>]
Member of <group> changed [from <state>] [to <state>]
```
The `Member of` trigger only works with Items that are a direct member of the Group.
The `Member of` trigger only works with Items that are a direct member of the Group.
It does not work with members of nested subgroups.
Also, as with Item event-based triggers, when using `received command`, the Rule will trigger before the Item's state is updated.
So in Rules where the Rule needs to know what the command was, use the `receivedCommand` implicit variable instead of `triggeringItem.state`.
@ -221,7 +223,9 @@ The `thingUID` is the identifier assigned to the Thing, manually in your configu
You can find it from PaperUI or from Karaf remote console.
For example, one z-wave device can be "zwave:device:c5155aa4:node14".
> Note: You need to use quotes around `thingUID` if it contains special characters such as ':'.
::: tip Note
You need to use quotes around `thingUID` if it contains special characters such as ':'.
:::
{: #channel-based-triggers}
### Channel-based Triggers
@ -233,7 +237,9 @@ Your rules can take actions based upon trigger events generated by these trigger
You can decide whether you want to catch only a specific or any trigger the channel provides.
Here is the syntax for these cases (parts in square brackets are optional):
> Note: You need to use quotes around `triggerChannel` if it contains special characters such as `:`.
::: tip Note
You need to use quotes around `triggerChannel` if it contains special characters such as `:`.
:::
```java
Channel "<triggerChannel>" triggered [<triggerEvent>]
@ -343,59 +349,59 @@ sendCommand("My_Lamp_" + index, ON)
{: #using-state-of-items-in-rules}
### Using the States of Items in Rules
Often it is desired to calculate other values from Item states or to compare Item states against other values
Often it is desired to calculate other values from Item states or to compare Item states against other values
In openHAB, every item carries a state.
The state of an Item is an Object itself and can be accessed with `MyItem.state`.
A complete and up-to-date list of item types are currently allowed in OpenHAB and the command types each item can accept is given in the [openHab documentation for items]({{base}}/concepts/items.html).
To use the state of an Item in rules it is often necessary to know what type of state the Item is carrying and how to convert it into types that can be used in such operations.
A complete and up-to-date list of item types are currently allowed in OpenHAB and the command types each item can accept is given in the [openHab documentation for items]({{base}}/concepts/items.html).
To use the state of an Item in rules it is often necessary to know what type of state the Item is carrying and how to convert it into types that can be used in such operations.
Conversely, to use the result of a calculation to modify the state of an item may require its transformation into a suitable type.
This section differentiates between command type and state type.
For ease of reading, it is possible to simply add “type” to the end of a command type thereby obtaining the state type.
For example, a Color Item can receive an OnOffType, IncreaseDecreaseType, PercentType, or HSBType.
This section differentiates between command type and state type.
For ease of reading, it is possible to simply add “type” to the end of a command type thereby obtaining the state type.
For example, a Color Item can receive an OnOffType, IncreaseDecreaseType, PercentType, or HSBType.
Therefore the following are all valid commands one can send to a Color Item:
- `MyColorItem.sendCommand(ON)`
- `MyColorItem.sendCommand(INCREASE)`
- `MyColorItem.sendCommand(new PercentType(50))`
- `MyColorItem.sendCommand(new HSBType(new DecimalType(123), new PercentType(45), new PercentType(67)))`
An alternative way to command or update the state of an item is through the use of specially formatted strings.
The section in the [item documentation on formatting]({{base}}/concepts/items.html#state-and-command-type-formatting) details the requirements for the formatting.
An alternative way to command or update the state of an item is through the use of specially formatted strings.
The section in the [item documentation on formatting]({{base}}/concepts/items.html#state-and-command-type-formatting) details the requirements for the formatting.
Even though many Items accept commands and updates of various different types, each stores its state internally using only one type.
The Color Item from the example above will accept various command types, but will only return an HSBType.
Even though many Items accept commands and updates of various different types, each stores its state internally using only one type.
The Color Item from the example above will accept various command types, but will only return an HSBType.
Groups can be declared with any Item type and the internal state of the Group will match that type.
Groups can be declared with any Item type and the internal state of the Group will match that type.
For example, `Group:Switch` will return an OnOffType for its state.
Each State Type provides a number of convenience methods that will greatly aid in conversion and calculations.
Each State Type provides a number of convenience methods that will greatly aid in conversion and calculations.
There are two ways to discover these methods:
- Use the [openHAB VS Code Extension](/docs/configuration/editors.html#editors.html#openhab-vs-code-extension) and the `<ctrl><space>` key combo to list all the available methods
- Look at the JavaDocs for the given type.
For example, the [JavaDoc for HSBType](http://www.eclipse.org/smarthome/documentation/javadoc/index.html?org/eclipse/smarthome/core/library/types/HSBType.html) shows getRed, getBlue, and getGreen methods.
These methods can be called in Rules-DSL without the "get" part in name as in `(MyColorItem.state as HSBType).red)`.
They retrieve the state of MyColorItem and then casts it as HSBType to be able to use the methods associated with the HSBType.
These methods can be called in Rules-DSL without the "get" part in name as in `(MyColorItem.state as HSBType).red)`.
They retrieve the state of MyColorItem and then casts it as HSBType to be able to use the methods associated with the HSBType.
{: #conversions}
#### Working with Item States: Conversions
*Reminder: For a complete and up-to-date list of what item types are currently allowed in openHAB and the command types each item can accept refer to the section on [items in the openHAB documentation]({{base}}/concepts/items.html).*
Below a **non-exhaustive** list of some more common conversions.
Below a **non-exhaustive** list of some more common conversions.
The interested reader is encouraged to also visit the [forum](https://community.openhab.org) where many more examples can be found.
##### Conversion of Item.state to String
All Item states can be converted into a string by invoking `MyItem.state.toString`.
All Item states can be converted into a string by invoking `MyItem.state.toString`.
##### Color Item
A Color Item stores an **HSBType**.
The HSB stands for Hue, Saturation, and Brightness.
Often one has the desired color as an RGB value (Red, Green, Blue).
The following code can be used to send an RGB value to a Color Item.
The HSB stands for Hue, Saturation, and Brightness.
Often one has the desired color as an RGB value (Red, Green, Blue).
The following code can be used to send an RGB value to a Color Item.
```java
import java.awt.Color
@ -421,7 +427,7 @@ val blue = (MyColorItem.state as HSBType).blue / 100 * 255
##### Contact Item
A Contact Item carries a OpenClosedType.
OpenClosedType is an Enumeration.
OpenClosedType is an Enumeration.
One can convert from Open and Closed to 1 and 0 with code similar to:
```java
@ -431,12 +437,12 @@ val contactNum = if (MyContactItem.state == OPEN) 1 else 0
##### DateTime Item
A DateTime Item carries a **DateTimeType**.
DateTimeType presents the biggest challenge when converting and performing calculations.
The problems stem from the fact that by default the Rules use a Joda DateTime class to represent time, most notably `now`.
DateTimeType presents the biggest challenge when converting and performing calculations.
The problems stem from the fact that by default the Rules use a Joda DateTime class to represent time, most notably `now`.
However, DateTimeType is not a Joda DateTime and in fact the two are incompatible, requiring some conversion in order to use the two together.
The lowest common denominator when working with time is to get at the epoch value.
Epoch is the number of milliseconds that have passed since 1 January 1970 GMT and stored in a `long`.
The lowest common denominator when working with time is to get at the epoch value.
Epoch is the number of milliseconds that have passed since 1 January 1970 GMT and stored in a `long`.
With epoch, one can compare two dates together, convert a Joda DateTime to a DateTimeType and vice versa.
```java
@ -456,7 +462,7 @@ calendar.timeInMillis = now.millis
val dtt = new DateTimeType(calendar)
```
In certain cases it is needed to convert an epoch timestamp to a human readable and/or store it in a DateTimeType and a DateTime Item.
In certain cases it is needed to convert an epoch timestamp to a human readable and/or store it in a DateTimeType and a DateTime Item.
Here an option to do so utilizing SimpleDateFormat:
```java
@ -474,7 +480,7 @@ val DateTimeType timestamp = DateTimeType.valueOf(timestampString)
val String datetime_string = DateTime_Item.state.format("%1$td.%1$tm.%1$ty %1$tH:%1$tM"))
```
Both Joda DateTime as well as DateTimeType provide a number of useful methods for comparing date times together and/or extracting parts of the date.
Both Joda DateTime as well as DateTimeType provide a number of useful methods for comparing date times together and/or extracting parts of the date.
For some examples:
```java
@ -492,7 +498,7 @@ val hours = (MyDateTimeItem.state as DateTimeType).zonedDateTime.get(Calendar::H
##### Dimmer Item
A Dimmer Item carries a **PercentType**.
PercentType can be cast to and treated like a java.lang.Number, where Number represents any type of numerical value.
PercentType can be cast to and treated like a java.lang.Number, where Number represents any type of numerical value.
The Rules language supports doing mathematical and logical operations with Numbers
The Number Object supports methods for getting primitive versions of that Number if needed.
@ -508,7 +514,7 @@ val float dimAsFloat = dimVal.floatValue
If the conversion from or into hexadecimal values is necessary, the following examples may be useful:
```java
// to convert a hex_code (a number expressed in hexadecimals) to a Number type
// to convert a hex_code (a number expressed in hexadecimals) to a Number type
val dimVal = Integer.parseInt(hex_code, 16) as Number
//for very large_hex_codes use
val dimVal = Long.valueOf(large_hex_code, 16).longValue() as Number
@ -522,7 +528,7 @@ Additional conversions that might be useful are listed below under NumberItem
##### Location Item
A Location Items carries a **PointType**.
A PointType consist of two or three DecimalType numbers representing latitude and longitude in degrees, and an optional altitude in meters.
A PointType consist of two or three DecimalType numbers representing latitude and longitude in degrees, and an optional altitude in meters.
Here are a few examples:
```java
@ -582,14 +588,14 @@ var isQuantity = myItem.state instanceof QuantityType
Other useful conversions can be found under Dimmer Item.
One warning comes with DecimalType (also holds true for QuantityType).
The full explanation is [beyond the scope of this introduction](https://community.openhab.org/t/ambiguous-feature-call-whats-wrong-designer-user-or-bug/9477/4).
One warning comes with DecimalType (also holds true for QuantityType).
The full explanation is [beyond the scope of this introduction](https://community.openhab.org/t/ambiguous-feature-call-whats-wrong-designer-user-or-bug/9477/4).
To avoid an error mentioning an "Ambiguous Method Call" always cast the state of a DecimalType to a Number, not DecimalType.
##### Player Item
The Player item allows to control players (e.g. audio players) with commands such as Play, Pause, Next, Previous, Rewind and Fastforward.
The Player Item carries three types with predefined commands
The Player Item carries three types with predefined commands
| State Type | Commands |
|---------------------------|---------------------|
@ -632,7 +638,7 @@ val itemvalue = new java.math.BigDecimal(Integer::parseInt(myHexValue, 16))
##### Switch Item
A Switch Item carries a OnOffType.
OnOffType is an Enumeration.
OnOffType is an Enumeration.
One can convert from ON and OFF to 1 and 0 with code similar to:
```java
@ -642,27 +648,27 @@ val SwitchNum = if (MySwitchItem.state == ON) 1 else 0
#### Deeper Dive
While interacting with Item states, care must be taken to understand the difference between Objects and primitives.
As all object-oriented computer languages, Java and the Rules DSL have implemented the concept of inheritance.
While interacting with Item states, care must be taken to understand the difference between Objects and primitives.
As all object-oriented computer languages, Java and the Rules DSL have implemented the concept of inheritance.
However, inheritance only applies to Objects and does **not** apply to primitives; examples for primitives are `integer` and `boolean`.
Inheritance allows to take an existing Object type, called a Class, and adding to it to make it into something different.
This “something different” becomes a Child of the original Class, the parent. The Child still can do everything the parent could do.
The top level base Class for all Objects in Java and the Rules DSL is called simply `Object`.
Inheritance allows to take an existing Object type, called a Class, and adding to it to make it into something different.
This “something different” becomes a Child of the original Class, the parent. The Child still can do everything the parent could do.
The top level base Class for all Objects in Java and the Rules DSL is called simply `Object`.
In addition to other useful things, the class `Object` implements a method called `toString`.
And since `Object` is the parent of all Objects, ALL Classes also implement a `toString` method.
_However primitives do not inherit from Object.
In addition to other useful things, the class `Object` implements a method called `toString`.
And since `Object` is the parent of all Objects, ALL Classes also implement a `toString` method.
_However primitives do not inherit from Object.
They don't inherit from anything and they don't have any methods at all which includes the lack of a toString Method._
Objects are typically equipped with many more type conversion methods, while primitives do not support any type conversion.
Objects are typically equipped with many more type conversion methods, while primitives do not support any type conversion.
This distinction is very relevant when trying to use the result of a calculation and apply it to an Item state.
The `sendCommand` is a generic action and needs to be able to work with all Item types.
Actions only support two String arguments as all Objects will support the conversion `toString`.
`sendCommand (MyItem, new_state)` will automatically use the `MyItem.toString` method to convert MyItem into a String.
It will also attempt to do so with the second argument if `new_state` is not already a String.
However, if the second argument is a primitive, and not an Object, it does not carry a method `toString`.
Thus, Rules DSL will not be able to cast `new_state` as a String.
As a consequence, the use of `sendCommand(MyItem, primitive)`, using a primitive as the second argument, will almost always fail.
The `sendCommand` is a generic action and needs to be able to work with all Item types.
Actions only support two String arguments as all Objects will support the conversion `toString`.
`sendCommand (MyItem, new_state)` will automatically use the `MyItem.toString` method to convert MyItem into a String.
It will also attempt to do so with the second argument if `new_state` is not already a String.
However, if the second argument is a primitive, and not an Object, it does not carry a method `toString`.
Thus, Rules DSL will not be able to cast `new_state` as a String.
As a consequence, the use of `sendCommand(MyItem, primitive)`, using a primitive as the second argument, will almost always fail.
The different syntax for the generic and the objective-specific differs and is given in the table below:
@ -671,10 +677,10 @@ The different syntax for the generic and the objective-specific differs and is g
| `postUpdate(MyItem, new_state)` | `MyItem.postUpdate(new_state)` |
| `sendCommand(MyItem, new_state)` | `MyItem.sendCommand(new_state)` |
The benefit of using Objects over primitives is apparent through the following type conversions that are automatically invoked by Object as the context requires.
The benefit of using Objects over primitives is apparent through the following type conversions that are automatically invoked by Object as the context requires.
Using the method `MyItems.sendCommand()` that is owned by MyItem will use the `sendCommand` method that is suitable to make the necessary type conversions.
For example, the `NumberItem` class would have a `sendCommand(int)`, `sendCommand(long)`, `sendCommand(float)`, `sendCommand(double)`, `sendCommand(Number)`, `sendCommand(DecimalType)`, and `sendCommand(String)` method.
Each of these separate methods is individually written to handle all of these different types of Objects.
For example, the `NumberItem` class would have a `sendCommand(int)`, `sendCommand(long)`, `sendCommand(float)`, `sendCommand(double)`, `sendCommand(Number)`, `sendCommand(DecimalType)`, and `sendCommand(String)` method.
Each of these separate methods is individually written to handle all of these different types of Objects.
MyItem will automatically apply the method that corresponds to the argument type.
{: #implicit-variables}

6
configuration/sitemaps.md
View File

@ -414,9 +414,11 @@ Video [item=<itemname>] [icon="<iconname>"] url="<url of video to embed>" [encod
```
Allows you to display a video as part of your Sitemap.
Note: not all video encodings (formats) are supported; you may need to transcode your video.
::: tip Note
Not all video encodings (formats) are supported; you may need to transcode your video.
The video must be reachable directly via URL.
An embedded and/or protected video are not supported.
An embedded and/or protected video is not supported.
:::
- `item` can refer to a String Item whose state is a URL to a video. Some clients may not (yet) consider `item`.
- `url` is the default URL from which to retrieve the video if there is no associated Item or if the associated item's state is not a URL.

48
configuration/things.md
View File

@ -19,7 +19,9 @@ These Channels can be linked to [items]({{base}}/concepts/items.html).
Items are used to control Things and consume their information.
Ultimately, when Items are linked to Channels on a Thing, they become available to the various user interfaces and to the rules engine.
*Note:* Things are a new concept in openHAB 2, Things definitions are not needed for 1.x bindings.
::: tip Note
Things are a new concept in openHAB 2, Things definitions are not needed for 1.x bindings.
:::
## Defining Things
@ -40,10 +42,12 @@ From start to finish, the process for fully configuring a physical entity repres
There are two methods for defining Things provided by the various bindings:
through [discovery]({{base}}/concepts/discovery.html) or by manual definition in configuration text files.
*Note:* Some bindings do not fully support auto-discovery, others are hard to manually cover by the file based approach.
::: tip Note
Some bindings do not fully support auto-discovery, others are hard to manually cover by the file based approach.
Please consult the documentation for each binding to determine the best way to add that binding's Things and Items to openHAB.
For some bindings, manual Thing definitions are required.
Other bindings (such as the [ZWave](/addons/bindings/zwave/) binding) currently prefer or require the discovery method.
:::
### Defining Things Using Discovery
@ -70,14 +74,14 @@ The syntax for `.things` files is defined as follows (parts in `<..>` are requir
Thing <binding_id>:<type_id>:<thing_id> "Label" @ "Location" [ <parameters> ]
```
The first keyword defines whether the entry is a bridge or a thing.
The next statement defines the UID of the thing which contains of the following three segments: `binding id`, `thing type id`, `thing id`.
So the first two segments must match to a thing type supported by a binding (e.g. `network:device` or `astro:moon`), whereas the thing id can be freely defined.
The first keyword defines whether the entry is a bridge or a thing.
The next statement defines the UID of the thing which contains of the following three segments: `binding id`, `thing type id`, `thing id`.
So the first two segments must match to a thing type supported by a binding (e.g. `network:device` or `astro:moon`), whereas the thing id can be freely defined.
Optionally, you may provide a label in order to recognize it easily, otherwise the default label from the thing type will be displayed.
To help organizing your things, you also may define a location (`Location` in the example above).
Inside the squared brackets configuration parameters of the thing are defined.
Inside the squared brackets configuration parameters of the thing are defined.
The type of the configuration parameter is determined by the binding and must be specified accordingly in the DSL.
@ -111,9 +115,9 @@ Bridge hue:bridge:mybridge [ ipAddress="192.168.3.123" ] {
}
```
Within the curly brackets things can be defined, that should be members of the bridge.
For the contained thing only the thing type ID and thing ID must be defined (e.g. 0210 bulb1).
So the syntax is `Thing <thingTypeId> <thingId> []`.
Within the curly brackets things can be defined, that should be members of the bridge.
For the contained thing only the thing type ID and thing ID must be defined (e.g. 0210 bulb1).
So the syntax is `Thing <thingTypeId> <thingId> []`.
The resulting UID of the thing is `hue:0210:mybridge:bulb1`.
Bridges that are defined somewhere else can also be referenced in the DSL:
@ -122,20 +126,20 @@ Bridges that are defined somewhere else can also be referenced in the DSL:
Thing hue:0210:mybridge:bulb (hue:bridge:mybridge) [lightId="3"]
```
The referenced bridge is specified in the parentheses.
Please notice that the UID of the thing also contains the bridge ID as third segment.
The referenced bridge is specified in the parentheses.
Please notice that the UID of the thing also contains the bridge ID as third segment.
For the contained notation of things the UID will be inherited and the bridge ID is automatically taken as part of the resulting thing UID.
**Example of a MQTT Bridge with Generic MQTT Things :**
```xtend
Bridge mqtt:broker:MyMQTTBroker [ host="192.168.178.50", secure=false, username="MyUserName", password="MyPassword"] {
Thing topic sonoff_Dual_Thing "Light_Dual" @ "Sonoff" {
Thing topic sonoff_Dual_Thing "Light_Dual" @ "Sonoff" {
Channels:
Type switch : PowerSwitch1 [ stateTopic="stat/sonoff_dual/POWER1" , commandTopic="cmnd/sonoff_dual/POWER1", on="ON", off="OFF"]
Type switch : PowerSwitch2 [ stateTopic="stat/sonoff_dual/POWER2" , commandTopic="cmnd/sonoff_dual/POWER2", on="ON", off="OFF"]
Type string : Version [stateTopic="stat/sonoff_dual/STATUS2", transformationPattern="JSONPATH:$.StatusFWR.Version"]
}
}
Thing topic sonoff_TH_Thing "Light_TH" @ "Sonoff" {
Channels:
Type switch : PowerSwitch [ stateTopic="stat/sonoff_TH/POWER", commandTopic="cmnd/sonoff_TH/POWER", on="ON", off="OFF" ]
@ -143,16 +147,16 @@ Bridge mqtt:broker:MyMQTTBroker [ host="192.168.178.50", secure=false, username=
Type number : Temperature [stateTopic="tele/sonoff_TH/SENSOR", transformationPattern="JSONPATH:$.AM2301.Temperature"]
Type number : Humidity [stateTopic="tele/sonoff_TH/SENSOR", transformationPattern="JSONPATH:$.AM2301.Humidity"]
}
}
}
```
### Defining Channels
It is also possible to manually define channels.
Usually this is not needed, as channels will be automatically created by the binding based on the thing type description.
It is also possible to manually define channels.
Usually this is not needed, as channels will be automatically created by the binding based on the thing type description.
It is also possible to add additional channels to existing things and for bindings that allow to create generic things (for example the [MQTT Generic Thing Binding](/addons/bindings/mqtt.generic/)) all channels can be defined by the user.
#### State channels
#### State channels
```xtend
Thing yahooweather:weather:losangeles [ location=2442047, unit="us", refresh=120 ] {
@ -164,8 +168,8 @@ Thing yahooweather:weather:losangeles [ location=2442047, unit="us", refresh=120
}
```
Each channel definition must be placed inside the curly braces and begin with the keyword `State` followed by the accepted item type (e.g. `String`).
After this the channel ID follows with the configuration of a channel.
Each channel definition must be placed inside the curly braces and begin with the keyword `State` followed by the accepted item type (e.g. `String`).
After this the channel ID follows with the configuration of a channel.
The framework will merge the list of channels coming from the binding and the user-defined list in the DSL.
As state channels are the default channels, you can omit the `State` keyword, the following example creates the same channels as the example above:
@ -213,7 +217,7 @@ Many bindings provide standalone channel type definitions like this:
</thing:thing-descriptions>
```
They can be referenced within a thing’s channel definition, so that they need to be defined only once and can be reused for many channels.
They can be referenced within a thing’s channel definition, so that they need to be defined only once and can be reused for many channels.
You may do so in the DSL as well:
```xtend
@ -223,10 +227,10 @@ Thing yahooweather:weather:losangeles [ location=2442047, unit="us", refresh=120
}
```
The Type keyword indicates a reference to an existing channel definition.
The Type keyword indicates a reference to an existing channel definition.
The channel kind and accepted item types of course are takes from the channel definition, therefore they don’t need to be specified here again.
You may optionally give the channel a proper label (like “Yesterday’s Temperature” in the example above) so you can distinguish the channels easily.
You may optionally give the channel a proper label (like “Yesterday’s Temperature” in the example above) so you can distinguish the channels easily.
If you decide not to, then the label from the referenced channel type definition will be used.
### Linking Items

48
developers/bindings/index.md
View File

@ -56,9 +56,9 @@ A weather bindings `WeatherHandlerFactory` for example supports only one *ThingT
@NonNullByDefault
@Component(configurationPid = "binding.myweatherbinding", service = ThingHandlerFactory.class)
public class WeatherHandlerFactory extends BaseThingHandlerFactory {
private static final Collection<ThingTypeUID> SUPPORTED_THING_TYPES_UIDS = Collections.singleton(WeatherBindingConstants.THING_TYPE_WEATHER);
@Override
public boolean supportsThingType(ThingTypeUID thingTypeUID) {
return SUPPORTED_THING_TYPES_UIDS.contains(thingTypeUID);
@ -118,7 +118,7 @@ The startup of a handler is divided in two essential steps:
1. Handler is registered: `ThingHandler` instance is created by a `ThingHandlerFactory` and tracked by the framework.
In addition, the handler can be registered as a service if required, e.g. as `FirmwareUpdateHandler` or `ConfigStatusProvider`.
2. Handler is initialized: `ThingHandler.initialize()` is called by the framework in order to initialize the handler.
This method is only called if all 'required' configuration parameters of the Thing are present.
The handler is ready to work (methods like `handleCommand`, `handleUpdate` or `thingUpdated` can be called).
@ -247,9 +247,9 @@ a user-interface requested a refreshed value, if will send a `RefreshType` comma
@Override
public void handleCommand(ChannelUID channelUID, Command command) {
if (command instanceof RefreshType) {
updateWeatherData();
switch (channelUID.getId()) {
case CHANNEL_TEMPERATURE:
updateState(channelUID, getTemperature());
@ -271,7 +271,7 @@ For this the binding developer can call a method from the `BaseThingHandler` cla
```java
updateState("channelId", OnOffType.ON)
```
```
The call will be delegated to the framework, which changes the state of all bound items.
It is binding specific when the channel should be updated.
@ -333,7 +333,7 @@ The status can be updated via an inherited method from the BaseThingHandler clas
```java
updateStatus(ThingStatus.OFFLINE, ThingStatusDetail.OFFLINE.COMMUNICATION_ERROR);
```
```
The second argument of the method takes a `ThingStatusDetail` enumeration value, which further specifies the current status situation.
A complete list of all thing statuses and thing status details is listed in the [Thing Status](../../concepts/things.html#thing-status) chapter.
@ -349,9 +349,11 @@ After the thing is created, the framework calls the `initialize` method of the h
At this time the state of the thing is *INTIALIZING* as long as the binding sets it to something else.
Because of this the default implementation of the `initialize()` method in the `BaseThingHandler` just changes the status to *ONLINE*.
*Note:* A binding should not set any other state than ONLINE, OFFLINE and UNKNOWN.
::: tip Note
A binding should not set any other state than ONLINE, OFFLINE and UNKNOWN.
Additionally, REMOVED must be set after `handleRemoval()` has completed the removal process.
All other states are managed by the framework.
:::
Furthermore bindings can specify a localized description of the thing status by providing the reference of the localization string, e.g &#64;text/rate_limit.
The corresponding handler is able to provide placeholder values as a JSON-serialized array of strings:
@ -478,10 +480,10 @@ public void handleCommand(ChannelUID channelUID, Command command) {
switch (channelUID.getId()) {
case CHANNEL_ID_COLOR_TEMPERATURE:
StateUpdate lightState = lightStateConverter.toColorLightState(command);
StateUpdate lightState = lightStateConverter.toColorLightState(command);
hueBridgeHandler.updateLightState(getLight(), lightState);
break;
case CHANNEL_ID_COLOR:
break;
case CHANNEL_ID_COLOR:
// ...
}
}
@ -492,10 +494,10 @@ Inside the `BridgeHandler` the list of *Things* can be retrieved via the `getThi
### Bridge Handler Implementation
A `BridgeHandler` handles the communication between the openHAB framework and a *bridge* (a device that acts as a gateway to enable the communication with other devices) represented by a `Bridge` instance.
A bridge handler has the same properties as thing handler.
Therefore, the `BridgeHandler` interface extends the `ThingHandler` interface.
### The BaseBridgeHandler
openHAB provides an abstract implementation of the `BridgeHandler` interface named `BaseBridgeHandler`.
@ -507,7 +509,7 @@ It is recommended to use this class, because it covers a lot of common logic.
A `BridgeHandler` has the same life cycle than a `ThingHandler` (created by a `ThingHandlerFactory`, well defined life cycle by handler methods `initialize()` and `dispose()`, see chapter [Life Cycle](thing-handler.html#life-cycle)).
A bridge acts as a gateway in order to provide access to other devices, the *child things*.
Hence, the life cycle of a child handler depends on the life cycle of a bridge handler.
Bridge and child handlers are subject to the following restrictions:
Bridge and child handlers are subject to the following restrictions:
- A `BridgeHandler` of a bridge is initialized before `ThingHandler`s of its child things are initialized.
- A `BridgeHandler` is disposed after all `ThingHandler`s of its child things are disposed.
@ -649,14 +651,14 @@ TODO
Bindings can implement the `DiscoveryService` interface and register it as an OSGi service to inform the framework about devices and services, that can be added as things to the system (see also [Inbox & Discovery Concept](../../concepts/discovery.html)).
A discovery service provides discovery results.
The following table gives an overview about the main parts of a `DiscoveryResult`:
The following table gives an overview about the main parts of a `DiscoveryResult`:
| Field | Description |
|-------|-------------|
| `thingUID` | The `thingUID` is the unique identifier of the specific discovered thing (e.g. a device's serial number). It *must not* be constructed out of properties, that can change (e.g. IP addresses). A typical `thingUID` could look like this: `hue:bridge:001788141f1a`
| `thingTypeUID` | Contrary to the `thingUID` is the `thingTypeUID` that specifies the type the discovered thing belongs to. It could be constructed from e.g. a product number. A typical `thingTypeUID` could be the following: `hue:bridge`.
| `bridgeUID` | If the discovered thing belongs to a bridge, the `bridgeUID` contains the UID of that bridge.
| `properties` | The `properties` of a `DiscoveryResult` contain the configuration for the newly created thing.
| `thingUID` | The `thingUID` is the unique identifier of the specific discovered thing (e.g. a device's serial number). It *must not* be constructed out of properties, that can change (e.g. IP addresses). A typical `thingUID` could look like this: `hue:bridge:001788141f1a`
| `thingTypeUID` | Contrary to the `thingUID` is the `thingTypeUID` that specifies the type the discovered thing belongs to. It could be constructed from e.g. a product number. A typical `thingTypeUID` could be the following: `hue:bridge`.
| `bridgeUID` | If the discovered thing belongs to a bridge, the `bridgeUID` contains the UID of that bridge.
| `properties` | The `properties` of a `DiscoveryResult` contain the configuration for the newly created thing.
| `label` | The human readable representation of the discovery result. Do not put IP/MAC addresses or similar into the label but use the special `representationProperty` instead. |
| `representationProperty` | The name of one of the properties which discriminates the discovery result best against other results of the same type. Typically this is a serial number, IP or MAC address. The representationProperty often matches a configuration parameter and is also explicitly given in the thing-type definition. |
@ -701,7 +703,7 @@ The `Discovery` class of a binding which implements `AbstractDiscoveryService` s
where `<binding-id>` is the id of the binding, i.e. `astro` for the Astro binding.
Such a registered service will be picked up automatically by the framework.
### Background Discovery
### Background Discovery
If the implemented discovery service enables background discovery, the `AbstractDiscoveryService` class automatically starts it.
If background discovery is enabled, the framework calls `AbstractDiscoveryService#startBackgroundDiscovery` when the binding is activated and `AbstractDiscoveryService#stopBackgroundDiscovery` when the component is deactivated.
@ -762,7 +764,7 @@ With this, dynamic discoveries (like UPnP or mDNS) can re-discover existing thin
### Remove older results
Normally, older discovery results already in the inbox are left untouched by a newly triggered scan.
If this behavior is not appropriate for the implemented discovery service, one can override the method `stopScan` to call `removeOlderResults` as shown in the following example from the Hue binding:
If this behavior is not appropriate for the implemented discovery service, one can override the method `stopScan` to call `removeOlderResults` as shown in the following example from the Hue binding:
```java
@Override
@ -793,7 +795,7 @@ The devoloper has to take care about that.
UPnP discovery is implemented in the framework as `UpnpDiscoveryService`.
It is widely used in bindings.
To facilitate the development, binding developers only need to implement a `UpnpDiscoveryParticipant`.
Here the developer only needs to implement three simple methods:
Here the developer only needs to implement three simple methods:
- `getSupportedThingTypeUIDs` - Returns the list of thing type UIDs that this participant supports.
The discovery service uses this method of all registered discovery participants to return the list of currently supported thing type UIDs.
@ -852,7 +854,7 @@ public class HueBridgeDiscoveryParticipant implements UpnpDiscoveryParticipant {
mDNS discovery is implemented in the framework as `MDNSDiscoveryService`.
To facilitate the development, binding developers only need to implement a `MDNSDiscoveryParticipant`.
Here the developer only needs to implement four simple methods:
Here the developer only needs to implement four simple methods:
- `getServiceType` - Defines the [mDNS service type](http://www.dns-sd.org/ServiceTypes.html).
- `getSupportedThingTypeUIDs` - Returns the list of thing type UIDs that this participant supports.

10
developers/guidelines.md
View File

@ -188,7 +188,7 @@ void myFun() {
try {
doSomething();
} catch (IOException e) {
logger.warn("Explain what went wrong and how to avoid it. You can have arguments {}.", someVariable, e);
logger.warn("Explain what went wrong and how to avoid it. You can have arguments {}.", someVariable, e);
}
}
```
@ -338,14 +338,18 @@ For HTTP Operations
* org.eclipse.jetty.http.*
* org.eclipse.jetty.util.*
Note: HttpClient instances should be obtained by the handler factory through the HttpClientFactory service and unless there are specific configuration requirements, the shared instance should be used.
::: tip Note
HttpClient instances should be obtained by the handler factory through the HttpClientFactory service and unless there are specific configuration requirements, the shared instance should be used.
:::
For Web Socket Operations
* org.eclipse.jetty.websocket.client
* org.eclipse.jetty.websocket.api
Note: WebSocketClient instances should be obtained by the handler factory through the WebSocketClientFactory service and unless there are specific configuration requirements, the shared instance should be used.
::: tip Note
WebSocketClient instances should be obtained by the handler factory through the WebSocketClientFactory service and unless there are specific configuration requirements, the shared instance should be used.
:::
Additionally these libraries are allowed

24
developers/utils/events.md
View File

@ -60,12 +60,14 @@ The event source is optional and represents the name of the source identifying t
| ItemStateChangedEvent | The state of an item has changed. | smarthome/items/{itemName}/statechanged |
| GroupItemStateChangedEvent | The state of a group item has changed through a member. | smarthome/items/{itemName}/{memberName}/statechanged |
**Note:** The `ItemStateEvent` is always sent if the state of an item is updated, even if the state did not change.
::: tip Note
The `ItemStateEvent` is always sent if the state of an item is updated, even if the state did not change.
`ItemStateChangedEvent` is sent only if the state of an item was really changed.
It contains the old and the new state of the item.
The `GroupItemStateChangedEvent` is sent only if the state of a group item was changed by a member.
It contains the old and the new state of the group item as well as the member.
:::
#### Thing Events
@ -77,9 +79,11 @@ It contains the old and the new state of the group item as well as the member.
| ThingStatusInfoEvent | The status of a thing is updated. | smarthome/things/{thingUID}/status |
| ThingStatusInfoChangedEvent | The status of a thing changed. | smarthome/things/{thingUID}/statuschanged |
**Note:** The `ThingStatusInfoEvent` is always sent if the status info of a thing is updated, even if the status did not change.
::: tip Note
The `ThingStatusInfoEvent` is always sent if the status info of a thing is updated, even if the status did not change.
`ThingStatusInfoChangedEvent` is sent only if the status of a thing was really changed.
It contains the old and the new status of the thing.
:::
#### Inbox Events
@ -163,7 +167,7 @@ Each event subscriber must be registered via OSGi Declarative Services (DS) unde
<provide interface="org.eclipse.smarthome.core.events.EventSubscriber"/>
</service>
</scr:component>
```
```
The listing below summarizes some best practices in order to implement event subscribers:
@ -196,7 +200,7 @@ public class SomeItemEventSubscriber extends AbstractItemEventSubscriber {
return eventFilter;
}
@Override
@Override
protected void receiveCommand(ItemCommandEvent commandEvent) {
// do something
}
@ -249,7 +253,7 @@ The following Java snippet shows a new event type extending the class `AbstractE
public class SunriseEvent extends AbstractEvent {
public static final String TYPE = SunriseEvent.class.getSimpleName();
private final SunriseDTO sunriseDTO;
SunriseEvent(String topic, String payload, SunriseDTO sunriseDTO) {
@ -261,7 +265,7 @@ public class SunriseEvent extends AbstractEvent {
public String getType() {
return TYPE;
}
public SunriseDTO getSunriseDTO() {
return sunriseDTO;
}
@ -290,7 +294,7 @@ Event factories can be added by implementing the `EventFactory` interface or ext
The `AbstractEventFactory` provides some useful utility for parameter validation and payload serialization & deserialization with JSON.
The classes are located in the openHAB core bundle.
```java
```java
public class SunEventFactory extends AbstractEventFactory {
private static final String SUNRISE_EVENT_TOPIC = "smarthome/sun/{time}/sunrise";
@ -303,15 +307,15 @@ public class SunEventFactory extends AbstractEventFactory {
protected Event createEventByType(String eventType, String topic, String payload, String source) throws Exception {
if (SunriseEvent.TYPE.equals(eventType)) {
return createSunriseEvent(topic, payload);
}
}
return null;
}
private Event createSunriseEvent(String topic, String payload) {
SunriseDTO sunriseDTO = deserializePayload(payload, SunriseDTO.class);
return new SunriseEvent(topic, payload, sunriseDTO);
}
public static SunriseEvent createSunriseEvent(Sunrise sunrise) {
String topic = buildTopic(SUNRISE_EVENT_TOPIC, sunrise.getTime());
SunriseDTO sunriseDTO = map(sunrise);

12
installation/docker.md
View File

@ -100,12 +100,12 @@ docker run \
openhab/openhab:<version>-<architecture>-<distribution>
```
Where
Where
- `<uid>` is the user ID number for the `openhab` user which you can obtain using the command `id openhab`,
- `<gid>` is the group ID number for the `openhab` user,
- `<version>` is the version of openHAB,
- `<architecture>` is the architecture of your system and
- `<uid>` is the user ID number for the `openhab` user which you can obtain using the command `id openhab`,
- `<gid>` is the group ID number for the `openhab` user,
- `<version>` is the version of openHAB,
- `<architecture>` is the architecture of your system and
- `<distribution>` is the base system (debian or alpine).
It is important that the ID number is passed in.
@ -174,7 +174,7 @@ Note, always review the README on [Docker Hub](https://hub.docker.com/r/openhab/
- `--net=host` : by default Docker will place a container into its own network stack. However, openHAB 2 requires UPnP discovery so this parameter makes the Docker container use the host's network stack.
- `-v /etc/localtime:/etc/localtime:ro` : ties the time of the container to the host's time, read only so the container cannot change the host's time
- `-v /etc/timezone:/etc/timezone:ro` : ties the timezone of the container to the host's time zone, read only so the container cannot change the host's time zone
- `-v /opt/openhab/conf:/openhab/conf` : location of the conf folder for openHAB configurations (NOTE: you must create these folders on the host before running the container)
- `-v /opt/openhab/conf:/openhab/conf` : location of the conf folder for openHAB configurations (*Note:* you must create these folders on the host before running the container)
- `-v /opt/openhab/userdata:/openhab/userdata` : location for logs, cache, persistence databases, etc.
- `-v /opt/openhab/addons:/openhab/addons` : only needed if installing addons unavailable via PaperUI or the Karaf Console
- `-v /opt/openhab/.java:/openhab/.java` : needed by the Nest 1.x binding (and others?), location of the security token

14
installation/linux.md
View File

@ -36,16 +36,18 @@ If you're unsure which manual file you should download, using `dpkg --print-arch
When installing Zulu or Zulu Embedded from a .zip or .tar archive, make sure to [set Zulu as the main Java "alternative"](https://docs.azul.com/zulu/zuludocs/#ZuluUserGuide/SwitchingBetweenJavaAlternatives/SwitchBetweenJavaAlts.htm).
**Note:** Make sure to download Zulu or Java **8**, as openHAB is not yet compatible with Java 9.
::: tip Note
Make sure to download Zulu or Java **8**, as openHAB is not yet compatible with Java 9.
:::
## Installation
openHAB 2 can be installed through
openHAB 2 can be installed through
- the openHABian project **(easiest method, ships with the openHABian configuration tool)**
- a package repository (apt, yum)
- manually from file.
The installation through the **openHABian project** and the use of the provided openHABian configuration tool is recommended for end users.
The installation through the **openHABian project** and the use of the provided openHABian configuration tool is recommended for end users.
Installing using the provided **package repository** (using `apt`, `apt-get`, `yum` or `dnf`) is easier, but requires more manualconfiguration later on due to the missing openHABian configuration tool.
@ -279,7 +281,7 @@ Systems based on **systemd** (e.g. Debian 8, Ubuntu 15.x, Raspbian Jessie and ne
# Stop the openHAB background service
sudo systemctl stop openhab2.service
# Get the service log since the last boot
sudo journalctl -u openhab2.service -b
@ -737,7 +739,7 @@ Next, add the desired share configurations to the end of the file:
public=no
create mask=0777
directory mask=0777
[openHAB2-logs]
comment=openHAB2 logs
path=/var/log/openhab2

10
installation/security.md
View File

@ -172,8 +172,10 @@ sudo service nginx restart
For further security, you may wish to ask for a **username and password** before users have access to openHAB.
This is fairly simple in NGINX once you have the reverse proxy setup, you just need to provide the server with a basic authentication user file.
**Note:** There is currently an issue with Proxy Authentication and HABmin when using some browsers.
::: tip Note
There is currently an issue with Proxy Authentication and HABmin when using some browsers.
If you require HABmin, consider connecting locally or using Safari for now.
:::
{: #nginx-auth-user}
##### Creating the First User
@ -434,7 +436,11 @@ To test your security settings [SSL Labs](https://www.ssllabs.com/ssltest/) prov
This optional section is for those who would like to strengthen the HTTPS security on openHAB, it can be applied regardless of which HTTPS method you used [above](#nginx-https), **but you need to follow at least one of them first**.
First, we need to generate a stronger key exchange, to do this we can generate an additional key with OpenSSL **Note: depending on your hardware this will take up to few minutes to complete:**
First, we need to generate a stronger key exchange, to do this we can generate an additional key with OpenSSL.
::: tip Note
Depending on your hardware this will take up to few minutes to complete:
:::
```shell
mkdir -p /etc/nginx/ssl

7
tutorials/beginner/configuration.md
View File

@ -57,9 +57,12 @@ But if you start a new discovery process later, the thing will reappear.
In this example, we click on the check icon of the thing with the IP address 192.168.1.103.
Let's assume this is John's mobile phone which we want to use for presence detection.
We change the (automatically added during the discovery) name of the thing on the next page to "John's Mobile" and click on the "ADD AS THING" button.
*Please note: If your network devices use a DHCP server to obtain ther IP addresses automatically, please make sure to define a DHCP reservation for a device which you want to use in openHAB.
::: tip Note
If your network devices use a DHCP server to obtain ther IP addresses automatically, please make sure to define a DHCP reservation for a device which you want to use in openHAB.
Otherwise it's IP address may change in the future and your thing definiton won't work any more.
Information about how to define a DHCP reservation can be normally be found in the manual of your network router.*
*Information about how to define a DHCP reservation can be normally be found in the manual of your network router.*
:::
![](images/picture_10.jpg)

5
tutorials/beginner/sitemap.md
View File

@ -40,7 +40,10 @@ Open the default.items file and define your first item:
Switch Presence_Mobile_John "Johns Mobile" <network> { channel="network:device:192_168_1_103:online" }
```
*Note: Item names have to be unique! You should follow a certain naming convention concerning your items.
::: tip Note
Item names have to be unique! You should follow a certain naming convention concerning your items.
:::
In this example, we used the purpose of the item, "Presence", followed by the device type, "_Mobile", and finally the owner's name, "_John", to construct the final item name.
Another suggestion for different items, for example a wallplug which is plugged-in in the living room in the first floor providing power to a TV, is to use the type, the floor, the room and the usage of the item.

258
tutorials/migration.md
View File

@ -13,8 +13,10 @@ Where needed, additional details are provided for other platforms (Windows, OSX,
These instructions emphasize the text based procedures over the use of PaperUI and Habmin which is closer to the openHAB 1.x experience.
Note: In all of the other pages in this documentation, openHAB 2 is simply referred to as openHAB.
::: tip Note
In all of the other pages in this documentation, openHAB 2 is simply referred to as openHAB.
In order to distinguish between the two versions in this, the current version is referred to as openHAB 2.
:::
This page is structured as follows:
@ -25,7 +27,7 @@ This page is structured as follows:
## Preparation
Now is the time to consider and plan for your newly installed openHAB.
Now is the time to consider and plan for your newly installed openHAB.
Some questions to ask and answer include:
- Are you happy with your current deployment and maintenance of the deployment?
@ -33,19 +35,19 @@ Some questions to ask and answer include:
- Have you wanted to migrate to a container (e.g. [Docker]({{base}}/installation/docker.html) or a virtual machine)?
- Do you want to start over fresh on a brand new OS install?
Your answers to these and other similar questions will help guide you to prepare your installation before you start the migration.
Your answers to these and other similar questions will help guide you to prepare your installation before you start the migration.
For example, if you want to start using git to back up and configuration manage your openHAB configurations, or if you are considering moving to [Docker]({{base}}/installation/docker.html) or a VM or starting over fresh (e.g. [openHABian](https://github.com/ThomDietrich/openhabian)), now is a good time to start the process.
The following procedure primarily focuses on an in-place migration.
If you are migrating to a fresh install, container, or another VM some of the following steps can be skipped.
The following procedure primarily focuses on an in-place migration.
If you are migrating to a fresh install, container, or another VM some of the following steps can be skipped.
Those steps are identified.
One major consideration is that at the time of this writing openHAB 2 does not implement authentication and authorization (i.e. no username and password).
One major consideration is that at the time of this writing openHAB 2 does not implement authentication and authorization (i.e. no username and password).
If you are relying upon port forwarding to access your openHAB server remotely instead of via a VPN, SSH tunneling, or [my.openhab](https://my.openhab.org/), we highly recommend [setting up a reverse proxy]({{base}}/configuration/nginx.html).
## Backups
The first step is to backup everything that you have modified in the existing openHAB 1.x installation.
The first step is to backup everything that you have modified in the existing openHAB 1.x installation.
If you installed using apt-get these files may include:
- `/etc/openhab` - configuration files
@ -58,7 +60,7 @@ If you are on an operating system that does not support apt-get or performed a m
## Shutdown openhab 1.x
One cannot run openHAB 1.x and openHAB 2 at the same time on the same machine with default settings.
One cannot run openHAB 1.x and openHAB 2 at the same time on the same machine with default settings.
They both use the same networking ports and some bindings require exclusive access to hardware resources (e.g. zwave, RFXCOM).
On an apt-get installed openHAB 1.x running on a systemd based OS (Ubuntu 15+, Raspbian Jessy+) run:
@ -73,10 +75,10 @@ On manually installed systems follow your usual procedure for stopping openHAB (
Follow the instructions for your platform [here]({{base}}/installation/index.html).
There are three choices to make: Release, Testing, or SNAPSHOT.
There are three choices to make: Release, Testing, or SNAPSHOT.
Release contains the most recent stable release and remains unchanged until the next release.
Occasionally, the Release may receive an update containing important bug fixes that were backported to the Release version.
Testing is a stable version of openHAB 2 that is periodically made when the SNAPSHOT version reaches a state where there are no known bugs.
Testing is a stable version of openHAB 2 that is periodically made when the SNAPSHOT version reaches a state where there are no known bugs.
SNAPSHOT is on the bleeding edge of development and includes everything that has been merged into the baseline in the past 24-hours.
If you plan on running openHAB 1.x as your primary while migrating make sure to disable openHAB 2 from starting automatically.
@ -89,49 +91,49 @@ sudo systemctl disable openhab2.service
Start your newly installed openHAB 2 instance per the instruction in the installation guide for your platform and navigate to `http://<openhab server ip>:8080` where `<openhab server ip>` is the address of the server where openHAB 2 is running.
Congratulations, you have a running openHAB 2!
Congratulations, you have a running openHAB 2!
See [Concepts]({{base}}/concepts/index.html) and below for important differences between openHAB 1.x and openHAB 2.
Theoretically one should be able to just enable the [openHAB 1.x Compatibility Layer]({{base}}/developers/development/compatibilitylayer.html#how-to-use-openhab-1x-add-ons-that-are-not-part-of-the-distribution), copy over the existing add-ons and config files and have it work.
However, while the compatibility layer is very good and very capable, this approach will result in errors and end up being more work than the steps below.
Theoretically one should be able to just enable the [openHAB 1.x Compatibility Layer]({{base}}/developers/development/compatibilitylayer.html#how-to-use-openhab-1x-add-ons-that-are-not-part-of-the-distribution), copy over the existing add-ons and config files and have it work.
However, while the compatibility layer is very good and very capable, this approach will result in errors and end up being more work than the steps below.
Therefore the first steps will be to get it running using the 1.9 version of the bindings installed through openHAB 2's new add-on management system.
There are three approaches one can use to install and configure bindings, an all text based one, using the Karaf console, or using one of the administration GUIs (i.e. PaperUI or Habmin 2).
There are three approaches one can use to install and configure bindings, an all text based one, using the Karaf console, or using one of the administration GUIs (i.e. PaperUI or Habmin 2).
While all three approaches are presented below, the text based approach is the recommended one for those coming from openHAB 1.x as it will be more familiar.
While it is possible to mix and match the approaches below (e.g. using Text Based for one step and Karaf for another) the recommended approach is to stick with the same approach for the full tutorial.
### Text Based (Recommended)
In your configurations folder for openHAB 2 (`/etc/openhab2` on apt-get installed instances) there is a new folder named `services`.
In this folder you will find a file named `runtime.cfg`.
This file contains global openHAB 2 parameters.
Open this file for editing and you will find a number of parameters you may want to set.
In your configurations folder for openHAB 2 (`/etc/openhab2` on apt-get installed instances) there is a new folder named `services`.
In this folder you will find a file named `runtime.cfg`.
This file contains global openHAB 2 parameters.
Open this file for editing and you will find a number of parameters you may want to set.
In particular for this tutorial we recommend setting:
- `org.eclipse.smarthome.persistence:default=mapdb` - default persistence, use whatever was set in `persistence:default` in openhab.cfg
- `autoapprove:enabled=false` - makes it so you must manually approve automatically discovered Things in the Inbox (see below)
- `org.eclipse.smarthome.links:autoLinks=false` - prevents openHAB from automatically creating an Item for each automatically discovered Thing.
Next open for editing `addons.cfg`.
Next open for editing `addons.cfg`.
This file contains parameters related to add-ons including allowing one to choose which add-ons to install.
For now just set the following parameters:
- `package = expert` - expert is a good choice here.
- `package = expert` - expert is a good choice here.
It will include the standard UIs, all transformation services and the 1.x compatibility layer, though you can choose your UIs and add-ons individually later.
- `remote = true` - required for the installation of legacy 1.x add-ons
- `legacy = true` - required to install the 1.x version of an add-on for which there is a 2.x native version
- `binding = ` - a comma separated list of the bindings from openHAB 1.x that you use.
If you are in doubt of the name of a binding, look in openhab.cfg for that binding's configurations.
- `binding = ` - a comma separated list of the bindings from openHAB 1.x that you use.
If you are in doubt of the name of a binding, look in openhab.cfg for that binding's configurations.
The first part of the tag in openhab.cfg will be that name of the binding, then append a 1.
For example, the configuration parameters for the MQTT Binding start with "mqtt" in openhab.cfg so the name of the binding is "mqtt1".
You can find the list of bindings [here](/addons/#bindings).
- `ui = ` - if you intend on using PaperUI include "paper", if you use zwave I recommend "habmin".
- `ui = ` - if you intend on using PaperUI include "paper", if you use zwave I recommend "habmin".
The list of UIs are [here]({{base}}/configuration/#versatility).
- `action = ` - the list of action add-ons, see [here](/addons/#action) for list of possible actions.
- `transformation = ` - the list of transformations you use, see [here](/addons/#transform) for a list of possible transformations.
- `transformation = ` - the list of transformations you use, see [here](/addons/#transform) for a list of possible transformations.
Unlike in openHAB 1, one must install transformations separately.
- `voice = ` - see [here](/addons/#voice)
- `System Intergrations = ` - homekit, Azure IoT, etc., see [here](/addons/#io)
- `System Intergrations = ` - homekit, Azure IoT, etc., see [here](/addons/#io)
Do not list myopenhab/openhabcloud at this time, instructions for it are below.
Do not install any 2.x version binding at this time.
We want to get your current OH 1.x confiuguration running on the OH 2 core first.
@ -186,7 +188,7 @@ transformation = xslt,map,regex,javascript
voice =
# A comma-separated list of miscellaneous services to install (e.g. "myopenhab")
misc =
misc =
```
### Karaf Console (Alternative)
@ -224,7 +226,7 @@ For each add-on you are using in openHAB 1.x, and for each transformation type y
feature:install <add-on name>
```
using the name from the list.
using the name from the list.
For example, to install the Weather Binding run:
```bash
@ -237,55 +239,55 @@ To get a list of all currently installed items run:
feature:list | grep Started
```
At this time only install add-ons that are 1.x.0.
At this time only install add-ons that are 1.x.0.
The 2.0 add-ons will be installed later.
### PaperUI Approach (Alternative)
These instructions assume no edits have been made to `runtime.cfg` or `addons.cfg` as described in the previous sections.
Navigate your browser to `http://<openhab server address>:8080` and select PaperUI from the list of UIs.
Select "Expert" from the list of default packages.
Navigate your browser to `http://<openhab server address>:8080` and select PaperUI from the list of UIs.
Select "Expert" from the list of default packages.
Now select PaperUI and navigate to `Configuration -> System` on the left hand side.
Enable "Include Legacy 1.x Bindings" and "Access Remote Repositories".
This will allow you to install your current bindings even if there is an openHAB 2 version available.
Enable "Include Legacy 1.x Bindings" and "Access Remote Repositories".
This will allow you to install your current bindings even if there is an openHAB 2 version available.
Press "Save".
![PaperUI System Settings](images/PaperUI-Config-System.png)
Now select "Add-ons" from the left and browse or search for each of the bindings and add-ons you currently use.
Make note of those that do not appear in the list.
Do not install any binding that has a version 2.x at this time.
Now select "Add-ons" from the left and browse or search for each of the bindings and add-ons you currently use.
Make note of those that do not appear in the list.
Do not install any binding that has a version 2.x at this time.
If there is not a 1.x.0 version we will install the binding manually (see below).
This is a great opportunity to identify those bindings you actually use and only install those.
When you find a binding to install, press the Install button and wait for installation to complete.
When you find a binding to install, press the Install button and wait for installation to complete.
Do not install the myopenhab/openhabcloud Binding yet.
One thing to be aware of is any configuration done in PaperUI gets saved to a files and folders under $OPENHAB_CONF.
Binding configurations, Items, Things, et. al. created in, edited in, and otherwise modified in PaperUI will not appear in the conf directories.
For example, if you create an Item in PaperUI, you will not find that new Item in any of the .items files.
Instead they get saved to a JSONDB file located in $OPENHAB_USERDATA/jsondb.
Since none of the administration UIs are currently capable of doing everything and we want to minimize the number of changes necessary, you will ultimately end up with a mix of database and text based configuration.
Since none of the administration UIs are currently capable of doing everything and we want to minimize the number of changes necessary, you will ultimately end up with a mix of database and text based configuration.
This is why we recommend not using PaperUI for those migrating to openHAB 2 from openHAB 1.x.
### Configure Add-ons
As bindings and other add-ons are installed, you can watch for errors in the logs.
As bindings and other add-ons are installed, you can watch for errors in the logs.
Errors at this time may not be important but make note of those that did generate errors during installation for special attention later.
Once a binding or add-on is installed, it will create a `$OPENHAB_CONF/services/<add-on name>.cfg` file.
Unlike in openHAB 1.x where all the binding configurations are placed in the one openhab.cfg file, openHAB 2 has a separate .cfg file for each binding.
Once a binding or add-on is installed, it will create a `$OPENHAB_CONF/services/<add-on name>.cfg` file.
Unlike in openHAB 1.x where all the binding configurations are placed in the one openhab.cfg file, openHAB 2 has a separate .cfg file for each binding.
Transfer the settings for each binding from openhab.cfg to its new .cfg file, removing the binding name from the parameter.
For example, the parameter `nest:refresh=300000` in openhab.cfg becomes `refresh=300000` in nest.cfg.
Note that a .cfg file is not always generated.
Note that a .cfg file is not always generated.
If one is not automatically generated and it is a binding that has a section in openhab.cfg, you can create one yourself and transfer the settings as described above.
One important thing to note is that bindings and add-ons that require extra steps to register with a cloud service like Nest will require reregistering again as if this were the first installation and configuration (e.g. you need to generate a new pin code for Nest).
Unlike in openHAB 1.x, transformations are not automatically included in openHAB 2.
Unlike in openHAB 1.x, transformations are not automatically included in openHAB 2.
Make sure you include these in your installation as well.
### Installing Unofficially Supported openHAB 1.x Add-ons
@ -296,26 +298,26 @@ Be aware that not all openHAB 1.8 and earlier Add-ons are expected to be compati
Please note also, that support for these early bindings may not be available anymore and that for most an updated version will be availble (see [here](/addons#bindings) for a full list of supported bindings).
Install the openHAB 1.x compatibility layer using the Karaf Console instructions above.
Copy your openhab.cfg file to `$OPENHAB_CONF/services`.
Copy your openhab.cfg file to `$OPENHAB_CONF/services`.
If you are running an apt-get installed openHAB 1.x openhab.cfg is located in `/etc/openhab/configurations`.
For an apt-get installed openHAB 2 the `$OPENHAB_CONF` folder is located in `/etc/openhab2`.
For an apt-get installed openHAB 2 the `$OPENHAB_CONF` folder is located in `/etc/openhab2`.
For manually installed openHAB 1.x this file is located in `$OPENHAB_CONF/configurations` and in manually installed openHAB 2 it is `$OPENHAB_CONF/conf`.
This file will have a lot of redundant configuration information in it that you have already moved over to individual binding .cfgs.
This file will have a lot of redundant configuration information in it that you have already moved over to individual binding .cfgs.
Make sure to comment those out and just leave the config parameters for the bindings you are manually installing.
Now copy the add-on's jar files that you want to install to the `$OPENHAB_CONF/addons` folder for openHAB 2.
Now copy the add-on's jar files that you want to install to the `$OPENHAB_CONF/addons` folder for openHAB 2.
For example:
```bash
cp /usr/share/openhab/addons/org.openhab.binding.astro-1.8.3.jar /usr/share/openhab2/addons
```
There may be some errors about there not being a `bind` and `unbind` method.
There may be some errors about there not being a `bind` and `unbind` method.
If everything worked you should see in the log the same entries from the binding you see when openHAB 1.x starts.
Watch the logs for errors as they can be informative.
For example, some Actions require a corresponding Binding be installed first.
Watch the logs for errors as they can be informative.
For example, some Actions require a corresponding Binding be installed first.
An example error of this sort looks like:
```text
@ -324,24 +326,24 @@ org.osgi.framework.BundleException: Could not resolve module: org.openhab.action
Unresolved requirement: Import-Package: org.openhab.binding.astro.internal.calc
```
Note, the above error is for illustration purposes.
Note, the above error is for illustration purposes.
You should not be installing Astro this way.
These instructions are only for add-ons that are not listed in PaperUI or the Karaf Console.
### Final Add-ons Installation Steps
openHAB 2 has a different [folder layout]({{base}}/installation/linux.html#file-locations).
Of particular node are the `$OPENHAB_CONF` folders and `OPENHAB_CONF` folders.
Of particular node are the `$OPENHAB_CONF` folders and `OPENHAB_CONF` folders.
See the previous link for the location of these folders for your installation.
As with openHAB 1.x, one must restart openHAB 2 to pick up changes to .cfg files.
Therefore restart openHAB 2 now.
If you haven't already, configure default persistence now.
If you haven't already, configure default persistence now.
You can do this through `runtime.cfg` or PaperUI.
Now openHAB 2 is ready to receive your other configurations, items and such.
Watch the log file as you transfer over files for errors.
Watch the log file as you transfer over files for errors.
These errors will have to be fixed.
Copy over your files in the following order:
@ -370,15 +372,15 @@ cp $OPENHAB1_CONF/configurations/sitemaps/* $OPENHAB_CONF/sitemaps/*
### Sitemap
* Change the default icons to png for ClassicUI and BasicUI if migrating custom icons.
This can be done in PaperUI under Configuration -> Service -> BasicUI and ClassicUI.
* Change the default icons to png for ClassicUI and BasicUI if migrating custom icons.
This can be done in PaperUI under Configuration -> Service -> BasicUI and ClassicUI.
Set the "Default Icon Format" to "Bitmap".
* Not all of the default icons that came with openHAB 1.x are available in the default set for openHAB 2.
If you are missing an icon in your sitemap that could be the cause.
* Not all of the default icons that came with openHAB 1.x are available in the default set for openHAB 2.
If you are missing an icon in your sitemap that could be the cause.
The full list of openHAB 2 icons is [here]({{base}}/configuration/iconsets/classic/).
* Dynamic icons must have a default.
* Dynamic icons must have a default.
For example, if one has a bunch of Wunderground icons (e.g. wunderground-chanceflurries.png) there must be a `wunderground.png` icon as well.
* The URLs to the openHAB frontends have changed:
@ -391,11 +393,11 @@ cp $OPENHAB1_CONF/configurations/sitemaps/* $OPENHAB_CONF/sitemaps/*
* Static webview files are now located in `$OPENHAB_CONF/html` instead of `/usr/share/openhab/webapps`
* The name of the sitemap (i.e. the word right after `sitemap` at the top of the file) must match the file name.
* The name of the sitemap (i.e. the word right after `sitemap` at the top of the file) must match the file name.
For example the file named `myhome.sitemap` should start with `sitemap myhome`.
* Charts no longer display a legend by default.
If this parameter is not set, the legend is hidden if there is only one chart series.
Add 'legend=true' to restore the chart's legend.
Add 'legend=true' to restore the chart's legend.
### Rules
@ -407,11 +409,11 @@ These can be used to simulate events that can trigger a rule, even in an install
Potential pitfalls in rules code:
* All references to org.openhab.* in imports and class references should be removed. All of these classes are automatically included and have moved.
* import org.joda.time.* statements should also be removed, they are also included by default.
* To test for Items with an Undefined state replace `if(MyItem.state == Undefined)` with `if(MyItem.state == NULL)`.
Case matters.
`NULL` is only valid when testing an Item's state to see if it is undefined.
* To test for Items with an Undefined state replace `if(MyItem.state == Undefined)` with `if(MyItem.state == NULL)`.
Case matters.
`NULL` is only valid when testing an Item's state to see if it is undefined.
`null` is used pretty much everywhere else to mean "no value" and usually indicates no result or an error.
* The `HSBType` state type can no longer be constructed using a `java.awt.Color` object, and there is no longer a `toColor()` method.
* The `HSBType` state type can no longer be constructed using a `java.awt.Color` object, and there is no longer a `toColor()` method.
Use the following alternatives:
```java
@ -419,34 +421,34 @@ var HSBType hsb = HSBType::fromRGB(color.red, color.green, color.blue)
var Color color = Color::getHSBColor(hsb.hue.floatValue / 360, hsb.saturation.floatValue / 100, hsb.brightness.floatValue / 100)
```
Continue watching the logs as you move files over.
There will likely be a number of errors.
Continue watching the logs as you move files over.
There will likely be a number of errors.
Take note of them with plans to return and correct them if they persist.
## Testing
- **Items**: Watch `$OPENHAB_CONF/logs/events.log` and methodically work through all
of your Items activating and deactivating them one-by-one to verify the events
appear in the logs as expected.
appear in the logs as expected.
The REST API (installable from the Misc tab in PaperUI) can be helpful here as it will let you issue commands or updates to Items directly.
This may require running openHAB 2 for some period of time and/or writing new rules, using the REST API, or external scripts to exercise all the Items.
- **Persistence**: Check your persistence locations to see if all your persisted Items are listed, if possible.
Check your charts on your sitemap to make sure they are being updated.
Check openhab.log or the Karaf console log:tail for errors when Rules call persistence methods to get historical data (e.g. lastUpdate).
- **Persistence**: Check your persistence locations to see if all your persisted Items are listed, if possible.
Check your charts on your sitemap to make sure they are being updated.
Check openhab.log or the Karaf console log:tail for errors when Rules call persistence methods to get historical data (e.g. lastUpdate).
Restart openHAB and verify those Items configured with restoreOnStartup are initialized to their last state.
The REST API can he helpful here as well as it lets you issue queries to Persistence.
- **Rules**: When you first copy over your rules there will be many errors, particularly if the rules assume that all Items have a state.
One can easily forget to check for NULL in an openHAB instance that has been running for some time and one is using restoreOnStartup.
- **Rules**: When you first copy over your rules there will be many errors, particularly if the rules assume that all Items have a state.
One can easily forget to check for NULL in an openHAB instance that has been running for some time and one is using restoreOnStartup.
But because this is a brand new instance there are no values in the database to restore the Items to when openHAB starts.
- **Sitemap**: The most common Sitemap issue will be missing icons.
Browse through your sitemap methodically and identify those entries that have a missing or wrong icon.
Select an alternative from the [defaults]({{base}}/addons/iconsets/classic/readme.html) or copy the ones you were using from openHAB 1.x to the conf/icons/classic folder.
Both BasicUI and ClassicUI pull their icons from that folder.
- **Sitemap**: The most common Sitemap issue will be missing icons.
Browse through your sitemap methodically and identify those entries that have a missing or wrong icon.
Select an alternative from the [defaults]({{base}}/addons/iconsets/classic/readme.html) or copy the ones you were using from openHAB 1.x to the conf/icons/classic folder.
Both BasicUI and ClassicUI pull their icons from that folder.
For details on custom icons make sure to check the icons section in the [Items]({{base}}/configuration/iconsets/classic/) documentation.
One important change since openHAB 1.x is that icon filenames need to be lowercase only in openHAB 2.
Once you are satisfied that your new openHAB system is up and running take a deep breath and take a break.
Let it run for a few days or a week and verify that everything is working as it should.
Once you are satisfied that your new openHAB system is up and running take a deep breath and take a break.
Let it run for a few days or a week and verify that everything is working as it should.
Watch the logs for inexplicable errors.
Once you are happy with how it is running you can start migrating to the openHAB 2 native bindings and start taking advantage of Things and Channels (see the next section).
You can even just stop here.
@ -458,10 +460,10 @@ VSCode replaces openHAB Designer as the Integrated Development Environment for O
## New Concepts: Things and Channels
One of the new notions that people quickly come across when moving to openHAB 2 native bindings is that of a ["Thing"]({{base}}/concepts/things.html).
One of the new notions that people quickly come across when moving to openHAB 2 native bindings is that of a ["Thing"]({{base}}/concepts/things.html).
To understand what they are and how they relate to Items, we will compare them to how Items are "bound" and configured in openHAB 1.x.
In openHAB 1.x (and importantly still for 1.x version bindings running in openHAB 2) one has to add ["binding configuration"](https://github.com/openhab/openhab/wiki/Explanation-of-items#binding-config) in curly brackets to the end of Item definitions in order to link that Item to some control point on a physical device or API.
In openHAB 1.x (and importantly still for 1.x version bindings running in openHAB 2) one has to add ["binding configuration"](https://github.com/openhab/openhab/wiki/Explanation-of-items#binding-config) in curly brackets to the end of Item definitions in order to link that Item to some control point on a physical device or API.
The [openHAB wiki](https://github.com/openhab/openhab/wiki) gives a nice examples of how this looks:
```java
@ -473,21 +475,21 @@ String Error_Ventilation "Error in Ventilation %s" { comfoair="error_mes
Number DiningRoomTemp "Maximum Away Temp. [%.1f °F]" { nest="<[thermostats(Dining Room).away_temperature_high_f]" }
```
Every binding came up with its own syntax for this binding configuration and while the rest of the item file had nice syntax checks and content assist when using Designer, this wasn't possible to provide for the binding configurations themselves.
The only way for the user to figure out what to put in there was to visit the wiki page of the binding.
Every binding came up with its own syntax for this binding configuration and while the rest of the item file had nice syntax checks and content assist when using Designer, this wasn't possible to provide for the binding configurations themselves.
The only way for the user to figure out what to put in there was to visit the wiki page of the binding.
This not only are syntax errors and typos difficult to detest but it also prevents any "automated" editing of the binding configurations, e.g. through user-friendly UIs.
Besides the syntax, the old scheme leaves the binding developers the choice to implement multi-instance support or not.
Usually most bindings started off supporting a single instance only to notice later on that it would be useful to add support for more than one.
For example, you can see in the KNX binding configuration above that it simply does not allow one to select an interface (KNX system) to use for that Item.
Besides the syntax, the old scheme leaves the binding developers the choice to implement multi-instance support or not.
Usually most bindings started off supporting a single instance only to notice later on that it would be useful to add support for more than one.
For example, you can see in the KNX binding configuration above that it simply does not allow one to select an interface (KNX system) to use for that Item.
Instead, a single globally configured connection is defined in the openhab.cfg file.
These issues were identified [a long time ago](https://groups.google.com/d/msg/openhab/NSiveF9U1vk/PVLemrdrpVsJ) and the concept of [Things and Channels](https://www.eclipse.org/forums/index.php/t/668424/) were introduced to solve them.
The general idea is to standardize the binding configuration and move it away from the .items file.
A Thing represents a configurable device/system/unit, which provides different functionality through a set of one or more Channels.
These issues were identified [a long time ago](https://groups.google.com/d/msg/openhab/NSiveF9U1vk/PVLemrdrpVsJ) and the concept of [Things and Channels](https://www.eclipse.org/forums/index.php/t/668424/) were introduced to solve them.
The general idea is to standardize the binding configuration and move it away from the .items file.
A Thing represents a configurable device/system/unit, which provides different functionality through a set of one or more Channels.
Each Channel corresponds exactly to one binding configuration string (stuff in { }) in openHAB 1.x.
Let's look at a concrete example.
Let's look at a concrete example.
The [Network Binding](addons/bindings/network) (the impoved binding to the OH1 Network Health binding) supports exactly one Thing which takes one parameter: the IP number of the device on the network.
Thus, as described in the Binding's readme one would manually define a Thing in a .things file (located in conf/things) with the line (this can also be achieved through the PaperUI:
@ -518,10 +520,10 @@ As you can see, the Channel ID consists of the Thing's name, and the Channel nam
For manually defined Things, you can find the syntax for defining a Thing on a given Item in that Binding's readme.
However, with the concept of Things some openHAB 2 bindings are able to automatically discover and create Things for you.
These automatically created Things will appear in your Inbox which you can access in PaperUI, Habmin, or the Karaf console.
These Things can be accepted by the user.
When you view these Things in one of the admin UIs it will list all of the supported Channels the Thing supports.
However, with the concept of Things some openHAB 2 bindings are able to automatically discover and create Things for you.
These automatically created Things will appear in your Inbox which you can access in PaperUI, Habmin, or the Karaf console.
These Things can be accepted by the user.
When you view these Things in one of the admin UIs it will list all of the supported Channels the Thing supports.
To define an Item for one of these Channels, simply copy the Channel ID into your Item's definition like the above.
Finally, I will reiterate, Things and Channels only exist for 2.0 version bindings.
@ -529,7 +531,7 @@ Any 1.9 bindings still use the traditional binding configuration as described on
## Retire openHAB 1.x
Now that you have a fully running and tested openHAB 2 instance, now is the time to disable and remove openHAB 1.x.
Now that you have a fully running and tested openHAB 2 instance, now is the time to disable and remove openHAB 1.x.
Stop openHAB 1.x if it is running:
```bash
@ -557,13 +559,13 @@ As mentioned above, openHAB Designer is no longer recommended or supported. Ther
### myopenHAB.org
There is no 1.x My.openHAB binding that is compatible with openHAB 2, only a native 2.0 openHAB Cloud Connector binding.
Furthermore, one can have only one openHAB instance linked to a http://myopenhab.org account at a time.
There is no 1.x My.openHAB binding that is compatible with openHAB 2, only a native 2.0 openHAB Cloud Connector binding.
Furthermore, one can have only one openHAB instance linked to a http://myopenhab.org account at a time.
This is why we have saved migrating this binding until now.
Each openHAB instance generates its own unique UUID and Secret so one cannot simply copy these files from your old openHAB 1.x installation.
Using your preferred method for add-on installation (see above) install the openHAB Cloud Connector binding (Misc tab in PaperUI).
Using your preferred method for add-on installation (see above) install the openHAB Cloud Connector binding (Misc tab in PaperUI).
Once installed a new `uuid` and `secret` file will be created.
These two files are located in a different place in openHAB 2: `$OPENHAB_CONF/uuid` and `$OPENHAB_CONF/myopenhab/secret`.
@ -571,28 +573,28 @@ Log into your myopenHAB account and select "Account" from the pull down menu und
![myopenHAB Account Menu](images/myopenhab-account.png)
Copy the contents of the `uuid` file into the openHAB UUID field.
Copy the contents of the `uuid` file into the openHAB UUID field.
Copy the contents of the `secret` file into the openHAB Secret field.
You may need to restart openHAB at this point to get the binding to reconnect.
You may need to restart openHAB at this point to get the binding to reconnect.
It should now show your system as being online and running openHAB 2.
![myopenHAB Account Menu](images/myopenhab-connected.png)
### Other Bindings
One is not required to use 2.x version addi-ons with openHAB 2.
It is highly recommended to do so as most cases where there is a 1.x and a 2.x add-on, only the 2.x binding is undergoing continued development.
One is not required to use 2.x version addi-ons with openHAB 2.
It is highly recommended to do so as most cases where there is a 1.x and a 2.x add-on, only the 2.x binding is undergoing continued development.
On-the-other-hand, some of the 2.x bindings work significantly differently from their 1.x versions. See the [add-on's 1.x](https://github.com/openhab/openhab1-addons/wiki) and [openHAB 2 addons](/addons/#bindings) to compare and contrast the two versions.
Identify an add-on where there is a 2.x version that you want to migrate to.
Begin by identifying those Items that use this binding.
Identify an add-on where there is a 2.x version that you want to migrate to.
Begin by identifying those Items that use this binding.
On Linux/OSX this can easily be done with the following command
```bash
grep <binding> $OPENHAB_CONF/items/*
```
where `<binding>` is the string used in the binding config on the Item.
where `<binding>` is the string used in the binding config on the Item.
For example:
```bash
@ -602,21 +604,21 @@ grep astro /opt/openhab2/conf/items/*
Now comment out those Items to ensure there are no unexpected interactions between the old configurations and the new ones.
Next uninstall the 1.x binding.
In the Karaf console use the command `feature:uninstall <add-on name>`.
If you used addons.cfg to install the addons you must uninstall it using the Karaf console.
Next uninstall the 1.x binding.
In the Karaf console use the command `feature:uninstall <add-on name>`.
If you used addons.cfg to install the addons you must uninstall it using the Karaf console.
In PaperUI, browse to the add-on and choose uninstall.
Move the add-on's .cfg file to a backup location.
Move the add-on's .cfg file to a backup location.
Some bindings have significantly changed their configurations but much of the old information will still be relevant.
Install the 2.0 version of the add-on using your preferred method as described above.
Install the 2.0 version of the add-on using your preferred method as described above.
If this is the zwave binding, install the Habmin UI at this time as well if you have not done so already.
Configure the add-on as described in the add-on's readme file.
Once it is properly configured and if the binding supports automatic Thing discovery, new Things will start to slowly appear in the Inbox.
If left on its own this process can take five minutes to an hour.
However, one can press the scan button in PaperUI -> Inbox to speed this up.
Configure the add-on as described in the add-on's readme file.
Once it is properly configured and if the binding supports automatic Thing discovery, new Things will start to slowly appear in the Inbox.
If left on its own this process can take five minutes to an hour.
However, one can press the scan button in PaperUI -> Inbox to speed this up.
Or from the Karaf console one can run:
```bash
@ -627,8 +629,8 @@ smarthome:discovery openhab-binding-<binding name>
### Managing the Inbox using PaperUI
In PaperUI, review the Items in the Inbox and accept those that should be included in your configuration.
You can press the eye icon to hide the Thing from the list if you never plan on including it, such as a dead zwave node.
In PaperUI, review the Items in the Inbox and accept those that should be included in your configuration.
You can press the eye icon to hide the Thing from the list if you never plan on including it, such as a dead zwave node.
Once approved browsing to the Configuration -> Things menus and selecting the Thing from the list one can get the list of Channel IDs for that Thing.
### Managing the Inbox Using the Karaf Console
@ -641,8 +643,10 @@ smarthome:inbox
![Karaf console inbox listing](images/karaf-inbox.png)
NOTE: The screenshot above shows Ignored Inbox Items.
::: tip Note
The screenshot above shows Ignored Inbox Items.
New Items will not show "IGNORED".
:::
To accept a Thing from the Inbox run:
@ -670,11 +674,11 @@ smarthome:inbox ignore <thingId>
### Linking Channels to Items
There is more than one way to link Channels to Items using PaperUI, Karaf console, and through the text configuration files.
There is more than one way to link Channels to Items using PaperUI, Karaf console, and through the text configuration files.
Only the text configuration files are covered here as they are closer to the openHAB 1.x way of doing things and will cause the least amount of work to migrate.
Open your .items files where you commented out the Items that used the old version of the binding.
Replace the old binding's configuration with the Channel ID that Item represents.
Open your .items files where you commented out the Items that used the old version of the binding.
Replace the old binding's configuration with the Channel ID that Item represents.
For example:
```java
@ -687,18 +691,18 @@ becomes
Switch S_L_Family "Family Room Lamp" <light> {channel="zwave:device:528f7aca:node10:switch_binary"}
```
Congratulations, you are now using the 2.x version of the binding.
Assuming the behaviors of the binding are the same, there should be no required changes to your Rules, Sitemaps, or Persitence.
Congratulations, you are now using the 2.x version of the binding.
Assuming the behaviors of the binding are the same, there should be no required changes to your Rules, Sitemaps, or Persitence.
Test your Items each step of the way to verify they are working.
### Manually Creating Things
Not all 2.0 bindings support automatic discovery of Things or by their very nature require manual creation of Things.
As with linking Channels to Items, there is more than one way to do this including through PaperUI, Habmin, the REST API, or through text files.
Not all 2.0 bindings support automatic discovery of Things or by their very nature require manual creation of Things.
As with linking Channels to Items, there is more than one way to do this including through PaperUI, Habmin, the REST API, or through text files.
This tutorial will only cover creating Things in text files as that will be closer to the openHAB 1.x way of doing things.
All definitions of new Things are written to .things files in the `$OPENHAB_CONF/things` folder.
The syntax for a Thing definition varies from binding to binding.
See the binding's readme for the specific format and parameters required.
Also see the binding's readme for the list of channels the Thing supports.
All definitions of new Things are written to .things files in the `$OPENHAB_CONF/things` folder.
The syntax for a Thing definition varies from binding to binding.
See the binding's readme for the specific format and parameters required.
Also see the binding's readme for the list of channels the Thing supports.
As discussed above, the Channel ID will be the `<Thing ID>#<channel>`.