OpenHAB
/
openhab-addons
mirror of https://github.com/openhab/openhab-addons.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

[jsscripting] Updates to latest openhab-js library (#12171) 

* Updates to latest openhab-js library
* Update for new default log level in 3.3

Signed-off-by: Dan Cunningham <dan@digitaldan.com>
pull/12173/head
Dan Cunningham 2022-01-30 09:28:58 -08:00 committed by GitHub
parent 927dbba107
commit 00da156b1b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 94 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

144
bundles/org.openhab.automation.jsscripting/README.md
View File

@ -7,20 +7,23 @@ to common openHAB functionality within rules including items, things, actions, l
- [Configuration](#configuration) - [Configuration](#configuration)
- [UI Based Rules](#ui-based-rules) - [UI Based Rules](#ui-based-rules)
- [Adding Triggers](#adding-triggers)
- [Adding Actions](#adding-actions)
- [Scripting Basics](#scripting-basics) - [Scripting Basics](#scripting-basics)
- [require](#require) - [Require](#require)
- [console](#console) - [Console](#console)
- [setInterval](#setinterval) - [SetTimeout](#settimeout)
- [setTimeout](#settimeout) - [SetInterval](#setinterval)
- [scriptLoaded](#scriptloaded) - [ScriptLoaded](#scriptloaded)
- [scriptUnLoaded](#scriptunloaded) - [ScriptUnLoaded](#scriptunloaded)
- [Paths](#paths) - [Paths](#paths)
- [Standard Library](#standard-library) - [Standard Library](#standard-library)
- [items](#items) - [Items](#items)
- [actions](#actions) - [Actions](#actions)
- [cache](#cache) - [Cache](#cache)
- [log](#log) - [Log](#log)
- [time](#time) - [Time](#time)
- [Utils](#utils)
- [File Based Rules](#file-based-rules) - [File Based Rules](#file-based-rules)
- [JSRule](#jsrule) - [JSRule](#jsrule)
- [Rule Builder](#rule-builder) - [Rule Builder](#rule-builder)
@ -39,14 +42,15 @@ The quickest way to add rules is through the openHAB Web UI.
Advanced users, or users migrating scripts from existing systems may want to use [File Based Rules](#file-based-rules) for managing rules using files in the user configuration directory. Advanced users, or users migrating scripts from existing systems may want to use [File Based Rules](#file-based-rules) for managing rules using files in the user configuration directory.
### Adding Triggers ### Adding Triggers
Using the openHAB UI, first create a new rule and set a trigger condition Using the openHAB UI, first create a new rule and set a trigger condition
![openHAB Rule Configuration](./doc/rule-config.png) ![openHAB Rule Configuration](./doc/rule-config.png)
### Adding Actions
Select "Add Action" and then select "ECMAScript 262 Edition 11". Its important this is "Edition 11" or higher, earlier versions will not work. This will bring up a empty script editor where you can enter your javascript. ### Adding Actions
Select "Add Action" and then select "ECMAScript 262 Edition 11".
Its important this is "Edition 11" or higher, earlier versions will not work.
This will bring up a empty script editor where you can enter your javascript.
![openHAB Rule Engines](./doc/rule-engines.png) ![openHAB Rule Engines](./doc/rule-engines.png)
@ -79,12 +83,13 @@ The openHAB JSScripting runtime attempts to provide a familiar environment to Ja
### Require ### Require
Scripts may include standard NPM based libraries by using CommonJS require. The library search path will look in `automation/js/node_modules` in the user configuration directory. Scripts may include standard NPM based libraries by using CommonJS require.
The library search path will look in `automation/js/node_modules` in the user configuration directory.
### Console ### Console
The JSScripting binding supports the standard `console` object for logging. The JSScripting binding supports the standard `console` object for logging.
Script debug logging is enabled by default at the `TRACE` level, but can be configured using the [console logging]({{base}}/administration/logging.html) commands. Script debug logging is enabled by default at the `INFO` level, but can be configured using the [console logging]({{base}}/administration/logging.html) commands.
```text ```text
log:set DEBUG org.openhab.automation.script log:set DEBUG org.openhab.automation.script
@ -98,11 +103,12 @@ Supported logging functions include:
- `console.debug(obj1 [, obj2, ..., objN])` - `console.debug(obj1 [, obj2, ..., objN])`
- `console.trace(obj1 [, obj2, ..., objN])` - `console.trace(obj1 [, obj2, ..., objN])`
where `obj1 ... objN` is a list of JavaScript objects to output. The string representations of each of these objects are appended together in the order listed and output. where `obj1 ... objN` is a list of JavaScript objects to output.
The string representations of each of these objects are appended together in the order listed and output.
see https://developer.mozilla.org/en-US/docs/Web/API/console for more information about console logging. see https://developer.mozilla.org/en-US/docs/Web/API/console for more information about console logging.
### setTimeout ### SetTimeout
The global setTimeout() method sets a timer which executes a function or specified piece of code once the timer expires. The global setTimeout() method sets a timer which executes a function or specified piece of code once the timer expires.
```javascript ```javascript
@ -114,7 +120,7 @@ The global `clearTimeout()` method cancels a timeout previously established by c
see https://developer.mozilla.org/en-US/docs/Web/API/setTimeout for more information about setTimeout. see https://developer.mozilla.org/en-US/docs/Web/API/setTimeout for more information about setTimeout.
### setInterval ### SetInterval
The setInterval() method repeatedly calls a function or executes a code snippet, with a fixed time delay between each call. The setInterval() method repeatedly calls a function or executes a code snippet, with a fixed time delay between each call.
@ -166,10 +172,11 @@ Full documentation for the openHAB JavaScript library can be found at [openhab-j
The items namespace allows interactions with openHAB items. The items namespace allows interactions with openHAB items.
See [openhab-js : items ](https://openhab.github.io/openhab-js/items.html) for full API documentation See [openhab-js : items](https://openhab.github.io/openhab-js/items.html) for full API documentation
* items : <code>object</code> * items : <code>object</code>
* .getItem(name, nullIfMissing) ⇒ <code>Item</code> * .getItem(name, nullIfMissing) ⇒ <code>Item</code>
* .getItems() ⇒ <code>Array.&lt;Item&gt;</code>
* .getItemsByTag(...tagNames) ⇒ <code>Array.&lt;Item&gt;</code> * .getItemsByTag(...tagNames) ⇒ <code>Array.&lt;Item&gt;</code>
* .createItem(itemName, [itemType], [category], [groups], [label], [tags], [giBaseType], [groupFunction], [itemMetadata]) * .createItem(itemName, [itemType], [category], [groups], [label], [tags], [giBaseType], [groupFunction], [itemMetadata])
* .addItem(itemName, [itemType], [category], [groups], [label], [tags], [giBaseType], [groupFunction]) * .addItem(itemName, [itemType], [category], [groups], [label], [tags], [giBaseType], [groupFunction])
@ -194,6 +201,7 @@ Calling `getItem(...)` returns an `Item` object with the following properties:
* .members ⇒ <code>Array.&lt;Item&gt;</code> * .members ⇒ <code>Array.&lt;Item&gt;</code>
* .descendents ⇒ <code>Array.&lt;Item&gt;</code> * .descendents ⇒ <code>Array.&lt;Item&gt;</code>
* .isUninitialized ⇒ <code>Boolean</code> * .isUninitialized ⇒ <code>Boolean</code>
* .groupNames ⇒ <code>Array.&lt;String&gt;</code>
* .tags ⇒ <code>Array.&lt;String&gt;</code> * .tags ⇒ <code>Array.&lt;String&gt;</code>
* .getMetadataValue(namespace) ⇒ <code>String</code> * .getMetadataValue(namespace) ⇒ <code>String</code>
* .updateMetadataValue(namespace, value) ⇒ <code>String</code> * .updateMetadataValue(namespace, value) ⇒ <code>String</code>
@ -223,7 +231,7 @@ Note `serviceId` is optional, if omitted, the default persistance service will b
* ItemHistory : <code>object</code> * ItemHistory : <code>object</code>
* .averageSince(timestamp, serviceId) ⇒ <code>Number</code> * .averageSince(timestamp, serviceId) ⇒ <code>Number</code>
* .changedSince(timestamp, serviceId) ⇒ <code>Boolean</code> * .changedSince(timestamp, serviceId) ⇒ <code>Number</code>
* .deltaSince(timestamp, serviceId) ⇒ <code>Number</code> * .deltaSince(timestamp, serviceId) ⇒ <code>Number</code>
* .deviationSince(timestamp, serviceId) ⇒ <code>Number</code> * .deviationSince(timestamp, serviceId) ⇒ <code>Number</code>
* .evolutionRate(timestamp, serviceId) ⇒ <code>Number</code> * .evolutionRate(timestamp, serviceId) ⇒ <code>Number</code>
@ -246,24 +254,25 @@ console.log("KitchenDimmer averageSince", item.history.averageSince(yesterday));
### Actions ### Actions
The actions namespace allows interactions with openHAB actions. The following are a list of standard actions. The actions namespace allows interactions with openHAB actions.
The following are a list of standard actions.
Additional actions provided by user installed addons can be accessed using their common name on the actions name space Additional actions provided by user installed addons can be accessed using their common name on the actions name space
(example: `actions.Pushsafer.pushsafer(...)`) (example: `actions.Pushsafer.pushsafer(...)`)
See [openhab-js : actions ](https://openhab.github.io/openhab-js/actions.html) for full API documentation and additional actions. See [openhab-js : actions](https://openhab.github.io/openhab-js/actions.html) for full API documentation and additional actions.
#### Audio Actions #### Audio Actions
See [openhab-js : actions.Audio ](https://openhab.github.io/openhab-js/actions.html#.Audio) for complete documentation See [openhab-js : actions.Audio](https://openhab.github.io/openhab-js/actions.html#.Audio) for complete documentation
### BusEvent #### BusEvent
See [openhab-js : actions.BusEvent ](https://openhab.github.io/openhab-js/actions.html#.BusEvent) for complete documentation See [openhab-js : actions.BusEvent](https://openhab.github.io/openhab-js/actions.html#.BusEvent) for complete documentation
## Ephemeris Actions #### Ephemeris Actions
See [openhab-js : actions.Ephemeris ](https://openhab.github.io/openhab-js/actions.html#.Ephemeris) for complete documentation See [openhab-js : actions.Ephemeris](https://openhab.github.io/openhab-js/actions.html#.Ephemeris) for complete documentation
Ephemeris is a way to determine what type of day today or a number of days before or after today is. For example, a way to determine if today is a weekend, a bank holiday, someone’s birthday, trash day, etc. Ephemeris is a way to determine what type of day today or a number of days before or after today is. For example, a way to determine if today is a weekend, a bank holiday, someone’s birthday, trash day, etc.
@ -276,7 +285,7 @@ let weekend = actions.Ephemeris.isWeekend();
#### Exec Actions #### Exec Actions
See [openhab-js : actions.Exec ](https://openhab.github.io/openhab-js/actions.html#.Exec) for complete documentation See [openhab-js : actions.Exec](https://openhab.github.io/openhab-js/actions.html#.Exec) for complete documentation
Execute a command line. Execute a command line.
@ -296,9 +305,9 @@ let response = actions.Exec.executeCommandLine('echo', 'Hello World!');
response = actions.Exec.executeCommandLine(Duration.ofSeconds(20), 'echo', 'Hello World!'); response = actions.Exec.executeCommandLine(Duration.ofSeconds(20), 'echo', 'Hello World!');
``` ```
### HTTP Actions #### HTTP Actions
See [openhab-js : actions.HTTP ](https://openhab.github.io/openhab-js/actions.html#.HTTP) for complete documentation See [openhab-js : actions.HTTP](https://openhab.github.io/openhab-js/actions.html#.HTTP) for complete documentation
```javascript ```javascript
// Example GET Request // Example GET Request
@ -307,9 +316,9 @@ var response = actions.HTTP.sendHttpGetRequest('<url>');
Replace `<url>` with the request url. Replace `<url>` with the request url.
### ScriptExecution Actions #### ScriptExecution Actions
See [openhab-js : actions.ScriptExecution ](https://openhab.github.io/openhab-js/actions.html#.ScriptExecution) for complete documentation See [openhab-js : actions.ScriptExecution](https://openhab.github.io/openhab-js/actions.html#.ScriptExecution) for complete documentation
```javascript ```javascript
@ -332,19 +341,19 @@ let active = this.myTimer.isActive();
// Reschedule the timer. // Reschedule the timer.
this.myTimer.reschedule(now.plusSeconds(5)); this.myTimer.reschedule(now.plusSeconds(5));
``` ```
### Semantics Actions #### Semantics Actions
See [openhab-js : actions.Semantics ](https://openhab.github.io/openhab-js/actions.html#.Semantics) for complete documentation See [openhab-js : actions.Semantics](https://openhab.github.io/openhab-js/actions.html#.Semantics) for complete documentation
### Things Actions #### Things Actions
See [openhab-js : actions.Things ](https://openhab.github.io/openhab-js/actions.html#.Things) for complete documentation See [openhab-js : actions.Things](https://openhab.github.io/openhab-js/actions.html#.Things) for complete documentation
### Voice Actions #### Voice Actions
See [openhab-js : actions.Voice ](https://openhab.github.io/openhab-js/actions.html#.Voice) for complete documentation See [openhab-js : actions.Voice](https://openhab.github.io/openhab-js/actions.html#.Voice) for complete documentation
### Cloud Notification Actions #### Cloud Notification Actions
(optional action if openhab-cloud is installed) (optional action if openhab-cloud is installed)
@ -365,7 +374,7 @@ Replace `<message>` with the notification text.
The cache namespace provides a default cache that can be use to set and retrieve objects that will be persisted between reloads of scripts. The cache namespace provides a default cache that can be use to set and retrieve objects that will be persisted between reloads of scripts.
See [openhab-js : cache ](https://openhab.github.io/openhab-js/cache.html) for full API documentation See [openhab-js : cache](https://openhab.github.io/openhab-js/cache.html) for full API documentation
* cache : <code>object</code> * cache : <code>object</code>
* .get(key, defaultSupplier) ⇒ <code>Object | null</code> * .get(key, defaultSupplier) ⇒ <code>Object | null</code>
@ -391,8 +400,8 @@ console.log("Count",counter.times++);
``` ```
### Log ### Log
By default the JS Scripting binding supports console logging like `console.log()` and `console.debug()` to the openHAB By default the JS Scripting binding supports console logging like `console.log()` and `console.debug()` to the openHAB default log.
default log. Additionally scripts may create their own native openHAB logs using the log namespace Additionally scripts may create their own native openHAB logs using the log namespace.
```javascript ```javascript
let logger = log('my_logger'); let logger = log('my_logger');
@ -403,7 +412,9 @@ logger.debug("Hello {}!", "world");
### Time ### Time
openHAB internally makes extensive use of the `java.time` package. openHAB-JS exports the excellent [JS-Joda](https://js-joda.github.io/js-joda/) library via the `time` namespace, which is a native Javascript port of the same API standard used in Java for `java.time`. Anywhere that a native Java `ZonedDateTime` or `Duration` is required, the runtime will automatically convert a JS-Joda `ZonedDateTime` or `Duration` to its Java counterpart. openHAB internally makes extensive use of the `java.time` package.
openHAB-JS exports the excellent [JS-Joda](#https://js-joda.github.io/js-joda/) library via the `time` namespace, which is a native Javascript port of the same API standard used in Java for `java.time`.
Anywhere that a native Java `ZonedDateTime` or `Duration` is required, the runtime will automatically convert a JS-Joda `ZonedDateTime` or `Duration` to its Java counterpart.
Examples: Examples:
```javascript ```javascript
@ -420,9 +431,19 @@ actions.Exec.executeCommandLine(time.Duration.ofSeconds(20), 'echo', 'Hello Worl
See [JS-Joda](https://js-joda.github.io/js-joda/) for more examples and complete API usage. See [JS-Joda](https://js-joda.github.io/js-joda/) for more examples and complete API usage.
### Utils
openHAB internally is a Java program.
openHAB-JS converts between Java and JavaScript data types and reverse.
See [openhab-js : utils](https://openhab.github.io/openhab-js/utils.html) for full API documentation
## File Based Rules ## File Based Rules
The JSScripting binding will load scripts from `automation/js` in the user configuration directory. The system will automatically reload scripts when changes are detected to files. Local variable state is not persisted among reloads, see using the [cache](#cache) for a connivent way to persist objects. The JSScripting binding will load scripts from `automation/js` in the user configuration directory.
The system will automatically reload scripts when changes are detected to files.
Local variable state is not persisted among reloads, see using the [cache](#cache) for a connivent way to persist objects.
File based rules can be created in 2 different ways: using [JSRule](#jsrule) or the [Rule Builder](#rule-builder). File based rules can be created in 2 different ways: using [JSRule](#jsrule) or the [Rule Builder](#rule-builder).
@ -442,10 +463,14 @@ rules.JSRule({
execute: data => { execute: data => {
items.getItem("BalconyLights").sendCommand("ON"); items.getItem("BalconyLights").sendCommand("ON");
actions.NotificationAction.sendNotification(email, "Balcony lights are ON"); actions.NotificationAction.sendNotification(email, "Balcony lights are ON");
} },
tags: ["Balcony", "Lights"],
id: "BalconyLightsOn"
}); });
``` ```
Note: `description`, `tags` and `id` are optional.
Multiple triggers can be added, some example triggers include: Multiple triggers can be added, some example triggers include:
```javascript ```javascript
@ -493,10 +518,15 @@ Rules are started by calling `rules.when()` and can chain together [triggers](#r
[conditions](#rule-builder-conditions) and [operations](#rule-builder-operations) in the following pattern: [conditions](#rule-builder-conditions) and [operations](#rule-builder-operations) in the following pattern:
```javascript ```javascript
rules.when().triggerType()...if().conditionType().then().operationType()...build(name,description); rules.when().triggerType()...if().conditionType().then().operationType()...build(name, description, tags, id);
``` ```
Rule are completed by calling `.build(name,description)` , if name or description are omitted, a generated value will be used. Rule are completed by calling `.build(name, description, tags, id)` , all parameters are optional and reasonable defaults will be used if omitted.
- `name` String rule name - defaults generated name
- `description` String Rule description - defaults generated description
- `tags` Array of string tag names - defaults empty array
- `id` String id - defaults random UUID
A simple example of this would look like: A simple example of this would look like:
@ -557,11 +587,13 @@ Additionally all the above triggers have the following functions:
#### Rule Builder Conditions #### Rule Builder Conditions
* `if(optionalFunction)` * `if(optionalFunction)`
* `.stateOfItem(state)` * `.stateOfItem(itemName)`
* `is(state)`
* `in(state...)`
#### Rule Builder Operations #### Rule Builder Operations
* `then(optionalFunction)` * `then(optionalFunction)`
* `.build(name, description)` * `.build(name, description, tags, id)`
* `.copyAndSendState()` * `.copyAndSendState()`
* `.copyState()` * `.copyState()`
* `.inGroup(groupName)` * `.inGroup(groupName)`
@ -579,19 +611,19 @@ Additionally all the above triggers have the following functions:
//Basic rule, when the BedroomLight1 is changed, run a custom function //Basic rule, when the BedroomLight1 is changed, run a custom function
rules.when().item('BedroomLight1').changed().then(e => { rules.when().item('BedroomLight1').changed().then(e => {
console.log("BedroomLight1 state", e.newState) console.log("BedroomLight1 state", e.newState)
}).build(); }.build();
//turn on the kitchen light at SUNSET //turn on the kitchen light at SUNSET
rules.when().timeOfDay("SUNSET").then().sendOn().toItem("KitchenLight").build("Sunset Rule","turn on the kitchen light rules.when().timeOfDay("SUNSET").then().sendOn().toItem("KitchenLight").build("Sunset Rule","turn on the kitchen light
at SUNSET"); at SUNSET");
//turn off the kitchen light at 9PM //turn off the kitchen light at 9PM and tag rule
rules.when().cron("0 0 21 * * ?").then().sendOff().toItem("KitchenLight").build("9PM Rule", "turn off the kitchen light rules.when().cron("0 0 21 * * ?").then().sendOff().toItem("KitchenLight").build("9PM Rule", "turn off the kitchen light
at 9PM"); at 9PM", ["Tag1", "Tag2"]);
//set the colour of the hall light to pink at 9PM //set the colour of the hall light to pink at 9PM, tag rule and use a custom ID
rules.when().cron("0 0 21 * * ?").then().send("300,100,100").toItem("HallLight").build("Pink Rule", "set the colour of rules.when().cron("0 0 21 * * ?").then().send("300,100,100").toItem("HallLight").build("Pink Rule", "set the colour of
the hall light to pink at 9PM"); the hall light to pink at 9PM", ["Tag1", "Tag2"], "MyCustomID");
//when the switch S1 status changes to ON, then turn on the HallLight //when the switch S1 status changes to ON, then turn on the HallLight
rules.when().item('S1').changed().toOn().then(sendOn().toItem('HallLight')).build("S1 Rule"); rules.when().item('S1').changed().toOn().then(sendOn().toItem('HallLight')).build("S1 Rule");

2
bundles/org.openhab.automation.jsscripting/pom.xml
View File

@ -25,7 +25,7 @@
<graal.version>21.3.0</graal.version> <graal.version>21.3.0</graal.version>
<asm.version>6.2.1</asm.version> <asm.version>6.2.1</asm.version>
<oh.version>${project.version}</oh.version> <oh.version>${project.version}</oh.version>
<ohjs.version>openhab@1.2.1</ohjs.version> <ohjs.version>openhab@1.2.2</ohjs.version>
</properties> </properties>
<build> <build>