Merge branch 'main' into stateDescription_read_write

Author: stefan-hoehn

.vuepress/process_file.rb

@@ -116,10 +116,12 @@ def process_file(indir, file, outdir, source)
       line = line.gsub(%r{]\((.*)/(.*)\)}, '](../thing.html?manufacturer=\1&file=\2)') if file == "zwave/doc/things.md"
 
       # Misc replaces (relative links, remove placeholder interpreted as custom tags)
-      line = line.gsub("http://docs.openhab.org/addons/uis/habpanel/readme.html", "/docs/configuration/habpanel.html")
-      line = line.gsub("http://docs.openhab.org/addons/uis/basic/readme.html", "/addons/ui/basic/")
-      line = line.gsub(%r{http://docs\.openhab\.org/addons/(.*)/(.*)/readme\.html}, '/addons/\1/\2/')
-      line = line.gsub("http://docs.openhab.org/", "/docs/")
+      line = line.gsub(%r{https?://docs\.openhab\.org/addons/uis/habpanel/readme\.html}, "/docs/configuration/habpanel.html")
+      line = line.gsub(%r{https?://docs\.openhab\.org/addons/uis/basic/readme\.html}, "/addons/ui/basic/")
+      line = line.gsub(%r{https?://docs\.openhab\.org/addons/(.*)/(.*)/readme\.html}, '/addons/\1/\2/')
+      line = line.gsub(%r{https?://docs\.openhab\.org/}, "/docs/")
+      line = line.gsub(%r{https?://openhab\.org/docs/}, "/docs/")
+      line = line.gsub(%r{https?://www\.openhab\.org/docs/}, "/docs/")
       line = line.gsub("/addons/io/", "/addons/integrations/")
       line = line.gsub("{{base}}/", "./docs/")
       line = line.gsub("(images/", "(./images/")

configuration/items.md

@@ -674,22 +674,34 @@ This parameter allows to post an update or command to an item after a period of
 
 The expiration timer is started or restarted every time an item receives an update or a command _other than_ the specified "expire" update/command.
 Any future expiring update or command is cancelled, if the item receives an update or command that matches the "expire" update/command.
+See `ignoreStateUpdate` and `ignoreCommands` [configurations](#configurations-for-expire) below.
 
-The parameter accepts a duration of time that can be a combination of hours, minutes and seconds in the format
+The parameter accepts a duration of time that can be a combination of days, hours, minutes and seconds in the format `Xd Xh Xm Xs` where X is a _long_ integer.
+Every part is optional, but all parts present must be in the given order (days, hours, minutes, seconds).
+Whitespaces are allowed between the sections.
 
 ```shell
 expire="1h 30m 45s"
 expire="1h05s"
 expire="55h 59m 12s"
+expire="2d 7h 59m 12s"
 ```
 
-Every part is optional, but all parts present must be in the given order (hours, minutes, seconds).
-Whitespaces are allowed between the sections.
+A non-negative expiry value can be specified using the [ISO8601 Duration format](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/time/Duration.html#parse(java.lang.CharSequence)).
+Java's `Duration` class supports days, hours, minutes, and seconds.
+Note that while the ISO8601 format allows for fractional seconds, the openHAB `expire` feature only supports durations with a minimum granularity of one second.
+
+```shell
+expire="PT1H30M45S"
+expire="PT1H5S"
+expire="PT55H59M12S"
+expire="P2DT7H59M12S"
+```
 
 This duration can optionally be followed by a comma and the state or command to post, when the timer expires.
 If this optional section is not present, it defaults to the Undefined (`UnDefType.UNDEF`) state.
 
-```shell
+```java
 Player MyPlayer   { expire="1h,command=STOP" }                // send STOP command after one hour
 Number MyChannel  { channel="xxx", expire="5m,state=0" }      // update state to 0 after five minutes
 String MyMessage  { channel="xxx", expire="3m12s,Hello" }     // update state to Hello after three minutes and 12 seconds
@@ -701,6 +713,28 @@ Note that the `state=` part is optional.
 In the special case of a String item, it is possible to define a state/command as the string "UNDEF" or "NULL" by putting it into single quotes (e.g. "1m,state='UNDEF'").
 Without the quotes, the state would be the system type `UNDEF`.
 
+###### Configurations for `expire`
+
+The `expire` parameter is stored as an item metadata which supports the following configurations:
+
+| Configuration Parameter | Description                                                                                                                  |
+|:------------------------|:-----------------------------------------------------------------------------------------------------------------------------|
+| `duration`              | The expire duration as described above.                                                                                      |
+| `command`               | The command to send when the timer expires.                                                                                  |
+| `state`                 | The state to change the item to when the timer expires. This is mutually exclusive to the `command` parameter.               |
+| `ignoreStateUpdate`     | When set to true, do not reset or restart the expire timer when the item received a state update event. Defaults to `false`. |
+| `ignoreCommands`        | When set to true, do not reset or restart the timer when the item received a command. Defaults to `false`.                   |
+
+Examples:
+
+```java
+// These four definitions are equivalent
+Number MyChannel  { expire="5m,state=0" }
+Number MyChannel  { expire="5m,0" }
+Number MyChannel  { expire="5m" [state=0] }
+Number MyChannel  { expire="" [duration="5m", state=0] }
+```
+
 #### Profiles
 
 With Profiles, you are able to change the behavior how Channels interact with your Items.

configuration/rules-dsl.md

@@ -765,21 +765,24 @@ MyItem will automatically apply the method that corresponds to the argument type
 
 Besides the implicitly available variables for items and commands/states, rules can have additional pre-defined variables, depending on their triggers:
 
-- `receivedCommand` - implicitly available in every rule that has at least one command event trigger.
-- `previousState` - implicitly available in every rule that has at least one status change event trigger.
-- `newState` - implicitly available in every rule that has at least one status update or status change event trigger.
-- `triggeringItemName` - implicitly available in every rule that has at least one status update, status change or command event trigger.
-- `triggeringItem` - implicitly available in every rule that has a "Member of" trigger.
-- `triggeringGroupName` - implicitly available in every rule that has a "Member of" trigger.
-- `triggeringGroup` - implicitly available in every rule that has a "Member of" trigger.
-- `receivedEvent` - implicitly available in every rule that has a channel-based trigger.
-- `triggeringChannel` - implicitly available in every rule that has a channel-based trigger.
-- `triggeringThing` - implicitly available in every rule that has a thing-based trigger.
-- `previousThingStatus` - implicitly available in every rule that has a thing-based trigger.
-- `newThingStatus` - implicitly available in every rule that has a thing-based trigger.
-
-- `sharedCache` - a cache that is shared between all rules and all scripting languages
-- `privateCache` - a cache private to the script/rule that requests it
+| Variable              | Description                                                                                                                                                                                          |
+| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `receivedCommand`     | implicitly available in every rule that has at least one command event trigger.                                                                                                                      |
+| `previousState`       | implicitly available in every rule that has at least one status change event trigger.                                                                                                                |
+| `newState`            | implicitly available in every rule that has at least one status update or status change event trigger.                                                                                               |
+| `lastStateUpdate`     | implicitly available in every rule that has at least one status update or status change event trigger. This variable contains the time when the last state update occurred prior to the current one. |
+| `lastStateChange`     | implicitly available in every rule that has at least one status change event trigger. This variable contains the time when the last state change occurred prior to the current one.                  |
+| `triggeringItemName`  | implicitly available in every rule that has at least one status update, status change or command event trigger.                                                                                      |
+| `triggeringItem`      | implicitly available in every rule that has a "Member of" trigger.                                                                                                                                   |
+| `triggeringGroupName` | implicitly available in every rule that has a "Member of" trigger.                                                                                                                                   |
+| `triggeringGroup`     | implicitly available in every rule that has a "Member of" trigger.                                                                                                                                   |
+| `receivedEvent`       | implicitly available in every rule that has a channel-based trigger.                                                                                                                                 |
+| `triggeringChannel`   | implicitly available in every rule that has a channel-based trigger.                                                                                                                                 |
+| `triggeringThing`     | implicitly available in every rule that has a thing-based trigger.                                                                                                                                   |
+| `previousThingStatus` | implicitly available in every rule that has a thing-based trigger.                                                                                                                                   |
+| `newThingStatus`      | implicitly available in every rule that has a thing-based trigger.                                                                                                                                   |
+| `sharedCache`         | a cache that is shared between all rules and all scripting languages                                                                                                                                 |
+| `privateCache`        | a cache private to the script/rule that requests it                                                                                                                                                  |
 
 For further documentation on using the cache see [here](jsr223.html#cache-preset).
 

configuration/things.md

@@ -64,7 +64,7 @@ These files are stored in `$OPENHAB_CONF/things`.
 
 The syntax for `.things` files is defined as follows (parts in `<..>` are required):
 
-```xtend
+```java
 Thing <binding_id>:<type_id>:<thing_id> "Label" @ "Location" [ <parameters> ]
 ```
 
@@ -80,7 +80,7 @@ The type of the configuration parameter is determined by the binding and must be
 
 **Examples:**
 
-```xtend
+```java
 Thing network:device:webcam "Webcam" @ "Living Room" [ hostname="192.168.0.2", timeout="5000", ... ]
 Thing astro:moon:home [ geolocation="50.12345,10.98765", interval=300 ]
 Thing ntp:ntp:local [ hostname="de.pool.ntp.org" ]
@@ -101,7 +101,7 @@ Please check each individual binding's [documentation](/addons/#binding) for det
 
 Bridges can be defined together with contained things. The following configuration shows the definition of a Hue bridge with two Hue lamps:
 
-```xtend
+```java
 Bridge hue:bridge:mybridge [ ipAddress="192.168.3.123" ] {
  Thing 0210 bulb1 [ lightId="1" ]
  Thing 0210 bulb2 [ lightId="2" ]
@@ -115,7 +115,7 @@ The resulting UID of the thing is `hue:0210:mybridge:bulb1`.
 
 Bridges that are defined somewhere else can also be referenced in the DSL:
 
-```xtend
+```java
 Thing hue:0210:mybridge:bulb "Label" (hue:bridge:mybridge) @ "Location" [lightId="3"]
 ```
 
@@ -125,7 +125,7 @@ For the contained notation of things the UID will be inherited and the bridge ID
 
 **Example of a MQTT Bridge with Generic MQTT Things :**
 
-```xtend
+```java
 Bridge mqtt:broker:MyMQTTBroker [ host="192.168.178.50", secure=false, username="MyUserName", password="MyPassword"] {
   Thing topic sonoff_Dual_Thing "Light_Dual" @ "Sonoff" {
     Channels:
@@ -151,7 +151,7 @@ It is also possible to add additional channels to existing things and for bindin
 
 #### State channels
 
-```xtend
+```java
 Thing yahooweather:weather:losangeles [ location=2442047, unit="us", refresh=120 ] {
  Channels:
   State String : customChannel1 "My Custom Channel" [
@@ -167,7 +167,7 @@ The framework will merge the list of channels coming from the binding and the us
 
 As state channels are the default channels, you can omit the `State` keyword, the following example creates the same channels as the example above:
 
-```xtend
+```java
 Thing yahooweather:weather:losangeles [ location=2442047, unit="us", refresh=120 ] {
  Channels:
   String : customChannel1 "My Custom Channel" [
@@ -181,7 +181,7 @@ You may optionally give the channel a proper label (like “My Custom Channel”
 
 #### Trigger channels
 
-```xtend
+```java
 Thing yahooweather:weather:losangeles [ location=2442047, unit="us", refresh=120 ] {
  Channels:
   Trigger String : customChannel1 -[
@@ -196,7 +196,7 @@ Trigger channels are defined with the keyword `Trigger` and only support the typ
 
 Many bindings provide standalone channel type definitions like this:
 
-```xtend
+```java
 <thing:thing-descriptions bindingId="yahooweather" [...]>
     <channel-type id="temperature">
         <item-type>Number</item-type>
@@ -213,7 +213,7 @@ Many bindings provide standalone channel type definitions like this:
 They can be referenced within a thing’s channel definition, so that they need to be defined only once and can be reused for many channels.
 You may do so in the DSL as well:
 
-```xtend
+```java
 Thing yahooweather:weather:losangeles [ location=2442047, unit="us", refresh=120 ] {
     Channels:
         Type temperature : my_yesterday_temperature "Yesterday's Temperature"
@@ -236,12 +236,12 @@ In order to link a Thing to an Item in an `.items` file, open the Thing in UI un
 In the list of Thing Channels, look for the Channel you wish to link to an Item and copy the Channel's ID.
 For instance, a Z-Wave switch might have a Switch Channel that has an ID like this:
 
-```xtend
+```java
 zwave:device:1a2b3c4d:node2:switch_binary
 ```
 
 To bind that Channel to an Item in an `.items` file, you can define an Item in the file like so:
 
-```xtend
+```java
 Switch Kitchen_Light_Switch "Kitchen Light" (Indoor_Lights) { channel="zwave:device:1a2b3c4d:node2:switch_binary" }
 ```

configuration/transformations.md

@@ -201,19 +201,19 @@ However, beware that `stateFromItemScript` _should_ be left blank, because norma
 
 Example usage in an `.items` file:
 
-```xtend
+```java
 Number <itemName> { channel="<channelUID>"[profile="transform:JS", toItemScript="decode_json.js", commandFromItemScript="encode_json.js" ] }
 ```
 
 Here, additional parameters can also be injected into the script using the URL style syntax, e.g.:
 
-```xtend
+```java
 Number <itemName> { channel="<channelUID>"[profile="transform:RB", toItemScript="multiply.rb?factor=10", commandFromItemScript="multiply.rb?factor=0.1" ] }
 ```
 
 Inline script is also supported in the profile syntax.
 
-```xtend
+```java
 Number <itemName> { channel="<channelUID>"[profile="transform:RB", toItemScript="| input.to_f * 10", commandFromItemScript="| input.to_f * 0.1" ] }
 ```