How to use Join App in NodeRED

The day finally comes where Join app is almost everywhere!

It has been a few days since Joao got the Join working with the NodeRED. If you never heard of NodeRED, this is a Raspberry Pi (or Windows, Linux etc) visual programming. If the idea of writing lines of code makes you feel uncomfortable, you should seriously check the NodeRED out.  Using Join App in NodeRed is simple, as dedicated nodes are available.

Join App in NodeRED

By the time you read this tutorial, installing NodeRED should be as simple as executing the following code in the terminal:

npm install node-red-contrib-join-joaoapps

Then restarting the NodeRED:

node-red-stop 
node-red-start
or 
sudo reboot

Or through the Pallete Manager in the NodeRED interface itself (look for node-red-contrib-join-joaoapps). If you want to sideload the latest code from GitHub, use the instructions below.

Installing Join Nodes from GitHub

To install node simply log in via SSH to Raspberry Pi and run:

git clone https://github.com/joaomgcd/node-red-contrib-join-joaoapps.git /home/pi/.node-red/join

Navigate to the node folder and install downloaded files:

cd ~/.node-red
sudo npm link join

Then restart the server to apply the changes and delete the git file

node-red-stop
node-red-start

You should see the node in after logging in to your NodeRED server. Before we can use Join App in NodeRED we have to configure the node for sending and receiving notifications.

You have to use the beta version of the Join app. Open Google Play store, find Join app, and sign up for beta releases. The main version does not support the NodeRED features yet. It will be added later to the main release.
Join by joaoapps
Price: Free+

I’m running my NodeRED from a $5 RaspberryPI Zero. It’s a very cheap way of running the NodeRED server. While adding the Join Extension is recommended, it is not needed if you forward the Join port defined in the config and point it to your NodeRED IP.

Due to the processing speed of RPI Zero, adding the Join extension to Chromium and setting the encryption is a lengthy process due to CPU utilisation, but it assures that your push can be received from WAN, without ports forwarded. Please remember to go to Join extension settings (advanced) to set the port and relay a full push.

Please note in the current version of the Join for NodeRED the encryption is not (yet) supported and must be disabled on all Join devices. 

Using Join in NodeRED

Open this link to grab your API key. Keep it safe, don’t share it! You will need this to authorise the Join server. Add a Join Received Message node to your flow and open the config tab:

This slideshow requires JavaScript.

There are three screens to customise. The command filter is what your commands will start with in order to trigger the NodeRED. If you set the filter to ‘node‘ this is how your commands have to be formatted:

node=:=this is a message

Open the server config and add a Join server. The default port is 1820, but you can set it to whatever you want as long as the port is not used by other programs. Consider forwarding this port in your router and pointing it at the NodeRED server local IP.

Lastly, authorise the Join by entering the API key and adding a unique name. This name will appear as one of your Join devices.

Join Receive Message Node

Now, you can add a debug node and deploy the flow. We can send a test message from Join.  For the purpose of this tutorial I’m sending:

node=:=test

The message received will look like this:And will contain the information:

{
"payload":
{
 "command":"node",
 "null":"test"
},
"push":{
 "text":"node=:=test",
 "deviceId":"ID_of_this_device",
 "senderId":"ID_of_sender",
 "id":"93824743-e810-3399-c21e-9101720678f0",
 "date":1520094138569},
 "_msgid":"f20a81ae.f1865" }
}

Let’s also add a variable name in the Join Received Message config, to make the message more useful. When I send a new message:

node=:=test1=:=test2

I will get:

which is constructed like this:

{"payload":
{
"command":"node",
"var":["test1","test2"]
},
"push":
{
    "text":"node=:=test1=:=test2",
    "deviceId":"4291ac29aebe469XXXXXXXXXXXXXXXX",
    "senderId":"bcfcd58474cf450aXXXXXXXXXXXXXXX",
    "id":"d54f59dc-2a71-fbfb-acb3-6e17064c3311",
    "date":1520454904359
},

"senderId":"bcfcd5847XXXXXX",
"_msgid":"8149c7e2.c6b518"
}

Great! How can we actually use this information? You can access this information or send it to another node. The information is stored in the following functions:

msg.payload - contains the entire message
msg.payload.command is "node"
msg.payload.var[0] contains "test1"
msg.payload.var[1] contains "test2"
msg.push.text contains "node=:=test1==test2"
etc...

Let’s create an example. I’m going to create a simple website with a weather widget. To display the website I’m going to add:

npm install node-red-dashboard

and use it to create a user-friendly interface with texts, toggles and our weather report. To display a simple text on this website, use the text node. For the sake of this example, I’m not going to create the entire weather reporting profile in Tasker (see this if you want your own weather report in Tasker).

I will use Join just to send the relevant information:

node=:=The weather is nice today!

This message will be received by the Join Receive Message node and stored as msg.payload.var (I populated the variable field with “var”). To send this value further as the payload, I need to use a function node with the following code:

var x = msg.payload.var; //arays should use msg.payload.var[z] where z is the array position 
msg.payload = x;

return msg;

Once the progress is saved and nodes are linked, I can test it out:

You can use this system to send any information over from Join (and Tasker) to NodeRED and let the NodeRED process it accordingly.

Join Push Node

To send the messages or information to Join devices, you will have to use the other node Join Push. The node will send the information to the device of your choice. The Join Push can act in 2 ways:

  • Command mode (title field is empty, the text field is used)
  • Notification mode (title has data)
Command mode

If you leave out the title, the data is sent to the target device without creating a notification. This command is intercepted by Tasker or EventGhost and act upon.  You can still set other fields like URL or icon.

Notification mode

Adding the title to your push will create a notification on your Android phone or Chrome web browser.  This is the best option if you want to create a simple notification on your target device. You can also use that to trigger a Tasker profile or EventGhost action.

There are 2 ways in which you can configure the Join Push node:

Simple

Double click on the node, and fill in the information. You won’t be able to programmatically change this information. It’s best for static notifications like “Your PC is online”

If you want to send a message to a Join Device named Laptop – the fields should be:

DeviceID: (use if you don't use Device Name)
Device Name: Laptop
Title: Device Status
Text: Your PC is online!
Icon URL: (optional) url of a publicly available icon

If you are interested in using the deviceID – see this link to look up your Join Devices and get their IDs.

Advanced

This is a more fun of doing things as you can dynamically assign the values to each field. To send the same notification we have to use an empty Join Push node and the function node defined in this way.

msg.text = "Your PC is online!";
msg.title = "Device Status";
msg.devices = "Laptop";
msg.icon= "url of your icon";
return msg;

It’s worth noting that we can also set the properties of the Join Push using NodeRED topics.Lastly, if you want to issue the same message to multiple devices, provide a name for each device separated by the comma symbol.

Advanced Push Object

Join Node 1.1.1 introduced the full API, which can be used to create the push object. Every aspect of the message sent now can be configured programmatically.

For ease of use, a separate JSON object can be configured (msg.push) to send the notification containing more details:

msg.push = {
"title":"An awesome titile",
"text":"Super Text", 
"icon":"url_to/file.png",
"smallicon": "url-to/House-Icon.png",

//... enter more values if needed

};
return msg;

Thanks to the complete API, you can set parameters like notification settings, files, clipboard or SMS information. Just refer back to the Join API to get the correct key values for your JSON object.

Conclusion

I have been waiting for a simple way of connecting NodeRED and Tasker for some time. Join makes it so simple. If you are new to NodeRED, I would recommend you to check it out. You can run your own server on a $5 device. If you are new to Tasker and Join, both are great options to communicate with Android devices. You can download the tutorial nodes from the link below.

Support NotEnoughTech
A lot of time and effort goes into keeping NotEnoughTech alive! If my work helped you out, consider buying me a coffee or check out exclusive rewards available to Patreon supporters.
SHARE