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 time stamp 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 Upper case 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 upper case 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 upper case.

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 Single Output

You can use an array to return multiple msg objects on a single 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 on Single Output:

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 code of the function node:

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

Video -Node-Red Function Node for Beginners

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

Reusing Function Nodes

You can save your function nodes in the library and reuse them in other flows by importing them

To save a function to the library double click on the function to edit it and click on the bookmark icon next to the function name.

A drop down menu appears to either import or save the function to the library.

node-red-function-library

See this tutorial on storing flows and functions for more details.

You can also use a sub flow to store your functions. Using a sub flow makes them available as nodes which you can select from the node palette on the left. See this video on creating and using subflows.

Using Additional Node Modules

If you need to use an node module e.g the os or fs module then you need to enable them in the settings.js file under the functionGlobalContext: object as shown in the screen shot below:

To use them in the function node they are part of the global object so use:
var os=global.get(‘os’);
var fs=global.get(‘fs’);

Function Example:

This function will list all files of the type .js on the console

var fs=global.get('fs');
var path="/home/steve/.node-red";
try{
fs.readdir(path, function(err, items) {
    for (var i=0; i<items.length; i++) {
 var r=items[i].search(/\.js/);
if (r!= -1)
        node.log(items[i]);
else
node.log(items[i]+"is not a js file");
    } //for loop
});
}
catch(err){
node.log("error");
}
return msg;

Note: path attention to the file path name



Resources:

Related Tutorials


Please rate? And use Comments to let me know more
[Total: 2    Average: 4.5/5]

11 comments

  1. Hi, I’m trying to run a function that is powering my HVAC system based on the CO2 and TEMP. I have managed to create this in one function (MQTT is sending the msg.payload.XXX values), but as I’m powering a 230v device I would need it to 1st ramp up to full power (i.e value 1024) and then ( say after 10 seconds ) to return to value 100 (otherwise could be that the 100 is not enough to start VAC motor turning) . This should only occur when moving from value Zero to 100.
    This is my current function code:

    if (msg.payload.VP8 == 1) {
    msg.payload = 0; //”Sauna on, Power 0″;
    } else if (msg.payload.VP7 == 0 && msg.payload.VP8 == 0) {
    msg.payload = msg.payload.VP6; //”Manual ; power from Slider”;
    } else if (msg.payload.OUT_TEMP <= -5) {
    msg.payload = 0; //"Power 0";
    } else if (msg.payload.OUT_TEMP <= 0) {
    msg.payload = 100; //"Power 100 / 10%"; THIS IS WHERE I NEED THE RAMP UP FUNCTION
    } else if (msg.payload.OUT_TEMP = 5 && msg.payload.CO2 = 5 && msg.payload.CO2 = 5 && msg.payload.CO2 = 5 && msg.payload.CO2 5; i–){
    test.push({payload:[i]});
    }
    return [test];

    I’m I trying to achieve too much in single function or…

    Any help would be appreciated. Thank you.

  2. Hi,
    I want to set the username and password property of mqtt broker from outside the node.
    For, example, I get an authentication token from an http request, I want to send that token as username for mqtt broker. How can I do this?

  3. Hi,
    Thanks for the great tutorial.
    I am new to node red, and an alien to JS.
    I have a message payload that contains a numerical array. I want to convert the payload to base64 string. Using the base64 node doesn’t work properly for arrays.

  4. Hello,
    I am new to Node-Red and am trying to use builtin javascript functions within the function node without much luck.

    Here is my code for the function node:
    msg.payload = { “time” :
    toString(getHours()) + “:” +
    toString(getMinutes()) }
    return msg;

    However, I get the error “ReferenceError: getHours is not defined (line 2, col 14)” even though getHours() is a builtin javascript function to get the hours of the day.
    I would just like the payload to have time in the format “hh:mm”, but I am unable to get it done.

    Look forward to your thoughts and response.
    Kind regards
    Shantanu

  5. Hi, perhaps you can help me. This is probably very simple, but i have been stuck for hours now..
    What i want to do is the to extract temp: value from the object and create a msg.payload
    For some reason the node i am using is just outputting “object” with no payload…

    Example data

    2018-11-03 13:04:20node: 275738a1.8d2a68
    msg : Object
    object
    class: “sensor”
    protocol: “fineoffset”
    id: 247
    model: “temperaturehumidity”
    humidity: 48
    temp: 25.8
    _msgid: “b6d54241.12cfa”

    1. Hi
      You might want to read this as it goes into the msg object in more detail.
      Usually the msg object has a payload but doesn’t have to have one.
      If it had a payload you would access it using
      msg.payload

      to get the humidity from your object use
      msg.humidity
      and temperature
      msg.temp
      Does that make sense? Does it work?
      rgds
      steve

Leave a Reply

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