@essenius/node-red-openhab4

Description

Nodes facilitating integration of openHAB 4 with Node-RED, allowing for the use of Node Red as a rules engine for OpenHAB.

Inspired by https://github.com/pdmangel/node-red-contrib-openhab2. Largely rewritten and made to work with openHAB 4, which has a different Rest API from openHAB 2.

Nodes

openhab4-controller

Configuration node for communication with an openHAB controller, which is used by all the other nodes.

Configuration:

• Name: name for the configuration node (mandatory as referred to by the other nodes)
• Protocol: http or https
• Allow Self Signed Certificates: switch off certificate checking (default off)
• Host: the host name or ip address (default localhost)
• Port: the ip port (default 8080)
• Path: the additional base path (default empty)
• Username: the user name to authenticate on openHAB (default empty)
• Password: the password to authenticate (default empty)

openhab4-in

Listens to state changes of a selected openHAB Item.

Configuration:

• Name: the name of the node instance (default empty, then takes over the item name)
• Controller: the openHAB controller
• Filter Items: the filter applied to the dropdown. Empty means no filter.
• Item Name: the name of the item to listen to. Overrides msg.item.

Output messages (2 channels):

Channel 1:

• msg.item: the name of the item
• msg.topic: StateEvent
• msg.payload: the new state of the selected item

Channel 2:

• msg.item: the name of the item
• msg.topic: RawEvent
• msg.payload: raw (unprocessed) event for the selected item

openhab4-health

Monitors the health and status of the openHAB4 controller connection.

Configuration:

• Name: the node name (default empty)
• Controller: the openHAB controller

Output messages (3 channels):

Channel 1:

• msg.topic : ConnectionStatus
• msg.payload : connection status (ON or OFF)

Channel 2:

• msg.topic : ConnectionError
• msg.payload : error message

Channel 3:

• msg.topic : RawEvent
• msg.payload : raw (unprocessed) event for all items

openhab4-out

Sends commands or state updates to a selected openHAB Item.

Configuration:

• Name: name of the node instance (default empty, then takes over the item name)
• Controller: the openHAB controller
• Filter Items: the filter applied to the dropdown. Empty means no filter.
• Item Name: the item to set. overrides msg.item.
• Topic: ItemCommand or ItemUpdate. Overrides msg.topic.
• Payload : The command or update value to send to the selected item. Overrides msg.payload.

Output messages(1 channel):

Channel 1: if output is successful, the input message is copied to this channel.

openhab4-get

Gets an openHAB item (i.e. fetch on demand).

Configuration:

• Name: the name of the node instance (default empty, then takes over the item name)

• Controller: the openHAB controller

• Filter Items: the filter applied to the dropdown. Empty means no filter.

• Item Name: the item to get. Overrides msg.item.

Output messages (1 channel):

Channel 1: The input message with addition of:

• msg.payload : the item object (name, label, state, ...)
• msg.payload_in : copy of incoming message payload.

Test flow

An example flow is provided in examples/test-flow-localhost.json. This expects the OpenHAB server at http://localhost:8080 and uses an item called TestItem. it will create a separate tab with a couple of flows that use all the nodes. There is also a test flow generator which uses environment variables for OpenHAB protocol, server, port and test item. See DEVELOPMENT.md for more details.

Development Guide

See DEVELOPMENT.md.

Release notes

v0.2.74

• Nodes openhab4-controller and openhab4-get working
• First push to GitHub

v0.2.91

• openhab4-in working
• loads of code optimizations

v0.2.93

• openhab4-out added
• Fixed JSON parsing error ("Unexpected end of JSON input") when openHAB returns empty responses for successful commands
• Improved error handling for EventSource message parsing in controller and events nodes
• Enhanced robustness against malformed JSON in event streams

v0.2.96

• openhab4-health added

v0.2.101

• reduced duplication
• eliminated clutter
• fixed errors with node names, resulting in IDs being used in debug window.

v0.2.120

• implemented item filter for get, in and out nodes
• cleaned up documentation

v0.2.145

• support for https and basic authentication

v0.2.147

• added unit testing framework (mocha, chai@4, node-red-node-test-helper, sinon, proxyquire) and initial unit tests

v0.2.212

• branch coverage over 90%, several defects fixed, refactored for better testability and duplication elimination, enabled ESLint

v0.2.223

• Introduced last run timestamp with status

v0.9.0

• First pre-release on npm

v0.9.2

• Dependency fixes, added example for localhost.

v0.9.5

• fixed bug in item retrieval for in/out/get node definition (eliminated duplicates).

Dependency restrictions

As this is a commonjs project, chai needs to stay at version 4, and node-fetch at version 2. Newer versions do not support commonjs.