Skip to content

Commit d000e5d

Browse files
lsiepellsiepel
authored
Merge branch 'openhab:main' into main
2 parents 7f0e2c0 + ce80a98 commit d000e5d

File tree

70 files changed

+2863
-509
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

70 files changed

+2863
-509
lines changed

‎CODEOWNERS‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@
119119
/bundles/org.openhab.binding.ephemeris/ @clinique
120120
/bundles/org.openhab.binding.epsonprojector/ @mlobstein
121121
/bundles/org.openhab.binding.etherrain/ @dfad1469
122-
/bundles/org.openhab.binding.evcc/ @florian-h05 @marcelGoerentz
122+
/bundles/org.openhab.binding.evcc/ @marcelGoerentz
123123
/bundles/org.openhab.binding.evohome/ @Nebula83
124124
/bundles/org.openhab.binding.exec/ @kgoderis
125125
/bundles/org.openhab.binding.feed/ @openhab/add-ons-maintainers

‎bundles/org.openhab.automation.jsscripting/README.md‎

Lines changed: 56 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -71,16 +71,57 @@ console.log("Thing status",thingStatusInfo.getStatus());
7171

7272
See [openhab-js](https://openhab.github.io/openhab-js) for a complete list of functionality.
7373

74-
### UI Event Object
74+
### Event Object
75+
76+
When a rule is triggered, the script is provided the event instance that triggered it.
77+
The specific data depends on the event type.
78+
The `event` object provides some information about that trigger.
7579

76-
**NOTE**: Note that `event` object is different in UI based rules and file based rules! This section is only valid for UI based rules. If you use file based rules, refer to [file based rules event object documentation](#event-object).
77-
Note that `event` object is only available when the UI based rule was triggered by an event and is not called from another rule!
78-
Trying to access `event` in this case does not work and will lead to an error. Use `this.event` instead (will be `undefined` when it does not exist).
80+
This table gives an overview over the `event` object:
7981

80-
When you use "Item event" as trigger (i.e. "[item] received a command", "[item] was updated", "[item] changed"), there is additional context available for the action in a variable called `event`.
81-
When a rule is triggered, there is additional context available for the action in a variable called `event`.
82+
| Property Name | Trigger Types | Description | Rules DSL Equivalent |
83+
|-------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------------------|------------------------|
84+
| `oldState` | `ItemStateChangeTrigger`, `GroupStateChangeTrigger` | Previous state of Item or Group that triggered event | `previousState` |
85+
| `newState` | `ItemStateChangeTrigger`, `GroupStateChangeTrigger` | New state of Item or Group that triggered event | N/A |
86+
| `receivedState` | `ItemStateUpdateTrigger`, `GroupStateUpdateTrigger` | State of Item that triggered event | `triggeringItem.state` |
87+
| `receivedCommand` | `ItemCommandTrigger`, `GroupCommandTrigger` | Command that triggered event | `receivedCommand` |
88+
| `itemName` | `Item****Trigger`, `Group****Trigger` | Name of Item that triggered event | `triggeringItem.name` |
89+
| `groupName` | `Group****Trigger` | Name of the group whose member triggered event | N/A |
90+
| `receivedEvent` | `ChannelEventTrigger` | Channel event that triggered event | N/A |
91+
| `channelUID` | `ChannelEventTrigger` | UID of channel that triggered event | N/A |
92+
| `oldStatus` | `ThingStatusChangeTrigger` | Previous state of Thing that triggered event | N/A |
93+
| `newStatus` | `ThingStatusChangeTrigger` | New state of Thing that triggered event | N/A |
94+
| `status` | `ThingStatusUpdateTrigger` | State of Thing that triggered event | N/A |
95+
| `thingUID` | `Thing****Trigger` | UID of Thing that triggered event | N/A |
96+
| `cronExpression` | `GenericCronTrigger` | Cron expression of the trigger | N/A |
97+
| `time` | `TimeOfDayTrigger` | Time of day value of the trigger | N/A |
98+
| `timeOnly` | `DateTimeTrigger` | Whether the trigger only considers the time part of the DateTime Item | N/A |
99+
| `offset` | `DateTimeTrigger` | Offset in seconds added to the time of the DateTime Item | N/A |
100+
| `eventType` | all except `PWMTrigger`, `PIDTrigger` | Type of event that triggered event (change, command, triggered, update, time) | N/A |
101+
| `triggerType` | all except `PWMTrigger`, `PIDTrigger` | Type of trigger that triggered event | N/A |
102+
| `eventName` | all | simple Java class name of the triggering event, e.g. `ExecutionEvent` | N/A |
103+
| `eventClass` | all | full Java class name of the triggering event, e.g. `org.openhab.core.automation.events.ExecutionEvent` | N/A |
104+
| `module` | all | (user-defined or auto-generated) name of trigger | N/A |
105+
| `raw` | all | Original contents of the event including data passed from a calling rule | N/A |
82106

83-
This table gives an overview over the `event` object for most common trigger types:
107+
All properties are typeof `string` except for properties contained by `raw` which are unmodified from the original types.
108+
109+
Please note that when using `GenericEventTrigger`, the available properties depend on the chosen event types.
110+
It is not possible for the openhab-js library to provide type conversions for all properties of all openHAB events, as those are too many.
111+
In case the event object does not provide type-conversed properties for your chosen event type, use the `payload` property to gain access to the event's (Java data type) payload.
112+
113+
**NOTE:**
114+
`Group****Trigger`s use the equivalent `Item****Trigger` as trigger for each member.
115+
116+
See [openhab-js : EventObject](https://openhab.github.io/openhab-js/rules.html#.EventObject) for full API documentation.
117+
118+
When disabling the option _Convert Event from Java to JavaScript type in UI-based scripts_, you will receive a raw Java event object instead of the `event` object described above.
119+
See the expandable section below for more details.
120+
121+
<details>
122+
<summary>Raw UI Event Object</summary>
123+
124+
This table gives an overview over the raw Java `event` object for UI-based scripts for most common trigger types:
84125

85126
| Property Name | Type | Trigger Types | Description | Rules DSL Equivalent |
86127
|----------------|----------------------------------------------------------------------------------------------------------------------|----------------------------------------|---------------------------------------------------------------------------------------------------------------|------------------------|
@@ -110,6 +151,8 @@ console.log(event.itemState == "test") // WRONG. Will always log "false"
110151
console.log(event.itemState.toString() == "test") // OK
111152
```
112153

154+
</details>
155+
113156
## Scripting Basics
114157

115158
The openHAB JavaScript Scripting runtime attempts to provide a familiar environment to JavaScript developers.
@@ -295,6 +338,8 @@ See [openhab-js : items](https://openhab.github.io/openhab-js/items.html) for fu
295338
- .removeItem(itemOrItemName) ⇒ `Item|null`
296339
- .replaceItem([itemConfig](#itemconfig)) ⇒ `Item|null`
297340
- .safeItemName(s) ⇒ `string`
341+
- .metadata ⇒ [`items.metadata` namespace](https://openhab.github.io/openhab-js/items.metadata.html): Manage metadata directly without the need of going "through" the Item
342+
- .itemChannelLink ⇒ [`items.itemChannelLink` namespace](https://openhab.github.io/openhab-js/items.itemChannelLink.html): Manage Item -> channel links
298343

299344
```javascript
300345
var item = items.KitchenLight;
@@ -1190,6 +1235,9 @@ Local variable state is not persisted among reloads, see using the [cache](#cach
11901235
11911236
File based rules can be created in 2 different ways: using [JSRule](#jsrule) or the [Rule Builder](#rule-builder).
11921237
1238+
When a rule is triggered, the script is provided information about the event that triggered the rule in the `event` object.
1239+
Please refer to [Event Object](#event-object) for documentation.
1240+
11931241
See [openhab-js : rules](https://openhab.github.io/openhab-js/rules.html) for full API documentation.
11941242
11951243
### JSRule
@@ -1284,7 +1332,7 @@ Rule are completed by calling `.build(name, description, tags, id)` , all parame
12841332
A simple example of this would look like:
12851333
12861334
```javascript
1287-
rules.when().item("F1_Light").changed().then().send("changed").toItem("F2_Light").build("My Rule", "My First Rule");
1335+
rules.when().item("F1_Light").changed().then().send("changed").toItem("F2_Light").build("My Rule", "My First Rule", ['MyTag1', 'Tag2'], 'MyRuleID');
12881336
```
12891337
12901338
Operations and conditions can also optionally take functions:
@@ -1410,54 +1458,6 @@ rules.when(true).item('HallLight').receivedCommand().then().sendIt().toItem('Kit
14101458
rules.when(true).item('HallLight').receivedUpdate().then().copyState().fromItem('BedroomLight1').toItem('BedroomLight2').build();
14111459
```
14121460
1413-
### Event Object
1414-
1415-
**NOTE**: The `event` object is different in UI Based Rules and File Based Rules!
1416-
This section is only valid for File Based Rules.
1417-
If you use UI Based Rules, refer to [UI based rules event object documentation](#ui-event-object).
1418-
1419-
When a rule is triggered, the script is provided the event instance that triggered it.
1420-
The specific data depends on the event type.
1421-
The `event` object provides some information about that trigger.
1422-
1423-
This table gives an overview over the `event` object:
1424-
1425-
| Property Name | Trigger Types | Description | Rules DSL Equivalent |
1426-
|-------------------|-----------------------------------------------------|-------------------------------------------------------------------------------|------------------------|
1427-
| `oldState` | `ItemStateChangeTrigger`, `GroupStateChangeTrigger` | Previous state of Item or Group that triggered event | `previousState` |
1428-
| `newState` | `ItemStateChangeTrigger`, `GroupStateChangeTrigger` | New state of Item or Group that triggered event | N/A |
1429-
| `receivedState` | `ItemStateUpdateTrigger`, `GroupStateUpdateTrigger` | State of Item that triggered event | `triggeringItem.state` |
1430-
| `receivedCommand` | `ItemCommandTrigger`, `GroupCommandTrigger` | Command that triggered event | `receivedCommand` |
1431-
| `itemName` | `Item****Trigger`, `Group****Trigger` | Name of Item that triggered event | `triggeringItem.name` |
1432-
| `groupName` | `Group****Trigger` | Name of the group whose member triggered event | N/A |
1433-
| `receivedEvent` | `ChannelEventTrigger` | Channel event that triggered event | N/A |
1434-
| `channelUID` | `ChannelEventTrigger` | UID of channel that triggered event | N/A |
1435-
| `oldStatus` | `ThingStatusChangeTrigger` | Previous state of Thing that triggered event | N/A |
1436-
| `newStatus` | `ThingStatusChangeTrigger` | New state of Thing that triggered event | N/A |
1437-
| `status` | `ThingStatusUpdateTrigger` | State of Thing that triggered event | N/A |
1438-
| `thingUID` | `Thing****Trigger` | UID of Thing that triggered event | N/A |
1439-
| `cronExpression` | `GenericCronTrigger` | Cron expression of the trigger | N/A |
1440-
| `time` | `TimeOfDayTrigger` | Time of day value of the trigger | N/A |
1441-
| `timeOnly` | `DateTimeTrigger` | Whether the trigger only considers the time part of the DateTime Item | N/A |
1442-
| `offset` | `DateTimeTrigger` | Offset in seconds added to the time of the DateTime Item | N/A |
1443-
| `eventType` | all except `PWMTrigger`, `PIDTrigger` | Type of event that triggered event (change, command, triggered, update, time) | N/A |
1444-
| `triggerType` | all except `PWMTrigger`, `PIDTrigger` | Type of trigger that triggered event | N/A |
1445-
| `eventClass` | all | Java class name of the triggering event | N/A |
1446-
| `module` | all | (user-defined or auto-generated) name of trigger | N/A |
1447-
| `raw` | all | Original contents of the event including data passed from a calling rule | N/A |
1448-
1449-
All properties are typeof `string` except for properties contained by `raw` which are unmodified from the original types.
1450-
1451-
Please note that when using `GenericEventTrigger`, the available properties depend on the chosen event types.
1452-
It is not possible for the openhab-js library to provide type conversions for all properties of all openHAB events, as those are too many.
1453-
In case the event object does not provide type-conversed properties for your chosen event type, use the `payload` property to gain access to the event's (Java data type) payload.
1454-
1455-
**NOTE:**
1456-
`Group****Trigger`s use the equivalent `Item****Trigger` as trigger for each member.
1457-
Time triggers do not provide any event instance, therefore no property is populated.
1458-
1459-
See [openhab-js : EventObject](https://openhab.github.io/openhab-js/rules.html#.EventObject) for full API documentation.
1460-
14611461
## Advanced Scripting
14621462
14631463
### Libraries

‎bundles/org.openhab.automation.jsscripting/pom.xml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
<properties>
1818
<!-- Remember to check if the fix https://github.com/openhab/openhab-core/pull/4437 still works when upgrading GraalJS -->
1919
<graaljs.version>24.2.1</graaljs.version>
20-
<ohjs.version>openhab@5.12.0</ohjs.version>
20+
<ohjs.version>openhab@5.13.0</ohjs.version>
2121
</properties>
2222

2323
<dependencies>
@@ -65,7 +65,7 @@
6565
</goals>
6666
<configuration>
6767
<!--suppress UnresolvedMavenProperty -->
68-
<arguments>install ${ohjs.version} webpack@^5.94.0 webpack-cli@^5.1.4 --prefix .</arguments>
68+
<arguments>install ${ohjs.version} webpack@^5.101.3 webpack-cli@^5.1.4 --prefix .</arguments>
6969
<!-- webpack & webpack-cli versions should match to the ones from openhab-js -->
7070
</configuration>
7171
</execution>

0 commit comments

Comments
 (0)