node-red-contrib-things 3.2.6
A set of Node-RED nodes that uses an agnostic state management system to keep IOT device states and provide a uniform control system.
A set of Node-RED nodes that uses an agnostic state management system to keep IOT device states and provide a uniform control system.
Purpose
First, what these nodes do not do: These nodes have no connection outside of Node-RED. They do not directly receive data, nor do they directly send data.
This is an internal system that helps you better manage Node-RED projects, minimizing overhead and simplying flows. You provide outside connections, wire them to these nodes, and super-charge Node-RED! The system is minimalistic as possible while supporting virtually any use case.
Usage
The core concept is to reduce all IOT devices into a common "language". This makes flows simpler and modification much easier. To facilitate this abstraction, this collection is provides four main segments/nodes:
- The inputs from various platforms of your choice are linked into the update node, which routes to...
- The trigger node, which links into your logic.
- Your logic may link into a command node, which routes to...
- The process node, which links back to the various platforms.
Exact usage varies depending on your use-case. However, this system is designed with the following general concepts in mind. This is an over-simplified representation. The two connections in the middle represent some of the inner-workings of this system.
The get, list, and test nodes assist in your flows.
Inspiration
I started this library because I was using Lifx, TP-Link/Kasa, Harmony, Z-Wave, and several other types of "things", and I wanted to treat all lights, sensors, etc. as equals. When designing device flows, I didn't want to worry about the underlying platform.
A lot of the ideas used in this library are based on standard state management systems, most notably React and Redux.
I also tried to use as much built-in functionality as possible to keep with the themes of Node-RED. For example, the ready node behaves similarly to the built-in inject node. Many other properties follow Node-RED inputs conventions.
Lastly, I used node status -- as much as possible -- to assist with debugging. I've found that useful status makes nodes much more powerful. Debug options are also available on most nodes.
What is a Thing?
A thing, as used in this library, is any device or entity in Node-RED for which you maintain state, trigger off state changes, and/or control. These could be simple devices such as lights and sensors, more complex devices such as thermostats and entertainment devices, or even non-connected "things" such as people.
This library of nodes does not actually connect to any of the devices; it only acts as a state management system. All outside communication needs to go through another Node-RED node. For example, to use Lifx lights, you need one of the Lifx Node-RED libraries.
Things Directory
After deployment, the Things Directory lists all things configured in the setup nodes. Information for each thing includes name, type, ID, status, state, and props. Proxied state values show a small button when hovered that links to the proxy thing. You can filter the directory at the top.
IMPORTANT: If your Things Directory shows "DISCONNECTED" and you are using a container such as Docker, ensure you are allowing port 8120 through on your container in addition to the standard 1880 for Node-RED. This library uses port 8120 for websocket communication of real-time thing-related data to the editor.
Upgrading from v2
Version 3 has breaking changes from version 2. Versions <3.2.0 contain automatic conversion functions to handle the differences. If you want to upgrade from ^2 to >=3.2.0, it is recommended that you first upgrade to version 3.1.3, then open every setup and trigger node and verify they remain configured as desired. After that, you can then upgrade to >=3.2.0 without issue. Failure to follow these instructions may result in loss of configuration data.
Nodes
There are 8 nodes included: setup, update, trigger, get, test, list, command, and process.
setup
You must configure all things using this node. Use a different setup node for each type in your flows. It is up to you how you organize your types. We recommended you base them on the platforms you use -- in other words, based on how the devices connect into and out of Node-RED. There are no inputs or outputs for this node. The flows creates all listed things on deployment.
Properties
| Property | Info |
|---|---|
| Thing Type | User's choice. Typically, the platform that these things use to connect outside of Node-RED. |
| Things | Lists each thing of this type. Click a thing to see detailed setup properties. |
| (common) | Optional. Each type can have common State, Commands, or Status Function. These apply to all things of this type unless overridden for an individual thing. |
For each thing:
| Property | Info |
|---|---|
| Name | Required. Must be unique among all things |
| ID | Optional. Must be unique among all things of same type |
| Props | Optional. Static properties |
| State | Optional. Initial state and proxied states.
|
| Commands | Optional. Special actions to take when handling commands.
|
| Children | Optional. A list of other things.
|
| Status Function | Optional. A function that runs to determine the status of a thing. This function takes current state and props as input, and outputs a node status object. The output object can contain text, fill, and/or shape. if individual thing has a status function it will override the type-level status function. |
update
A node that updates a thing's state, potentially causing separate trigger node(s) to output. Updates are quite flexible and can be configured in a few ways.
Properties
| Property | Info |
|---|---|
| Thing Name | Optional. When specified, all input messages are directed to this thing. If not provided, the input message must include thing name. |
| Update Properties | Optional. The state keys/values to update. If any updates are configured, then input payload is ignored. To use input payload as the state update, the update properties list must be empty. |
| Thing Type | Optional. When specified, the node will watch for all things of the type and update its status with any missing things. Additionally, if specified, input messages can optionally use thing ID instead of name. If not provided, the node will not display a status. |
Input
| Key | Type | Info |
|---|---|---|
topic |
string | Optional. Thing name. Only used if not specified in properties. Note: will not override property setting. Alternatively, if the node is configured with a thing type, then the thing ID can be used as the topic. |
payload |
object | Optional. The state update. Ignored if any updates are set in properties. |
replace |
boolean | Optional. If true, the new state completely replaces current state. Otherwise it will be merged, top-level only. Caution: Proxy state keys will be erased when using replace option. |
trigger
A node that outputs a message when a thing's state changes. Can be configured in many ways.
Properties
| Property | Info |
|---|---|
| Thing Test | Test used to determine what things to watch. Can be configured to check against any static attributes of each thing. List of matching things is made immediately after setup and is not updated until nodes are re-deployed. Each thing is tracked individually. Editor will show how many things match the current configuration. Click the number to see the full list. |
| Trigger | Configure when to trigger an output. "All Updates" triggers on any state update, regardless of changes. Use state. to track a specific state key. Leave empty to trigger on any state change. Ignore initialization option prevents triggers when the value changes from undefined. |
| Payload | Configure what to output on msg.payload. Can be a typical Node-RED typed value, or part of the thing state. Leave state. empty to output the entire state. Use the copy button to quickly copy the state field from the Trigger. |
Output
| Key | Type | Info |
|---|---|---|
topic |
string | Thing name |
payload |
any | Depends on Payload property |
get
A node that appends specified values of a thing to a message.
Properties
| Property | Info |
|---|---|
| Thing Name | The thing to reference |
| Message | Similar to the built-in inject node |
Input
| Key | Type | Info |
|---|---|---|
topic |
string | Optional. Thing name, if not specified in properties. Note: will not override property setting. |
Output
Same message from input, with specified properties changed/added.
test
A node that allows a message to pass based on specified conditions related to a thing. The message is not modified.
Properties
| Property | Info |
|---|---|
| Thing Name | The thing to reference |
| Conditions | The conditions that must be met to allow the message to pass through |
| 2nd Output | Optionally choose to have a 2nd output that passes the message if the test fails |
Input
| Key | Type | Info |
|---|---|---|
topic |
string | Optional. Thing name, if not specified in properties. Note: will not override property setting. |
Output
Input message is passed through.
list
A node that lists all things that match the specified conditions.
Properties
| Property | Info |
|---|---|
| Output | Choose the type and value of the output |
| Property | Specify what property to output on |
| Conditions | The conditions that must be met to include a thing on the list. Leave empty to list all things. |
Output
The input message is forwarded (unless Discard input message is checked), with the addition of output specified in the properties.
command
A node that initiates sending of a command to a thing or multiple things. Note that this node provides no communication to the outside. It only relays messages to respective process node(s).
The node checks for any command configuration for the thing and transform/forward, if necessary. If there is no configuration, then the command processes for self and also forwards to all children.
Properties
| Property | Info |
|---|---|
| Thing Name | Optional. When specified, all input messages are directed to this thing. If not provided, the input message must include thing name. |
| Command | Optional. When specified, used as the command. If not provided, the input must include the command. |
Input
| Key | Type | Info |
|---|---|---|
topic |
string | Thing name, if not specified in properties. Note: will not override property setting. |
payload |
any | The command, if not specified in properties. Note: will not override property setting. |
process
A node that listens for messages from command nodes for a specific thing type, and then outputs the message. Note that this node does not provide any communication to the outside. It only relays messages from repsective command nodes. Its purpose is to funnel all messages intended for a certain node library into one place.
Properties
| Property | Info |
|---|---|
| Thing Type | The thing type to listen for |
| Topic | The property or custom string to send as the msg.topic |
Output
| Key | Type | Info |
|---|---|---|
topic |
string | As configured in properties |
payload |
any | The command, passed from a command node |
thing |
object | The entire thing object |
Bugs and Feedback
For bug reports, feature requests, and questions please use the GitHub Issues.
