- [Configuration](#configuration)
- [UI Based Rules](#ui-based-rules)
+ - [Adding Triggers](#adding-triggers)
+ - [Adding Actions](#adding-actions)
- [Scripting Basics](#scripting-basics)
- - [require](#require)
- - [console](#console)
- - [setInterval](#setinterval)
- - [setTimeout](#settimeout)
- - [scriptLoaded](#scriptloaded)
- - [scriptUnLoaded](#scriptunloaded)
- - [Paths](#paths)
+ - [Require](#require)
+ - [Console](#console)
+ - [SetTimeout](#settimeout)
+ - [SetInterval](#setinterval)
+ - [ScriptLoaded](#scriptloaded)
+ - [ScriptUnLoaded](#scriptunloaded)
+ - [Paths](#paths)
- [Standard Library](#standard-library)
- - [items](#items)
- - [actions](#actions)
- - [cache](#cache)
- - [log](#log)
- - [time](#time)
+ - [Items](#items)
+ - [Actions](#actions)
+ - [Cache](#cache)
+ - [Log](#log)
+ - [Time](#time)
+ - [Utils](#utils)
- [File Based Rules](#file-based-rules)
- [JSRule](#jsrule)
- [Rule Builder](#rule-builder)
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
-
Using the openHAB UI, first create a new rule and set a trigger condition
-### 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.
### 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
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
log:set DEBUG org.openhab.automation.script
- `console.debug(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.
-### setTimeout
+### SetTimeout
The global setTimeout() method sets a timer which executes a function or specified piece of code once the timer expires.
```javascript
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 global `clearInterval()` method cancels a timed, repeating action which was previously established by a call to `setInterval()`.
-NOTE: Timers will not be canceled if a script is deleted or modified, it is up to the user to manage timers. See using the [cache](#cache) namespace as well as [ScriptLoaded](#scriptloaded) and [ScriptUnLoaded](#scriptunloaded) for a convenient way of managing persisted objects, such as timers between reloads or deletions of scripts.
+NOTE: Timers will not be canceled if a script is deleted or modified, it is up to the user to manage timers. See using the [cache](#cache) namespace as well as [ScriptLoaded](#scriptloaded) and [ScriptUnLoaded](#scriptunloaded) for a convenient way of managing persisted objects, such as timers between reloads or deletions of scripts.
see https://developer.mozilla.org/en-US/docs/Web/API/setInterval for more information about setInterval.
### Items
-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>
* .getItem(name, nullIfMissing) ⇒ <code>Item</code>
+ * .getItems() ⇒ <code>Array.<Item></code>
* .getItemsByTag(...tagNames) ⇒ <code>Array.<Item></code>
* .createItem(itemName, [itemType], [category], [groups], [label], [tags], [giBaseType], [groupFunction], [itemMetadata])
* .addItem(itemName, [itemType], [category], [groups], [label], [tags], [giBaseType], [groupFunction])
* .members ⇒ <code>Array.<Item></code>
* .descendents ⇒ <code>Array.<Item></code>
* .isUninitialized ⇒ <code>Boolean</code>
+ * .groupNames ⇒ <code>Array.<String></code>
* .tags ⇒ <code>Array.<String></code>
* .getMetadataValue(namespace) ⇒ <code>String</code>
* .updateMetadataValue(namespace, value) ⇒ <code>String</code>
* ItemHistory : <code>object</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>
* .deviationSince(timestamp, serviceId) ⇒ <code>Number</code>
* .evolutionRate(timestamp, serviceId) ⇒ <code>Number</code>
### 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
(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
-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.
-Additional information can be found on the [Ephemeris Actions Docs](https://www.openhab.org/docs/configuration/actions.html#ephemeris) as well as the [Ephemeris JavaDoc](https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/ephemeris).
+Additional information can be found on the [Ephemeris Actions Docs](https://www.openhab.org/docs/configuration/actions.html#ephemeris) as well as the [Ephemeris JavaDoc](https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/ephemeris).
```javascript
// Example
#### 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.
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
// Example GET Request
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
// Reschedule the timer.
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)
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>
* .get(key, defaultSupplier) ⇒ <code>Object | null</code>
The `defaultSupplier` provided function will return a default value if a specified key is not already associated with a value
-**Example** *(Get a previously set value with a default value (times = 0))*
+**Example** *(Get a previously set value with a default value (times = 0))*
```js
let counter = cache.get("counter", () => ({ "times": 0 }));
console.log("Count",counter.times++);
```
-**Example** *(Get a previously set object)*
+**Example** *(Get a previously set object)*
```js
let counter = cache.get("counter");
if(counter == null){
```
### Log
-By default the JS Scripting binding supports console logging like `console.log()` and `console.debug()` to the openHAB
-default log. Additionally scripts may create their own native openHAB logs using the log namespace
+By default the JS Scripting binding supports console logging like `console.log()` and `console.debug()` to the openHAB default log.
+Additionally scripts may create their own native openHAB logs using the log namespace.
```javascript
let logger = log('my_logger');
### 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:
```javascript
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
-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).
execute: data => {
items.getItem("BalconyLights").sendCommand("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:
```javascript
[conditions](#rule-builder-conditions) and [operations](#rule-builder-operations) in the following pattern:
```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:
#### Rule Builder Conditions
* `if(optionalFunction)`
- * `.stateOfItem(state)`
+ * `.stateOfItem(itemName)`
+ * `is(state)`
+ * `in(state...)`
#### Rule Builder Operations
* `then(optionalFunction)`
- * `.build(name, description)`
+ * `.build(name, description, tags, id)`
* `.copyAndSendState()`
* `.copyState()`
* `.inGroup(groupName)`
//Basic rule, when the BedroomLight1 is changed, run a custom function
rules.when().item('BedroomLight1').changed().then(e => {
console.log("BedroomLight1 state", e.newState)
-}).build();
+}.build();
//turn on the kitchen light at SUNSET
rules.when().timeOfDay("SUNSET").then().sendOn().toItem("KitchenLight").build("Sunset Rule","turn on the kitchen light
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
-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
-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
rules.when().item('S1').changed().toOn().then(sendOn().toItem('HallLight')).build("S1 Rule");
projects / openhab-addons.git / commitdiff