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

OH3 preparations (1/x) (#1305) 

* Replace esh namespace with org.openhab in several locations

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

* Add armbian warning.

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

* Adress needed installation/index changes

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

* Adress needed installation/rasppi changes

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

* Adress needed installation/docker changes

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

* Additional improvements for the linux article.

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

* Additional improvements for the linux article.

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

* Additional improvements for the linux article.

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

* Additional improvements and renamings.

Signed-off-by: Jerome Luckenbach <github@luckenba.ch>
pull/1307/head
Jerome Luckenbach 2020-12-12 12:27:08 +01:00 committed by GitHub
parent d10a909c9c
commit ab36fb90f4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
15 changed files with 298 additions and 298 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
administration/jsondb.md
View File

@ -86,11 +86,11 @@ Within the `OPENHAB_USERDATA/jsondb/` directory, you will find the following fil
| Filename | _Contents_ |
|-----------------------------------------------------------------|---------------------------------------|
| org.eclipse.smarthome.config.discovery.**DiscoveryResult.json** | _Results of Paper UI Discovery_ |
| org.eclipse.smarthome.core.items.**Item.json** | _Items configurations_ |
| org.eclipse.smarthome.core.thing.link.**ItemChannelLink.json** | _Item to Channel Link configurations_ |
| org.eclipse.smarthome.core.thing.link.**ItemThingLink.json** | _Item to Thing Link configurations_ |
| org.eclipse.smarthome.core.thing.**Thing.json** | _Things configurations_ |
| org.openhab.config.discovery.**DiscoveryResult.json** | _Results of Paper UI Discovery_ |
| org.openhab.core.items.**Item.json** | _Items configurations_ |
| org.openhab.core.thing.link.**ItemChannelLink.json** | _Item to Channel Link configurations_ |
| org.openhab.core.thing.link.**ItemThingLink.json** | _Item to Thing Link configurations_ |
| org.openhab.core.thing.**Thing.json** | _Things configurations_ |
## Example Use
@ -100,13 +100,13 @@ In this example, we will use the Network Binding (2.0) to Search for Things, add
Step 1. Add new Thing (name: `ISP_Gateway`) from Paper UIs Inbox:
![Add_Thing_Paper_UI](./images/add_thing_paper_ui.png)
Step 2. Check the contents of the `OPENHAB_USERDATA/jsondb/org.eclipse.smarthome.core.thing.Thing.json` file:
Step 2. Check the contents of the `OPENHAB_USERDATA/jsondb/org.openhab.core.thing.Thing.json` file:
```
root@rpi3:~# more /var/lib/openhab2/jsondb/org.eclipse.smarthome.core.thing.Thing.json
root@rpi3:~# more /var/lib/openhab2/jsondb/org.openhab.core.thing.Thing.json
{
"network:device:172_16_13_254": {
"class": "org.eclipse.smarthome.core.thing.internal.ThingImpl",
"class": "org.openhab.core.thing.internal.ThingImpl",
"value": {
"label": "ISP_Gateway",
"channels": [
@ -194,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.openhab.core.thing.Thing.json` file:
![New_Json](./images/new_json_file.png)

18
administration/logging.md
View File

@ -52,7 +52,7 @@ openhab> log:tail
A useful functionality is that filters can be applied:
```
openhab> log:tail org.eclipse.smarthome.io.rest.core.item.ItemResource
openhab> log:tail org.openhab.io.rest.core.item.ItemResource
20:36:52.879 [DEBUG] [thome.io.rest.core.item.ItemResource] - Received HTTP POST request at 'items/Light_FF_Bath_Ceiling' with value 'ON'.
20:36:53.545 [DEBUG] [thome.io.rest.core.item.ItemResource] - Received HTTP POST request at 'items/Light_FF_Bath_Ceiling' with value 'OFF'.
```
@ -142,7 +142,7 @@ logInfo("heating-control.rules", "This is a log entry of type Info!")
logDebug("heating-control.rules", "This is a log entry of type Debug!")
```
The main package of all script/rules based log entries is predefined as `org.eclipse.smarthome.model.script`.
The main package of all script/rules based log entries is predefined as `org.openhab.model.script`.
The chosen subpackage is appended to the end of the main package.
It can be useful for filtering or package-based log level settings.
@ -233,7 +233,7 @@ The configuration file for openHAB is placed in the [openhab-distro/lauch/home/l
<!-- We have removed part of the original file in this example -->
...
<logger name="smarthome.event" level="INFO" additivity="false">
<!-- The element <logger> may contain zero or more <appender-ref> elements -->
<appender-ref ref="EVENTFILE" />
@ -243,7 +243,7 @@ The configuration file for openHAB is placed in the [openhab-distro/lauch/home/l
<!-- Logback uses inheritance to determine the log level.
If a given logger is NOT assigned a level it inherits one from the its closest ancestor -->
<logger name="org.openhab" level="DEBUG" />
<logger name="org.eclipse.smarthome" level="DEBUG" />
<logger name="org.openhab" level="DEBUG" />
<logger name="org.eclipse.jetty" level="INFO" />
<logger name="org.jupnp" level="ERROR"/>
@ -252,16 +252,16 @@ The configuration file for openHAB is placed in the [openhab-distro/lauch/home/l
<logger name="javax.jmdns.impl.constants" level="OFF"/>
<logger name="tuwien.auto.calimero" level="WARN" />
<!-- The root logger is at the top of the logger hierarchy.
All loggers inherit its level, if there are no ancestors
between the root and the logger -->
<!-- The root logger is at the top of the logger hierarchy.
All loggers inherit its level, if there are no ancestors
between the root and the logger -->
<root level="INFO">
<appender-ref ref="FILE" />
<appender-ref ref="STDOUT" />
</root>
<logger name="OSGi" level="OFF" />
</configuration>
```
@ -300,7 +300,7 @@ The process of redirecting the log to a text file is as simple as :
- adding a new `FileAppender` and specifying the path of the output file:
```xml
```xml
<appender name="YOUR_APPENDER_NAME" class="ch.qos.logback.core.FileAppender">
<file>relative/path/to/file.log</file>
<encoder>

18
concepts/discovery.md
View File

@ -14,27 +14,27 @@ openHAB bindings therefore implement _Discovery Services_ for Things, which prov
### Background Discovery
Some discovery services support automatic discovery in the background, while for others a scan needs to be triggered manually.
Services that support background discovery usually have it enabled by default.
Services that support background discovery usually have it enabled by default.
It is possible to override this setting and deactivate background discovery for individual services by setting `discovery.<serviceid>:background=false`, where `serviceid` is usually identical to a binding id, e.g. the LIFX background discovery can be disabled through `discovery.lifx:background=false`.
## Inbox
The inbox holds a list of all discovered Things (`DiscoveryResult`) from all active discovery services.
A discovery result represents a discovered Thing of a specific Thing type, that could be instantiated as a Thing.
The result usually contains properties that identify the discovered Things further like IP address or a serial number.
Each discovery result also has a timestamp when it was added to or updated in the inbox and it may also contain a time to live, indicating the time after which it is be automatically removed from the inbox.
The inbox holds a list of all discovered Things (`DiscoveryResult`) from all active discovery services.
A discovery result represents a discovered Thing of a specific Thing type, that could be instantiated as a Thing.
The result usually contains properties that identify the discovered Things further like IP address or a serial number.
Each discovery result also has a timestamp when it was added to or updated in the inbox and it may also contain a time to live, indicating the time after which it is be automatically removed from the inbox.
Discovery results can either be ignored or approved, where in the latter case a Thing is created for them and they become available in the application.
If an entry is ignored, it will be hidden in the inbox without creating a Thing for it.
Discovery results can either be ignored or approved, where in the latter case a Thing is created for them and they become available in the application.
If an entry is ignored, it will be hidden in the inbox without creating a Thing for it.
openHAB offers a service to automatically ignore duplicate discovery results in the inbox whenever, a) a Thing has been created manually, that represents the same Thing as the respective discovery result would create, or b) whenever a Thing has been discovered separately by two alternate discovery services.
Such duplicate Things are identified as either Things with the same Thing UID, or Things with an identical `representation property`.
For a manually created Thing, its representation property is either a `property` or a `configuration parameter` of the Thing.
This auto-ignore service is enabled by default but can be disabled by setting `org.eclipse.smarthome.inbox:autoIgnore=false`.
This auto-ignore service is enabled by default but can be disabled by setting `org.openhab.inbox:autoIgnore=false`.
### Auto Approve
If the manual acceptance of discovery results by the user is not desired, it is possible to turn on the auto-approval feature of the inbox.
In this case, every new entry gets automatically approved immediately (unless it has been marked as ignored as a duplicate).
The auto approval can be enabled by the setting `org.eclipse.smarthome.inbox:autoApprove=true`; the default is false.
The auto approval can be enabled by the setting `org.openhab.inbox:autoApprove=true`; the default is false.

28
concepts/units-of-measurement.md
View File

@ -8,27 +8,27 @@ title: Units Of Measurement
# Units Of Measurement
To express measured values in a scientific correct unit the framework supports units of measurement.
By using quantified decimal values in state updates and commands, the framework is able to automatically convert values to a desired unit which may be defined by the system locale or on a per-use-basis.
By using quantified decimal values in state updates and commands, the framework is able to automatically convert values to a desired unit which may be defined by the system locale or on a per-use-basis.
## QuantityType
## QuantityType
Bindings use the `QuantityType` to post updates of sensor data with a quantifying unit.
Bindings use the `QuantityType` to post updates of sensor data with a quantifying unit.
This way the framework and/or the user is able to convert the quantified value to other matching units:
A weather binding which reads temperature values in °C would use the `QuantityType` to indicate the unit as °C.
The framework is then able to convert the values to either °F or Kelvin according to the configuration of the system.
The default conversion the framework will use is locale-based:
The framework tries to convert a `QuantityType` to the default unit of the configured locale.
This is the imperial system for the United States (locale US) and Liberia (language tag "en-LR").
The metric system with SI units is used for the rest of the world.
This conversion will convert the given `QuantityType` into a default unit for the specific dimension of the type.
This is the imperial system for the United States (locale US) and Liberia (language tag "en-LR").
The metric system with SI units is used for the rest of the world.
This conversion will convert the given `QuantityType` into a default unit for the specific dimension of the type.
This is:
| Dimension | default unit metric | default unit imperial |
|---------------|----------------------------|------------------------|
| Length | Meter (m) | Inch (in) |
| Temperature | Celsius (°C) | Fahrenheit (°F) |
| Pressure | Hectopascal (hPa) | Inch of mercury (inHg) |
| Pressure | Hectopascal (hPa) | Inch of mercury (inHg) |
| Speed | Kilometers per hour (km/h) | Miles per hour (mph) |
| Intensity | Irradiance (W/m2) | Irradiance (W/m2) |
| Dimensionless | Abstract unit one (one) | Abstract unit one (one)|
@ -36,23 +36,23 @@ This is:
## NumberItem linked to QuantityType Channel
In addition to the automated conversion the `NumberItem` linked to a Channel delivering `QuantityTypes` can be configured to always have state updates converted to a specific unit.
In addition to the automated conversion the `NumberItem` linked to a Channel delivering `QuantityTypes` can be configured to always have state updates converted to a specific unit.
The unit given in the state description is parsed and then used for conversion (if necessary).
The framework assumes that the unit to parse is always the last token in the state description.
If the parsing failed the locale-based default conversion takes place.
Number:Temperature temperature "Outside [%.2f °F]" { channel="...:current#temperature" }
In the example the `NumberItem` is specified to bind to Channels which offer values from the dimension `Temperature`.
Without the dimension information the `NumberItem` only will receive updates of type `DecimalType` without a unit and any conversion.
The state description defines two decimal places for the value and the fix unit °F.
In case the state description should display the unit the binding delivers or the framework calculates through locale-based conversion the pattern will look like this:
"Outside [%.2f %unit%]"
The special placeholder `%unit%` will then be replaced by the actual unit symbol.
The placeholder `%unit%` can be placed anywhere in the state description.
#### Defining ChannelTypes
In order to match `NumberItems` and Channels and define a default state description with unit placeholder the Channel also has to provide an Item type which includes the dimension information:
@ -69,11 +69,11 @@ The state description pattern "%.1f %unit%" describes the value format as floati
## Implementing UoM
When creating QuantityType states the framework offers some useful packages and classes:
The `org.eclipse.smarthome.core.library.unit` package contains the classes `SIUnits`, `ImperialUnits` and `SmartHomeUnits` which provide units unique to either of the measurement systems and common units used in both systems.
The `org.openhab.core.library.unit` package contains the classes `SIUnits`, `ImperialUnits` and `SmartHomeUnits` which provide units unique to either of the measurement systems and common units used in both systems.
The `MetricPrefix` class provides prefixes like MILLI, CENTI, HECTO, etc. and the `BinaryPrefix` class provides prefixes like KIBI, MEBI, etc. both of which are wrappers to create derived units.
The `org.eclipse.smarthome.core.library.dimension` and `javax.measure.quantity` packages provide interfaces which are used to type the generic QuantityType and units.
The `org.openhab.core.library.dimension` and `javax.measure.quantity` packages provide interfaces which are used to type the generic QuantityType and units.
## List of Units

82
configuration/jsr223.md
View File

@ -93,7 +93,7 @@ automationManager.addRule(sRule)
```groovy
import org.openhab.core.automation.*
import org.openhab.core.automation.module.script.rulesupport.shared.simple.*
import org.eclipse.smarthome.config.core.Configuration
import org.openhab.config.core.Configuration
scriptExtension.importPreset("RuleSupport")
scriptExtension.importPreset("RuleSimple")
@ -162,63 +162,63 @@ The `default` preset is preloaded, so it does not require importing.
|----------|-------------|
| `DateTime` | `org.joda.time.DateTime` (if Jodatime is available) |
| `LocalTime` | `org.joda.time.LocalTime` (if Jodatime is available) |
| `State` | `org.eclipse.smarthome.core.types.State` |
| `Command` | `org.eclipse.smarthome.core.types.State` |
| `State` | `org.openhab.core.types.State` |
| `Command` | `org.openhab.core.types.State` |
| `StringUtils` | `org.apache.commons.lang.StringUtils` |
| `URLEncoder` | `java.net.URLEncoder` |
| `FileUtils` | `org.apache.commons.io.FileUtils` |
| `FilenameUtils` | `org.apache.commons.io.FilenameUtils` |
| `File` | `java.io.File` |
| `IncreaseDecreaseType` | `org.eclipse.smarthome.core.library.types.IncreaseDecreaseType` |
| `IncreaseDecreaseType` | `org.openhab.core.library.types.IncreaseDecreaseType` |
| `DECREASE` | `IncreaseDecreaseType` enum item |
| `INCREASE` | `IncreaseDecreaseType` enum item |
| `OnOffType` | `org.eclipse.smarthome.core.library.types.OnOffType` |
| `OnOffType` | `org.openhab.core.library.types.OnOffType` |
| `ON` | `OnOffType` enum item |
| `OFF` | `OnOffType` enum item |
| `OpenClosedType` | `org.eclipse.smarthome.core.library.types.OpenClosedType` |
| `OpenClosedType` | `org.openhab.core.library.types.OpenClosedType` |
| `OPEN` | `OpenClosedType` enum item |
| `CLOSED` | `OpenClosedType` enum item |
| `StopMoveType` | `org.eclipse.smarthome.core.library.types.StopMoveType` |
| `StopMoveType` | `org.openhab.core.library.types.StopMoveType` |
| `STOP` | `StopMoveType` enum item |
| `MOVE` | `StopMoveType` enum item |
| `UpDownType` | `org.eclipse.smarthome.core.library.types.UpDownType` |
| `UpDownType` | `org.openhab.core.library.types.UpDownType` |
| `UP` | `UpDownType` enum item |
| `DOWN` | `UpDownType` enum item |
| `UnDefType` | `org.eclipse.smarthome.core.library.types.UnDefType` |
| `UnDefType` | `org.openhab.core.library.types.UnDefType` |
| `NULL` | `UnDefType` enum item |
| `UNDEF` | `UnDefType` enum item |
| `RefreshType` | `org.eclipse.smarthome.core.library.types.RefreshType` |
| `RefreshType` | `org.openhab.core.library.types.RefreshType` |
| `REFRESH` | `RefreshType` enum item |
| `NextPreviousType` | `org.eclipse.smarthome.core.library.types.NextPreviusType` |
| `NextPreviousType` | `org.openhab.core.library.types.NextPreviusType` |
| `NEXT` | `NextPreviousType` enum item |
| `PREVIOUS` | `NextPreviousType` enum item |
| `PlayPauseType` | `org.eclipse.smarthome.core.library.types.PlayPauseType` |
| `PlayPauseType` | `org.openhab.core.library.types.PlayPauseType` |
| `PLAY` | `PlayPauseType` enum item |
| `PAUSE` | `PlayPauseType` enum item |
| `RewindFastforwardType` | `org.eclipse.smarthome.core.library.types.RewindFastforwardType` |
| `RewindFastforwardType` | `org.openhab.core.library.types.RewindFastforwardType` |
| `REWIND` | `RewindFastforwardType` enum item |
| `FASTFORWARD` | `RewindFastforwardType` enum item |
| `QuantityType` | `org.eclipse.smarthome.core.library.types.QuantityType` |
| `StringListType` | `org.eclipse.smarthome.core.library.types.StringListType` |
| `RawType` | `org.eclipse.smarthome.core.library.types.RawType` |
| `DateTimeType` | `org.eclipse.smarthome.core.library.types.DateTimeType` |
| `DecimalType` | `org.eclipse.smarthome.core.library.types.DecimalType` |
| `HSBType` | `org.eclipse.smarthome.core.library.types.HSBType` |
| `PercentType` | `org.eclipse.smarthome.core.library.types.PercentType` |
| `PointType` | `org.eclipse.smarthome.core.library.types.PointType` |
| `StringType` | `org.eclipse.smarthome.core.library.types.StringType` |
| `SIUnits` | `org.eclipse.smarthome.core.library.unit.SIUnits` |
| `ImperialUnits` | `org.eclipse.smarthome.core.library.unit.SmartHomeUnits` |
| `MetricPrefix` | `org.eclipse.smarthome.core.library.unit.SmartHomeUnits` |
| `SmartHomeUnits` | `org.eclipse.smarthome.core.library.unit.SmartHomeUnits` |
| `BinaryPrefix` | `org.eclipse.smarthome.core.library.unit.SmartHomeUnits` |
| `items` | Instance of `java.util.Map&lt;String, State&gt;` |
| `QuantityType` | `org.openhab.core.library.types.QuantityType` |
| `StringListType` | `org.openhab.core.library.types.StringListType` |
| `RawType` | `org.openhab.core.library.types.RawType` |
| `DateTimeType` | `org.openhab.core.library.types.DateTimeType` |
| `DecimalType` | `org.openhab.core.library.types.DecimalType` |
| `HSBType` | `org.openhab.core.library.types.HSBType` |
| `PercentType` | `org.openhab.core.library.types.PercentType` |
| `PointType` | `org.openhab.core.library.types.PointType` |
| `StringType` | `org.openhab.core.library.types.StringType` |
| `SIUnits` | `org.openhab.core.library.unit.SIUnits` |
| `ImperialUnits` | `org.openhab.core.library.unit.SmartHomeUnits` |
| `MetricPrefix` | `org.openhab.core.library.unit.SmartHomeUnits` |
| `SmartHomeUnits` | `org.openhab.core.library.unit.SmartHomeUnits` |
| `BinaryPrefix` | `org.openhab.core.library.unit.SmartHomeUnits` |
| `items` | Instance of `java.util.Map&lt;String, State&gt;` |
| `ir` | Alias for `itemRegistry` |
| `itemRegistry` | Instance of `org.eclipse.smarthome.core.items.ItemRegistry` |
| `things` | Instance of `org.eclipse.smarthome.core.thing.ThingRegistry` |
| `itemRegistry` | Instance of `org.openhab.core.items.ItemRegistry` |
| `things` | Instance of `org.openhab.core.thing.ThingRegistry` |
| `rules` | Instance of `org.openhab.core.automation.RuleRegistry` |
| `events` | (internal) Used to send events, post commands, etc. [Details](#event_operations) below] |
| `actions` | Instance of `org.eclipse.smarthome.core.thing.binding.ThingActions` |
| `actions` | Instance of `org.openhab.core.thing.binding.ThingActions` |
| `scriptExtension` | (internal) For loading script presets. |
| `se` | Alias for `scriptExtension` |
@ -253,7 +253,7 @@ See language-specific documentation for examples.
| Variable | Description |
|----------|-------------|
| ActionType | `org.openhab.core.automation.type.ActionType` |
| ConfigDescriptionParameter | `org.eclipse.smarthome.config.core.ConfigDescriptionParameter` |
| ConfigDescriptionParameter | `org.openhab.config.core.ConfigDescriptionParameter` |
| ModuleType | `org.openhab.core.automation.type.ModuleType` |
| SimpleActionHandler | `org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleActionHandler` |
| SimpleConditionHandler | `org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleConditionHandler` |
@ -274,17 +274,17 @@ scriptExtension.importPreset("RuleSupport")
| Variable | Description |
|----------|-------------|
| Action | `org.openhab.core.automation.Action` |
| ActionBuilder | `org.openhab.core.automation.ActionBuilder` |
| Condition | `org.openhab.core.automation.Condition` |
| ConditionBuilder | `org.openhab.core.automation.ConditionBuilder` |
| Configuration | `org.eclipse.smarthome.config.core.Configuration` |
| ModuleBuilder | `org.openhab.core.automation.ModuleBuilder` |
| Rule | `org.openhab.core.automation.Rule` (use `SimpleRule` for defining rules) |
| Action | `org.openhab.core.automation.Action` |
| ActionBuilder | `org.openhab.core.automation.ActionBuilder` |
| Condition | `org.openhab.core.automation.Condition` |
| ConditionBuilder | `org.openhab.core.automation.ConditionBuilder` |
| Configuration | `org.openhab.config.core.Configuration` |
| ModuleBuilder | `org.openhab.core.automation.ModuleBuilder` |
| Rule | `org.openhab.core.automation.Rule` (use `SimpleRule` for defining rules) |
| Trigger | `org.openhab.core.automation.Trigger` |
| TriggerBuilder | `org.openhab.core.automation.TriggerBuilder` |
| TriggerBuilder | `org.openhab.core.automation.TriggerBuilder` |
| automationManager | Instance for managing rules and other openHAB module instances. (e.g., `addRule`) |
| ruleRegistry | `org.openhab.core.automation.Rule` |
| ruleRegistry | `org.openhab.core.automation.Rule` |
<a name="rulefactories_presets"></a>

32
configuration/restdocs.md
View File

@ -7,12 +7,12 @@ title: openHAB REST API
# openHAB REST API
Through the openHAB [REST API](https://en.wikipedia.org/wiki/REST_API) most aspects of the openHAB system can be readily accessed by other programs.
This includes for example, the access to all data related to Items, Things and Bindings as well as the capabilities to invoke actions that can change the state of Items or influence the behavior of other elements of openHAB.
Interactions with the REST API are based on the http protocol.
Access over the Internet to the REST API is possible, but this represents a significant security risk.
Users are encouraged to [ensure safe and secure connections](http://docs.openhab.org/installation/security.html).
Be aware that the documentation of the REST API may not be automatically installed, but once installed it is accessible through the openHAB dashboard.
Through the openHAB [REST API](https://en.wikipedia.org/wiki/REST_API) most aspects of the openHAB system can be readily accessed by other programs.
This includes for example, the access to all data related to Items, Things and Bindings as well as the capabilities to invoke actions that can change the state of Items or influence the behavior of other elements of openHAB.
Interactions with the REST API are based on the http protocol.
Access over the Internet to the REST API is possible, but this represents a significant security risk.
Users are encouraged to [ensure safe and secure connections](http://docs.openhab.org/installation/security.html).
Be aware that the documentation of the REST API may not be automatically installed, but once installed it is accessible through the openHAB dashboard.
## REST API Examples
@ -25,23 +25,23 @@ Be aware that the documentation of the REST API may not be automatically install
The openHAB REST API is excellently documented with detailled use instructions.
It would vastly exceed this space to present all possible examples.
Nevertheless, here is some examples using [curl](https://en.wikipedia.org/wiki/CURL), a common command line tool available for many platforms:
- Switching ```My_Item``` OFF by issuing an http [POST](https://en.wikipedia.org/wiki/POST_(HTTP)) request:
- Switching ```My_Item``` OFF by issuing an http [POST](https://en.wikipedia.org/wiki/POST_(HTTP)) request:
```java
curl -X POST --header "Content-Type: text/plain" --header "Accept: application/json" -d "OFF" "http://{openHAB_IP}:8080/rest/items/My_Item"
```
```
- Setting a Contact item ```My_Item``` to CLOSED by issuing an http PUT request to ```My_Item/state```:
- Setting a Contact item ```My_Item``` to CLOSED by issuing an http PUT request to ```My_Item/state```:
```java
curl -X PUT --header "Content-Type: text/plain" --header "Accept: application/json" -d "CLOSED" "http://{openHAB_IP}:8080/rest/items/My_Item/state"
```
```
- Retrieving a list of all Items and Groups by issuing a GET request:
- Retrieving a list of all Items and Groups by issuing a GET request:
```java
curl -X GET --header "Accept: application/json" "http://{openHAB_IP}:8080/rest/items?recursive=false"
```
```
- Retrieving a list of all sitemaps by issuing a GET request:
@ -59,7 +59,7 @@ curl "http://{openHAB_IP}:8080/rest/events?topics=smarthome/things/{thingUID}/st
curl "http://{openHAB_IP}:8080/rest/events?topics=smarthome/channels/{channelUID}/triggered"
```
The commands above have been copied from the REST API documentation for illustration.
The commands above have been copied from the REST API documentation for illustration.
## REST API documentation
@ -70,12 +70,12 @@ You will see an addon called "REST Documentation" that can be easily installed.
On the welcome screen of openHAB, you will now see a new interface called "REST API" where you can easily see the documentation of the REST API and test it!
All available commands will be displayed in the REST API documentation as a response to the button "Try me out" (may require some user input for mandatory fields).
All available commands will be displayed in the REST API documentation as a response to the button "Try me out" (may require some user input for mandatory fields).
## Additional Considerations
The REST API also supports server-push supporting subscriptions on change notification for certain resources.
One final remark - when openHAB's REST API is accessed from another domain the following error may be encountered: [No 'Access-Control-Allow-Origin' header is present on the requested resource](https://community.openhab.org/t/cors-problem-at-rest-api/3712/10).
In this case, it may be necessary to add the line `org.eclipse.smarthome.cors:enable=true` in the file `services/runtime.cfg`.
One final remark - when openHAB's REST API is accessed from another domain the following error may be encountered: [No 'Access-Control-Allow-Origin' header is present on the requested resource](https://community.openhab.org/t/cors-problem-at-rest-api/3712/10).
In this case, it may be necessary to add the line `org.openhab.cors:enable=true` in the file `services/runtime.cfg`.

2
configuration/things.md
View File

@ -20,7 +20,7 @@ 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.
::: tip Note
Things are a new concept in openHAB 2, Things definitions are not needed for 1.x bindings.
Things are a new concept in openHAB, Things definitions are not needed for 1.x bindings.
:::
## Defining Things

4
installation/armbian.md
View File

@ -7,6 +7,10 @@ title: Armbian
# Armbian
::: warning
This article may be outdated due to a main version change in openHAB
:::
## What is Armbian?
Armbian is a base operating system platform for single board computers.

12
installation/docker.md
View File

@ -5,7 +5,7 @@ title: Docker
{% include base.html %}
# openHAB 2 inside a Docker Container
# openHAB inside a Docker Container
Docker is the most popular among a collection of tools that provide containerization.
Containerization allows one to run a server in its own isolated environment without the overhead of running a full virtual machine.
@ -39,8 +39,6 @@ This is also set as the home directory of the `openhab` user.
The Image has a very minimal installation of Linux with no services running and just enough installed to allow openHAB to run.
At the time of this writing, the official image uses the latest snapshot version of openHAB 2.
## Installation through Docker
### Obtaining the Official image from DockerHub
@ -124,15 +122,15 @@ To change the runtime parameters stop the container then execute the long comman
Note, always review the README on [Docker Hub](https://hub.docker.com/r/openhab/openhab/) for the most up to date set of recommended arguments and environment variables.
If running on a Systemd based Linux distro (Ubuntu 16.04 to be specific).
The following openhab2.service file will start a new openHAB 2 container every time it starts the service and destroy that container when the service stops.
What that means is any data that you want to preserve between restarts of openHAB 2 (e.g. configuration, databases, etc.) must be mounted from your host file system into the container.
The following openhab2.service file will start a new openHAB container every time it starts the service and destroy that container when the service stops.
What that means is any data that you want to preserve between restarts of openHAB (e.g. configuration, databases, etc.) must be mounted from your host file system into the container.
Creating a new container on every run greatly simplifies the upgrade and update process.
It also ensures that you start with a fresh install every time you run which can avoid some problems.
```bash
[Unit]
Description=openHAB 2
Description=openHAB
Requires=docker.service
After=docker.service
@ -170,7 +168,7 @@ Finally run `sudo systemctl start openhab2.service` to start openHAB running.
Note, always review the README on [Docker Hub](https://hub.docker.com/r/openhab/openhab/) for the most up to date set of recommended arguments and environment variables.
- `/usr/bin/docker run` : create a new container from the passed in Image (last argument)
- `--name=openhab` : give the container a human remember able name
- `--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.
- `--net=host` : by default Docker will place a container into its own network stack. However, openHAB 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)

32
installation/index.md
View File

@ -7,49 +7,54 @@ title: Installation Overview
# Installation Overview
openHAB 2 is fully written in Java.
openHAB is fully written in Java.
As such, it only depends on a Java Virtual Machine, which is available for many platforms.
openHAB can be executed on different versions of **macOS** and **Windows** and many different variants of **Linux** (Ubuntu, Raspbian, ...).
Please be aware of the fact, that openHAB 2 is based on a new core and introduces new concepts.
Therefore, tutorials and help you may find on the internet for openHAB 1 **might** be outdated!
Please be aware of the fact, that openHAB is continously improved and changed.
Therefore, tutorials and help you may find on the internet for **might** be outdated!
Always keep this in mind, when searching for help and solutions.
## Platform Recommendations
1. You are **new to openHAB 2** and want to give it a try? You are in luck:
- Set up openHAB 2 on your local PC or Mac in just a few steps.
1. You are **new to openHAB** and want to give it a try? You are in luck:
- Set up openHAB on your local PC or Mac in just a few steps.
2. You gained some experience and want to use openHAB to seriously control your home?
1. You gained some experience and want to use openHAB to seriously control your home?
Typical hardware and software requirements are:
- **24/7 availability:** A dedicated system connected by Ethernet and running continuously.
- **Energy and space efficient:** A device capable of performing the task at hand without being exaggerated
- **Extendibility:** Your system should be capable of running additional software like an MQTT broker or a persistence and graphing software.
- **Peripherals:** Depending on your home automation hardware, you will need additional peripheral devices such as a WiFi interface or a special USB radio module.
Many devices are suited to host a continuous installation of openHAB 2.
Many devices are suited to host a continuous installation of openHAB.
Experiences with different devices and environments can be found in the [community forum hardware section](https://community.openhab.org/c/hardware/server).
The [Raspberry Pi](rasppi.html) as a minimal sufficient device is quite popular, especially as we offer a quick setup with [openHABian](openhabian.html).
A popular alternative is [our solution for the Synology DiskStation](synology.html), which many users already own in their homes.
The previously mentioned [openHABian](openhabian.html) can also be used to kickstart your openHAB 2 experience on existing Debian/Ubuntu based Linux systems.
The previously mentioned [openHABian](openhabian.html) can also be used to kickstart your openHAB experience on existing Debian/Ubuntu based Linux systems.
Please check the menu to the left for all available options.
## Prerequisites
Make sure that you have an up to date **Java 8** platform installed on your host system.
Make sure that you have an up to date **Java 11** platform installed on your host system.
Zulu is currently the recommended Java platform for openHAB.
[Download](https://www.azul.com/downloads/zulu-community/?&architecture=x86-64-bit&package=jdk#) and [installation](https://docs.azul.com/zulu/zuludocs/ZuluUserGuide/InstallingZulu/InstallationWindowsUsingZuluMSIFile.htm) instructions can be found on Azul Systems' Zulu website.
Oracle Java is also suitable for most configurations but licensing restrictions may apply.
OpenJDK may also be used, but it has some [known limitations](https://community.openhab.org/t/running-openhab-2-on-openjdk/21443/8?u=gatekeeper6838) with openHAB and is not recommended.
::: warning
Please note that higher versions than Java 11 are also not supported at the moment.
:::
| Java Platform | Advantages | Disadvantages |
|---------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Azul Zulu](https://www.azul.com/downloads/) | Completely open source, fully certified Java SE compliant build of OpenJDK, embedded version optimized for ARM devices [available here](https://www.azul.com/downloads/zulu-embedded/) | |
| [Oracle Java](https://java.com/en/) | Full openHAB support on all platforms | [Licensing restrictions](https://blog.takipi.com/running-java-on-docker-youre-breaking-the-law/), manual installation required on many Linux systems: [Ubuntu](https://help.ubuntu.com/community/Java), [Mint](https://community.linuxmint.com/tutorial/view/1091), and [Debian](https://wiki.debian.org/Java/Sun) are some examples |
| [AdoptOpenJDK](https://adoptopenjdk.net) | Open Source JDK backed by many large companies | |
Please download and install the **Java 8** version of the JVM.
Please download and install the **Java 11** version of the JVM.
openHAB 3 will use Java 11 and you *can* go for it with 2.X, too, but be aware that although developers are working hard to make this work, there might be problems with the oldest parts of openHAB such as some of the v1 bindings due to non-backward compatible changes in Java 11.
The **64-bit version** of the JVM is recommended on platforms using a 64-bit OS and an Intel or AMD processor.
@ -57,7 +62,6 @@ The **64-bit version** of the JVM is recommended on platforms using a 64-bit OS
The **32-bit version** of the JVM is recommended on ARM platforms such as the Raspberry Pi.
The 32-bit JVM performs better on the ARM platform. Some add-ons use libraries that do not work with a 64-bit JVM on ARM.
For best compatibility, namely with the openHAB Cloud service [myopenhab.org](https://www.myopenhab.org) and the [Eclipse IoT Marketplace]({{base}}/configuration/eclipseiotmarket.html), the minimum recommended Java 8 revision is "161".
Check your current Java version by opening a command line console and typing `java -version`:
```text
@ -70,7 +74,7 @@ Java HotSpot(TM) Client VM (build 25.121-b13, mixed mode)
Before you can start, two decisions have to be made:
1. openHAB 2 is available as a platform independent archive file or through a package repository:
1. openHAB is available as a platform independent archive file or through a package repository:
- **Manual setup:** Download and extract a platform independent zip archive: [macOS](macos.html), [Windows](windows.html), [Linux](linux.html#manual-installation)
- **Package setup:** Install through a package repository, including automatic updates.
This option is only available for Debian or Ubuntu derivatives and the recommended choice: [Linux (apt/deb)](linux.html#package-repository-installation)
@ -85,7 +89,7 @@ Please follow the instructions in the installation article matching your platfor
## Additional Steps
After you got openHAB 2 set up and running, there are a few additional setup steps you should consider:
After you got openHAB set up and running, there are a few additional setup steps you should consider:
- Configure a network share on your openHAB host device and mount it locally: [Linux Samba Share](linux.html#network-sharing), Windows file sharing, ...
@ -94,7 +98,7 @@ After you got openHAB 2 set up and running, there are a few additional setup ste
## Getting started
With the openHAB 2 distribution up and running, you should now continue with
With the openHAB distribution up and running, you should now continue with
the [Beginner Tutorial]({{base}}/tutorial)
or by working on your own configuration.

192
installation/linux.md
View File

@ -1,13 +1,13 @@
---
layout: documentation
title: openHAB 2 on Linux
title: openHAB on Linux
---
{% include base.html %}
# openHAB 2 on Linux
# openHAB on Linux
The following instructions will guide you through the process of setting up openHAB 2 and recommended packages for both .DEB (Ubuntu, Debian etc.) and .RPM (RedHat, CentOS, Fedora etc.) Linux systems.
The following instructions will guide you through the process of setting up openHAB and recommended packages for both .DEB (Ubuntu, Debian etc.) and .RPM (RedHat, CentOS, Fedora etc.) Linux systems.
All instructions can be executed in a terminal or remotely via SSH connection.
@ -37,12 +37,12 @@ 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).
::: tip Note
Make sure to download Zulu or Java **8**, as openHAB is not yet compatible with Java 9.
Make sure to download Zulu or Java **11**.
:::
## Installation
openHAB 2 can be installed through
openHAB can be installed through
- the openHABian project **(easiest method, ships with the openHABian configuration tool)**
- a package repository (apt, yum)
- manually from file.
@ -68,7 +68,7 @@ Alternatively resort to the [manual installation approach](#manual-installation)
{% include collapsible/body.html %}
First, add the openHAB 2 Bintray repository key to your package manager and allow Apt to use the HTTPS Protocol:
First, add the openHAB Bintray repository key to your package manager and allow Apt to use the HTTPS Protocol:
```shell
wget -qO - 'https://bintray.com/user/downloadSubjectPublicKey?username=openhab' | sudo apt-key add -
@ -81,32 +81,32 @@ Then, you can choose between, *Official (Stable)*, *Beta* or *Snapshot* builds:
The stable builds contain the latest official release with tested features.
Add the **openHAB 2 Stable Repository** to your systems apt sources list:
Add the **openHAB Stable Repository** to your systems apt sources list:
```shell
echo 'deb https://dl.bintray.com/openhab/apt-repo2 stable main' | sudo tee /etc/apt/sources.list.d/openhab2.list
echo 'deb https://dl.bintray.com/openhab/apt-repo2 stable main' | sudo tee /etc/apt/sources.list.d/openhab.list
```
- **Testing Release**
The beta and release candidate builds come out less frequently, but will contain new features that are currently in the testing phase.
Add the **openHAB 2 Beta Repository** to your systems apt sources list:
Add the **openHAB Beta Repository** to your systems apt sources list:
```shell
echo 'deb https://openhab.jfrog.io/openhab/openhab-linuxpkg testing main' | sudo tee /etc/apt/sources.list.d/openhab2.list
echo 'deb https://openhab.jfrog.io/openhab/openhab-linuxpkg testing main' | sudo tee /etc/apt/sources.list.d/openhab.list
```
- **Snapshot Release**
The snapshot build is created [almost daily](https://ci.openhab.org/job/openhab-linuxpkg/), and include the latest changes to the openHAB 2 core and add-ons.
The snapshot build is created [almost daily](https://ci.openhab.org/job/openhab-linuxpkg/), and include the latest changes to the openHAB core and add-ons.
These changes are often unstable, so you should use this branch only for testing or development purposes.
The snapshot repository is hosted in openHAB's [JFrog Artifactory instance](https://www.jfrog.com/Artifactory).
To use it, add the **openHAB 2 Unstable Repository** to your systems apt sources list:
To use it, add the **openHAB Unstable Repository** to your systems apt sources list:
```shell
echo 'deb https://openhab.jfrog.io/openhab/openhab-linuxpkg unstable main' | sudo tee /etc/apt/sources.list.d/openhab2.list
echo 'deb https://openhab.jfrog.io/openhab/openhab-linuxpkg unstable main' | sudo tee /etc/apt/sources.list.d/openhab.list
```
Next, resynchronize the package index:
@ -118,14 +118,14 @@ sudo apt-get update
Now install openHAB with the following command:
```shell
sudo apt-get install openhab2
sudo apt-get install openhab
```
When you choose to install an add-on, openHAB will download it from the internet on request.
If you plan on disconnecting your machine from the internet, then you will want to also install the add-ons package.
```shell
sudo apt-get install openhab2-addons
sudo apt-get install openhab-addons
```
{% include collapsible/item-end.html %}
@ -144,7 +144,7 @@ You may add all three to the same file, but make sure the desired repo is is set
```text
[openHAB-Stable]
name=openHAB 2.x.x Stable
name=openHAB 3.x.x Stable
baseurl=https://dl.bintray.com/openhab/rpm-repo2/stable
gpgcheck=1
gpgkey=https://bintray.com/user/downloadSubjectPublicKey?username=openhab
@ -157,7 +157,7 @@ You may add all three to the same file, but make sure the desired repo is is set
```text
[openHAB-Testing]
name=openHAB 2.x.x Testing
name=openHAB 3.x.x Testing
baseurl=https://openhab.jfrog.io/openhab/openhab-linuxpkg-rpm/testing
gpgcheck=1
gpgkey=https://bintray.com/user/downloadSubjectPublicKey?username=openhab
@ -166,12 +166,12 @@ You may add all three to the same file, but make sure the desired repo is is set
- **Snapshot Release**
The snapshot build is created [almost daily](https://ci.openhab.org/job/openhab-linuxpkg/), and include the latest changes to the openHAB 2 core and add-ons.
The snapshot build is created [almost daily](https://ci.openhab.org/job/openhab-linuxpkg/), and include the latest changes to the openHAB core and add-ons.
These changes are often unstable, so you should use this branch only for testing or development purposes.
```text
[openHAB-Snapshots]
name=openHAB 2.x.x Snapshots
name=openHAB 3.x.x Snapshots
baseurl=https://openhab.jfrog.io/openhab/openhab-linuxpkg-rpm/unstable
gpgcheck=1
gpgkey=https://openhab.jfrog.io/openhab/api/gpg/key/public
@ -181,23 +181,19 @@ You may add all three to the same file, but make sure the desired repo is is set
Now install openHAB with the following command, please note that for systems that support it `dnf` can be used instead of yum:
```shell
sudo yum install openhab2
sudo yum install openhab
```
When you choose to install an add-on, openHAB will download it from the internet on request.
If you plan on disconnecting your machine from the internet, then you will want to also install the add-ons package.
```shell
sudo yum install openhab2-addons
sudo yum install openhab-addons
```
{% include collapsible/item-end.html %}
{% include collapsible/end.html %}
Optionally, you may in addition install the legacy add-ons package `openhab2-addons-legacy`.
This package contains 1.x bindings, for which there is already a 2.x version available.
This might be useful if you're [coming from openHAB 1.x]({{base}}/tutorials/migration.html) for example.
#### Arch Linux
{% include collapsible/body.html %}
@ -238,10 +234,10 @@ Systems based on **sysVinit** (e.g. Ubuntu 14.x, Debian Wheezy and older):
{% include collapsible/body.html %}
```shell
sudo /etc/init.d/openhab2 start
sudo /etc/init.d/openhab2 status
sudo /etc/init.d/openhab start
sudo /etc/init.d/openhab status
sudo update-rc.d openhab2 defaults
sudo update-rc.d openhab defaults
```
{% include collapsible/item-end.html %}
@ -252,11 +248,11 @@ Systems based on **systemd** (e.g. Debian 8, Ubuntu 15.x, Raspbian Jessie and ne
{% include collapsible/body.html %}
```shell
sudo systemctl start openhab2.service
sudo systemctl status openhab2.service
sudo systemctl start openhab.service
sudo systemctl status openhab.service
sudo systemctl daemon-reload
sudo systemctl enable openhab2.service
sudo systemctl enable openhab.service
```
{% include collapsible/item-end.html %}
@ -264,7 +260,7 @@ sudo systemctl enable openhab2.service
The first start may take **up to 15 minutes**, this is a good time to reward yourself with hot coffee or a freshly brewed tea!
You should be able to reach the openHAB 2 Dashboard at [http://openhab-device:8080]() at this point.
You should be able to reach the openHAB Dashboard at [http://openhab-device:8080]() at this point.
If you're new to openHAB, then you should checkout the [beginner's tutorial]({{base}}/tutorials/beginner/1sttimesetup.html)!
![The openHAB 2 Dashboard page](images/Accueil_Openhab_2.png)
@ -283,16 +279,16 @@ Systems based on **sysVinit** (e.g. Ubuntu 14.x, Debian Wheezy and older):
```shell
# Learn about the current service status
sudo /etc/init.d/openhab2 status
sudo /etc/init.d/openhab status
# (Re-)Start openHAB (background service)
sudo /etc/init.d/openhab2 restart
sudo /etc/init.d/openhab restart
# Stop the openHAB background service
sudo /etc/init.d/openhab2 stop
sudo /etc/init.d/openhab stop
# Make openHAB automatically start after booting the Linux host
sudo update-rc.d openhab2 defaults
sudo update-rc.d openhab defaults
```
{% include collapsible/item-end.html %}
@ -304,20 +300,20 @@ Systems based on **systemd** (e.g. Debian 8, Ubuntu 15.x, Raspbian Jessie and ne
```shell
# Learn about the current service status
sudo systemctl status openhab2.service
sudo systemctl status openhab.service
# (Re-)Start openHAB (background service)
sudo systemctl restart openhab2.service
sudo systemctl restart openhab.service
# Stop the openHAB background service
sudo systemctl stop openhab2.service
sudo systemctl stop openhab.service
# Get the service log since the last boot
sudo journalctl -u openhab2.service -b
sudo journalctl -u openhab.service -b
# Make openHAB automatically start after booting the Linux host
sudo systemctl daemon-reload
sudo systemctl enable openhab2.service
sudo systemctl enable openhab.service
```
{% include collapsible/item-end.html %}
@ -370,13 +366,13 @@ To do this, simply select the repo as in the [installation instructions above](#
```shell
sudo apt-get update
apt-cache showpkg openhab2
apt-cache showpkg openhab
```
Once you know which version you want, you can upgrade/downgrade to it by using the `apt-get install openhab2=[version]` command, for example:
Once you know which version you want, you can upgrade/downgrade to it by using the `apt-get install openhab=[version]` command, for example:
```shell
sudo apt-get install openhab2=2.1.0-1
sudo apt-get install openhab=3.0.0
```
{% include collapsible/item-end.html %}
@ -396,13 +392,13 @@ You may want to switch to a different version of openHAB.
To do this, simply select the repo as in the [installation instructions above](#package-repository-installation), then find the version by bringing a list of all versions available to install:
```shell
rpm -q openhab2
rpm -q openhab
```
Once you know which version you want, you can upgrade/downgrade to it by using the `yum install openhab2-[version]` command, for example:
Once you know which version you want, you can upgrade/downgrade to it by using the `yum install openhab-[version]` command, for example:
```shell
sudo yum install openhab2-2.1.0-1
sudo yum install openhab-3.0.0
```
{% include collapsible/item-end.html %}
@ -410,7 +406,7 @@ sudo yum install openhab2-2.1.0-1
#### Uninstall
To uninstall openHAB 2 and get rid of all related files managed by the package manager, make a backup, then uninstall openHAB and remove the repository:
To uninstall openHAB and get rid of all related files managed by the package manager, make a backup, then uninstall openHAB and remove the repository:
{% include collapsible/start.html %}
{% include collapsible/heading.html %}
@ -420,8 +416,8 @@ Apt Based Systems
{% include collapsible/body.html %}
```shell
sudo apt-get purge openhab2*
sudo rm /etc/apt/sources.list.d/openhab2.list
sudo apt-get purge openhab*
sudo rm /etc/apt/sources.list.d/openhab.list
```
{% include collapsible/item-end.html %}
@ -432,7 +428,7 @@ Yum or Dnf Based Systems
{% include collapsible/body.html %}
```shell
sudo yum remove openhab2*
sudo yum remove openhab*
sudo rm /etc/yum.repos.d/openHAB.repo
```
@ -450,50 +446,50 @@ This user will later serve to execute the openHAB runtime with restricted permis
sudo adduser --system --no-create-home --group --disabled-login openhab
```
We are going to download a platform independent archive file and extract it to the path `/opt/openhab2`.
We are going to download a platform independent archive file and extract it to the path `/opt/openhab`.
Choose between the latest Beta release or a Snapshot with all incoming contributions, created daily.
As openHAB 2 is still in an evolving state, the snapshot may be the **preferred choice**.
As openHAB is still in an evolving state, the snapshot may be the **preferred choice**.
- **Official Release**
Download and extract the latest offical stable version of openHAB 2 from [our downloadpage](https://www.openhab.org/download/) to your host:
Download and extract the latest offical stable version of openHAB from [our downloadpage](https://www.openhab.org/download/) to your host:
```shell
cd /tmp
wget -O openhab-download.zip https://bintray.com/... # Insert download link here
sudo unzip openhab-download.zip -d /opt/openhab2
sudo unzip openhab-download.zip -d /opt/openhab
rm openhab-download.zip
```
- **Beta/RC Release**
If available, beta or release candidate builds of openHAB 2 can also be downloaded from [our downloadpage](https://www.openhab.org/download/) and extracted to your host as shown above.
If available, beta or release candidate builds of openHAB can also be downloaded from [our downloadpage](https://www.openhab.org/download/) and extracted to your host as shown above.
- **Snapshot Release**
Download and extract the latest snapshot version of openHAB 2 from [our downloadpage](https://www.openhab.org/download/) to your host. The process is analogue to above.
Download and extract the latest snapshot version of openHAB from [our downloadpage](https://www.openhab.org/download/) to your host. The process is analogue to above.
The extracted openHAB files should belong to the earlier created `openhab` user.
Execute:
```shell
sudo chown -hR openhab:openhab /opt/openhab2
sudo chown -hR openhab:openhab /opt/openhab
```
Everything is ready for a first test run.
**Execute** openHAB and you should be able to reach the openHAB 2 Dashboard at [http://openhab-device:8080]() after a few minutes:
**Execute** openHAB and you should be able to reach the openHAB Dashboard at [http://openhab-device:8080]() after a few minutes:
```shell
# execute as restricted user openhab:
sudo su -s /bin/bash -c '/opt/openhab2/start.sh' openhab
sudo su -s /bin/bash -c '/opt/openhab/start.sh' openhab
```
You will see the openHAB Console in your terminal and can directly interact with it.
Please be aware, that openHAB 2 will need a few minutes so finish the first start, even after the openHAB console is visible.
Let openHAB 2 settle for **around 15 minutes**.
Please be aware, that openHAB will need a few minutes so finish the first start, even after the openHAB console is visible.
Let openHAB settle for **around 15 minutes**.
If the portal is not reachable by then, restart once.
![The openHAB 2 portal page](images/Accueil_Openhab_2.png)
![The openHAB portal page](images/Accueil_Openhab_2.png)
An important downside of the above method is, that openHAB will be terminated, as soon as you close your terminal.
To work around that, a quick solution is, to execute openHAB in a detached [screen](https://www.howtoforge.com/linux_screen) terminal.
@ -504,13 +500,13 @@ A cleaner approach is to create a Linux service.
The following instructions are intended for a Linux init system based on **systemd** (e.g. Debian 8 / Ubuntu 15.x and newer).
This will allow you to register openHAB as a service, so that it runs at startup and automatically restarts if openHAB crashes.
The service will be running with the privileges of the user "openhab" and expects the openHAB files under `/opt/openhab2`.
The service will be running with the privileges of the user "openhab" and expects the openHAB files under `/opt/openhab`.
Create the file `/usr/lib/systemd/system/openhab2.service` with the following content:
Create the file `/usr/lib/systemd/system/openhab.service` with the following content:
```ini
[Unit]
Description=openHAB 2 - empowering the smart home
Description=openHAB - empowering the smart home
Documentation=https://www.openhab.org/docs/
Documentation=https://community.openhab.org
Wants=network-online.target
@ -520,11 +516,11 @@ After=network-online.target
User=openhab
Group=openhab
WorkingDirectory=/opt/openhab2
#EnvironmentFile=-/etc/default/openhab2
WorkingDirectory=/opt/openhab
#EnvironmentFile=-/etc/default/openhab
ExecStart=/opt/openhab2/runtime/bin/karaf daemon
ExecStop=/opt/openhab2/runtime/bin/karaf stop
ExecStart=/opt/openhab/runtime/bin/karaf daemon
ExecStop=/opt/openhab/runtime/bin/karaf stop
Restart=on-failure
SuccessExitStatus=0 143
@ -537,18 +533,18 @@ Next, enable the service to be executed on system startup, start the service and
```shell
# initialize the new service (execute only once)
sudo systemctl daemon-reload
sudo systemctl enable openhab2.service
sudo systemctl enable openhab.service
#start and retrieve status
sudo systemctl start openhab2.service
sudo systemctl status openhab2.service
sudo systemctl start openhab.service
sudo systemctl status openhab.service
```
The output of `status` after a successful execution should be similar to:
```text
openhab2.service - openHAB 2 - empowering the smart home
Loaded: loaded (/usr/lib/systemd/system/openhab2.service; enabled)
openhab.service - openHAB - empowering the smart home
Loaded: loaded (/usr/lib/systemd/system/openhab.service; enabled)
Active: active (running) since Thu 2016-08-14 01:16:00 GMT; 18h ago
Docs: https://www.openhab.org/docs/
https://community.openhab.org
@ -557,7 +553,7 @@ The output of `status` after a successful execution should be similar to:
#### Installing add-ons
When running a manual installation, it is possible to pre-download add-ons or legacy add-ons if you want to install any bindings at a later date without connecting to the internet.
Simply download the kar files (the latest builds can be found [here](https://ci.openhab.org/job/openHAB-Distribution/)) and move them to the `/opt/openhab2/addons` folder.
Simply download the kar files (the latest builds can be found [here](https://ci.openhab.org/job/openHAB-Distribution/)) and move them to the `/opt/openhab/addons` folder.
#### Upgrade
@ -603,14 +599,14 @@ Your personal configuration will be retained on upgrades, but you should **stop
#### Uninstall
To uninstall (or more precisely remove) openHAB 2 after being manually set up, take a backup if needed and then simply stop and deactivate the openHAB service and get rid of all files:
To uninstall (or more precisely remove) openHAB after being manually set up, take a backup if needed and then simply stop and deactivate the openHAB service and get rid of all files:
```shell
sudo systemctl stop openhab2.service
sudo systemctl disable openhab2.service
sudo rm -rf /opt/openhab2/
sudo rm /usr/lib/systemd/system/openhab2.service
sudo rm /lib/systemd/system/openhab2.service
sudo systemctl stop openhab.service
sudo systemctl disable openhab.service
sudo rm -rf /opt/openhab/
sudo rm /usr/lib/systemd/system/openhab.service
sudo rm /lib/systemd/system/openhab.service
sudo systemctl daemon-reload
```
@ -618,19 +614,19 @@ sudo systemctl daemon-reload
| | Repository Installation | Manual Installation (according to [guide](#manual-installation)) |
|:-----------------------------:|------------------------------|------------------------------------------------------------------|
| openHAB application | `/usr/share/openhab2` | `/opt/openhab2` |
| Additional add-on files | `/usr/share/openhab2/addons` | `/opt/openhab2/addons` |
| Site configuration | `/etc/openhab2` | `/opt/openhab2/conf` |
| Log files | `/var/log/openhab2` | `/opt/openhab2/userdata/logs` |
| Userdata like rrd4j databases | `/var/lib/openhab2` | `/opt/openhab2/userdata` |
| Backups folder | `/var/lib/openhab2/backups` | `/opt/openhab2/backups` |
| Service configuration | `/etc/default/openhab2` | (not preconfigured) |
| openHAB application | `/usr/share/openhab` | `/opt/openhab` |
| Additional add-on files | `/usr/share/openhab/addons` | `/opt/openhab/addons` |
| Site configuration | `/etc/openhab` | `/opt/openhab/conf` |
| Log files | `/var/log/openhab` | `/opt/openhab/userdata/logs` |
| Userdata like rrd4j databases | `/var/lib/openhab` | `/opt/openhab/userdata` |
| Backups folder | `/var/lib/openhab/backups` | `/opt/openhab/backups` |
| Service configuration | `/etc/default/openhab` | (not preconfigured) |
## Backup and Restore
It is recommended to make a backup of your configuration before *any* major change.
To make a backup of openHAB2, you need to retain your configuration and userdata files.
openHAB comes with scripts for storing your configuration in a zip file which is saved in `/var/lib/openhab2/backups` for automatic installs and `openhab2/backups` for manual installs.
openHAB comes with scripts for storing your configuration in a zip file which is saved in `/var/lib/openhab/backups` for automatic installs and `openhab/backups` for manual installs.
You can change the default path by setting the $OPENHAB_BACKUPS environment variable.
```shell
@ -660,18 +656,18 @@ Execute the following command in one session or have both files separated in ses
- Package repository based installation:
```shell
tail -f /var/log/openhab2/openhab.log -f /var/log/openhab2/events.log
tail -f /var/log/openhab/openhab.log -f /var/log/openhab/events.log
```
- Manual installation:
```shell
tail -f /opt/openhab2/userdata/logs/openhab.log -f /opt/openhab2/userdata/logs/events.log
tail -f /opt/openhab/userdata/logs/openhab.log -f /opt/openhab/userdata/logs/events.log
```
You could even set up an SSH configuration (in Putty or similar) to automatically connect and execute the commands every time you start working on your setup.
With openHAB 2 you can also [use the openHAB console]({{base}}/administration/logging.html#karaf-console) to have a colored glance at the logging information.
With openHAB you can also [use the openHAB console]({{base}}/administration/logging.html#karaf-console) to have a colored glance at the logging information.
## Recommended Additional Setup Steps
@ -741,7 +737,7 @@ Next, add the desired share configurations to the end of the file:
```ini
[openHAB2-userdata]
comment=openHAB2 userdata
path=/var/lib/openhab2
path=/var/lib/openhab
browseable=Yes
writeable=Yes
only guest=no
@ -751,7 +747,7 @@ Next, add the desired share configurations to the end of the file:
[openHAB2-conf]
comment=openHAB2 site configuration
path=/etc/openhab2
path=/etc/openhab
browseable=Yes
writeable=Yes
only guest=no
@ -761,7 +757,7 @@ Next, add the desired share configurations to the end of the file:
[openHAB2-logs]
comment=openHAB2 logs
path=/var/log/openhab2
path=/var/log/openhab
browseable=Yes
writeable=Yes
only guest=no
@ -775,7 +771,7 @@ Next, add the desired share configurations to the end of the file:
```ini
[openHAB-files]
comment=openHAB2
path=/opt/openhab2
path=/opt/openhab
browseable=Yes
writeable=Yes
only guest=no
@ -798,7 +794,7 @@ Make sure, the "openhab" user has ownership and/or write access to the openHAB c
This can be accomplished by executing:
```shell
sudo chown -hR openhab:openhab /etc/openhab2 /opt/openhab2/conf
sudo chown -hR openhab:openhab /etc/openhab /opt/openhab/conf
```
Finally check the configuration file for correctness and restart Samba to load the new settings:

2
installation/macos.md
View File

@ -136,7 +136,7 @@ sudo sh -c "$(curl -fsSL https://raw.githubusercontent.com/openhab/openhab-distr
## Backup and Restore
To make a backup of your openHAB 2 system, you need to retain your configuration and userdata files.
To make a backup of your openHAB system, you need to retain your configuration and userdata files.
As of version 2.2.0, you can use openHAB's scripts for storing your configuration in a zip file. From the terminal:
By default, the script saves the zip file in `/var/lib/openhab2/backups` for automatic installs and `openhab2/backups` for manual installs.
You can change the default path by setting the $OPENHAB_BACKUPS environment variable.

8
installation/rasppi.md
View File

@ -25,7 +25,7 @@ Recommendations for a ["headless"](https://en.wikipedia.org/wiki/Headless_comput
## Recommended Setup
We are proud to provide a **preconfigured image** for the Raspberry Pi, with the latest build of openHAB 2 and many useful software components (like Samba, Grafana or Mosquitto) as optional setup steps.
We are proud to provide a **preconfigured image** for the Raspberry Pi, with the latest build of openHAB and many useful software components (like Samba, Grafana or Mosquitto) as optional setup steps.
The image provided by the **openHABian** projects is based on Raspbian and under constant improvement.
Check out more details about [openHABian, the hassle-free openHAB setup](openhabian.html).
@ -68,13 +68,13 @@ sudo apt-get install screen mc vim git htop
```
**Note on Java:**
Raspbian in the latest full version already includes Oracle Java 8.
Raspbian in the latest full version already includes Oracle Java 11.
However, at the time of this writing, the installed revision is lower than the [recommended](index.html#prerequisites).
Raspbian Lite comes without Java to begin with.
Please refer to the Linux article for instructions on [how to install the latest Java 8 revision](linux.html).
Please refer to the Linux article for instructions on [how to install the latest Java 11 revision](linux.html).
**Installation:**
Finally install openHAB on your Raspberry Pi, just as it is described in the [openHAB 2 on Linux](linux.html) article:
Finally install openHAB on your Raspberry Pi, just as it is described in the [openHAB on Linux](linux.html) article:
- [Package Repository based Installation on Linux](linux.html#package-repository-installation)

58
installation/windows.md
View File

@ -5,9 +5,9 @@ title: Windows
{% include base.html %}
# openHAB 2 on Windows
# openHAB on Windows
The following instructions will guide you through the process of setting up openHAB 2.
The following instructions will guide you through the process of setting up openHAB.
This page is structured as follows:
@ -30,7 +30,7 @@ Create a New System Variable based on your Java installation directory:
![JAVA_HOME](images/JAVA_HOME.png)
The directory that openHAB is installed to must **contain no spaces**.
On this page, we will be using `C:\openHAB2` as an example.
On this page, we will be using `C:\openHAB` as an example.
## Installation
@ -39,11 +39,9 @@ To install it, follow these simple steps:
1. Download the latest Windows Stable or Snapshot ZIP archive file for manual installation from the [Download](https://www.openhab.org/download/) page.
2. Unzip the file in your chosen directory (e.g. `C:\openHAB2`)
2. Unzip the file in your chosen directory (e.g. `C:\openHAB`)
![openHAB 2 Folders](images/openHAB_2_Folders.png)
3. Start the server: Launch the runtime by executing the script `C:\openHAB2\start.bat` and wait a while for it to start and complete.
3. Start the server: Launch the runtime by executing the script `C:\openHAB\start.bat` and wait a while for it to start and complete.
![Karaf_Windows](images/Karaf_Windows.png)
@ -53,30 +51,30 @@ To install it, follow these simple steps:
### File Locations
Assuming a successful install, you will now have various folders inside `C:\openHAB2`:
Assuming a successful install, you will now have various folders inside `C:\openHAB`:
| | Windows Installation |
|:--------------------------------:|:-----------------------------|
| openHAB application | `C:\openHAB2\runtime` |
| Additional add-on files | `C:\openHAB2\addons` |
| Site configuration | `C:\openHAB2\conf` |
| Log files | `C:\openHAB2\userdata\logs` |
| Userdata like rrd4j databases | `C:\openHAB2\userdata` |
| Service configuration | `C:\openHAB2\userdata\etc` |
| openHAB application | `C:\openHAB\runtime` |
| Additional add-on files | `C:\openHAB\addons` |
| Site configuration | `C:\openHAB\conf` |
| Log files | `C:\openHAB\userdata\logs` |
| Userdata like rrd4j databases | `C:\openHAB\userdata` |
| Service configuration | `C:\openHAB\userdata\etc` |
## Backup
Make sure that you make regular backups of the **conf** and **userdata** folders, you can zip and unzip these folders too and from openHAB installations (even across most versions).
When you have a setup that you are happy with, it would be a good idea to make a backup of the whole `C:\openHAB2` folder.
When you have a setup that you are happy with, it would be a good idea to make a backup of the whole `C:\openHAB` folder.
Which can be used any time after a failure.
## Updating the openHAB Runtime
To start the update process, run PowerShell as an administrator and use the following commands, while replacing `x.x.x` with the wanted openHAB version.
Assuming you have openHAB installed in `C:\openHAB2`:
Assuming you have openHAB installed in `C:\openHAB`:
```shell
cd C:\openHAB2
cd C:\openHAB
. .\runtime\bin\update.ps1
Update-openHAB -OHVersion x.x.x
```
@ -97,25 +95,25 @@ By installing the openHAB process as a service in Windows, you can:
2. Issue the following two commands in your openHAB console:
```shell
feature:install service-wrapper
wrapper:install --name "openHAB2" --display "openHAB2" --description "openHAB 2 Service"
wrapper:install --name "openHAB" --display "openHAB" --description "openHAB Service"
```
![Wrapper Install_Windows](images/Wrapper_Install_Windows.jpg)
3. Shutdown the openHAB instance by typing `logout` in the currently running console.
4. Update the newly created `C:\openHAB2\userdata\etc\openHAB2-wrapper.conf` to include all necessary parameters.
4. Update the newly created `C:\openHAB\userdata\etc\openHAB-wrapper.conf` to include all necessary parameters.
- Copy all the config text from the below section and paste it in your `openHAB2-wrapper.conf`, replacing all existing content.
- Copy all the config text from the below section and paste it in your `openHAB-wrapper.conf`, replacing all existing content.
- Adapt the first entry (`OPENHAB_HOME`) to match your openHAB installation directory.
```conf
#*******************************************************
# openHAB2-wrapper.conf for Windows Service Installation
# openHAB-wrapper.conf for Windows Service Installation
#*******************************************************
# openHAB installation dir (Adapt this first setting to your system)
set.default.OPENHAB_HOME=C:\openHAB2
set.default.OPENHAB_HOME=C:\openHAB
# Wrapper Properties
set.default.OPENHAB_CONF=%OPENHAB_HOME%\conf
@ -170,10 +168,10 @@ By installing the openHAB process as a service in Windows, you can:
wrapper.syslog.loglevel=NONE
# Wrapper Windows Properties
wrapper.console.title=openHAB2
wrapper.ntservice.name=openHAB2
wrapper.ntservice.displayname=openHAB2
wrapper.ntservice.description=openHAB 2 Service
wrapper.console.title=openHAB
wrapper.ntservice.name=openHAB
wrapper.ntservice.displayname=openHAB
wrapper.ntservice.description=openHAB Service
wrapper.ntservice.dependency.1=
wrapper.ntservice.starttype=AUTO_START
wrapper.ntservice.interactive=false
@ -182,8 +180,8 @@ By installing the openHAB process as a service in Windows, you can:
5. Open an elevated command prompt and type the following commands:
```text
C:\openHAB2\userdata\bin\openHAB2-service.bat install
net start "openHAB2"
C:\openHAB\userdata\bin\openHAB-service.bat install
net start "openHAB"
```
![Admin cmd](images/Admin_CMD.jpg)
@ -196,7 +194,7 @@ By installing the openHAB process as a service in Windows, you can:
- Browsing to [http://localhost:8080](http://localhost:8080)
- Verifying that the Windows Service is running and set to Automatic Startup type.
Use `services.msc` and find the `openHAB2` service.
Use `services.msc` and find the `openHAB` service.
![Windows Service](images/Windows_Service.jpg)
@ -204,7 +202,7 @@ By installing the openHAB process as a service in Windows, you can:
### Connecting to the openHAB console
You can connect to openHAB's console using the the `C:\openHAB2\runtime\bin\client.bat` script on the local machine.
You can connect to openHAB's console using the the `C:\openHAB\runtime\bin\client.bat` script on the local machine.
Alternatively, you can use a standard SSH client:
- Install an SSH client application, e.g., [Putty](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html), [KiTTY](http://kitty.9bis.net/) or [Xshell 5](https://www.netsarang.com/products/xsh_overview.html)

90
introduction.md
View File

@ -22,7 +22,7 @@ h1.welcome {
<h1 class="welcome">Welcome!</h1>
The **open H**ome **A**utomation **B**us (openHAB, *pronounced ˈəʊpənˈhæb*) is an open source, technology agnostic home automation platform which runs as the center of your smart home!
The **open H**ome **A**utomation **B**us (openHAB, *pronounced ˈəʊpənˈhæb*) is an open source, technology agnostic home automation platform which runs as the center of your smart home!
<div style="clear:both"></div>
@ -34,8 +34,8 @@ Some of openHAB's strengths are:
## What You Need to Know Before You Start
**When home automation just seems to work, it is always the result of hard work.**
Home automation is fascinating and requires a considerable investment of your time.
**When home automation just seems to work, it is always the result of hard work.**
Home automation is fascinating and requires a considerable investment of your time.
Here are some key considerations especially for new users. To be successful, you will need to:
* Start slowly and one step at a time
@ -43,10 +43,10 @@ Here are some key considerations especially for new users. To be successful, you
* Remain flexible in how you want to achieve your goal
* Celebrate all the small successes
Remember, openHAB is just a computer program.
Remember, openHAB is just a computer program.
The computer will only do what *you* tell it to do.
openHAB can provide many default solutions that are easy to setup.
On the flip side, the more you insist that everything should look and work exactly the way you want it, the more work you will have to invest.
openHAB can provide many default solutions that are easy to setup.
On the flip side, the more you insist that everything should look and work exactly the way you want it, the more work you will have to invest.
openHAB is fully customizable, but doing so will require substantial effort on your part.
After you have read the documentation for openHAB, you will have:
@ -55,23 +55,23 @@ After you have read the documentation for openHAB, you will have:
* Learned how to install openHAB, as well as all other software that is needed to run openHAB (e.g., JAVA)
* Learned how your smart devices communicate with openHAB; how to make openHAB give commands to your smart devices; and how you can interact with openHAB
Keep your focus.
For almost everything, there is more than one way in openHAB to achieve a goal or perform a task.
Keep your focus.
For almost everything, there is more than one way in openHAB to achieve a goal or perform a task.
Initially, this can be frustrating and confusing, but it also gives great flexibility and does not mandate the use of certain devices or tools.
You may need to learn more about computers than you currently do.
But this may not be a problem as you are reading the documentation of software that will enable you to do home automation yourself.
Lastly, be prepared to start a new hobby: home automation.
Lastly, be prepared to start a new hobby: home automation.
Basic functions can be achieved in openHAB rather quickly, e.g., switch lights on at a certain time.
Basic functions can be achieved in openHAB rather quickly, e.g., switch lights on at a certain time.
Others will require much more effort and thought, e.g., how do I determine that someone is home, including guests, but not counting pets?
The openHAB forum is a great place to learn and discuss.
The openHAB forum is a great place to learn and discuss.
## A Quick Overview
openHAB communicates electronically with smart and not-so-smart devices, performs user-defined actions and provides web-pages with user-defined information as well as user-defined tools to interact with all devices.
To achieve this, openHAB segments and compartmentalizes certain functions and operations.
openHAB communicates electronically with smart and not-so-smart devices, performs user-defined actions and provides web-pages with user-defined information as well as user-defined tools to interact with all devices.
To achieve this, openHAB segments and compartmentalizes certain functions and operations.
The following table gives a top-level description of the most important concepts as well as a link to more information:
| Concepts | Meaning | More Information |
@ -84,41 +84,41 @@ The following table gives a top-level description of the most important concepts
| Sitemap | is the openHAB (software) generated user interface (web site) that presents information and allows for interactions | [click for more info on Sitemaps]({{base}}/configuration/sitemaps.html) |
While the table above gives an overview, please remember that it is incomplete and a simplification of openHAB for the sake of this overview.
More elements will be introduced in later chapters of the documentation.
More elements will be introduced in later chapters of the documentation.
All the above [Concepts]({{base}}/concepts/index.html) are explained in more depth on other pages that can be accessed either through the sidebar or the links in the table above.
### Channels
Channels are the logical link between a [Thing]({{base}}/concepts/things.html) and an [Item]({{base}}/concepts/items.html).
Channels originate from [Things]({{base}}/concepts/things.html) definition and define how your [Thing]({{base}}/concepts/things.html) can communicate with [Item]({{base}}/concepts/items.html) (and vice versa).
Channels originate from [Things]({{base}}/concepts/things.html) definition and define how your [Thing]({{base}}/concepts/things.html) can communicate with [Item]({{base}}/concepts/items.html) (and vice versa).
You will create channels when defining your [Thing]({{base}}/concepts/things.html).
During the definition of your [Thing]({{base}}/concepts/things) you will identify the channel to which your [Item]({{base}}/concepts/items.html) will be linked.
During the definition of your [Thing]({{base}}/concepts/things) you will identify the channel to which your [Item]({{base}}/concepts/items.html) will be linked.
These two steps ensure that openHAB can transmit the information from the [Thing]({{base}}/concepts/things.html) to the [Item]({{base}}/concepts/items.html) (and vice versa).
### Bindings
Bindings are software packages that are installed by the user in openHAB.
The main purpose of Bindings is to establish the connection between your device and your [Thing]({{base}}/concepts/things.html).
Bindings are software packages that are installed by the user in openHAB.
The main purpose of Bindings is to establish the connection between your device and your [Thing]({{base}}/concepts/things.html).
Bindings communicate with your device and translate all commands to and from openHAB between your device and your [Thing]({{base}}/concepts/things.html).
Bindings are provided in the [Add-on section](https://www.openhab.org/addons/) of this website.
Here you will find a searchable list of several hundred bindings to support as many devices as possible.
Here you will find a searchable list of several hundred bindings to support as many devices as possible.
New bindings are regularly added as developers integrate more devices into openHAB.
For each binding, detailed instructions and examples are provided that include guidance on configuration (if any) of the binding itself, the definition of [Things]({{base}}/concepts/things.html) supported by this binding and the Channels these [Things]({{base}}/concepts/things) provide.
For each binding, detailed instructions and examples are provided that include guidance on configuration (if any) of the binding itself, the definition of [Things]({{base}}/concepts/things.html) supported by this binding and the Channels these [Things]({{base}}/concepts/things) provide.
In most cases, the description also contains a fully worked out example that includes a definition of [Things]({{base}}/concepts/things) and its Channels, [Items]({{base}}/concepts/items.html) linked to those Channels and the use of these [Items]({{base}}/concepts/items.html) in a sitemap.
## While You Are Getting Started
To all newcomers: please read the section [New User Tutorial]({{base}}/tutorial).
That section provides you with step-by-step instructions for your first easy setup.
To all newcomers: please read the section [New User Tutorial]({{base}}/tutorial).
That section provides you with step-by-step instructions for your first easy setup.
OpenHAB runs on most popular platforms such as Linux, Windows and MacOS and on almost any hardware ranging from Raspberry Pis to desktop computers and server PCs.
You can find specific installation instructions for these and other platforms in the [Installation Overview]({{base}}/installation/index.html) article.
OpenHAB runs on most popular platforms such as Linux, Windows and MacOS and on almost any hardware ranging from Raspberry Pis to desktop computers and server PCs.
You can find specific installation instructions for these and other platforms in the [Installation Overview]({{base}}/installation/index.html) article.
If you have a strong preference towards a particular platform, then that platform is probably your best choice.
You can install openHAB on your desktop computer for evaluation purposes if you already have any of these systems available for use, but we recommend using a dedicated system in the long run.
You can install openHAB on your desktop computer for evaluation purposes if you already have any of these systems available for use, but we recommend using a dedicated system in the long run.
If you feel serious about home automation it is better to start with a dedicated system right away.
If you have no strong preference, get a [Raspberry Pi 4](https://www.raspberrypi.org/products/raspberry-pi-4-model-b/) with 2 GB and a 16 GB SD card and install [openHABian]({{base}}/installation/openhabian.html) for the best experience.
@ -131,10 +131,10 @@ You will want to have two GB for that to work smoothly.
Running Raspberries off the internal SD card only may result in system instabilities as these memory cards can degrade quickly under openHAB's use conditions (infamous 'wearout').
When you choose to deploy openHABian, it'll use the ZRAM feature to mitigate.
Once you have openHAB up and running, the [Configuration]({{base}}/configuration/index.html) article contains everything you need to know to get your openHAB installation talking to different devices around your home.
Once you have openHAB up and running, the [Configuration]({{base}}/configuration/index.html) article contains everything you need to know to get your openHAB installation talking to different devices around your home.
You will quickly discover that you may want to learn more about Things, Channels, Items, and more.
To do so, we highly recommend that you read the next chapter titled [Concepts]({{base}}/concepts/index.html).
You will quickly discover that you may want to learn more about Things, Channels, Items, and more.
To do so, we highly recommend that you read the next chapter titled [Concepts]({{base}}/concepts/index.html).
It provides more in-depth descriptions of Things, Items, Bindings, etc. that will help you as you dive deeper into openHAB.
The amount of information provided can be overwhelming but don't hesitate to return here to lookup infos.
@ -143,27 +143,27 @@ When you encounter questions along the way that the docs don't answer for you, t
## The openHAB Community
openHAB is not just software - it is also a **community** of users, contributors and maintainers, working together on an open-source, interoperable home automation system.
The center of this community is the [openHAB community forum](https://community.openhab.org).
openHAB is not just software - it is also a **community** of users, contributors and maintainers, working together on an open-source, interoperable home automation system.
The center of this community is the [openHAB community forum](https://community.openhab.org).
It is an active and responsive community of experienced users who generally respond quite quickly to forum questions.
[Mind the rules](https://community.openhab.org/t/how-to-ask-a-good-question-help-us-help-you/58396), please.
Remember that openHAB is an open-source development, driven exclusively by volunteers.
Remember that openHAB is an open-source development, driven exclusively by volunteers.
Please be kind and courteous, it will be most appreciated by those that will try to help you.
In many occasions, you will notice that your problem has already been raised, discussed and resolved by the community before.
You can search previous conversations and issues to see if your questions have already been answered.
In many occasions, you will notice that your problem has already been raised, discussed and resolved by the community before.
You can search previous conversations and issues to see if your questions have already been answered.
It is best practice and generally considered to be good etiquette to check fairly thoroughly before posting an own question.
If it is your first time posting a question, please read [How to help us help you](https://community.openhab.org/t/how-to-ask-a-good-question-help-us-help-you/58396) to see what information you will need to provide with your post.
## Putting it into Practice
Once you have got a first overview, it is time to practice.
Once you have got a first overview, it is time to practice.
Here a short list of the steps that you will need to consider to get openHAB up and running as your home automation system:
1. Install openHAB
2. If you already own a smart device, search the addons for the brand or technology used by that device (or simply browse the list of [add-ons](/addons/) for any technologies or services you may recognize)
2. If you already own a smart device, search the addons for the brand or technology used by that device (or simply browse the list of [add-ons](/addons/) for any technologies or services you may recognize)
3. Install a binding (in openHAB)
4. Define a “thing”
5. Add a “channel” to the “thing” if not created by the binding
@ -171,12 +171,12 @@ Here a short list of the steps that you will need to consider to get openHAB up
7. Link the “channel” to your “item”
8. Establish a sitemap
Most of the above can be done in openHAB through point-and-click processes in a graphical user interface.
But remember, there is always more than one way to achieve your goal in openHAB.
Most of the above can be done in openHAB through point-and-click processes in a graphical user interface.
But remember, there is always more than one way to achieve your goal in openHAB.
A final word for the DIY enthusiasts. openHAB is very flexible and can support many DIY devices.
However, you will quickly realize that DIY often literally means that you _"do it yourself"_.
Working with DIY solutions often requires a deeper level of understanding, as well as more patience and perseverance than the integration of ready-to-use devices from commercial vendors.
A final word for the DIY enthusiasts. openHAB is very flexible and can support many DIY devices.
However, you will quickly realize that DIY often literally means that you _"do it yourself"_.
Working with DIY solutions often requires a deeper level of understanding, as well as more patience and perseverance than the integration of ready-to-use devices from commercial vendors.
The choice is yours of course, but you will need to be prepared to spend either money or time (and sometimes both) to make your home automation goals a reality.
And quite often, the investment will be significant.
@ -185,12 +185,12 @@ But it comes with a rather steep learning curve.
## A Deeper Dive: openHAB Structure for Advanced Users
openHAB 2 is developed in [Java](https://www.java.com/) and uses [OSGi](https://www.osgi.org/) for modularity.
[Apache Karaf](http://karaf.apache.org/) serves as a container with [Eclipse Equinox](https://www.eclipse.org/equinox/) as the OSGi runtime environment.
openHAB is developed in [Java](https://www.java.com/) and uses [OSGi](https://www.osgi.org/) for modularity.
[Apache Karaf](http://karaf.apache.org/) serves as a container with [Eclipse Equinox](https://www.eclipse.org/equinox/) as the OSGi runtime environment.
[Jetty](https://www.eclipse.org/jetty/) is included as an HTTP server.
openHAB is highly modular software that can be extended through "Add-ons".
Add-ons give openHAB a wide array of capabilities, from User Interfaces, to the ability to interact with a large and growing number of physical Things.
Add-ons may come from the openHAB 2 distribution, the legacy openHAB 1 distribution or from other external sources.
openHAB is highly modular software that can be extended through "Add-ons".
Add-ons give openHAB a wide array of capabilities, from User Interfaces, to the ability to interact with a large and growing number of physical Things.
Add-ons may come from the openHAB distribution, the legacy openHAB 1 distribution or from other external sources.
If you are new to openHAB, we suggest you continue to the [Concepts]({{base}}/concepts/index.html) chapter where we introduce many fundamental ideas that are used throughout openHAB.