Node-RED Messages and Variables

Documentation for messages and variables

If you have read the previous article in this series, you have already seen messages in action. There, I shows you a couple of examples the included the "msg" object.

In this article I will expand on messages and introduce Node-RED variables.

I also recommend that you have a look at the official Node-RED documentation, where messages and variables are covered in detail. You should also read the documentation page on context.

Messages vs variables

A confusion that arises among people that are new to Node-RED has to do with the differences and similarities between messages and variables.

Let's clear this up right now.

That's it.

Messages

The main thing to remember about messages, is that the data that you want to pass to the next node is contained within an object named "msg". The msg object may contain as many attributes as you want. Some of those attributes are built-in, but you can also create your own.

The most important attribute is called "payload".

Most nodes will automatically save data in the payload attribute. For example, consider the MQTT-in node:

This node (like most other nodes), will store data in the msg.payload attribute. This is done by convention. You don't have to do anything specific to make this happen.

Because of this, you know that you can get the data you need to process or display in the next node by reading the contents of the payload. 

Here is an example of displaying the MQTT-in node data using a debug node:

Notice that the output of the debug node comes from the msg object. In the text field, I have typed "payload" so that I can access the payload data.

In the payload, you can store these types of data:

• Boolean. Valid values: true, false
• Number, such as 0, 123.4
• String, such as "hello"
• Array, such as [1,2,3,4]
• JSON Object, such as { "a": 1, "b": 2}
• Null
  

JSON object payloads are very flexible. As long as the JSON expression is valid, it can be stored in the message payload.

In the example below, you can see an inject node where I have set it's payload to contain a JSON document.

In the inject node, you can insert the JSON document in the payload by selecting the appropriate JSON data type, and then clicking on the button marked "..." (see arrow "1").

This will show the JSON editor:

The JSON editor makes it easy to create a JSON document. There is also a visual editor tab that allows you to browse through a JSON document.

You can pass this JSON (or other datatype) payload to the next node. For example, if the next node is a debug node, it will be configured like this:

In the debug window, the JSON document will look like this:

Some nodes, such as the inject node, can also work with custom attributes attached to the msg object. Here is an example:

In this example, I have created two custom attributes, a number and a string. I can use these attributes in the next node by referencing them:

Variables

Next up: variables.

With variables you can share data across any nodes, and even flows.

Think of variables in Node-RED as variables in a programming language like Ruby and Python. In such languages we have global and local variables. Access to the variable depends on the variable's scope.

Similarly in Node-RED, we have the concept of scope, and as a result there are variables that allow access to their values depending on their scope.

You can learn more about context in Node-RED by reading this documentation page.

In Node-RED there are three scopes:

• Node (equivalent to a local variable in Python). It is only visible to the node that set the value.
• Flow (equivalent to a global variable in Python). It is only visible to all nodes on the same flow (or tab in the editor)
• Global (equivalent to a system variable in Python) - visible to all nodes
  

A global variable is can be set by a node in one flow, and be read by another node in any other flow. In a programming language like Python, this is roughly equivalent to the concept of cross-process (or inter-process) communication.

Most often you will be working within a flow context. In such case, you can set a flow variable using the "flow.set()" function.

Here is an example from the Terrarium project:

To read a flow variable, you can use the "flow.get()" function. Here is an example from another function node:

Here, I read the value stored in a flow variable called "raw_humidity_value", and apply it to a calculation.

At this point, you have a good basis for getting into hands-on examples of flows that contains the most common Node-RED nodes.

In the next article, you will dive into the debug node.