Initial moving concepts pages from ESH repo. (#890)
* Initial moving concepts pages from ESH repo. * Fix iconset ressource path * Remove vuepress preview config filter due to reintregration. * Remove vuepress preview config filter due to reintregration. FIX Signed-off-by: Jerome Luckenbach <github@luckenba.ch>pull/907/head
Jerome Luckenbach
GitHub
parent
1f34da84f5
commit
71b80209f2
|
|
@ -88,7 +88,7 @@ module.exports = {
|
|||
}
|
||||
],
|
||||
sidebar: {
|
||||
'/docs/': DocsSidebarNavigation.filter((s, i) => s.title !== 'Concepts')
|
||||
'/docs/': DocsSidebarNavigation
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,42 @@
|
|||
---
|
||||
layout: documentation
|
||||
title: Audio & Voice
|
||||
---
|
||||
|
||||
{% include base.html %}
|
||||
|
||||
# Audio & Voice
|
||||
|
||||
Audio and voice features are an important aspect of any smart home solution as it is a very natural way to interact with the user.
|
||||
|
||||
Eclipse SmartHome comes with a very modular architecture that enables all kinds of different use cases.
|
||||
At its core, there is the notion of an *audio stream*.
|
||||
Audio streams are provided by *audio sources* and consumed by *audio sinks*.
|
||||
|
||||
|
||||
|
||||
- *Audio Streams* are essentially a byte stream with a given *audio format*.
|
||||
They do not need to be limited in size, i.e. it is also allowed to have continuous streams, e.g. the input from a microphone or from an Internet radio station.
|
||||
- *Audio Formats* define the container (e.g. WAV), encoding, bit rate, sample frequency and depth and the bit order (little or big endian).
|
||||
- *Audio Sources* are services that are capable of producing audio streams.
|
||||
They can support different formats and provide a stream in a requested format upon request.
|
||||
Typical audio source services are microphones. Typically, a continuous stream is expected from them.
|
||||
- *Audio Sinks* are services that accept audio streams of certain formats.
|
||||
Typically, these are expected to play the audio stream, i.e. they are some kind of speaker or media device.
|
||||
- *Text-to-Speech* (TTS) services are similar to audio sources with respect to the ability to create audio streams.
|
||||
The difference is that they take a string as an input and will synthesize this string to a spoken text using a given voice.
|
||||
TTS services can provide information about the voices that they support and the locale that those voices are associated with.
|
||||
Each voice supports exactly one locale.
|
||||
- *Speech-to-Text* (STT) services are similar to audio sinks, but they do not simply play back the stream, but convert it to a plain string.
|
||||
They provide information about supported formats and locales.
|
||||
|
||||
As plain text from an STT service is often not very useful, there is additionally the concept of a *human language interpreter*:
|
||||
|
||||
|
||||
|
||||
A *Human Language Interpreter* takes a string as an input.
|
||||
It then derives actions from it (like sending commands to devices) and/or replies with a string, which opens the possibility to realize conversations.
|
||||
As such an interpreter is not directly linked to audio streams, but operates on strings only, this can be the basis for any kind of assistant, e.g. for chat bots using the console, XMPP, Twitter or other messaging services.
|
||||
|
||||
Applications can dynamically choose which services to use, so that different sinks can be used for different use cases.
|
||||
Defaults can be set as a configuration for all those services in case an application does not ask for any specific service.
|
||||
|
|
@ -0,0 +1,49 @@
|
|||
---
|
||||
layout: documentation
|
||||
title: Categories
|
||||
---
|
||||
|
||||
{% include base.html %}
|
||||
|
||||
# Categories
|
||||
|
||||
Categories in Eclipse SmartHome are used to provide meta information about Things, Channels, etc. UIs can use this information to render specific icons or provide a search functionality to for example filter all Things for a certain category.
|
||||
|
||||
## Differences between categories
|
||||
|
||||
We separate the categories into `functional` and `visual`.
|
||||
Therefore we treat `Thing categories` as how the physical device **looks like** and `Channel categories` as something that describes the **functional purpose** of the Channel.
|
||||
|
||||
## Thing Categories
|
||||
|
||||
The Thing type definition allows to specify a category.
|
||||
User interfaces can parse this category to get an idea how to render this Thing.
|
||||
A Binding can classify each Thing into one of the existing categories.
|
||||
The list of all predefined categories can be found in our categories overview:
|
||||
|
||||
| Category | Description | Icon Example |
|
||||
|-----------------|-------------|{% for category in site.data.categories_thing %}
|
||||
|{{category.name}}|{{category.description}}|{:height="36px" width="36px"}|{% endfor %}
|
||||
|
||||
### Channel Group Categories
|
||||
|
||||
Channel Groups can be seen as a kind of `sub-device` as they combine certain (physical) abilities of a `Thing` into one. For such `Group Channels` one can set a category from the `Thing` category list.
|
||||
|
||||
## Channel Categories
|
||||
|
||||
The Channel type definition allows to specify a category.
|
||||
A Binding should classify each Channel into one of the existing categories or leave the category blank, if there is no good match.
|
||||
There are different types of categories for Channels, which are listed below.
|
||||
|
||||
{% for category in site.data.categories %}
|
||||
{% assign typesStr = typesStr | append: category.type | append: ',' %}
|
||||
{% endfor %}
|
||||
{% assign types = typesStr | split: ',' | uniq %}
|
||||
|
||||
{% for type in types %}
|
||||
#### {{ type }}
|
||||
|
||||
| Category | Icon Example |
|
||||
|-----------------|--------------|{% for category in site.data.categories %}{% if category.type == type %}
|
||||
|{{category.name}}|{:height="36px" width="36px"}|{% endif %}{% endfor %}
|
||||
{% endfor %}
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 38 KiB |
|
|
@ -0,0 +1 @@
|
|||
<mxfile userAgent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.130 Safari/537.36" type="device"><diagram>7VpRc9q4E/80zPQeyGAcU3iMA01vpneXOTL3vz51BBagqbF8sqHQT99deWXL2CYhOJfyv/AAeCWtpN/qt9qV3HFv17s7xeLVbzLgYaffC3Ydd9zp90feNXyjYJ8JvAE8oWCpRJCJnEIwFd85CXsk3YiAJ6WKqZRhKuKycC6jiM/Tkmwhw3IXMVsa9YVgOmdhVfo/EaQrkjqDUVHwkYvlivoZ9gdZQZLujY6AL9gmTLtaRHNdM6NLz8qdAGBKStCC/9a7Wx4iaAaQbOofGkrzQSoe0TiON6BBbFm4oTF2+oMQmvpxaeiDfzY4JH/N1FJEHfcGSnvxDr5BqGeB8m4q46zs2ipL+S7tslAsqd0cxsZVoRP+LelX9ywsAVuDQl+Ly09/TO9Ed8rVVsx5XlJuVVIKENh6tWyGgyhLjGCyhUHeb2ahSFZ6rEZJXsOSAVRl2bOwC/kCauXgNaFTHXTdCFaVWi8zJqwbyyQ1vSQxi2o7CkXEuyviByp0rpAghxrfaeB/yapsJSzTYpKZ7mNzP6DblqtUAINvsrU31qvTp5U4zubmS6i1COU3kCwEcMP1FzJKydk4QEj9/IGtRYhu6iMPtxy1IsjpGuqPHapzK0OpdM+u6/bgg3ikSn7lVgnKdQl2ZskX+oOrVrFAAAZjocBnCYlDjaRCJ0EztNlNhMeZcnKrWkRsv+NyzVO1hypUOswakMcdvc8ev1kebUTe1RhLt/IyGSPHusz1Fr4F/pB7qXc17puraXY1080smSsxe/M1x33NzadPXyZ/TX5/+PLw+X4yzepPUyWi5WuBdJLLOxHrx13eBcyvoEk0S/DnkQmeu4cseUGnQLPrYR/z5B3tKlOOu5XF73z51HO5bohPI0a9VaqzuL5yR/gZOEPP7bkVS9kWtL/bMpt35TjY/3Doed7IaWYfIKvx/CBCcKsGUEvUCmyB2F4qko0E6MFmzsWWnxff5LISRK8Y9TTEMM1RT7Jige71WNB0LARahizBIATbtxAOee8pLKGAyAQ6VkDUv64JiBwjPCciovT38iKiX1HHgr1cOFTxJm+hUMWjsDgO9yV/MoPDD659yFtu9CxnMCpnR/33VW9Qmx4Z2TnOgLr6DzqD1qjcypzLjuiYC/r5XALEZxjq5pHupeRFpwSgDzIW8/YyiCd03QjnhWVnp6B8z/ahZMFJU297KP8/efEpyE/lRs2bKXyJh6DHtu3GFMJOFOygvzlqiLkSsO1yNY3ZHFHLGii5iQKOu2xm5rPDhDxJaM4ZaqMEx9xbnRMmOHVJw4HJeRTcKKXRkzEHtH2Q2MYMGNxqoELExzIgYKL2fxNS+uEzPlx5+LgTKRbpevC/KGmENNFLuXTRlALF4PzFjnh4ULp4q8Ju4zogCBUPWQr5dKm/OlxJ3b0UuJnnJqRrMWPCSjqXDZ1a2fdnh4qGjyjKJlxRpM2cz/FJljdDtiyfgF2Tivkx4inbVfFEfGczXUGToHAAFA65/qGfWIsgwAZ+yGY89Nn861IzqY6sNSuAlildvVLf+XXkCWzrXfVH5u6AQO7SYjpzEXSBCyXbUS9Gg1wsEjwrPMtqTl1c3zpf84cnsPI5FDQJkvFgJkFya1yfoejTDXF4CPNsNnomYTscX/tsdOja37IrHfH9pIQkJM4g5Jl0K+fWZjztko1euXgZstEGWGyHSLaj55D2BkhL3GYf+cjnsg/iq1bY5zWQ+lT2Xf+L7KPFZBk6VnKrXwf6KdlHC/P12EdrzeygB+1bYV/tEdaBMTA3Khsji+fNK1WHtwqR1PUP0pVG40B2hJE/nBGAFCaZSz7phmO3kPxJgTmKlEyZMQouCG3je5kISlZUVtePEVMNmed3vLGWKEh5IpgEQ7jdMWdJ+o3DCzEtXU+U7eYMyI08dj9B/Dgh04DH4rWzzPrFS3vu5Ac=</diagram></mxfile>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
|
|
@ -0,0 +1,31 @@
|
|||
' State diagram for Thing Status Concept
|
||||
@startuml
|
||||
skinparam state {
|
||||
BackgroundColor White
|
||||
BorderColor Grey
|
||||
ArrowColor #01324D
|
||||
StartColor #01324D
|
||||
EndColor #01324D
|
||||
}
|
||||
[*] -up-> UNINITIALIZED
|
||||
UNINITIALIZED -right-> INITIALIZING
|
||||
INITIALIZING -left-> UNINITIALIZED
|
||||
INITIALIZING -right-> initialized
|
||||
|
||||
state initialized {
|
||||
ONLINE -right-> OFFLINE
|
||||
ONLINE --> UNKNOWN
|
||||
OFFLINE -left-> ONLINE
|
||||
OFFLINE --> UNKNOWN
|
||||
UNKNOWN --> ONLINE
|
||||
UNKNOWN --> OFFLINE
|
||||
}
|
||||
|
||||
initialized -left-> UNINITIALIZED
|
||||
|
||||
state removal {
|
||||
[*] --> REMOVING
|
||||
REMOVING --> REMOVED
|
||||
REMOVED --> [*]
|
||||
}
|
||||
@enduml
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
---
|
||||
layout: documentation
|
||||
title: Thing Discovery
|
||||
---
|
||||
|
||||
{% include base.html %}
|
||||
|
||||
# Thing Discovery
|
||||
|
||||
Many devices, technologies and systems can be automatically discovered on the network or browsed through some API. It therefore makes a lot of sense to use these features for a smart home solution.
|
||||
|
||||
In Eclipse SmartHome bindings therefore implement _Discovery Services_ for Things, which provide _Discovery Results_. All _Discovery Results_ are regarded as suggestions to the user and are put into the _inbox_.
|
||||
|
||||
### Background Discovery
|
||||
|
||||
A couple of 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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Eclipse SmartHome offers a service to automatically ignore discovery results in the inbox, whenever a Thing is created manually, that represents the same Thing, as the respective discovery result would create.
|
||||
This Thing would either have the same Thing UID or the value of its representation property is equal to the representation property's value in the discovery result.
|
||||
This service is enabled by default but can be disabled by setting `org.eclipse.smarthome.inbox:autoIgnore=false`.
|
||||
|
||||
### Auto Approve
|
||||
|
||||
If the manual acceptance of discovery results by the user is not wished, 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.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 74 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 24 KiB |
|
|
@ -0,0 +1,52 @@
|
|||
---
|
||||
layout: documentation
|
||||
title: Concepts
|
||||
---
|
||||
|
||||
{% include base.html %}
|
||||
|
||||
# Concepts
|
||||
|
||||
When first thinking about your home automation system, it may be helpful to bear in mind that there are two ways of thinking about or viewing your system; the physical view and the functional view.
|
||||
|
||||
The physical view will be familiar to you.
|
||||
This view focuses on the devices in your system, the connections between these devices (e.g. wires, Z-Wave, WiFi hardware), and other physical aspects of the system.
|
||||
|
||||
The functional view might be a new concept for you.
|
||||
The functional view focuses on how information about the devices, connections, and so on, is represented in user interfaces.
|
||||
The functional view includes focusing on how rules affect representations of physical devices in software.
|
||||
Perhaps most important to you, the functional view focuses on how an action in a user interface affects the software associated with the physical device it represents.
|
||||
|
||||
It is a bit of an over-simplification, but you can think of the physical view as being a view of the 'real world', and the functional view being a view of the 'software world'.
|
||||
|
||||
## Things, Channels, Bindings, Items and Links
|
||||
|
||||
**Things** are entities that can be physically added to a system.
|
||||
Things may provide more than one function (for example, a Z-Wave multi-sensor may provide a motion detector and also measure room temperature).
|
||||
Things do not have to be physical devices; they can also represent a web service or any other manageable source of information and functionality.
|
||||
|
||||
Things expose their capabilities through **Channels**.
|
||||
Whether an installation takes advantage of a particular capability reflected by a Channel depends on whether it has been configured to do so.
|
||||
When you configure your system, you do not necessarily have to use every capability offered by a Thing.
|
||||
You can find out what Channels are available for a Thing by looking at the documentation of the Thing's Binding.
|
||||
|
||||
**Bindings** can be thought of as software adapters, making Things available to your home automation system.
|
||||
They are add-ons that provide a way to link Items to physical devices.
|
||||
They also abstract away the specific communications requirements of that device so that it may be treated more generically by the framework.
|
||||
|
||||
**Items** represent capabilities that can be used by applications, either in user interfaces or in automation logic.
|
||||
Items have a **State** and they may receive commands.
|
||||
|
||||
The glue between Things and Items are **Links**.
|
||||
A Link is an association between exactly one Channel and one Item.
|
||||
If a Channel is linked to an Item, it is "enabled", which means that the capability the Item represents is accessible through that Channel.
|
||||
Channels may be linked to multiple Items and Items may be linked to multiple Channels.
|
||||
|
||||
To illustrate these concepts, consider the example below of a two-channel actuator that controls two lights:
|
||||
|
||||
|
||||
|
||||
The actuator is a Thing that might be installed in an electrical cabinet.
|
||||
It has a physical address and it must be configured in order to be used (remember the physical view introduced at the beginning of this article).
|
||||
|
||||
In order for the user to control the two lights, he or she access the capability of the actuator Thing (turning on and off two separate lights) through two Channels, that are Linked to two switch Items presented to the user through a user interface.
|
||||
|
|
@ -0,0 +1,159 @@
|
|||
---
|
||||
layout: documentation
|
||||
title: Items
|
||||
---
|
||||
|
||||
{% include base.html %}
|
||||
|
||||
# Items
|
||||
|
||||
Eclipse SmartHome has a strict separation between the physical world (the "Things", see below) and the application, which is built around the notion of "Items" (also called the virtual layer).
|
||||
|
||||
Items represent functionality that is used by the application (mainly user interfaces or automation logic).
|
||||
Items have a state and are used through events.
|
||||
|
||||
The following Item types are currently available (alphabetical order):
|
||||
|
||||
| Item Name | Description | Command Types |
|
||||
|--------------------|-------------|---------------|
|
||||
| Color | Color information (RGB) | OnOff, IncreaseDecrease, Percent, HSB |
|
||||
| Contact | Item storing status of e.g. door/window contacts | OpenClosed |
|
||||
| DateTime | Stores date and time | - |
|
||||
| Dimmer | Item carrying a percentage value for dimmers | OnOff, IncreaseDecrease, Percent |
|
||||
| Group | Item to nest other Items / collect them in Groups | - |
|
||||
| Image | Holds the binary data of an image | - |
|
||||
| Location | Stores GPS coordinates | Point |
|
||||
| Number | Stores values in number format, takes an optional dimension suffix | Decimal |
|
||||
| Number:<dimension> | like Number, additional dimension information for unit support | Quantity |
|
||||
| Player | Allows to control players (e.g. audio players) | PlayPause, NextPrevious, RewindFastforward |
|
||||
| Rollershutter | Typically used for blinds | UpDown, StopMove, Percent |
|
||||
| String | Stores texts | String |
|
||||
| Switch | Typically used for lights (on/off) | OnOff |
|
||||
|
||||
## Group Items
|
||||
|
||||
Group Items collect other Items into Groups.
|
||||
Group Items can themselves be members of other Group Items.
|
||||
Cyclic membership is not forbidden but strongly not recommended.
|
||||
User interfaces might display Group Items as single entries and provide navigation to its members.
|
||||
|
||||
Example for a Group Item as a simple collection of other Items:
|
||||
```
|
||||
Group groundFloor
|
||||
Switch kitchenLight (groundFloor)
|
||||
Switch livingroomLight (groundFloor)
|
||||
```
|
||||
|
||||
### Derive Group State from Member Items
|
||||
|
||||
Group Items can derive their own state from their member Items.
|
||||
To derive a state the Group Item must be constructed using a base Item and a Group function.
|
||||
When calculating the state, Group functions recursively traverse the Group's members and also take members of subgroups into account.
|
||||
If a subgroup however defines a state on its own (having base Item & Group function set) traversal stops and the state of the subgroup member is taken.
|
||||
|
||||
Available Group functions:
|
||||
|
||||
| Function | Parameters | Base Item | Description |
|
||||
|--------------------|-------------------------------|---------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| EQUALITY | - | \<all\> | Sets the state of the members if all have equal state. Otherwise UNDEF is set. In the Item DSL `EQUALITY` is the default and may be omitted. |
|
||||
| AND, OR, NAND, NOR | <activeState>, <passiveState> | \<all\> (must match active & passive state) | Sets the \<activeState\>, if the member state \<activeState\> evaluates to `true` under the boolean term. Otherwise the \<passiveState\> is set. |
|
||||
| SUM, AVG, MIN, MAX | - | Number | Sets the state according to the arithmetic function over all member states. |
|
||||
| COUNT | <regular expression> | Number | Sets the state to the number of members matching the given regular expression with their states. |
|
||||
| LATEST, EARLIEST | - | DateTime | Sets the state to the latest/earliest date from all member states |
|
||||
|
||||
Examples for derived states on Group Items when declared in the Item DSL:
|
||||
|
||||
- `Group:Number:COUNT(".*")` counts all members of the Group matching the given regular expression, here any character or state (simply count all members).
|
||||
- `Group:Number:AVG` calculates the average value over all member states which can be interpreted as `DecimalTypes`.
|
||||
- `Group:Switch:OR(ON,OFF)` sets the Group state to `ON` if any of its members has the state `ON`, `OFF` if all are off.
|
||||
- `Group:Switch:AND(ON,OFF)` sets the Group state to `ON` if all of its members have the state `ON`, `OFF` if any of the Group members has a different state than `ON`.
|
||||
- `Group:DateTime:LATEST` sets the Group state to the latest date from all its members states.
|
||||
|
||||
## State and Command Type Formatting
|
||||
|
||||
### StringType
|
||||
|
||||
`StringType` objects store a simple Java String.
|
||||
|
||||
### DateTimeType
|
||||
|
||||
`DateTimeType` objects are parsed using Java's `SimpleDateFormat.parse()` using the first matching pattern:
|
||||
|
||||
1. `yyyy-MM-dd'T'HH:mm:ss.SSSZ`
|
||||
2. `yyyy-MM-dd'T'HH:mm:ss.SSSz`
|
||||
3. `yyyy-MM-dd'T'HH:mm:ss.SSSX`
|
||||
4. `yyyy-MM-dd'T'HH:mm:ssz`
|
||||
5. `yyyy-MM-dd'T'HH:mm:ss`
|
||||
|
||||
Literal | Standard | Example
|
||||
--------|----------|--------
|
||||
z | General time zone | Pacific Standard Time; PST; GMT-08:00
|
||||
Z | RFC 822 time zone | -0800
|
||||
X | ISO 8601 time zone | -08; -0800; -08:00
|
||||
|
||||
### DecimalType, PercentType
|
||||
|
||||
`DecimalType` and `PercentType` objects use Java's `BigDecimal` constructor for conversion.
|
||||
`PercentType` values range from 0 to 100.
|
||||
|
||||
### QuantityType
|
||||
|
||||
A numerical type which carries a unit in addition to its value.
|
||||
The framework is capable of automatic conversion between units depending on the users locale settings.
|
||||
See the concept on [Units of Measurement](units-of-measurement.html) for more details.
|
||||
|
||||
### HSBType
|
||||
|
||||
HSB string values consist of three comma-separated values for hue (0-360°), saturation (0-100%), and value (0-100%) respectively, e.g. `240,100,100` for blue.
|
||||
|
||||
### PointType
|
||||
|
||||
`PointType` strings consist of three `DecimalType`s separated by commas, indicating latitude and longitude in degrees, and altitude in meters respectively.
|
||||
|
||||
### Enum Types
|
||||
|
||||
| Type | Supported Values |
|
||||
|-----------------------|-------------------------|
|
||||
| IncreaseDecreaseType | `INCREASE`, `DECREASE` |
|
||||
| NextPreviousType | `NEXT`, `PREVIOUS` |
|
||||
| OnOffType | `ON`, `OFF` |
|
||||
| OpenClosedType | `OPEN`, `CLOSED` |
|
||||
| PlayPauseType | `PLAY`, `PAUSE` |
|
||||
| RewindFastforwardType | `REWIND`, `FASTFORWARD` |
|
||||
| StopMoveType | `STOP`, `MOVE` |
|
||||
| UpDownType | `UP`, `DOWN` |
|
||||
|
||||
## A note on Items which accept multiple state data types
|
||||
|
||||
There are a number of Items which accept multiple state data types, for example `DimmerItem`, which accepts `OnOffType` and `PercentType`, `RollershutterItem`, which accepts `PercentType` and `UpDownType`, or `ColorItem`, which accepts `HSBType`, `OnOffType` and `PercentType`.
|
||||
Since an Item has a SINGLE state, these multiple data types can be considered different views to this state.
|
||||
The data type carrying the most information about the state is usually used to keep the internal state for the Item, and other datatypes are converted from this main data type.
|
||||
This main data type is normally the first element in the list returned by `Item.getAcceptedDataTypes()`.
|
||||
|
||||
Here is a short table demonstrating conversions for the examples above:
|
||||
|
||||
| Item Name | Main Data Type | Additional Data Types Conversions |
|
||||
|---------------|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| Color | `HSBType` | • `OnOffType` - `OFF` if the brightness level in the `HSBType` equals 0, `ON` otherwise <br/> • `PercentType` - the value for the brightness level in the `HSBType` |
|
||||
| Dimmer | `PercentType` | `OnOffType` - `OFF` if the brightness level indicated by the percent type equals 0, `ON` otherwise |
|
||||
| Rollershutter | `PercentType` | `UpDownType` - `UP` if the shutter level indicated by the percent type equals 0, `DOWN` if it equals 100, and `UnDefType.UNDEF` for any other value |
|
||||
|
||||
## Item Metadata
|
||||
|
||||
Sometimes additional information is required to be attached to Items for certain use-cases.
|
||||
This could be an application which needs some hints in order to render the Items in a generic way, or an integration with voice controlled assistants, or any other services which access the Items and need to understand their "meaning".
|
||||
|
||||
Such metadata can be attached to Items using disjunct namespaces so they won't conflict with each other.
|
||||
Each metadata entry has a main value and optionally additional key/value pairs.
|
||||
There can be metadata attached to an Item for as many namespaces as desired, like in the following example:
|
||||
|
||||
Switch "My Fan" { homekit="Fan.v2", alexa="Fan" [ type="oscillating", speedSteps=3 ] }
|
||||
|
||||
The metadata can be maintained via a dedicated REST endpoint and is included in the `EnrichedItemDTO` responses.
|
||||
|
||||
Extensions which can infer some metadata automatically need to implement and register a `MetadataProvider` service in order to make them available to the system.
|
||||
They may provision them from any source they like and also dynamically remove or add data.
|
||||
They are also not restricted to a single namespace.
|
||||
|
||||
The `MetadataRegistry` provides access for all extensions which need to read the Item metadata programmatically.
|
||||
It is the central place where additional information about Items is kept.
|
||||
|
|
@ -0,0 +1,34 @@
|
|||
---
|
||||
layout: documentation
|
||||
title: Profiles
|
||||
---
|
||||
|
||||
# Profiles
|
||||
|
||||
The communication between the framework and the Thing handlers is managed by the "Communication Manager", which in turn uses "Profiles" to determined what exactly needs to be done.
|
||||
This provides some flexibility to influence these communication paths.
|
||||
|
||||
By their nature, profiles are correlated to links between Items and Channels (i.e. `ItemChannelLinks`). So if one Channel is linked to several Items it also will have several profile instances, each handling the communication to exactly one of these Items.
|
||||
The same applies for the situation where one Item is linked to multiple Channels.
|
||||
|
||||
Profiles are created by ProfileFactories and are retained for the lifetime of their link.
|
||||
This means that they are allowed to retain a transient state, like e.g. the timestamp of the the last event or the last state.
|
||||
With this, it is possible to take into account the temporal dimension when calculating the appropriate action in any situation.
|
||||
|
||||
There exist two different kinds of profiles: state and trigger profiles.
|
||||
|
||||
### State Profiles
|
||||
|
||||
State profiles are responsible for communication between Items and their corresponding state Channels (`ChannelKind.STATE`).
|
||||
Their purpose is to forward state updates and commands to and from the Thing handlers.
|
||||
|
||||
### Trigger Profiles
|
||||
|
||||
Trigger Channels (`ChannelKind.TRIGGER`) by themselves do not maintain a state (as by their nature they only fire events).
|
||||
With the help of trigger profiles they can be linked to Items anyway.
|
||||
Hence the main purpose of a trigger profile is to calculate a state based on the fired events.
|
||||
This state then is forwarded to the linked Item by sending `ItemStateEvents`.
|
||||
|
||||
Trigger profiles are powerful means to implement some immediate, straight-forward logic without the need to write any rules.
|
||||
|
||||
Apart from that, they do not pass any commands or state updates to and from the Thing handler as by their nature trigger Channels are not capable of handling these.
|
||||
|
|
@ -0,0 +1,126 @@
|
|||
---
|
||||
layout: documentation
|
||||
title: Things
|
||||
---
|
||||
|
||||
# Things
|
||||
|
||||
Things are the entities that can physically be added to a system and which can potentially provide many functionalities in one.
|
||||
It is important to note that Things do not have to be devices, but they can also represent a web service or any other manageable source of information and functionality.
|
||||
From a user perspective, they are relevant for the setup and configuration process, but not for the operation.
|
||||
|
||||
Things can have configuration properties, which can be optional or mandatory.
|
||||
Such properties can be basic information like an IP address, an access token for a web service or a device specific configuration that alters its behavior.
|
||||
|
||||
### Channels
|
||||
|
||||
Things provide "Channels", which represent the different functions the Thing provides.
|
||||
Where the Thing is the physical entity or source of information, the Channel is a concrete function from this Thing.
|
||||
A physical light bulb might have a color temperature Channel and a color Channel, both providing functionality of the one light bulb Thing to the system.
|
||||
For sources of information the Thing might be the local weather with information from a web service with different Channels like temperature, pressure and humidity.
|
||||
|
||||
Channels are linked to Items, where such links are the glue between the virtual and the physical layer.
|
||||
Once such a link is established, a Thing reacts on events sent for an item that is linked to one of its Channels.
|
||||
Likewise, it actively sends out events for Items linked to its Channels.
|
||||
|
||||
### Bridges
|
||||
|
||||
A special type of Thing is a "bridge".
|
||||
Bridges are Things that need to be added to the system in order to gain access to other Things.
|
||||
A typical example of a bridge is an IP gateway for some non-IP based home automation system or a web service configuration with authentication information which every Thing from this web service might need.
|
||||
|
||||
### Discovery
|
||||
|
||||
As many Things can be automatically discovered, there are special mechanisms available that deal with the handling of [automatically discovered Things](discovery.html).
|
||||
|
||||
|
||||
## Thing Status
|
||||
|
||||
Each Thing has a status object, which helps to identify possible problems with the device or service.
|
||||
The following table provides an overview of the different statuses:
|
||||
|
||||
| Status | Description |
|
||||
|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| UNINITIALIZED | This is the initial status of a Thing, when it is added or the framework is being started. This status is also assigned, if the initializing process failed or the binding is not available. Commands, which are sent to Channels will not be processed. |
|
||||
| INITIALIZING | This state is assigned while the binding initializes the Thing. It depends on the binding how long the initializing process takes. Commands, which are sent to Channels will not be processed. |
|
||||
| UNKNOWN | The handler is fully initialized but due to the nature of the represented device/service it cannot really tell yet whether the Thing is ONLINE or OFFLINE. Therefore the Thing potentially might be working correctly already and may or may not process commands. But the framework is allowed to send commands, because some radio-based devices may go ONLINE if a command is sent to them. The handler should take care to switch the Thing to ONLINE or OFFLINE as soon as possible. |
|
||||
| ONLINE | The device/service represented by a Thing is assumed to be working correctly and can process commands. |
|
||||
| OFFLINE | The device/service represented by a Thing is assumed to be not working correctly and may not process commands. But the framework is allowed to send commands, because some radio-based devices may go back to ONLINE, if a command is sent to them. |
|
||||
| REMOVING | The device/service represented by a Thing should be removed, but the binding did not confirm the deletion yet. Some bindings need to communicate with the device to unpair it from the system. Thing is probably not working and commands can not be processed. |
|
||||
| REMOVED | This status indicates that the device/service represented by a Thing was removed from the external system after the REMOVING was initiated by the framework. Usually this status is an intermediate status because the Thing gets removed from the database after this status was assigned. |
|
||||
|
||||
The statuses UNINITIALIZED, INITIALIZING and REMOVING are set by the framework, where as the statuses UNKNOWN, ONLINE and OFFLINE are assigned from a binding.
|
||||
|
||||
Additionally, the REMOVED state is set by the binding to indicate that the removal process has been completed, i.e. the Thing must have been in REMOVING state before.
|
||||
|
||||
### Status Transitions
|
||||
|
||||
The following diagram shows the allowed status transitions:
|
||||
|
||||
|
||||
|
||||
The initial state of a Thing is UNINITIALIZED.
|
||||
From UNINITIALIZED the Thing goes into INITIALIZING.
|
||||
If the initialization fails, the Thing goes back to UNINITIALIZED.
|
||||
If the initialization succeeds, the binding sets the status of the Thing to UNKNOWN, ONLINE or OFFLINE, which all mean that the Thing handler is fully initialized.
|
||||
From one of this states the Thing can go back into UNINITIALIZED, REMOVING or REMOVED.
|
||||
The statuses REMOVING and REMOVED can also be reached from any of the other states.
|
||||
|
||||
## Status Details
|
||||
|
||||
A status is detailed further with a status detail object.
|
||||
The following table lists the different status details for each status:
|
||||
|
||||
<table>
|
||||
<tr valign="top"><td rowspan="7">UNINITIALIZED</td><td>NONE</td><td>No further status details available.</td></tr>
|
||||
<tr valign="top"> <td>HANDLER_MISSING_ERROR</td><td>The handler cannot be initialized, because the responsible binding is not available or started.</td></tr>
|
||||
<tr valign="top"> <td>HANDLER_REGISTERING_ERROR</td><td>The handler failed in the service registration phase.</td></tr>
|
||||
<tr valign="top"> <td>HANDLER_CONFIGURATION_PENDING</td><td>The handler is registered but can not be initialized caused by missing configuration parameters.</td></tr>
|
||||
<tr valign="top"> <td>HANDLER_INITIALIZING_ERROR</td><td>The handler failed in the initialization phase.</td></tr>
|
||||
<tr valign="top"> <td>BRIDGE_UNINITIALIZED</td><td>The bridge associated with this Thing is not initialized.</td></tr>
|
||||
<tr valign="top"> <td>DISABLED</td><td>The thing was explicitly disabled.</td></tr>
|
||||
<tr valign="top"><td>INITIALIZING</td> <td>NONE</td><td>No further status details available.</td></tr>
|
||||
<tr valign="top"><td>UNKNOWN</td> <td>NONE</td><td>No further status details available.</td></tr>
|
||||
<tr valign="top"><td rowspan="2">ONLINE</td> <td>NONE</td><td>No further status details available.</td></tr>
|
||||
<tr valign="top"> <td>CONFIGURATION_PENDING</td><td>The Thing is waiting to transfer configuration information to a device. Some bindings need to communicate with the device to make sure the configuration is accepted.</td></tr>
|
||||
<tr valign="top"><td rowspan="7">OFFLINE</td> <td>NONE</td><td>No further status details available.</td></tr>
|
||||
<tr valign="top"> <td>COMMUNICATION_ERROR</td><td>Error in communication with the device. This may also be only a temporary error.</td></tr>
|
||||
<tr valign="top"> <td>CONFIGURATION_ERROR</td><td>An issue with the configuration of a Thing prevents the communication with the represented device or service. This issue might be solved by reconfiguring the Thing.</td></tr>
|
||||
<tr valign="top"> <td>BRIDGE_OFFLINE</td><td>Assuming the Thing to be offline because the corresponding bridge is offline.</td></tr>
|
||||
<tr valign="top"> <td>FIRMWARE_UPDATING</td><td>The Thing is currently operating a firmware update.</td></tr>
|
||||
<tr valign="top"> <td>DUTY_CYCLE</td><td>The Thing is currently in DUTY_CYCLE state, which means it is blocked for further usage.</td></tr>
|
||||
<tr valign="top"> <td>GONE</td><td>The Thing has been removed from the bridge or the network to which it belongs and is no longer available for use. The user can now remove the Thing from the system.</td></tr>
|
||||
<tr valign="top"><td>REMOVING</td> <td>NONE</td><td>No further status details available.</td></tr>
|
||||
<tr valign="top"><td>REMOVED</td> <td>NONE</td><td>No further status details available.</td></tr>
|
||||
</table>
|
||||
|
||||
### Status Description
|
||||
|
||||
To provide additional information about the current status a description is used.
|
||||
The status description is to be specified by the binding.
|
||||
This description can be used for debugging purposes and should not be presented to the user, as it might contain unreadable technical information (e.g. an HTTP status code, or any other protocol specific information, which helps to identify the current problem).
|
||||
|
||||
### Thing Status API
|
||||
|
||||
The Thing interface defines a method `getStatusInfo()` to retrieve the current status of the Thing.
|
||||
The following code shows how to print the status of each Thing into the console:
|
||||
|
||||
```java
|
||||
Collection<Thing> things = thingRegistry.getAll();
|
||||
for (Thing thing : things) {
|
||||
ThingStatusInfo statusInfo = thing.getStatusInfo();
|
||||
switch (statusInfo.getStatus()) {
|
||||
case ONLINE:
|
||||
System.out.println("Thing is online");
|
||||
break;
|
||||
case OFFLINE:
|
||||
System.out.println("Thing is offline");
|
||||
break;
|
||||
default:
|
||||
System.out.println("Thing is in state " + statusInfo.getStatus());
|
||||
break;
|
||||
}
|
||||
System.out.println("Thing status detail: " + statusInfo.getStatusDetail());
|
||||
System.out.println("Thing status description: " + statusInfo.getDescription());
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,189 @@
|
|||
---
|
||||
layout: documentation
|
||||
title: Units Of Measurement
|
||||
---
|
||||
|
||||
{% include base.html %}
|
||||
|
||||
# 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.
|
||||
|
||||
## QuantityType
|
||||
|
||||
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:
|
||||
Depended on the configured locale the framework tries to convert a `QuantityType` to the default unit of the matching measurement system.
|
||||
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) |
|
||||
| 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)|
|
||||
| Angle | Degree (°) | Degree (°) |
|
||||
|
||||
## 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.
|
||||
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.
|
||||
In addition 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:
|
||||
|
||||
|
||||
<channel-type id="temperature">
|
||||
<item-type>Number:Temperature</item-type>
|
||||
<label>Temperature</label>
|
||||
<description>Current temperature</description>
|
||||
<state readOnly="true" pattern="%.1f %unit%" />
|
||||
</channel-type>
|
||||
|
||||
The state description pattern "%.1f %unit%" describes the value format as floating point with one decimal place and also the special placeholder for the unit.
|
||||
|
||||
## 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 `MetricPrefix` class provides prefixes like MILLI, CENTI, HECTO, etc. 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.
|
||||
|
||||
## List of Units
|
||||
|
||||
All units which are currently supported by default are listed in the tables below.
|
||||
|
||||
|
||||
Imperial:
|
||||
|
||||
| Type | Unit | Symbol |
|
||||
|-------------|-----------------|--------|
|
||||
| Pressure | Inch of Mercury | inHg |
|
||||
| Temperature | Fahrenheit | °F |
|
||||
| Speed | Miles per Hour | mph |
|
||||
| Length | Inch | in |
|
||||
| Length | Foot | ft |
|
||||
| Length | Yard | yd |
|
||||
| Length | Chain | ch |
|
||||
| Length | Furlong | fur |
|
||||
| Length | Mile | mi |
|
||||
| Length | League | lea |
|
||||
|
||||
SI:
|
||||
|
||||
| Type | Unit | Symbol |
|
||||
|------------------------|-------------------------|--------|
|
||||
| Acceleration | Metre per square Second | m/s2 |
|
||||
| AmountOfSubstance | Mole | mol |
|
||||
| Angle | Radian | rad |
|
||||
| Angle | Degree | ° |
|
||||
| Angle | Minute Angle | ' |
|
||||
| Angle | Second Angle | '' |
|
||||
| Area | Square Metre | m2 |
|
||||
| ArealDensity | Dobson Unit | DU |
|
||||
| CatalyticActivity | Katal | kat |
|
||||
| Dimensionless | Percent | % |
|
||||
| Dimensionless | Parts per Million | ppm |
|
||||
| Dimensionless | Decibel | dB |
|
||||
| ElectricPotential | Volt | V |
|
||||
| ElectricCapacitance | Farad | F |
|
||||
| ElectricCharge | Coulomb | C |
|
||||
| ElectricConductance | Siemens | S |
|
||||
| ElectricCurrent | Ampere | A |
|
||||
| ElectricInductance | Henry | H |
|
||||
| ElectricResistance | Ohm | Ω |
|
||||
| Energy | Joule | J |
|
||||
| Energy | Watt Second | Ws |
|
||||
| Energy | Watt Hour | Wh |
|
||||
| Energy | KiloWatt Hour | kWh |
|
||||
| Force | Newton | N |
|
||||
| Frequency | Hertz | Hz |
|
||||
| Illuminance | Lux | lx |
|
||||
| Intensity | Irradiance | W/m² |
|
||||
| Length | Metre | m |
|
||||
| Length | Kilometre | km |
|
||||
| LuminousFlux | Lumen | lm |
|
||||
| LuminousIntensity | Candela | cd |
|
||||
| MagneticFlux | Weber | Wb |
|
||||
| MagneticFluxDensity | Tesla | T |
|
||||
| Mass | Kilogram | kg |
|
||||
| Mass | Gram | g |
|
||||
| Power | Watt | W |
|
||||
| Pressure | Pascal | Pa |
|
||||
| Pressure | hectoPascal | hPa |
|
||||
| Pressure | Millimetre of Mercury | mmHg |
|
||||
| Pressure | Bar | bar |
|
||||
| Pressure | milliBar | mbar |
|
||||
| Radioactivity | Becquerel | Bq |
|
||||
| RadiationDoseAbsorbed | Gray | Gy |
|
||||
| RadiationDoseEffective | Sievert | Sv |
|
||||
| SolidAngle | Steradian | sr |
|
||||
| Speed | Metre per Second | m/s |
|
||||
| Speed | Kilometre per Hour | km/h |
|
||||
| Speed | Knot | kn |
|
||||
| Temperature | Kelvin | K |
|
||||
| Temperature | Celsius | °C |
|
||||
| Time | Second | s |
|
||||
| Time | Minute | min |
|
||||
| Time | Hour | h |
|
||||
| Time | Day | d |
|
||||
| Time | Week | week |
|
||||
| Time | Year | y |
|
||||
| Volume | Cubic Metre | m3 |
|
||||
|
||||
Prefixes:
|
||||
|
||||
| Name | Symbol | Value |
|
||||
|-------|--------|-------|
|
||||
| Yotta | Y | 10²⁴ |
|
||||
| Zetta | Z | 10²¹ |
|
||||
| Exa | E | 10¹⁸ |
|
||||
| Peta | P | 10¹⁵ |
|
||||
| Tera | T | 10¹² |
|
||||
| Giga | G | 10⁹ |
|
||||
| Mega | M | 10⁶ |
|
||||
| Kilo | k | 10³ |
|
||||
| Hecto | h | 10² |
|
||||
| Deca | da | 10 |
|
||||
| Deci | d | 10⁻¹ |
|
||||
| Centi | c | 10⁻² |
|
||||
| Milli | m | 10⁻³ |
|
||||
| Micro | µ | 10⁻⁶ |
|
||||
| Nano | n | 10⁻⁹ |
|
||||
| Pico | p | 10⁻¹² |
|
||||
| Femto | f | 10⁻¹⁵ |
|
||||
| Atto | a | 10⁻¹⁸ |
|
||||
| Zepto | z | 10⁻²¹ |
|
||||
| Yocto | y | 10⁻²⁴ |
|
||||
|
||||
|
||||
To use the prefixes simply add the prefix to the unit symbol e.g.
|
||||
|
||||
Examples:
|
||||
-milliAmpere - `mA`
|
||||
-centiMetre - `cm`
|
||||
-kiloWatt - `kW`
|
||||
Loading…
Reference in New Issue