Using the Node-Red Function Node- Beginners Guide

node-red-function-nodeThe function node is used to run JavaScript code against the msg object.

The function node accepts a msg object as input and can return 0 or more message objects as output.

This message object must have a payload property (msg.payload), and usually has other properties depending on the proceeding nodes.



Accessing the msg Properties in The Function Node.

The message payload can be accessed using:

var payload=msg.payload;

and can be modified using:

msg.payload=payload;

Likewise the message topic can be accessed using:

var topic=msg.topic;

and can be modified using:

msg.topic= topic;

It can be extended using

var  newvalue;
msg.newproperty=newvalue;

Now the msg object has a property called msg.newproperty.

Creating a New Message Object

Inside a function you can create a new msg object using:

var newMsg = { payload: msg.payload,topic:msg.topic };
return newMsg;

Using the Function Node

When you drop a function node onto a flow , and go to edit you will see a single line of code that returns the msg object and a blank line above were you can start to enter your own code.

node-red-function-edit

If you don’t return a msg object then the flow stops.

Simple Function Example 1

The flow below is uses the function node with the default code which simply returns the msg object.

The effect is simply to pass the msg object and all of it’s properties from the input node to the output node and the next node in the flow (debug).

simple-function-example

The inject node injects a msg object into the flow with the Unix timestamp as the payload and a blank topic. It is passes through the do nothing function node and you can see that this appears on the debug node.

Function Node Example 2

Next we use the inject node to inject a payload with the string “test string”  and a topic of test.

If we pass this into our do nothing function as before we get the following output.

node-red-function-example-2

The output is as expected. This time we show the topic as test and the payload as test string.

Now if we modify the function to change the payload t Uppercase and the topic to upper case using the following code:

var payload=msg.payload; //get payload
msg.payload=payload.toUpperCase(); //convert to uppercase
var topic=msg.payload; //get topic
msg.topic=topic.toUpperCase();//convert to uppercase
return msg;

The first line of the code retrieves the msg payload.

var payload=msg.payload; //get payload

The second line converts it to uppercase and re-assign it back to the msg object.

msg.payload=payload.toUpperCase();

We then do exactly the same with the topic property before returning the complete msg object.

The output on the debug screen is shown below:

function-node-example-2-out
Notice the topic and payload have been converted to uppercase.

Multiple Outputs

The function node can be configured with multiple outputs.

This is useful when the flow splits into separate paths depending on a message property.

To configure multiple outputs open the function node and use the up/down arrows to adjust the outputs.

Outputs are numbered starting with 1 at the top.

function-node-multiple-outputs

To return messages to multiple outputs you need to return an array. So the return looks like this:

return [msg1,msg2];

Msg1 will appear on output1 and msg2 on output2. To stop a flow you return null.

So to return the msg objext on output1 and nothing on output2 use:

return [msg1,null];

Example

In the example flow we use two inject nodes to inject a message on two different topics and send the message to the output based on the topic name.

Topic test1 goes to output1 and test2 goes to output2.

Node-Red-Function-Example-3

The following code is used in the function node to spit the message path based on the topic name.

Notice the return statement.

var topic=msg.topic;
if (topic=="test1"){
    return [msg,null];
    
}
if (topic=="test2"){
    return [null,msg];
    
}

The output on the debug screen is show below:

function-example-3-debug-screen

Multiple Messages on a Output

You can use an array to return multiple msg objects on an output.

So the return would look like this

return [msg_object_array];

Important you are returning an array of objects in an array.

This is best seen with an example

Example Multiple Messages:

In this example we use an inject node to inject a test string into the function node.

The function node takes the string and uses it for the message payload, but instead of sending 1 message it has a for loop which creates 3 messages and puts them in an array . The function returns the array as an array!

Here is the flow:

node-red-function-example-4

Here is the function code

var m_out=[]; //rray for message objects
var message=msg.payload;
for (i=0;i<3;i++){
    
    message=message+i; //add count to message
    var newmsg={payload:message,topic:msg.topic}
    m_out.push(newmsg);
}
return[m_out];

Important– notice the return statement returns an array.

Here is the debug screen output when run notice the debug screen shows 3 messages:

function-node-example-4-output

Storing Data

Data can be stored in the function node using the context object.

Storing data is covered in Storing Data in Node-Red Variables

Resources:

Related Tutorials


Facebooktwittergoogle_plusredditpinterestlinkedinmail

One comment

Leave a Reply

Your email address will not be published. Required fields are marked *