openhab-addons/bundles/org.openhab.automation.jsscripting/README.md

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
• Logging
• Core Actions
  • itemRegistry
  • Event Bus Actions
  • Exec Actions
  • HTTP Actions
  • Timers
  • Scripts Actions
• Cloud Notification Actions
• Persistence Extensions
• Ephemeris Actions
• Types and Units

Creating JavaScript Scripts

When this add-on is installed, JavaScript script actions will be run by this add-on and allow ECMAScript 2021+ features.

Alternatively, you can create scripts in the automation/jsr223 configuration directory. If you create an empty file called test.js, you will see a log line with information similar to:

    ... [INFO ] [.a.m.s.r.i.l.ScriptFileWatcher:150  ] - Loading script 'test.js'

To enable debug logging, use the console logging commands to enable debug logging for the automation functionality:

log:set DEBUG org.openhab.core.automation

For more information on the available APIs in scripts see the JSR223 Scripting documentation.

The following examples show how to access common openHAB functionalities.

Logging

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. The openHAB server uses the SLF4J library for logging.

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.');

The script uses the LoggerFactory to obtain a named logger and then logs a message like:

    ... [INFO ] [org.openhab.rule.<ruleId>   ] - Hello world!
    ... [WARN ] [org.openhab.rule.<ruleId>   ] - Successfully logged warning.
    ... [ERROR] [org.openhab.rule.<ruleId>   ] - 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 is on the way and will become the preferred API to work with openHAB.

let openhab = require('@runtime');

itemRegistry

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

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.

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.

openhab.HTTP = Java.type('org.openhab.core.model.script.actions.HTTP');

// Example GET Request
var response = openhab.HTTP.sendHttpGetRequest('<url>');

Replace <url> with the request url.

Timers

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.

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('<scriptToRun>');

// 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<String, Object> (a way to pass data).
openhab.RuleManager.runNow('<scriptToRun>', true, map);

Replace <scriptToRun> 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 such as myopenHAB.org.

For available actions have a look at the Cloud Notification Actions Docs.

openhab.NotificationAction = Java.type('org.openhab.io.openhabcloud.NotificationAction')

// Example
openhab.NotificationAction.sendNotification('<email>', '<message>'); // to a single myopenHAB user identified by e-mail
openhab.NotificationAction.sendBroadcastNotification('<message>'); // to all myopenHAB users

Replace <email> with the e-mail address of the user. Replace <message> with the notification text.

Persistence Extensions

For available commands have a look at Persistence Extensions in Scripts ans Rules.

For deeper information have a look at the Persistence Extensions JavaDoc.

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('<item>'), now.minusMinutes(5), "influxdb");

Replace <persistence> with the persistence service to use. Replace <item> 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.

For deeper information have a look at the Ephemeris JavaDoc.

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.

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