Skip to content

Commit

Permalink
Merge branch 'openhab:main' into main
Browse files Browse the repository at this point in the history
  • Loading branch information
@stefan-hoehn
stefan-hoehn authored May 27, 2023
2 parents 58cde9e + 524cf43 commit 5e7d0d5
Show file tree
Hide file tree
Showing 8 changed files with 178 additions and 60 deletions.
97 changes: 69 additions & 28 deletions concepts/units-of-measurement.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,34 +22,75 @@ 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.
The placeholder `%unit%` can be placed anywhere in the state description.
| Dimension | default unit metric | default unit imperial |
|--------------------------|----------------------------------|----------------------------------|
| Acceleration | Meter per square second (m/s²) | Meter per square second (m/s²) |
| Amount of Substance | Mole (mol) | Mole (mol) |
| Angle | Degree (°) | Degree (°) |
| Area | Square Meter (m²) | Square foot (ft²) |
| Areal Density | Dobson unit (DU) | Dobson unit (DU) |
| Catalytic Activity | Katal (kat) | Katal (kat) |
| Data Amount | Byte (B) | Byte (B) |
| Data Transfer Rate | Megabit per second (Mbit/s) | Megabit per second (Mbit/s) |
| Density | Kilogram per cubic meter (kg/m³) | Kilogram per cubic meter (kg/m³) |
| Dimensionless | Abstract unit one (one) | Abstract unit one (one) |
| Electric Capacitance | Farad (F) | Farad (F) |
| Electric Charge | Coulomb (C) | Coulomb (C) |
| Electric Conductance | Siemens (S) | Siemens (S) |
| Electric Conductivity | Siemens per meter (S/m) | Siemens per meter (S/m) |
| Electric Current | Ampere (A) | Ampere (A) |
| Electric Inductance | Henry (H) | Henry (H) |
| Electric Potential | Volt (V) | Volt (V) |
| Electric Resistance | Ohm (Ω) | Ohm (Ω) |
| Energy | Kilowatt hours (kWh) | Kilowatt hours (kWh) |
| Force | Newton (N) | Newton (N) |
| Frequency | Hertz (Hz) | Hertz (Hz) |
| Illuminance | Lux (lx) | Lux (lx) |
| Intensity | Irradiance (W/m²) | Irradiance (W/m²) |
| Length | Meter (m) | Inch (in) |
| Luminous Flux | Lumen (lm) | Lumen (lm) |
| Luminous Intensity | Candela (cd) | Candela (cd) |
| Magnetic Flux | Weber (Wb) | Weber (Wb) |
| Magnetic Flux Density | Tesla (T) | Tesla (T) |
| Mass | Kilogram (kg) | Pound (lb) |
| Power | Watt (W) | Watt (W) |
| Pressure | Hectopascal (hPa) | Inch of mercury (inHg) |
| Radiation Absorbed Dose | Gray (Gy) | Gray (Gy) |
| Radiation Effective Dose | Sievert (Sv) | Sievert (Sv) |
| Radioactivity | Becquerel (Bq) | Becquerel (Bq) |
| Solid Angle | Steradian (sr) | Steradian (sr) |
| Speed | Kilometers per hour (km/h) | Miles per hour (mph) |
| Temperature | Celsius (°C) | Fahrenheit (°F) |
| Time | Seconds (s) | Seconds (s) |
| Volume | Cubic Meter (m³) | US Gallon (gal) |
| Volumetric Flow Rate | Liter per minute (l/min) | US Gallon per minute (gal/min) |

In some cases the system default unit may not be the most useful unit for a given quantity.
For measuring precipitation km/h would be a quite uncommon unit, while mm/h would be the expected unit.
You can set the `unit` metadata to a different unit to change the item's unit:

```shell
Number:Speed "Rainfall" { unit="mm/h" }
```
This unit is then also used for persistence.
Setting the `unit` metadata to `kW` would persist 5.0 for a value of 5.0 kW (while 5000 would be persisted without because the system default is W).
Attention: Changing the unit of an item may corrupt your already persisted data, no automatic conversion takes place.
The unit of the item is independent of the state description.
The state description is used for display purposes only, it can contain any compatible unit and will not affect what is persisted or used in events.
## Number item with dimension and DecimalType
A `DecimalType` state update or command to a `Number` item that contains a dimension is considered to have the item's unit.
So updating a `Number:Length` item with `5.0` will set the item's state to 5 m or 5 in. (depending on your locale).
In case you set a different unit (see above, e.g. `km`) that is taken and the item will set it's state to 5 km.
## Number item without dimension and QuantityType
A `QuantityType` state update or command to a non-dimensional `Number` item will result in a state update that consists of the numeric part only.
So updating a `Number` item with `5.0 kW` will set the item's state to 5.0, updating the same item with `5.0 W` will also set the item's state to 5.0.
Linking dimension channels to non-dimensional items is therefore discouraged and will not be permitted in future versions of openHAB.
### Defining ChannelTypes
Expand Down
77 changes: 62 additions & 15 deletions configuration/items.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -296,31 +296,78 @@ In the example below, the "switch" icon has been selected:
Switch Livingroom_Light "Livingroom Ceiling Light" <switch>
```

#### Icons provided with openHAB

openHAB provides a set of [classic icons](/docs/configuration/iconsets/classic/) by default.
Users may add their own icons in either `png` or `svg` format in the openHAB icons configuration folder, `$OPENHAB_CONF/icons/classic/`.
The community marketplace provides other openHAB icon sets that can be installed, e.g. [this subset of iconify icons]( https://community.openhab.org/t/iconify-icon-provider/144508).
Users may also add their own icons in either `png` or `svg` format in the openHAB icons configuration folder, `$OPENHAB_CONF/icons/classic/`.

The following guidelines apply to user-added icon files:

- Only `png` or `svg` file formats may be used
- Icon filenames may include lowercase letters, numbers and underscores (`_`)
- Hyphens (`-`) are reserved for [Dynamic Icons](#dynamic-icons)
- Icon filenames may include lowercase letters, numbers, hyphens (`-`) and underscores (`_`)
- Example filenames:
- Good: `myswitch.svg`, `power_meter.png`, `tuer23.svg`
- Bad: `MySwitch.svg`, `power-meter.png`, `tür23.svg`

**Bitmaps or Vector Graphics:**
openHAB can work with either Bitmap (`png`) or Vector (`svg`) icon files.
The format should match the display capabilities of the user interfaces in use (e.g. Basic UI).
The format should match the display capabilities of the user interfaces in use.
It is thereby important to decide on one format beforehand; vector graphics are recommended.
The setting can be changed via UI for most user interfaces.
Most user interfaces don't expose this setting because they support both formats transparently.
But the setting can be changed via UI in certain user interfaces.
Please check the user interface documentation if in doubt.
Note that image files with the wrong file ending will be ignored.

Users may substitute their own icon for an icon from the default icon set by placing a file in the `$OPENHAB_CONF/icons/classic/` folder with the same filename as the name of the icon being substituted.

#### Icon sources

Some user interfaces supports other icons than those provided by openHAB.
Thus, the most generic reference to an icon is composed of 3 segments separated by a colon:

1. The first segment is the icon source, e.g. "oh"

1. The second segment is the icon set from this source, e.g. "classic"

1. The third segment is the name of an icon in this set, e.g. "switch"

If the value contains only two segments, the first segment is assumed to be the icon source and the second the icon name.
In this case, the icon set is to "classic" by default.
This is used in particular when the icon source only provides a single set of icons.
As an example, `<material:favorite>` references the "favorite" icon from the Material icons.
`<oh:switch>` references the "switch" icon from the openHAB classic icon set.

If the value contains only one segment, it is assumed to be the name of an icon from the openHAB classic icon set.
As an example, `<switch>` references the "switch" icon from the openHAB classic icon set.

Here are few examples showing the different options:

```java
Switch Livingroom_Light "Livingroom Ceiling Light" <switch>
Switch Parent_Bedroom_Light "Parent Bedroom Light" <oh:switch>
Switch Child_Bedroom_Light "Child Bedroom Light" <oh:classic:switch>
Switch Bathroom_Light "Bathroom Light" <material:lightbulb>
Switch Kitchen_Light "Kitchen Light" <f7:lightbulb>
Switch Garage_Light "Garage Light" <if:mdi:lightbulb>
```

Here is the list of available icon sources and how they are supported by the major user interfaces.

| Source name | Source description | Main UI | Basic UI | Android app | iOS app |
| -------------------- | ------------------------------------- | ---------- | --------------------------------- | ----------------- | ----------------- |
| `oh` | Icons provided via the openHAB server | Supported | Supported | Supported | Supported |
| `material` | [Material icons](https://fonts.google.com/icons?icon.set=Material+Icons) | Supported | Supported | Not yet supported | Not yet supported |
| `f7` | [Framework7 icons](https://framework7.io/icons/) | Supported | Not yet supported | Not yet supported | Not yet supported |
| `if` or `iconify` | [iconify icons](https://icon-sets.iconify.design/) | Supported | Supported but needs to be enabled | Not yet supported | Not yet supported |

Please note that the iconify option requires Internet connectivity on the client to access the external API.
The WEB browser will cache the retrieved icons to limit the requests and speed up the rendering.
Certain user interfaces provide a setting to enable this option, e.g. Basic UI disables this option by default but allows it to be enabled.

#### Dynamic Icons

Some icons are dynamically selected by openHAB depending on the Item's state.
If and only if the icon source is openHAB, some icons are dynamically selected by openHAB depending on the Item's state.
For example, a "switch" icon may appear to be green when the Item is "ON" and red when the item is "OFF.
Behind the scenes, openHAB is actually selecting two different icon files depending upon the Item state - `switch-on` or `switch-off`.
A third default icon file, `switch`, is required as well.
Expand All @@ -332,15 +379,15 @@ Dynamic icon filenames follow the pattern below:
<name>-<state>.<extension>
```

- `<name>` - the name of the icon set
- `<name>` - the name of the icon
- `-<state>` - the Item state the icon maps to in lowercase (e.g. "-on" or "-off", "-open" or "-closed")
- `<extension>` - bitmap (`png`) or vector graphic (`svg`) icon file extension ([see above](#icons))

Dynamic icon sets may consist of as many state-specific icon files as needed.
Each set must meet the following criteria:

- A default icon is mandatory.
The default icon filename is the name of the icon without a hyphen or state (e.g. `switch.svg`)
The default icon filename is the name of the icon without a state (e.g. `switch.svg`)

- Icon filenames must follow the naming restrictions given for [icons](#icons) above

Expand Down Expand Up @@ -476,13 +523,13 @@ Incompatible Item types within a Group may result in the invalid aggregation res
Examples for derived states on Group Items when declared in the Item DSL:

```java
Group:Number Lights "Active Lights [%d]" // e.g. "2"
Group:Switch:OR(ON,OFF) Lights "Active Lights [%d]" // e.g. ON and "2"
Group:Switch:AND(ON,OFF) Lights "Active Lights [%d]" // e.g. ON and "2"
Group:Number:AVG Temperatures "All Room Temperatures [%.1f °C]" // e.g. "21.3 °C"
Group:DateTime:EARLIEST LatestUpdate "Latest Update [%1$tY.%1$tm.%1$tY %1$tH:%1$tM:%1$tS]"
Group:DateTime:LATEST LastSeen "Last Seen [%1$tY.%1$tm.%1$tY %1$tH:%1$tM:%1$tS]"
Group:Number:COUNT("OFFLINE") OfflineDevices "Offline Devices [%d]" // e.g. "2"
Group:Number Lights "Active Lights [%d]" // e.g. "2"
Group:Switch:OR(ON,OFF) Lights "Active Lights [%d]" // e.g. ON and "2"
Group:Switch:AND(ON,OFF) Lights "Active Lights [%d]" // e.g. ON and "2"
Group:Number:Temperature:AVG Temperatures "All Room Temperatures [%.1f °C]" // e.g. "21.3 °C"
Group:DateTime:EARLIEST LatestUpdate "Latest Update [%1$tY.%1$tm.%1$tY %1$tH:%1$tM:%1$tS]"
Group:DateTime:LATEST LastSeen "Last Seen [%1$tY.%1$tm.%1$tY %1$tH:%1$tM:%1$tS]"
Group:Number:COUNT("OFFLINE") OfflineDevices "Offline Devices [%d]" // e.g. "2"
```

The first three examples above compute the number of active lights and store them as group state.
Expand Down
Loading

0 comments on commit 5e7d0d5

Please sign in to comment.