Node-Red - Getting Started
From Zenitel Wiki
Node-RED is the open-source software that is used as an event programming for Zenitel Connect Pro.
The benefits of Node-RED are
- Easy to use – Low-code platform, graphical way of programming
- Although low-code: still powerful
- Many existing integrations and programming examples
- Easy to re-use (export and import capability)
- Intuitive debug possibilities
For installation of Node-RED see the article: Node-Red - Installation
General description
Node-RED is a graphical programming language based around receiving, processing and sending messages.
Messages can be manipulated using 'nodes' that can be dragged and dropped to the workspace, linked together in chains and then sent to the output. With respect to Zenitel Connect Pro, these messages can be events occurring in the server, such as Calls or Door Opening events. Manipulation of the message may include IF statements, setting a new parameter such as Directory Number or including a delay.
Output from Node-RED can be sent back in to ZCP to initiate a new call, or control an output or relay. It could also be towards a third party application.
 |
| Node-RED example |
Zenitel Connect Pro configuration
License
Node-RED connects to Zenitel Connect Pro as a Zenitel Link user. This requires an
- Integration license (ZCL-API) - 1002720900
Zenitel Link user
The communication between Node-Red and Zenitel Connect Pro is using the "Zenitel Link" protocol.
A Zenitel Link user must be created in Zenitel Connect Pro.
- In ZCP go to System > Users
- Press the
to add a new user - Give the user a Name and a Password, and set the Role = "Zenitel Link User"
Firewall
The communication between Node-RED and ZCP requires that TCP port 8086 (Secure WAMP) is enabled in the firewall of the ZCP. This port is by default enabled.
 |
| Firewall ports for WAMP connection to Node-RED |
The Node-RED User Interface
To access the Node-RED web GUI enter https://[IP Address]:1880 in your browser, where "IP Address" is the IP address of the Zenitel Connect Pro. (e.g. "https://10.9.8.207:1880").
 |
| Node-RED User Interface overview |
The workspace consists of three main parts:
- The list of installed nodes (the pallette) that can be dragged into the main work area
- The main workarea with tabs for different flows
- The right side pane can display different things. Some information that can be found here is the help description on nodes, debug console, global variable data, and global configuration nodes
Under 4 you will find a menu with various options like import, export and the pallette manager
Installing WAMP nodes
|
This step is only necessary when running Node-RED on a third party server or on Zenitel Connect Pro prior to version 1.5.0. |
In order to connect Node-RED to Zenitel Connect Pro, you need to install the Zenitel specific WAMP connector nodes.
- In the Node-RED user interface click on the "Hamburger" menu icon in the top right, and choose Manage palette
- Choose the Install tab
- In the search bar, type zenitel and press enter
- Select 'node-red-contrib-zenitel-connect-pro' and press Install
 |
| Node-RED WAMP node installation |
|
|
If you get an EAI_AGAIN error on installing please check your DNS and Gateway settings of Zenitel Connect Pro |
This will install 3 groups of node nodes in the Palette (the left-hand side list of nodes). These three groups are Zenitel specific: Zenitel Events, Zenitel Actions and Zenitel Request.
- Zenitel Events is a group of nodes for subscribing to data in Zenitel Connect Pro. A detailed description of the nodes can be found in the article Node-Red - Zenitel Event Nodes
- Zenitel Actions are all nodes used to trigger an action in Zenitel Connect Pro. A detailed description of the nodes can be found in the article Node-Red - Zenitel Action Nodes
- Zenitel Request these nodes can be used to actively request data from Zenitel Connect Pro. A detailed description of the nodes can be found in the article Node-Red - Zenitel Request Nodes
Wamp URI's
A WAMP URI (Web Application Messaging Protocol, Uniform Resource Identifier) is a standardized way to identify resources in Zenitel Connect Pro.
In the Zenitel nodes these URI have been predefined for the specific function.
For a full overview of available WAMP URI's, enter <ZCP IP Address>/openapi in your browser (e.g. 10.9.8.207/openapi)
Setting up Node-RED for the first time
When setting up Node-RED for the first time, we need to add a WAMP Connection point and the authentication details.
- Drag and drop the Zenitel node you want into the workspace.
- Double click on the node
- Press the + icon beside the field Add new wamp-client
- Zenitel Connect Pro IP field: Enter the Zenitel Connect Pro IP Address"
- Zenitel Link Username field: The Zenitel Link username
- Zenitel Link Password field: The Zenitel Link password
- Name: Give your Wamp Connection a friendly name (e.g. "Zenitel Connect Pro")
- Click Add and then Done to finalize the properties. These details will be retained in the system
 |
| Node-RED WAMP client setup |
Importing flows
To import an existing flow, click on the "hamburger" icon in the top right corner and select Import. Now you can choose to:
- Import a file (json format), or
- Paste the source code in to the clipboard
 |
| Importing a flow |
Example
Trigger a second Relay at Door Opening
Scenario: A client requires that in addition to the Relay being triggered at the Door intercom for access control, a second relay on another device is required to provide a signal to indicate the door has been opened. This additional signal is for a mimic panel, and for input into the Building Management System.
The directory number of the Door is 202 and the Directory number of the second device is 204.
- From the Palette, drag and drop a Zenitel Door Open event node to the Workspace
- From the Palette, drag and drop a Zenitel GPO Trigger action node to the Workspace
- Connect the nodes by drawing a line between the connection points in each node
 |
| The two nodes connected in the Workspace |
Double-click the Zenitel Door Opening Event node and create a WAMP client as described above.
Fill in a directory number for the door station (202)
 |
| Configuring the Door Open event node |
Double-click the "Zenitel GPO Trigger" node, and in the drop down for the client pick the one created earlier.
For the other fields:
- Dirno is the directory number of the second device (204) where the relay needs to be triggered
- Output is Relay 1
- Action is Set Timed
- On time is 5
 |
| Configuring the Wamp Call node |
The flow should now look like this:
 |
| Node-RED flow configured, but not deployed |
The blue circle in a node indicates that there has been changes to the node which has not yet been Deployed.
Click on the Deploy button in the top right corner of the Node-RED interface to save the configuration. The nodes should now indicate that they have established connection with the Zenitel Connect Pro:
 |
| Node-RED flow configured and deployed |
If you now establish a call with the doorstation and press digit "6" to trigger the relay, also the relay of the second device should trigger.
Debugging and troubleshooting options
To be able to troubleshoot a flow you might want to be able to manipulate and inspect the messages being send between the nodes. There are two very useful nodes to accomplish this.
The inject node
The inject node can be used to inject a message anywhere in the flow. This can be particular useful when you are expecting a message coming from a third party system but this is not available yet. With the inject node you can start testing your flow beforehand.
 |
| The inject node |
 |
| The options for injecting different types of messages |
The debug node
On the right hand side of your Node-RED window there is a debug pane. You can display messages being send between nodes by using the debug node. If you have multiple debug nodes in your flow you can turn them on and off to only view the one you are interested in. In the configuration of this node you can choose to only display the message payload, which is only the actual data, or the entire message object that is including all the meta data.
 |
| The debug node |
 |
| The options for displaying only the payload or the entire message object |
Further reading
We advise beginners to read further in the Node-RED cookbook: https://cookbook.nodered.org