Merge branch 'openhab:main' into main

.vuepress/config.js

@@ -10,7 +10,7 @@ const HighlightRules = require('./highlight-rules')
 const base = process.env.OH_DOCS_VERSION ? `/v${process.env.OH_DOCS_VERSION}/` : '/'
 
 module.exports = {
-  title: 'v3 Documentation Preview',
+  title: 'v4 Documentation Preview',
   description: 'This is a preview of the main parts of the documentation, found in the openhab/openhab-docs repository',
   dest: 'vuepress',
   host: 'localhost',

configuration/items.md

@@ -552,18 +552,17 @@ The last Group counts all members of it matching the given regular expression, h
 
 Tags added to an Item definition allow a user to characterize the specific nature of the Item beyond its basic Item type.
 Tags can then be used by add-ons to interact with Items in context-sensitive ways.
+Tags are used by the [Semantic Model]({{base}}/tutorial/model.html).  The `"Light"` example below maps the item to the Semantic Model.
 
 Example:
 A Light in a typical home setup can be represented by a Switch, a Dimmer or a Color Item.
 To be able to interact with the light device via a natural voice command, for example, the fact that the Item is a light can be established by adding the "Lighting" tag as shown below.
 
 ```java
-Switch Livingroom_Light "Livingroom Ceiling Light" ["Lighting"]
+Switch Livingroom_Light "Livingroom Ceiling Light" ["Light"]
 ```
 
-Tagging is a new feature and only a few I/O add-ons have implemented it.
 The easiest way to determine if tags have been implemented in a specific add-on is to see if the add-on documentation explicitly discusses their usage.
-Tags will be ignored if no Items in the openHAB installation support it.
 
 See the [Hue Emulation Service](/addons/integrations/hueemulation/) or [HomeKit Add-on](/addons/integrations/homekit/) documentation for more details.
 

configuration/persistence.md

@@ -65,14 +65,92 @@ The following strategies are defined internally and may be used in place of `str
 openHAB uses [Quartz](https://www.quartz-scheduler.org/documentation) for time-related cron events.
 See the [Rules article]({{base}}/configuration/rules-dsl.html#time-based-triggers) for more information.
 
+### Filters
+
+This (optional) section allows you to name and define one or more `Filters`.
+The syntax is as follows:
+
+```java
+Filters {
+  <filterName1> : <filter definition>
+  <filterName2> : <filter definition>
+  ...
+}
+```
+
+Each filter definition starts with a unique identifier that identifies the filter type.
+
+#### Equals Filter `=` / Not Equals Filter (`!`)
+
+The equals (not equals) filter allows to persist only a given set of values (or exclude them).
+It can be used with every item type.
+The values need to be exactly the string representation of the state.
+One or more values can be given, separated by a comma `,`.
+
+```java
+Filters {
+  exactlySomeState : = "ARMED", "UNARMED"
+  notTheseStates : ! "UNDEF", "NULL"
+}
+```
+
+#### Threshold Filter (`>`)
+
+The threshold filter allows to discard values that are close to the last persisted value.
+It can only be used with `Number` items and has two modes: "relative" and "absolute".
+
+In "relative" mode the threshold is calculated as percentage of the last persisted value.
+This mode is selected by a `%` character and a decimal value (e.g. `> % 10` for "at least 10% deviation").
+
+In "absolute" mode the threshold is calculated by absolute difference to the last persisted value.
+This mode is selected by a decimal value with optional unit (e.g. `> 5 mA` for "at least 5 mA deviation").
+For plain `Number` items the unit can be omitted.
+
+```java
+Filters {
+  fiveMilliAmps : > 5 mA
+  tenPercent : > % 10
+}
+```
+
+#### Include Filter (`[]`) / Exclude Filter (`][`)
+
+The include (exclude) filter allows to define a range for accepted (rejected) values.
+It can only be used with `Number` items.
+
+The range is defined by to decimal values.
+The boundaries are always considered to be part (not part) of the defined range (i.e. a lower boundary of `5` considers a value of `5` to be inside the range for an include filter and outside of the range for exclude filters).
+In case of dimensional items (e.g `Number:Temperature`) a unit MUST be provided.
+
+```java
+Filters {
+  fromFiveToTenKelvin : [] 5 10 K
+  notBetweenSevenAndNine : ][ 7 9
+}
+```
+
+#### Time Filter (`T`)
+
+The time filter allows to discard values that arrive within the given time after a previous value (e.g. when using the `everyUpdate` strategy).
+It can be used with every item type.
+The filter definition consists of an integer value followed by a unit.
+The allowed units are `s` (seconds), `m` (minutes), `h` hours and `d` days.
+Composed values (`1 m 30 s`) are not possible and need to be expressed by a single value (`90 s`).
+
+```java
+Filters {
+  thirtySeconds : T 30 s
+}
+```
+
 ### Items
 
-This section defines which items should be persisted with which strategy.
+This section defines which items should be persisted with which strategy and filters.
 The syntax is as follows:
 
 ```java
 Items {
-    <itemlist1> [-> "<alias1>"] : [strategy = <strategy1>, <strategy2>, ...]
+    <itemlist1> [-> "<alias1>"] : [strategy = <strategy1>, <strategy2>, ...] [filter = <filter1>, <filter2>, ...]
     <itemlist2> [-> "<alias2>"] : [strategy = <strategyX>, <strategyY>, ...]
     ...
 
@@ -99,6 +177,10 @@ Strategies {
         everyDay  : "0 0 0 * * ?"
 }
 
+Filters {
+        fivepercent : > % 5
+        atMostOnceAMinute : T 1 m
+  }
 /*
  * Each line in this section defines for which Item(s) which strategy(ies) should be applied.
  * You can list single items, use "*" for all items or "groupitem*" for all members of a group

developers/guidelines.md

@@ -180,13 +180,13 @@ class MyCoolClass {
 }
 ```
 
-- Parametrized logging must be used (instead of string concatenation).
+- Parameterized logging must be used (instead of string concatenation).
 
 ```java
 void myFun() {
     String someValue = "abc";
     int someInt = 12;
-    logger.log("Current value is {} and int is {}", someValue, someInt);
+    logger.debug("Current value is {} and int is {}", someValue, someInt);
 }
 ```
 

tutorials/getting_started/custom_widgets.md

@@ -130,7 +130,7 @@ config:
   iconColor: '=(items[props.item].state == "ON") ? "yellow" : "gray"'
   title: =props.title
   color: '=(items[props.item].state == "ON") ? "yellow" : "gray"'
-  item: props.item
+  item: =props.item
 ```
 
 Save the widget and return to one of the Items that should use this widget.

tutorials/getting_started/tips-and-tricks.md

@@ -53,7 +53,7 @@ The developer sidebar search ignores case and searches inside the following enti
   - name
   - label
   - tags (requires exact match)
-  - metadata namespaces (requires exact match)
+  - metadata
 - Pages
   - uid
   - label
@@ -62,6 +62,8 @@ The developer sidebar search ignores case and searches inside the following enti
   - Item name & Thing UID of triggers, actions & conditions
   - script code (e.g. Rules DSL, JavaScript, and even Blockly)
   - script MIME types (requires exact match)
+  - Blockly scripts (using 'block', 'blockly' or 'blocksource' as search string, where case is ignored)
+  - tags (requires exact match)
 
 ### Pinned Objects
 

ui/sitemaps.md

@@ -496,8 +496,8 @@ Video url="https://demo.openhab.org/Hue.m4v"
 ### Element Type 'Chart'
 
 ```java
-Chart [item=<itemname>] [icon="<iconname>"] [label="<labelname>"] [refresh=xxxx]
-[period=xxxx] [service="<service>"] [legend=true/false] [forceasitem=true/false] [yAxisDecimalPattern=xxxx]
+Chart item=<itemname> [icon="<iconname>"] [label="<labelname>"] [refresh=xxxx]
+period=xxxx [service="<service>"] [legend=true/false] [forceasitem=true/false] [yAxisDecimalPattern=xxxx]
 ```
 
 Adds a time-series chart object for the display of logged data.