|
|
| (17 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| {{C}} | | {{C}} |
| =Introduction= | | == Introduction == |
| Node-RED is the open-source software that is used as an event programming for Zenitel Connect Pro.<br> | | Node-RED is the open-source software that is used as a event programming for Zenitel Connect Pro. |
| | |
| The benefits of Node-RED are | | The benefits of Node-RED are |
| *Easy to use – Low code platform, graphical way of programming | | * Easy to use – Low code platform, graphical way of programming |
| *Although low code: still powerful | | * Although low code: still powerful |
| *Many existing integrations and programming examples | | * Ideally with many existing integrations and programming examples |
| *Easy to re-use (export and import capability) | | * Easy to re-use (export and import capability) |
| *Intuitive debug possibilities | | * Intuitive debug possibilities |
| | |
| For installation of Node-RED you can go to this article: [[Node-Red - Installation]]
| |
| <br>
| |
| ==Interface==
| |
| <table style="max-width:80%; border-style: double; border-color: #c7c7c7;">
| |
| <tr style="rowspan:2;">
| |
| <td style="display: block; vertical-align: bottom;">[[Image:Node_red_workspace.JPG|1000px]]</td>
| |
| </tr>
| |
| <tr>
| |
| <td style='background-color:#efefef;'>Node-RED User Interface</td>
| |
| </tr>
| |
| </table>
| |
| ==Operation==
| |
| Node-RED is a graphical programming language based around receiving, processing and sending messages.<br>
| |
| 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.<br>
| |
| With respect to Zenitel Connect Pro, these messages can be events occuring, such as Calls or Door Opening events.<br>
| |
| Manipulation of the message may include IF statements, setting a new parameter such as Directory Number or including a delay.<br>
| |
| Output from Node-RED can be sent back in to ZCP to initiate a new call, or control a GPO. It could also be towards a third party application.<br>
| |
| <table style="max-width:80%; border-style: double; border-color: #c7c7c7;">
| |
| <tr style="rowspan:2;">
| |
| <td style="display: block; vertical-align: bottom;">[[Image:Node_red_mpc.JPG|1000px]]</td>
| |
| </tr>
| |
| <tr>
| |
| <td style='background-color:#efefef;'>Node-RED example</td>
| |
| </tr>
| |
| </table>
| |
| | |
| ==Communication between Node-RED and Zenitel Connect Pro==
| |
| ===Firewall===
| |
| Communication between Node-RED and ZCP is via WAMP.<br>
| |
| This requires that port 8086 is enabled in the firewall of ZCP for Secure WAMP which is the default. If you are using unsecure WAMP, you need to enable port 8087.<br>
| |
| <table style="max-width:80%; border-style: double; border-color: #c7c7c7;">
| |
| <tr style="rowspan:2;">
| |
| <td style="display: block; vertical-align: bottom;">[[Image:Node_red_firewall.JPG|600px]]</td>
| |
| </tr>
| |
| <tr>
| |
| <td style='background-color:#efefef;'>Firewall ports for WAMP connection to Node-RED</td>
| |
| </tr>
| |
| </table>
| |
| | |
| ===Zenitel Link===
| |
| By default, there is no account in ZCP that will allow for connection to the Zenitel Link interface.<br>
| |
| A dedicated Zenitel Link user must be created in the System and Users menu.
| |
| *Press the + icon to add a new user.
| |
| *Give the user a name and a password, and set the Role to Zenitel Link User
| |
| *Press the Tick icon.
| |
| | |
| =Installing Zenitel Connect Pro WAMP connector node=
| |
| | |
| To connect Node-RED to Zenitel Connect Pro, we must first install the Zenitel specific WAMP connector node<br>
| |
| *Navigate to the Node Red menu and choose 'Manage palette'
| |
| *Choose the 'Install' tab
| |
| *In the search bar, type 'Zenitel' and press enter
| |
| *Select 'Node-RED-contrib-zenitel-wamp-auth' and press Install
| |
|
| |
|
| <table style="max-width:80%; border-style: double; border-color: #c7c7c7;">
| | There are three locations where Node-RED can be installed and run: |
| <tr style="rowspan:2;">
| | * On a virtual installation of Zenitel Connect Pro |
| <td style="display: block; vertical-align: bottom;">[[Image:Node_red_wamp_install.JPG|600px]]</td>
| | * On an ICX-510 running Zenitel Connect Pro |
| </tr>
| | * On a 3rd party server |
| <tr>
| |
| <td style='background-color:#efefef;'>Node-RED WAMP node installation</td>
| |
| </tr>
| |
| </table>
| |
|
| |
|
| =WAMP Message Formatting=
| | One installation of Node-RED can connect to multiple Zenitel Connect Pro servers, there is no need for each having their own. |
| ZCP sends information as an Array containing labels and values as strings.<br>
| |
| The format of these arrays varies depending on the message itself, and the format documentation is available from <zcp_ipaddress>/openapi<br>
| |
| The Open Door event for example generates the following items <br>
| |
| from_dirno - Directory Number of operator opening door
| |
| from_name - Display name of operator opening door
| |
| door_dirno - Directory number of Door
| |
| door_name - Display name of Door
| |
| gpo
| |
| gpo_id - Id of the GPO activated
| |
| mac_address - MAC of the device hosting the GPO being activated
| |
| time - Duration in seconds for a timed relay activation.
| |
| <br>
| |
| Node-RED receives this array as a message payload, which is referred to as msg.payload<br> | |
|
| |
|
| As an example, if we look at a Door Open event, it has the following properties<br>
| | For How To get started with Node-RED you can go to this article: [[Node-Red - Getting Started]] |
| msg.payload.args[0]["door_dirno"]
| |
| msg.payload.args[0]["door_name"]
| |
| msg.payload.args[0]["from_dirno"]
| |
| msg.payload.args[0]["from_name"]
| |
| msg.payload.args[0][gpo]["gpo_id"]
| |
| msg.payload.args[0][gpo]["mac_address"]
| |
| msg.payload.args[0][gpo]["time"]
| |
| <br>
| |
| Using this information, we can receive Door Opening events, and process this information.<br>
| |
| =Wamp Nodes=
| |
|
| |
|
| There are 2 WAMP nodes that we utilise in our Node-RED Flow; Wamp In and Wamp Call<br>
| | __TOC__ |
| *Wamp In is a listener that will subscribe to certain WAMP events in ZCP and pass these messages to other nodes in the Flow.
| |
| *Wamp Call is a publisher that will send messages it receives to certain WAMP connection points within ZCP.
| |
|
| |
|
| WAMP events that the Wamp In node can connect to include items like devices and directory, groups, calls and open door.<br>
| | == License == |
| WAMP connection points that the Wamp Call node can connect to include items like calls, open door, gpos and device key emulation.<br>
| | Node-Red connects to Zenitel Connect Pro as a Zenitel Link user. This requires an |
| | * Integration license (ZCL-API) - 1002720900 |
|
| |
|
| For example, to subscribe to Call events, you would drag a Wamp In node to the workspace, and subscribe to com.zenitel.calls. All call activity would be reported by this node to the next node in the chain.<br>
| | == Installation == |
| To make a call using Node-RED, you would drag a Wamp Call node to the workspace, and attach it to com.zenitel.calls.post. Sending a correctly formatted message to this node would initiate a call in ZCP<br> | | === Installation on a virtual Zenitel Connect Pro === |
| | To install Node-RED on a virtual Zenitel Connect Pro you have to install an additional '''.swu''' package on top of an existing installation of Zenitel Connect Pro. The file is independent of the virtualization used; the same installation file is used both in VMWare and Virtual Box environment. |
|
| |
|
| ==First time use==
| | From the [[Downloads#Zenitel_Connect_Pro_.28ZCP.29|Downloads page]] download the file '''Zenitel_Connect_VM_x.x.x-node-red.swu''', where the x.x.x denotes the version of Zenitel Connect Pro you are running. |
| When setting up Node-RED for the first time, we need to add a WAMP Connection point and the authentication details.<br>
| |
| *Drag and drop a Wamp In node to the workspace.
| |
| *Double click on the node
| |
| *Press the + icon beside the field 'Add new wamp-client'
| |
| *Add your ZCP IP Address to the wamp.placeholder.router field
| |
| *Add 'zenitel' to the wamp.placeholder.realm field
| |
| *Add your Zenitel Link username to the wamp.placeholder.authid field
| |
| *Add your Zenitel Link password to wamp.placeholder.password field
| |
| *Give your Wamp Connection a friendly name
| |
| *Click Add and then Done to finalise the properties. These details will be retained in the system
| |
|
| |
|
| =Examples=
| | To install the additional package you can use the [[Software Update (Zenitel Connect Pro)|standard upgrade procedure]] for the Zenitel Connect Pro. |
| ==First example flow==
| |
| A client requires that in addition to the Relay being triggered at the Door 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.<br>
| |
| The directory number of the Door is 202 and the Directory number of the second device is 204.<br>
| |
| This is the only door that is monitored in this way, so while other doors may be opened, they should be ignored.<br>
| |
|
| |
|
| <table style="max-width:80%; border-style: double; border-color: #c7c7c7;"> | | <table style="max-width:80%; border-style: double; border-color: #c7c7c7;"> |
| <tr style="rowspan:2;"> | | <tr style="rowspan:2;"> |
| <td style="display: block; vertical-align: bottom;">[[Image:Node_red_flow1.JPG|600px]]</td> | | <td style="display: block; vertical-align: bottom;">[[Image:Nodered loading.png|700px]]</td> |
| </tr> | | </tr> |
| <tr> | | <tr> |
| <td style='background-color:#efefef;'>Firewall ports for WAMP connection to Node-RED</td> | | <td style='background-color:#efefef;'>Additional Node-RED package loading</td> |
| </tr> | | </tr> |
| </table> | | </table> |
|
| |
|
| To achieve this, we can subscribe to the Open Door WAMP event using a Wamp In node that is subscribed to the Open Door events at com.zenitel.system.open_door.<br>
| |
| <table style="max-width:80%; border-style: double; border-color: #c7c7c7;">
| |
| <tr style="rowspan:2;">
| |
| <td style="display: block; vertical-align: bottom;">[[Image:Node_red_wampin.JPG|600px]]</td>
| |
| </tr>
| |
| <tr>
| |
| <td style='background-color:#efefef;'>Firewall ports for WAMP connection to Node-RED</td>
| |
| </tr>
| |
| </table>
| |
| When we receive an Open Door event, we can extract the door extension number using a change node<br>
| |
| <table style="max-width:80%; border-style: double; border-color: #c7c7c7;">
| |
| <tr style="rowspan:2;">
| |
| <td style="display: block; vertical-align: bottom;">[[Image:Node_red_flow1_change1.JPG|600px]]</td>
| |
| </tr>
| |
| <tr>
| |
| <td style='background-color:#efefef;'>Firewall ports for WAMP connection to Node-RED</td>
| |
| </tr>
| |
| </table>
| |
| Then we can filter based on the door_dirno field using a switch node.<br>
| |
| <table style="max-width:80%; border-style: double; border-color: #c7c7c7;">
| |
| <tr style="rowspan:2;">
| |
| <td style="display: block; vertical-align: bottom;">[[Image:Node_red_flow1_switch.JPG|600px]]</td>
| |
| </tr>
| |
| <tr>
| |
| <td style='background-color:#efefef;'>Firewall ports for WAMP connection to Node-RED</td>
| |
| </tr>
| |
| </table>
| |
| We can then create a new message containing the details for the second device and relay.<br>
| |
| <table style="max-width:80%; border-style: double; border-color: #c7c7c7;">
| |
| <tr style="rowspan:2;">
| |
| <td style="display: block; vertical-align: bottom;">[[Image:Node_red_flow1_change2.JPG|600px]]</td>
| |
| </tr>
| |
| <tr>
| |
| <td style='background-color:#efefef;'>Firewall ports for WAMP connection to Node-RED</td>
| |
| </tr>
| |
| </table>
| |
| Finally, we can send this message to ZCP using a Wamp Call node connected to the GPO connection at com.zenitel.devices.device.gpos.gpo.post<br>
| |
| <table style="max-width:80%; border-style: double; border-color: #c7c7c7;">
| |
| <tr style="rowspan:2;">
| |
| <td style="display: block; vertical-align: bottom;">[[Image:Node_red_wampcall.JPG|600px]]</td>
| |
| </tr>
| |
| <tr>
| |
| <td style='background-color:#efefef;'>Firewall ports for WAMP connection to Node-RED</td>
| |
| </tr>
| |
| </table>
| |
|
| |
|
| In this flow, we use a Change node to write the incoming msg.payload.args[0]["door_dirno"] string into msg.payload<br>
| | <br> |
| We then use a Switch node to test whether the Door is Directory number 202 and if it is, the message is passed to the next Change node.<br>
| | After installation you need to add '''TCP port 1880''' in the [[Firewall (Zenitel Connect Pro)|firewall of Zenitel Connect Pro]]. |
| In the last Change node, we delete the msg.payload value, and create the outgoing array required for a GPO command.<br>
| | Zenitel advises to close port 1880 again once Node-RED has been setup and the flows operate as intended. This way it is not possible to re-program any flows until the port is opened again in the firewall by an administrator. |
| This is then sent to ZCP using a Wamp Call node. | |
| | |
| ==Second example flow==
| |
| In the same scenario as the first, we can use a small amount of Java code to achieve the same results, but within a Function node.<br>
| |
|
| |
|
| <table style="max-width:80%; border-style: double; border-color: #c7c7c7;"> | | <table style="max-width:80%; border-style: double; border-color: #c7c7c7;"> |
| <tr style="rowspan:2;"> | | <tr style="rowspan:2;"> |
| <td style="display: block; vertical-align: bottom;">[[Image:Node_red_flow2.JPG|600px]]</td> | | <td style="display: block; vertical-align: bottom;">[[Image:Nodered firewall.png|700px]]</td> |
| </tr> | | </tr> |
| <tr> | | <tr> |
| <td style='background-color:#efefef;'>Node-RED WAMP node installation</td> | | <td style='background-color:#efefef;'>Open port 1880</td> |
| </tr> | | </tr> |
| </table> | | </table> |
|
| |
|
| Again, we subscribe to the Open Door event using a Wamp In node.<br>
| | <br> |
| The incoming messages are sent to a Function node that extracts the value from msg.payload.args[0]["open_door"], uses an If statement to test whether the door is Dir 202, and then formats the outgoing message to be sent to the Wamp Call node.<br>
| |
| <table style="max-width:80%; border-style: double; border-color: #c7c7c7;">
| |
| <tr style="rowspan:2;">
| |
| <td style="display: block; vertical-align: bottom;">[[Image:node_red_flow2_function.JPG|600px]]</td>
| |
| </tr>
| |
| <tr>
| |
| <td style='background-color:#efefef;'>Node-RED WAMP node installation</td>
| |
| </tr>
| |
| </table>
| |
| The Function Node code is
| |
| {{Code3| // Retrieve the incoming number from the message payload
| |
| var door <nowiki>=</nowiki> msg.payload.args[0]["door_dirno"];
| |
|
| |
|
| // Test whether the door open is Directory number 202
| | === Installation on a ICX-510 Zenitel Connect Pro === |
| if (door <nowiki>==</nowiki> 202){
| | The procedure for installing Node-RED on a ICX-510 is the same as for a virtual environment, the only difference is the swu file. |
| // Create the new outgoing command
| |
| msg <nowiki>=</nowiki> {
| |
| payload: {
| |
| 'dirno': '204',
| |
| 'id': 'relay1',
| |
| 'operation': 'set_timed',
| |
| 'time': 3
| |
| }
| |
| }
| |
| // Send the command to the next node
| |
| return msg;
| |
| } }}
| |
|
| |
|
| ==Third example flow==
| | From the [[Downloads#Zenitel_Connect_Pro_.28ZCP.29|Downloads page]] download the file '''Zenitel_Connect_ICX_x.x.x-node-red.swu''', where the x.x.x denotes the version of Zenitel Connect Pro you are running. |
| If we have many doors in our system and we need to provide a related relay for each door, we can expand our Function node with a key-value pair table.<br>
| |
| An IP-LCM provides up to 9 relays, so our function needs to relate to the Directory Number and the Relay to be used.<br>
| |
|
| |
|
| The code is
| | To install the additional package you can use the [[Software Update (Zenitel Connect Pro)|standard upgrade procedure]] for the Zenitel Connect Pro. |
| {{Code3|// Retrieve the incoming number from the message payload
| |
| var door <nowiki>=</nowiki> msg.payload.args[0]["door_dirno"];
| |
|
| |
|
| // Define a lookup table for door number substitutions with an additional 'id' field
| | === Installation on a 3rd party server === |
| // Each door number maps to an object with 'dirno' and 'id'
| | For installation on a 3rd party server we direct you to the installation guide from Node-RED: https://nodered.org/docs/getting-started/local |
| var lookupTable <nowiki>=</nowiki> {
| |
| 202: { dirno: 204, id: 'relay1' }, // Example: if door is 202, activate relay 1 on IP-LCM at Directory number 204
| |
| 302: { dirno: 204, id: 'relay2' }, // Example: if door is 302, activate relay 2 on IP-LCM at Directory number 204
| |
| 402: { dirno: 204, id: 'relay3' } // Add more pairs as needed with their respective 'dirno' and 'id'
| |
| // Add new entries here in the format: 'door_number': { dirno: 'substitute_number', id: 'relayX' }
| |
| };
| |
|
| |
|
| // Check if the incoming 'door' number exists in the lookup table
| |
| if (lookupTable.hasOwnProperty(door)) {
| |
| // Get the corresponding object (which contains both dirno and id) from the lookup table
| |
| var substitution <nowiki>=</nowiki> lookupTable[door];
| |
|
| |
|
| // Create a new message object with the substituted 'dirno' and 'id' values
| | === Accessing the Node-RED web GUI === |
| msg <nowiki>=</nowiki> {
| | You can access the Node-RED web GUI that is used for programming via '''https://[server IP]:1880''' |
| payload: {
| |
| 'dirno': substitution.dirno.toString(), // Convert the number to string if needed
| |
| 'id': substitution.id, // Use the 'id' from the lookup table
| |
| 'operation': 'set_timed', // Example operation, adjust as needed
| |
| 'time': 3 // Example time value, adjust as needed
| |
| }
| |
| };
| |
|
| |
| // Return the modified message
| |
| return msg;
| |
| } else {
| |
| // If the 'door' number does not exist in the lookup table, return null or handle the case appropriately
| |
| node.warn("Door number " <nowiki>+</nowiki> door <nowiki>+</nowiki> " not found in lookup table.");
| |
| return null;
| |
| } }}
| |
|
| |
|
| =Free available data on the Internet=
| | An alternative is to add a tile to the Zenitel Connect Pro GUI under third party applications. Go to '''3rd Party Applications''' and fill in the fields '''Name''', '''Description''' and '''Source URL'''. Source URL is the IP address and Port number where you access Node-RED. After clicking the checkmark to save these settings you can upload a .SVG file as an icon. |
| On the internet there are lots of API's available to request various types of data. Some of these are on a payment plan but there is also many that are provided by governments free of charge. Examples of these are weather and natural events related data or timetables for public transport.
| |
| Here you can find the example of the National Weather Service in the US: https://www.weather.gov/documentation/services-web-api.
| |
| In their documentation you find that '''<nowiki>https://api.weather.gov/gridpoints/{wfo}/{x},{y}/forecast</nowiki>''' gives you the weather forecast for a specific location. The values for '''wfo''', '''x''', and '''y''' are a location system used by the NWS, the description is in the documentation.
| |
| If we fill in the values for a given location in the US we get for example a request URL that looks like this: '''https://api.weather.gov/gridpoints/EAX/46,52/forecast'''
| |
| This URL can be used with the HTTP request node.
| |
| | |
| <table style="max-width:80%; border-style: double; border-color: #c7c7c7;">
| |
| <tr style="rowspan:2;">
| |
| <td style="display: block; vertical-align: bottom;">[[Image:Http request.png|600px]]</td>
| |
| </tr>
| |
| <tr>
| |
| <td style='background-color:#efefef;'>The URL in the HTTP request node</td>
| |
| </tr>
| |
| </table>
| |
| | |
| Now when this node gets triggered it will request the current weather forecast from the NWS.
| |
| | |
| =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.
| |
| <table style="max-width:80%; border-style: double; border-color: #c7c7c7;"> | | <table style="max-width:80%; border-style: double; border-color: #c7c7c7;"> |
| <tr style="rowspan:2;"> | | <tr style="rowspan:2;"> |
| <td style="display: block; vertical-align: bottom;">[[Image:Inject node.png|600px]]</td> | | <td style="display: block; vertical-align: bottom;">[[Image:NodeRED 3rd party app.png|900px]]</td> |
| </tr> | | </tr> |
| <tr> | | <tr> |
| <td style='background-color:#efefef;'>The inject node</td> | | <td style='background-color:#efefef;'>Adding Node-RED as a third party application</td> |
| </tr> | | </tr> |
| </table> | | </table> |
| Line 302: |
Line 84: |
| <table style="max-width:80%; border-style: double; border-color: #c7c7c7;"> | | <table style="max-width:80%; border-style: double; border-color: #c7c7c7;"> |
| <tr style="rowspan:2;"> | | <tr style="rowspan:2;"> |
| <td style="display: block; vertical-align: bottom;">[[Image:Inject node message options.png|600px]]</td> | | <td style="display: block; vertical-align: bottom;">[[Image:NodeRED on ZCP home.png|700px]]</td> |
| </tr> | | </tr> |
| <tr> | | <tr> |
| <td style='background-color:#efefef;'>The options for injecting different types of messages</td> | | <td style='background-color:#efefef;'>Node-RED linked on the home screen of Zenitel Connect Pro</td> |
| </tr> | | </tr> |
| </table> | | </table> |
|
| |
|
| ==The debug node==
| | After accessing the web GUI of Node-RED this article explains how to start programming: [[Node-Red - Getting Started]] |
| 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.
| |
| | |
| <table style="max-width:80%; border-style: double; border-color: #c7c7c7;">
| |
| <tr style="rowspan:2;">
| |
| <td style="display: block; vertical-align: bottom;">[[Image:Debug node.png|600px]]</td>
| |
| </tr>
| |
| <tr>
| |
| <td style='background-color:#efefef;'>The debug node</td>
| |
| </tr>
| |
| </table>
| |
| | |
| <table style="max-width:80%; border-style: double; border-color: #c7c7c7;">
| |
| <tr style="rowspan:2;">
| |
| <td style="display: block; vertical-align: bottom;">[[Image:Debug node options.png|600px]]</td>
| |
| </tr>
| |
| <tr>
| |
| <td style='background-color:#efefef;'>The options for displaying only the payload or the entire message object</td>
| |
| </tr>
| |
| </table>
| |
|
| |
|
| =Further reading=
| |
| We advise beginners to read further in the Node-RED cookbook: https://cookbook.nodered.org
| |
|
| |
|
| [[Category: Zenitel Connect Pro]] | | [[Category: Zenitel Connect Pro]] |
| [[Category: Zenitel Connect Pro Integrations]] | | [[Category: Zenitel Connect Pro Integrations]] |
