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.topic; //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 2 or more 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 path you return null on that output.

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

return [msg1,null];

or

return [msg1];

Example 2 outputs

In the example flow we use two inject nodes to inject a message on two different topics to a function node with two outputs.

The function sends 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

Returning Nothing From a Function Node

We have seen this previously but it is important to understand that sometimes the function node may not return anything.

When a function node doesn’t return anything the nodes connected to the function output aren’t triggered and the flow stops for that path.

There are several ways of doing this:

  • Don’t use a return statement
  • Return a null msg object e.g. return null;

Returning Messages Asynchronously

Generally you return a message at the end of the function using the return statement but you can return a message in the function node using the node.send() function.

This is useful for example when looping through an array or object and sending data.

In the example function below I loop trough an array 10 times and send a message each time.

count=0;
for(var i=0;i<10;i++)
{
msg.payload=count;
node.send(msg)
count+=1; 
}

When using node.send() in the function node don’t use a return statement.

Displaying Status Information

Your can display stays information from your own function nodes in the admin UI.

To do that use the following:

node.status(Object)

The object you pass can have three key value pairs:

  • fill – This is the fill colour can be: red, green, yellow, blue or grey
  • shape- Ring or Dot
  • Text – descriptive text

The screen shot below shows an example function configured to display status information using the following:

node.status({fill:"green",shape:"ring",text:"done"});

function-status

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 in The Function Node

If you need to use a 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: pay attention to the file path name



Resources:

Related Tutorials


Click to rate this post!
[Total: 0 Average: 0]

33 comments

  1. Hi, I try to add some data to my MariaDB via Node-red and the functions box.
    If I run the code below, it works fine. But I like of course to exchange the fixed values to actual values from enitities from home assistant. I have tried to send a value of the entity via the msg.payload and it works, but I like to send like 5 different values/entities into the function. How can I do that?

    msg.payload=[];
    msg.topic=”INSERT INTO data_consumption (`month`, `year`, `upload`, `download`) VALUES (02, 2021, 34, 54);”
    return msg;

    Thank you!

    1. Instead of 02 use a variable called month. You receive the data in the payloade.g.
      msg.payload={“month”:01,”year”:2021} //example
      var month=msg.payload.month;
      var year=msg.payload.year;

      msg.topic=”INSERT INTO data_consumption (`month`, `year`, `upload`, `download`) VALUES (month, year, 34, 54);”

      You will probably need to delimit the variables as they are strings. Here is an insert taken from one of projects.

      query=query+” values(“+stored_order_number+”,\'”+paper_order_number+”\’,”+

      stored_order_number=integer and doesnt require delimiting
      paper_order_number=string and does require it.
      Hope that helps
      Rgds
      Steve

  2. Steve,
    Can I output messages without executing the return statement ??? If so, how do I do it ? I want to send multiple messages to MQTT and I don’t want to create numerous output ports in a function node.

    Mike

  3. I’m trying to get one input to 1 of 5 function node outputs, e.g “i’m in bed” should go to msg1, next to msg2 etc. It’s basically a payload of ‘on’ and the ‘topic’. I could do it with switch nodes but I’m trying to save some screen space and up my game. I think I’m close but can’t put my finger on it!
    var des=msg.payload.description.summary;
    msg.topic = (des);
    var pay=(payload = ‘on’);
    msg.payload = (pay)

    if(des.includes(“i’m in bed”))
    {return [msg,null,null,null,null]}
    else if (des.includes(“i’m getting up”))
    {return [msg,null,msg,null,null,null]}
    else if (des.includes(“i’m having a nap”))
    {return [msg,null,null,msg,null,null]}
    else if (des.includes(“i’m going to sleep”))
    {return [null,null,null,msg,null]}
    else if (des.includes(“bedside light”))
    {return [null,null,null,null,msg]}

    return [msg1, msg2, msg3, msg4, msg5];
    Thanks and Happy New Year!

    1. Try changing
      var des=msg.payload.description.summary;
      msg.topic = (des);
      var pay=(payload = ‘on’);
      msg.payload = (pay)

      var des=msg.payload.description.summary;
      to msg.payload=”on;

      Not sure what you want to do with the topic

      1. Thanks Steve for the quick reply. Ah I see now that I didn’t have to modify the variable ‘payload’, just state that it was ‘on’. Great.
        The topic is going out to call various input booleans and set timers (I will get to javascript service calls from function nodes in the future!) and so needs to come out of the correct function node output – so far I can get the same topic as x5 messages or various topics on only the first output.
        I think I need something like this at the top but I’m unsure of the format.
        var msg1 = msg.topic1 + msg.payload;
        var msg2 = msg.topic2 + msg.payload;
        var msg3 = msg.topic3 + msg.payload;
        var msg4 = msg.topic4 + msg.payload;
        var msg5 = msg.topic5 + msg.payload;
        and then define the topics as;
        msg1.topic = “i’m in bed”; //reading so bedside light on for 2 hours
        msg2.topic = “i’m getting up”; //allow motion triggers
        msg3.topic = “i’m having a nap” //deny bedroom motion triggers + set alarm
        msg4.topic = “i’m going to sleep” //deny bedroom motion triggers + turn stuff off
        msg5.topic = “bedside light”
        is it the Return statement that isn’t working? Thanks

    2. Your original code works but you are using smart quotes and also quotes in quotes. Smart quotes are created on windows. Use notepad as the editor and not word.
      I’ve tested the code below
      //var des=msg.payload.description.summary;
      var des= “in bed”;
      msg.payload = “on”;

      if(des.includes(“in bed”))
      {return [msg,null,null,null,null]}

      else if (des.includes(“getting up”))
      {return [msg,null,msg,null,null,null]}
      else if (des.includes(“having a nap”))
      {return [msg,null,null,msg,null,null]}
      else if (des.includes(“going to sleep”))
      {return [null,null,null,msg,null]}
      else if (des.includes(“bedside light”))
      {return [null,null,null,null,msg]}

      1. Yes I spotted the ” and ‘ issues when some of the outputs worked and not others! For completion – this is what I ended up with;
        var des=msg.payload.description.summary;
        msg.topic = (des);
        msg.payload=”on”;
        var msg1 = {};
        var msg2 = {};
        var msg3 = {};
        var msg4 = {};
        var msg5 = {};

        if(des.includes(“i’m in bed”))
        {return [msg,null,null,null,null]}
        if(des.includes(“i’m getting up”))
        {return [null,msg,null,null,null]}
        if(des.includes(“i’m having a nap”))
        {return [null,null,msg,null,null]}
        if(des.includes(“i’m going to sleep”))
        {return [null,null,null,msg,null]}
        else if(des.includes(“bedside light”))
        {return [null,null,null,null,msg]}
        return msg;

        Thanks for the help, this was a battle to understand, adapt and apply other peoples code from a fairly n00b perspective. Cheers

  4. Hi,
    I am trying to use a function Node to setup flow variables with stock prices from an API but I am not a programmer.

    Currently I have:

    var t = “sharePrice.”+msg.payload.symbol
    var p = msg.payload.close
    flow.set(t,p)
    return msg;

    This works just fine when the stock symbol is something like: QCOM
    The problem I have is that some stocks are returned with the exchange tagged on the end: LLOY.XLON

    I need to test for .XLON (or any other exchange for that matter) and remove it before using the above code, but all attempts have failed so far.

    Can you help, please!

    Thank you.

    1. The easiest way is to replace the string with a blank
      use
      var x =(msg.payload.symbol).replace(“QCOM”,””);
      and repeat for the others.
      another way is to split the string and take the first element
      var x= (msg.payload.symbol).split(“.”);
      your value is in x[0];
      rgds
      Steve

  5. I’m trying to pull an attribute from object into a JSON but can’t find the right syntax.

    Use case is I have an open garage door alert that should include in the push notification how long the garage door has been open (based on a counter in the sequence. I have a counter node that passes the counter value as msg.count into a change node used for defining my push notification message to my phone. I want to use msg.count in the JSON expression for the message but I can’t seem to parse it out. When I try “message”: “Garage door has been open for {{msg.count}} minutes.”, I receive a “Call-service API error. Error Message: UndefinedError: ‘msg’ is undefined” error. How can I reference this msg value in my JSON?

    1. Hi
      It looks like you are using the template node try {{count}}. If that doesn’t work send me the flow using the ask steve page
      Rgds
      Steve

  6. Hi Steve,
    How can I set msg.payload with parameters to function node rather than inject node. means send msg.payload from http or template nodes on separate flow.

    1. Not really quite sure what you are getting at. The message node can set any msg property. The inject node is used normally to start a flow.

  7. Hi Steve,

    Please help how to calculate op time of a device (i’m using ibm iot conveyor belt).
    I’ve been following this https://github.com/cflurin/node-red-contrib-dsm/wiki/Operating-time , but unfortunately i can’t make it stop.

    [{“id”:”f879cfca.16851″,”type”:”tab”,”label”:”Flow 13″,”disabled”:false,”info”:””},{“id”:”e6720831.30cde8″,”type”:”dsm”,”z”:”f879cfca.16851″,”name”:”operating time v1″,”sm_config”:”{\n \”currentState\”: \”stopped\”,\n \”states\”: {\n \”stopped\”: {\n \”on\”: \”started\”\n },\n \”started\”: {\n \”inc\”: \”counting\”,\n \”off\”: \”stopped\”\n },\n \”counting\”: {\n \”inc\”: \”counting\”,\n \”off\”: \”stopped\”\n }\n },\n \”data\”: {\n \”prev_time\”: null,\n \”time\”: 0,\n \”seconds\”: 0,\n \”interval\”: 1,\n \”interval_output\”: true,\n \”hms_format\”: true\n },\n \”methods\”: {\n \”init\”: [\n \”sm.calc_time = function() {\”,\n \” var now = Date.now();\”,\n \” sm.data.time += now – sm.data.prev_time;\”,\n \” sm.data.prev_time = now;\”,\n \” sm.data.seconds = Math.round(sm.data.time / 1000);\”,\n \”};\”,\n \”sm.sec2hhmmss = function(sec) {\”,\n \”var t = {};\”,\n \”t.h = pad(Math.floor(sec / 3600));\”,\n \”sec %= 3600;\”,\n \”t.m = pad(Math.floor(sec / 60));\”,\n \”t.s = pad(sec % 60);\”,\n \”return t.h+’:’+t.m+’:’+t.s;\”,\n \”};\”\n ],\n \”on\”: [\n \”if (sm.currentState === ‘started’) {\”,\n \” sm.data.prev_time = Date.now();\”,\n \” resume(‘inc’, msg);\”,\n \”}\”,\n \”output = false;\”\n ],\n \”inc\”: [\n \”timeout.interval = setTimeout(function() {\”,\n \” sm.calc_time();\”,\n \” msg.data = sm.data;\”,\n \” if (sm.data.interval_output) {\”,\n \” msg.payload = sm.data.hms_format ? sm.sec2hhmmss(sm.data.seconds): sm.data.seconds;\”,\n \” node.send(msg);\”,\n \” }\”,\n \” resume(‘inc’, msg);\”,\n \”}, sm.data.interval*1000);\”,\n \”output = false;\”\n ],\n \”off\”: [\n \”clearTimeout(timeout.interval);\”,\n \”sm.calc_time();\”,\n \”msg.payload = sm.data.hms_format ? sm.sec2hhmmss(sm.data.seconds): sm.data.seconds;\”\n ],\n \”reset\”: [\n \”sm.data.time = 0;\”,\n \”sm.data.seconds = 0;\”\n ],\n \”status\”: {\n \”fill\”: {\n \”get\”: \”sm.currentState === ‘counting’ ? ‘green’ : ‘grey’;\”\n },\n \”shape\”: \”dot\”,\n \”text\”: {\n \”get\”: \”‘time ‘ + (sm.data.hms_format ? sm.sec2hhmmss(sm.data.seconds): sm.data.seconds);\”\n }\n }\n }\n}\n”,”x”:750,”y”:360,”wires”:[[“58ee86f3.1578d8”]]},{“id”:”56f65892.a42a48″,”type”:”function”,”z”:”f879cfca.16851″,”name”:”START”,”func”:”msg.payload=\”start\”\nmsg.topic=\”on\”\nreturn msg;”,”outputs”:1,”noerr”:0,”x”:540,”y”:320,”wires”:[[“e6720831.30cde8”]]},{“id”:”7fa2319e.ccd0a”,”type”:”function”,”z”:”f879cfca.16851″,”name”:”STOP”,”func”:”msg.payload=\”stop\”\nmsg.topic=\”off\”\nreturn msg;\n”,”outputs”:1,”noerr”:0,”x”:530,”y”:400,”wires”:[[“e6720831.30cde8”]]},{“id”:”9fbe35bd.5b7388″,”type”:”ibmiot in”,”z”:”f879cfca.16851″,”authentication”:”boundService”,”apiKey”:””,”inputType”:”evt”,”logicalInterface”:””,”ruleId”:””,”deviceId”:”conveyor-belt1″,”applicationId”:””,”deviceType”:”iot-conveyor-belt”,”eventType”:”+”,”commandType”:””,”format”:”json”,”name”:”IBM IoT – Conveyor”,”service”:”registered”,”allDevices”:””,”allApplications”:””,”allDeviceTypes”:””,”allLogicalInterfaces”:””,”allEvents”:true,”allCommands”:””,”allFormats”:””,”qos”:0,”x”:210,”y”:320,”wires”:[[“56f65892.a42a48″,”7fa2319e.ccd0a”]]},{“id”:”58ee86f3.1578d8″,”type”:”debug”,”z”:”f879cfca.16851″,”name”:””,”active”:true,”tosidebar”:true,”console”:false,”tostatus”:false,”complete”:”false”,”x”:980,”y”:360,”wires”:[]}]

    1. Hi
      The flow doesn’t import can you contact me via the ask steve page and we can exchange it via email attachment.
      Rgds
      Steve

    1. Not quite sure what you mean but the function node doesn’t start anything instead it accepts an input and produces an output so something else would need to capture the photo and pass it into the function node.

  8. I use your course with interest. Good job. I found a small error in the article “node-red-functions” – change the payload to Upper case.
    It is written:
    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;

    should be (errata):
    var payload = msg.payload; // get payload
    msg.payload payload.toUpperCase = (); // convert to uppercase
    var topic = msg.topic; // get topic !!!!!!
    msg.topic = topic.toUpperCase (); // convert to uppercase
    return msg;

    Regards …

  9. 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.

    1. No your not. If you send me a copy of the flow I’ll take a look. Use the ask steve page and paste it there.
      Rgds
      Steve

  10. 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?

  11. 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.

  12. 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

  13. 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 to steve Cancel reply

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