The official guide to making the Node-RED editor and Node-RED runtime communication a two-way street with open-source node.
For the download link and tutorial video, click here.
The two communication directions to consider are thus: a) node editor to node runtime, and b) node runtime to node editor.
APIs and methods to use to communicate between a Node-RED node editor and its runtime
How can this communication be accomplished? The answer lies in a few undocumented APIs... caveat emptor, because these APIs are undocumented, it is possible that they might change without notice in the future but, as far as the author can surmise, these APIs have been stable for quite a few versions, and the functionality that they unlock is worth the (estimated small) risk of having to change the code of a custom node to support newer Node-RED versions.
Node editor to node runtime communication
RED.httpAdmin. All Express' routing methods are available, and authorization middleware may be implemented using the
RED.auth.needsPermission API if a given endpoint needs to have specific restrictions.
A fairly complete example of how to create a POST HTTP endpoint is in the inject node:
This API call creates an
/inject endpoint, which takes an Express route parameter
id, meant to be the node ID, and is only accessible with appropriate write permissions specific to this node type. The
RED.auth.needsPermission call may be omitted if no specific restrictions are needed, thus the API call would have only two callback functions, as in:
The inject node code snippet also shows how to access the route parameters using the
req.params object, in this case to get a specific node's runtime object via the
RED.nodes.getNode Node-RED runtime API. Getting a node's object allows for sending input messages to it via Node-RED's node
Another Node-RED runtime API of note in the inject node code snippet is the
RED._ i18n (internationalization) API. The first argument of the call is the internationalization string to use, and the second argument is an object providing values to be replaced in the internationalization string. This can be thought of as a simple templating engine, where in the internationalization string any word of the form
__arg__is replaced by the value corresponding to the property arg in the object passed as the second argument in the
RED._ API call. In the snippet, the internationalizing string inject-comm.failed is "
Inject failed: __error__", thus the second argument of the
RED._ API call provides the value for the error argument.
On the node editor, the HTTP endpoint may be accessed using jQuery's ajax API. The relevant code parts in the inject node's editor are:
The HTTP POST call is done in the
doInject function (
$ is the traditional identifier of the
jQuery() function), where the
node object contains the node ID, which is used in the URL.
Node runtime to node editor communication
This direction relies on the WebSocket that Node-RED's runtime maintains with its editor. The Node-RED runtime
RED.events API is used to access this functionality. The downloadfile node runtime shows an example of this:
runtime-event is emitted whose payload is an object with three relevant fields,
id is the identifier of the event payload.
retain is a Boolean flag that indicates whether the event payload should be retained to be sent when a new WebSocket client connects or not. Note that if
true, the event payload is saved in an object keyed by the event payload
id, thus if this
id is not unique, the previously retained event
payload is overwritten. payload is the data that needs to be communicated to the editor, and can be of any serializable type (if
null an empty object is sent). The event payload is sent through the WebSocket to the editor with the topic
[EVENT-PAYLOAD-ID] represents the value of the event payload
On the node editor side, an event listener can be instantiated using the
RED.comms.subscribe API. This API has two parameters, the topic to subscribe to, and a callback to be used when a message with the subscribed topic is received. To subscribe to
runtime-event events, the downloadfile node uses the
notification/# topic, which captures all
runtime-event events. The appropriate topic coming from the node runtime is then filtered and acted upon, in this case a browser's file save dialog opens, giving the user the ability to save messages from the editor to a local file system.
To download the download-file node:
To watch our video tutorial: