diff --git a/concepts/units-of-measurement.md b/concepts/units-of-measurement.md index c3a44d12cf..67cbaba45a 100644 --- a/concepts/units-of-measurement.md +++ b/concepts/units-of-measurement.md @@ -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 diff --git a/configuration/items.md b/configuration/items.md index 17cae6399f..e6b4694e23 100644 --- a/configuration/items.md +++ b/configuration/items.md @@ -296,31 +296,78 @@ In the example below, the "switch" icon has been selected: Switch Livingroom_Light "Livingroom Ceiling Light" ``` +#### 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, `` references the "favorite" icon from the Material icons. +`` 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, `` 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 Parent_Bedroom_Light "Parent Bedroom Light" +Switch Child_Bedroom_Light "Child Bedroom Light" +Switch Bathroom_Light "Bathroom Light" +Switch Kitchen_Light "Kitchen Light" +Switch Garage_Light "Garage Light" +``` + +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. @@ -332,7 +379,7 @@ Dynamic icon filenames follow the pattern below: -. ``` -- `` - the name of the icon set +- `` - the name of the icon - `-` - the Item state the icon maps to in lowercase (e.g. "-on" or "-off", "-open" or "-closed") - `` - bitmap (`png`) or vector graphic (`svg`) icon file extension ([see above](#icons)) @@ -340,7 +387,7 @@ 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 @@ -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. diff --git a/developers/addons/addon.md b/developers/addons/addon.md index d1e710864f..30cf4887e6 100644 --- a/developers/addons/addon.md +++ b/developers/addons/addon.md @@ -41,18 +41,18 @@ If the add-on consists of more than one bundle, only one `addon.xml` is allowed ``` -| Property | Description | | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -| addon.id | An identifier for the add-on | mandatory | -| type | Either `automation`, `binding`, `misc`, `persistence`, `transform`, `ui` or `voice` | mandatory | -| name | A human-readable name for the add-on | mandatory | -| description | A human-readable description for the add-on | optional | -| connection | `local` for add-ons that only interact locally, `cloud` for add-ons that require a cloud connection, `cloudDiscovery` for add-ons that require a cloud connection for set-up | optional | -| countries | List of two-letter ISO country codes that are supported (all countries if empty) | optional | -| service-id | The ID (service.pid or component.name) of the main binding service, which can be configured through OSGi configuration admin service. Should only be used in combination with a config description definition | optional | -| config-description | The configuration description for the binding within the ConfigDescriptionRegistry (cf. [Configuration Description](config-xml.html)) | optional | -| config-description-ref | The reference to a configuration description for the binding within the ConfigDescriptionRegistry | optional | -| config-description-ref.uri | The URI of the configuration description for the binding within the ConfigDescriptionRegistry | mandatory | +| Property | Description | | +| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | +| addon.id | An identifier for the add-on | mandatory | +| type | Either `automation`, `binding`, `misc`, `persistence`, `transform`, `ui` or `voice` | mandatory | +| name | A human-readable name for the add-on | mandatory | +| description | A human-readable description for the add-on | optional | +| connection | `none` for add-ons that have no interactions with external systems at all, `local` for add-ons that only interact locally without internet access, `hybrid` for add-ons that interact locally without internet access, but can optionally use a cloud connection for extended functionality (such as discovery), `cloud` for add-ons that require a cloud connection | optional | +| countries | List of two-letter ISO country codes (ISO 3166-1 alpha-2) that are supported (all countries if empty). Must be in lowercase | optional | +| service-id | The ID (service.pid or component.name) of the main binding service, which can be configured through OSGi configuration admin service. Should only be used in combination with a config description definition | optional | +| config-description | The configuration description for the binding within the ConfigDescriptionRegistry (cf. [Configuration Description](config-xml.html)) | optional | +| config-description-ref | The reference to a configuration description for the binding within the ConfigDescriptionRegistry | optional | +| config-description-ref.uri | The URI of the configuration description for the binding within the ConfigDescriptionRegistry | mandatory | The full XML schema for add-on definitions is specified in the [Add-on XSD](https://openhab.org/schemas/addon-1.0.0.xsd) file. diff --git a/images/addons/liquidcheck.png b/images/addons/liquidcheck.png new file mode 100644 index 0000000000..87628f0cb3 Binary files /dev/null and b/images/addons/liquidcheck.png differ diff --git a/installation/index.md b/installation/index.md index 9704783f6f..cadf0ec8b5 100644 --- a/installation/index.md +++ b/installation/index.md @@ -130,3 +130,29 @@ or by working on your own configuration. The very active [openHAB Community Forum](https://community.openhab.org) can provide you with many more details, hints, and tips. If you run into any problems, use the search function in the forum or open a new thread with your detailed question. + +## Upgrading + +In some cases upgrading to a new version of openHAB requires additional steps. +For textual based configuration this can usually be done using a text editor or VS Code. +UI configuration updates to the JSON database should not be done manually but by using the upgrade tool. + +The upgrade tool is a java application and allows performing different steps. +Each step can only be executed once (unless you `--force` the tool to perform them again). +Currently the following steps are supported as arguments to `--command`: + +- `itemCopyUnitToMetadata`: With openHAB 4 presentation and internal representation of the unit of an item are separated. +This step copies the unit set in the state description of an item to the new `unit` metadata. +This is necessary to keep units consistent for data persisted with previous versions of openHAB. +- `linkUpgradeJsProfile`: The JS Scripting transformation/profile has been removed because of changing to Java 17. +They have been replaced by the generic script transformation/profile which require different configuration options. +This step rewrites the profiles to the new format. + +The upgrade tool needs to know the path to the openHAB userdata folder (e.g. `/var/lib/openhab` on most Debian like systems). +If the tool is not operated from that folder, it can be specified by using `--dir /var/lib/openhab` on the commandline. + +Example: + +```shell +java -jar upgradetool.jar --dir /var/lib/openhab --command itemCopyUnitToMetadata +``` diff --git a/tutorials/getting_started/item_widgets.md b/tutorials/getting_started/item_widgets.md index 92d497f9cd..83910a14e3 100644 --- a/tutorials/getting_started/item_widgets.md +++ b/tutorials/getting_started/item_widgets.md @@ -35,8 +35,8 @@ For complicated expressions, gradually build up the expression in this tool unti ## Visibility -Each custom defined widget has a "Visibility" and "Visible to" property. -The "Visibility" option takes a boolean `true` or `false` (without quotes) or the result of a boolean expression to determine whether or not to render the widget. +Each custom defined widget has a "Visibility" and a "Visible to" property. +The "Visibility" option takes a boolean `true` or `false` or the result of a boolean expression to determine whether or not to render the widget. The "Visibile to" property controls which type of user can see the widget. Take heed of the warning, this is not a security feature, but it can be used to limit what a regular user can see in the automatically generated parts of the Overview Page. diff --git a/ui/layout-pages.md b/ui/layout-pages.md index 66f3c7c878..a99ee33750 100644 --- a/ui/layout-pages.md +++ b/ui/layout-pages.md @@ -202,7 +202,7 @@ _Screen Width:_ Screen width in CSS pixels. Defaults to 1280. _Screen Height:_ -Screen width in CSS pixels. Defaults to 720. +Screen height in CSS pixels. Defaults to 720. _Scaling:_ Enabling this scales the defined screen to the width available in the browser window. @@ -257,7 +257,7 @@ _Screen Width:_ Screen width in CSS pixels. Defaults to 1280. _Screen Height:_ -Screen width in CSS pixels. Defaults to 720. +Screen height in CSS pixels. Defaults to 720. _Scaling:_ Enabling this scales the defined screen to the width available in the browser window. All widgets are resized accordingly. diff --git a/ui/sitemaps.md b/ui/sitemaps.md index 5d344a86ca..fcc835a2c0 100644 --- a/ui/sitemaps.md +++ b/ui/sitemaps.md @@ -497,7 +497,7 @@ Video url="https://demo.openhab.org/Hue.m4v" ```java Chart [item=] [icon=""] [label=""] [refresh=xxxx] -[period=xxxx] [service=""] [legend=true/false] [forceasitem=true/false] +[period=xxxx] [service=""] [legend=true/false] [forceasitem=true/false] [yAxisDecimalPattern=xxxx] ``` Adds a time-series chart object for the display of logged data. @@ -516,6 +516,10 @@ Adds a time-series chart object for the display of logged data. - `forceasitem` is used to show the value of a `Group` instead of showing a graph for each member (which is the default). +- `yAxisDecimalPattern` is used to format the values on the y axis. + It accepts [DecimalFormat](https://docs.oracle.com/javase/7/docs/api/java/text/DecimalFormat.html). + For example with `#.##` a number has to decimals. + Visit [Charts](https://github.com/openhab/openhab/wiki/Charts) in the Wiki for examples. **Other options to look out for:**