From 4b170de4e5231892e9b1ffd1b3a86feb2a036aed Mon Sep 17 00:00:00 2001 From: Florian Hotze Date: Mon, 29 Nov 2021 09:44:26 +0100 Subject: [PATCH] [jsscripting] Improve docs with Actions (#11624) Updated the documentation with: * Core Actions * Cloud Notification Actions * Persistence Extensions * Ephemeris Actions * Types and Units Instead of the single "imports", the default scope (openhab-core/DefaultScriptScopeProvider.java) is used. It's imported as `openhab`, services are under `openhab.service`. As the helper library is on the way (openhab/openhab-js): * Added note about console.log and logging in general. * Added note that the lib is on the way. Signed-off-by: Florian Hotze Signed-off-by: Nick Waterton --- .../README.md | 225 +++++++++++++++++- 1 file changed, 216 insertions(+), 9 deletions(-) diff --git a/bundles/org.openhab.automation.jsscripting/README.md b/bundles/org.openhab.automation.jsscripting/README.md index 23b1dcd9bd128..77ae84528f03b 100644 --- a/bundles/org.openhab.automation.jsscripting/README.md +++ b/bundles/org.openhab.automation.jsscripting/README.md @@ -1,6 +1,21 @@ # JavaScript Scripting This add-on provides support for JavaScript (ECMAScript 2021+) that can be used as a scripting language within automation rules. +JavaScript scripts provide access to almost all the functionality in an openHAB runtime environment. + +- [Creating JavaScript Scripts](#creating-javascript-scripts) +- [Logging](#logging) +- [Core Actions](#core-actions) + - [itemRegistry](#itemregistry) + - [Event Bus Actions](#event-bus-actions) + - [Exec Actions](#exec-actions) + - [HTTP Actions](#http-actions) + - [Timers](#timers) + - [Scripts Actions](#scripts-actions) +- [Cloud Notification Actions](#cloud-notification-actions) +- [Persistence Extensions](#persistence-extensions) +- [Ephemeris Actions](#ephemeris-actions) +- [Types and Units](#types-and-units) ## Creating JavaScript Scripts @@ -21,23 +36,215 @@ log:set DEBUG org.openhab.core.automation For more information on the available APIs in scripts see the [JSR223 Scripting]({{base}}/configuration/jsr223.html) documentation. -## Script Examples +The following examples show how to access common openHAB functionalities. + +## Logging -JavaScript scripts provide access to almost all the functionality in an openHAB runtime environment. As a simple example, the following script logs "Hello, World!". Note that `console.log` will usually not work since the output has no terminal to display the text. +__Please note:__ Support for `console.log` will likely be added together with a logging API in the [helper library](https://github.com/openhab/openhab-js). The openHAB server uses the [SLF4J](https://www.slf4j.org/) library for logging. -```js -const LoggerFactory = Java.type('org.slf4j.LoggerFactory'); - -LoggerFactory.getLogger("org.openhab.core.automation.examples").info("Hello world!"); +```javascript +let logger = Java.type('org.slf4j.LoggerFactory').getLogger('org.openhab.rule.' + this.ruleUID); +logger.info('Hello world!'); +logger.warn('Successfully logged warning.'); +logger.error('Successfully logged error.'); ``` -Depending on the openHAB logging configuration, you may need to prefix logger names with `org.openhab.core.automation` for them to show up in the log file (or you modify the logging configuration). - The script uses the [LoggerFactory](https://www.slf4j.org/apidocs/org/slf4j/Logger.html) to obtain a named logger and then logs a message like: ```text - ... [INFO ] [.openhab.core.automation.examples:-2 ] - Hello world! + ... [INFO ] [org.openhab.rule. ] - Hello world! + ... [WARN ] [org.openhab.rule. ] - Successfully logged warning. + ... [ERROR] [org.openhab.rule. ] - Successfully logged error. +``` + +## Core Actions + +The openHAB services, which are pre-included in the integrated JavaScript engine, must explicitely be imported. + +__Please note:__ The [helper library](https://github.com/openhab/openhab-js) is on the way and will become the preferred API to work with openHAB. + +```javascript +let openhab = require('@runtime'); +``` + +### itemRegistry + +```javascript +let state = openhab.itemRegistry.getItem(itemName).getState(); +``` + +You can use `toString()` to convert an item's state to string or `toBigDecimal()` to convert to number. + +### Event Bus Actions + +```javascript +openhab.events.sendCommand(itemName, command); +openhab.events.postUpdate(itemName, state); +``` + +`command` and `state` can be a string `'string'` or a number depending on the item. + +### Exec Actions + +Execute a command line. + +```javascript +openhab.Exec = Java.type('org.openhab.core.model.script.actions.Exec'); +let Duration = Java.type('java.time.Duration'); + +// Execute command line. +openhab.Exec.executeCommandLine('echo', 'Hello World!'); + +// Execute command line with timeout. +openhab.Exec.executeCommandLine(Duration.ofSeconds(20), 'echo', 'Hello World!'); + +// Get response from command line. +let response = openhab.Exec.executeCommandLine('echo', 'Hello World!'); + +// Get response from command line with timeout. +response = openhab.Exec.executeCommandLine(Duration.ofSeconds(20), 'echo', 'Hello World!'); +``` + +### HTTP Actions + +For available actions have a look at the [HTTP Actions Docs](https://www.openhab.org/docs/configuration/actions.html#http-actions). + +```javascript +openhab.HTTP = Java.type('org.openhab.core.model.script.actions.HTTP'); + +// Example GET Request +var response = openhab.HTTP.sendHttpGetRequest(''); +``` + +Replace `` with the request url. + +### Timers + +```javascript +let ZonedDateTime = Java.type('java.time.ZonedDateTime'); +let now = ZonedDateTime.now(); +openhab.ScriptExecution = Java.type('org.openhab.core.model.script.actions.ScriptExecution'); + +// Function to run when the timer goes off. +function timerOver () { + logger.info('The timer is over.'); +} + +// Create the Timer. +this.myTimer = openhab.ScriptExecution.createTimer(now.plusSeconds(10), timerOver); + +// Cancel the timer. +this.myTimer.cancel(); + +// Check whether the timer is active. Returns true if the timer is active and will be executed as scheduled. +let active = this.myTimer.isActive(); + +// Reschedule the timer. +this.myTimer.reschedule(now.plusSeconds(5)); +``` + +### Scripts Actions + +Call scripts created in the UI (Settings -> Scripts) with or without parameters. + +```javascript +openhab.scriptExtension = Java.type('org.openhab.core.automation.module.script.ScriptExtensionProvider'); +let bundleContext = Java.type('org.osgi.framework.FrameworkUtil').getBundle(openhab.scriptExtension.class).getBundleContext(); +openhab.RuleManager = bundleContext.getService(bundleContext.getServiceReference('org.openhab.core.automation.RuleManager')); + +// Simple call. +openhab.RuleManager.runNow(''); + +// Advanced call with arguments. +let map = new java.util.HashMap(); +map.put('identifier1', 'value1'); +map.put('identifier2', 'value2'); +// Second argument is whether to consider the conditions, third is a Map (a way to pass data). +openhab.RuleManager.runNow('', true, map); +``` + +Replace `` with your script's (unique-)id. + +## Cloud Notification Actions + +Notification actions may be placed in Rules to send alerts to mobile devices registered with an [openHAB Cloud instance](https://github.com/openhab/openhab-cloud) such as [myopenHAB.org](https://myopenhab.org/). + +For available actions have a look at the [Cloud Notification Actions Docs](https://www.openhab.org/docs/configuration/actions.html#cloud-notification-actions). + +```javascript +openhab.NotificationAction = Java.type('org.openhab.io.openhabcloud.NotificationAction') + +// Example +openhab.NotificationAction.sendNotification('', ''); // to a single myopenHAB user identified by e-mail +openhab.NotificationAction.sendBroadcastNotification(''); // to all myopenHAB users +``` + +Replace `` with the e-mail address of the user. +Replace `` with the notification text. + +## Persistence Extensions + +For available commands have a look at [Persistence Extensions in Scripts ans Rules](https://www.openhab.org/docs/configuration/persistence.html#persistence-extensions-in-scripts-and-rules). + +For deeper information have a look at the [Persistence Extensions JavaDoc](https://www.openhab.org/javadoc/latest/org/openhab/core/persistence/extensions/persistenceextensions). + +```javascript +openhab.PersistenceExtensions = Java.type('org.openhab.core.persistence.extensions.PersistenceExtensions'); +let ZonedDateTime = Java.type('java.time.ZonedDateTime'); +let now = ZonedDateTime.now(); + +// Example +var avg = openhab.PersistenceExtensions.averageSince(itemRegistry.getItem(''), now.minusMinutes(5), "influxdb"); ``` + +Replace `` with the persistence service to use. +Replace `` with the itemname. + +## Ephemeris Actions + +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. + +For available actions, have a look at the [Ephemeris Actions Docs](https://www.openhab.org/docs/configuration/actions.html#ephemeris). + +For deeper information have a look at the [Ephemeris JavaDoc](https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/ephemeris). + +```javascript +openhab.Ephemeris = Java.type('org.openhab.core.model.script.actions.Ephemeris'); + +// Example +let weekend = openhab.Ephemeris.isWeekend(); +``` + +## Types and Units + +Import types from openHAB Core for type conversion and more. +Import Units from openHAB Core for unit conversion and more. + +```javascript +openhab.typeOrUnit = Java.type('org.openhab.core.library.types.typeOrUnit'); + +// Example +openhab.HSBType = Java.type('org.openhab.core.library.types.HSBType'); +let hsb = openhab.HSBType.fromRGB(4, 6, 9); +``` + +Available types are: +* `QuantityType` +* `StringListType` +* `RawType` +* `DateTimeType` +* `DecimalType` +* `HSBType` +* `PercentType` +* `PointType` +* `StringType` + +Available untis are: +* `SIUnits` +* `ImperialUnits` +* `MetricPrefix` +* `Units` +* `BinaryPrefix`