openHAB JS Automation Tools

This library provides some utilities for the openHAB JS Scripting Add-On.

Please note that it depends on the openHAB JavaScript Library, which is included in the JS Scripting Add-On by default. Therefore, it is only listed in the devDependencies of this package.

Installation

• Requires the openHAB JavaScript binding which comes with a version of the openHAB library.
• Go to the javascript user scripts directory: cd $OPENHAB_CONF/automation/js
• Run npm install @hotzware/openhab-tools (you may need to install npm)

Compatibility

This library depends on openhab >= 5.7.0 (which is included since openHAB 4.3.0) and openhab_rules_tools >= 2.0.3.

openhab_rules_tools will automatically get installed by npm, openhab is already included with the add-on. Just make sure you have a compatible version installed (use console.log(utils.OPENHAB_JS_VERSION) to check the currently used version).

Conventions

Window States

Whilst contacts normally only have a binary state, 0 for CLOSED and 1 for OPEN, this is sometimes not enough.

Especially speaking about windows, most windows have more than a simple open or closed state. Normal German windows have three states: Closed, tilted, opened. I even have windows in the rooftop with four states: Closed, small ventilation (a bit opened), large ventilation (more opened), (fully) opened.

To work with these more complex states, the following convention is made:

• 0 represents CLOSED
• 0.3 represents small ventilation
• 0.5 represents tilted and large ventilation
• 1 represents OPEN

In general, any decimal in the range (0, 1] represents some form of open. By still using 0 and 1 for closed and open, this format is compatible with the binary format, just round up the float using Math.ceil().

If the closed state is required, this library will check for equality to 0. If any opened state is required, it will check for greater than 0.

API

To have a look at all capabilities of this library, have a look at the JSDoc.

The README will only take care of the most important stuff, and explain the more complicated ones.

itemutils

• dimItem: Dims an Item step-by-step to a target state.
• getGroupUtils: See Group Utilities

Group Utilities

The Group Utilities provide a number of functions on groups, e.g. arithmetic operations like min/max and count operations.

Examples

const { itemutils } = require('@hotzware/openhab-tools');
// The name of the member with the maximum state.
itemutils.getGroupUtils(group).membersMax.name;
// The sum of states.
itemutils.getGroupUtils(group).membersSum;
// Count how many members are on.
itemutils.getGroupUtils(group).membersCount(item => item.state === 'ON');

See JSDoc: GroupUtils for full API documentation.

rulesx

• createAlarmClock: See Alarm Clock.
• createAlarmClockItems: Creates the required Items for an alarm clock and optionally also generates Sitemap code, which is printed to the log.
• createSceneEngine: See Scene Engine.

Alarm Clock

Creates an alarm clock with time and days configurable over Items, therefore compatible with Sitemaps.

Under the hood, two rules are created. The first rule, the so-called manager rule, watches for configuration changes and updates the cron trigger of the second rule, the alarm clock itself. It also disables and enables the alarm clock rule based on the switchItem.

Required Items

Configuration Items must follow a specific naming scheme, switchItem can be anything.

Alarm Rule

rulesx.createAlarmClock(switchItem, data => { console.log('Successfully tested alarm clock.'); });

See JSDoc: getAlarmClock() for full API documentation.

Scene Engine

Call scene by sending a command to the sceneItem.

When a member of the scene changes it's state, the rule will check whether a defined scene is matching the current states and which scene.

It creates a full rule with triggers and actions out of your scene definition.

The sceneItem

Must be a Number item. You can assign a scene to every positive integer value, except to 0.

0 is the value the Item is et to when no match with a scene is found on members' change.

Scene definition

Scene definition works with an array of objects.

const sceneDefinition = {
  controller: 'scene call item name',
  scenes: [ // For each numeric state of the controller Item one object.
    { // Object for the value 1 of the controller Item.
      value: 1,
      targets: [ // Target states of items in the scene. Parameters explained later.
        { item: 'Florian_Licht', value: 'ON', required: true, conditionFn: function() { return parseFloat(items.getItem('Helligkeit').state) >= 10000; } },
        { item: 'Florian_LED_Stripes', value: 'OFF', required: false }
      ] 
    },
    { // Object for the value 15 of the controller Item.
      value: 15,
      targets: [ // Target states of items in the scene. Parameters explained later.
        { item: 'Florian_LED_Stripes', value: 'ON', required: true }
      ]
    }
  ]
};

Create the Scene Engine

rulesx.createSceneEngine(sceneDefinition);

See JSDoc: createSceneEngine() for full API documentation.

thingsx

• createThingStatusToItemRule: Creates a rule that posts Thing statuses to String Items.
• createThingStatusNotificationRule: Creates a rule that sends a notification when a Things goes offline and back online.
• createReEnableThingWithItemRule: Creates a rule that re-enabled a Thing on command ON to a given Item.
• reEnableThing: Re-enables a Thing by first disabling and then enabling it again.
• MlscRestClient: Class providing state fetching from and command sending to music_led_strip_control.

See JSDoc: thingsx for full API documentation.