The Sequencing widget is used to create a "sequence of operations" (also known as flows) and dashboards to automate everyday tasks, as well as to create instrument panels and dashboards for visualization. This widget leverages Node-RED, an open-source, flow-based, programming tool. Node-RED provides the ability to create sequences using drag-and-drop function blocks called 'nodes' and a web-based interface to connect the nodes, eliminating the need to write code. A ready-to-use library of nodes allows you to quickly start creating sequences or flows that contain custom logic and/or display information on a web pages with UI elements for creating dashboards and visualization.
The Sequencing Widget - Node-RED Onboarding Tutorial provides hands-on exercises approach to help you understand the basics of Node-RED and the Sequencing widget so that you can start to create your own flows using the SmartServer IoT. Proceeding class-by-class through this tutorial and completing the exercises for each class will help you towards this goal.
This section consists of the following:
The Sequencing widget is shown in the figure below (the part that appears within the red, dashed box is the Node-RED workspace).
Note: To best view all of the information on this widget, click the Expand button ( ).
- – opens / closes the sidebar with the flow menu and allows you to refresh the flow list
- DASHBOARD / FLOW toggle – opens the Sequencing widget view in a Node-RED browser
Using Node-RED Flows
The Sequencing widget provides a frame view of the Node-RED workspace within the widget with some SmartServer IoT specific extensions found above the black Node-RED frame (refer to the figure and descriptions above). For a guide on how to use the Node-RED workspace itself, please refer to the Node-RED website and documentation.
SmartServer IoT uses the power of the openly available Node-RED visual programming tool to create dataflows and webflows for datapoints that exist in a SmartServer IoT. A dataflow is a Node-RED flow that only contains a sequence of operation without any UI elements. A webflow is a Node-RED flow that contains some visualization or UI element. The datapoints are read from and written to the IAP message broker in the SmartServer IoT using IAP Input and Output nodes respectively.
Using IAP Nodes in Node-RED Flows
There two IAP nodes that SmartServer IoT adds to the palette of standard nodes for the Node-RED programming tool in order to interact with SmartServer IoT datapoints. Using the flow programming concept, IAP nodes bring in a datapoint into a dataflow or a webflow using IAP Input node and write values back to a datapoint using an IAP Output node. In between the IAP Input and the Output nodes, any standard Node-RED node can be used to perform logical operations and create displays.
The IAP Input and Output nodes are found in the Node-RED palette of the Sequencing widget. To find/use these nodes, scroll down the list of nodes to the network category, as shown below.
Note: To remove nodes or connectors from the flow, click on the node/connector to select it, and then press DELETE on your keyboard. Save your changes by clicking Deploy.
IAP Input Nodes
IAP Input nodes connect to the IAP MQTT broker and subscribe to a specified datapoint.
To view/set the property settings for the IAP Input node, drag-and-drop the IAP Input node onto the Node-RED workspace area and double-click on the node.
The Edit iap-input node view appears as shown below.
View/set the IAP Input node properties settings, which are as follows:
- Broker – path to the IAP message broker
- Topic – MQTT topic where datapoint is retrieved from (all monitored datapoints are published in glp/+/+/ev/data)
- Name – name of the datapoint displayed on the Node-RED workspace
- Polling – the polling interval for a selected datapoint in seconds, with a default of 300 seconds. On-demand monitoring for the selected datapoint will be generated at the selected interval, with a maximum age set to 75% of the interval so that polls are not generated for cached datapoint values received within 75% of the requested poll interval.
- Fixed – fixed if checkbox is enabled; otherwise, relative (see Setting Fixed and Relative Nodes for more information).
- Filters – set one or more filters to the unfiltered datapoint list to refine it to a smaller, more management list as needed. Filters can be set by:
- Device type
- Datapoint type
- Block name
- Block index
- Datapoint name
- Device name – available only for the fixed datapoint option
- Context type – valid values include campus, building, floor, room, or area (available only for the fixed datapoint option)
- Context – fully qualified path (available only for the fixed datapoint option)
- Selected Datapoints – lists the selected datapoint for the IAP Input node; device type datapoints for relative and device datapoints for fixed; appearing in the format: /<hostname>/<protocol>/<device_handle>/<block_name>/<block_index>/<datapoint_name> (shown below).
Select the datapoint that you wish to choose and click Done to save any IAP Input node property settings that you have made.
IAP Output Nodes
IAP Output nodes connect to the IAP MQTT broker and publish values to a specified datapoint. These nodes include a single input that when updated, will update the selected datapoint or datapoint field.
To view/set the property settings for the IAP Output node, drag-and-drop the IAP Output node onto the Node-RED workspace area and double-click on the node.
The Edit iap-output node view appears as shown below.
View/set the IAP Output node properties settings, which are as follows:
To set the datapoint priority for the IAP-Output node, which may be needed for BACnet devices, you will need to add the priority parameter to the Node-RED msg.payload that you send to the IAP-Output node. The following figure shows an example of setting the datapoint priority using a Node-RED function node.
Function node code shows setting write priority to 15.
Setting Fixed and Relative Nodes
A fixed datapoint is an exact matches to a datapoint in the system belonging to a specific device. Therefore, if you select fixed, the datapoint is always the same when the flow is deployed to a new context.
A relative datapoint is a datapoint type derived from a device type and is not tied to an actual device. Relative datapoints are used to replicate a flow template across a context or multiple contexts. If a datapoint type defined by a relative datapoint is found in the context that is applied to a flow template, the system will match that found datapoint to that relative datapoint. There can be multiple actual datapoints that get matched to a relative datapoint. The value of this node will reflect the last updated value in the list of datapoints that is matched to this relative datapoint.
Both IAP Input and Output nodes provide the option to select between relative (default/disabled checkbox) and fixed (enabled checkbox) datapoints, as shown the IAP Input node properties view shown below.
If the fixed option is enabled, a more robust list of datapoints will be displayed on the IAP Input/Output node view since the list is generated for each device. If the relative option is enabled, a narrower list of datapoints will be displayed on the IAP Input/Output node view since the list is generated for each device type.
Click Done to save any IAP Input or Output node settings that you make.
Creating a flow is as simple as dragging and dropping an IAP Input, IAP Output, and other standard nodes available in the Node-RED menu, and connecting them together. New flows are created using the Add Flow button (
) on the Sequencing widget.
Standard Node-RED nodes provides a wide array of functionality to parse, route, process and display data by connecting one node to another in a wire sheet format. To learn how to create some samples flows, follow the Sequencing Widget - Node-RED Onboarding Tutorial.
To navigate across multiple flows on the workspace, click the desired flow tab from the top of the workspace, or click the List Flows button (
) and select the flow from the available list.
Use Flow tabs or List Flows button to switch between flows
Select the flow from the list
IAP Node Status
The IAP node status feature is available with SmartServer 3.0 and higher.
The IAP node status is displayed on the Sequencing widget below the IAP Input or IAP Output node. A description of the node statuses that can appear on the CMS are as follows:
Connected, Relative, <datapoint>
For a relative node, this status message indicates if the flow is deployed and connected to IAP MQTT broker. If so, the status Connected, Relative is followed by the type name of the datapoint (not the fully qualified name) as shown in the example below.
Connected, Fixed, <datapoint>
For a fixed node, this status message indicates if the flow is deployed and connected to IAP broker. If so, the status Connected, Fixed is followed by the instance name of the datapoint (not the fully qualified name) as shown in the example below.
Connected, Matched, <datapoint>
In the case where there are multiple matches for a relative datapoint within one context, all applicable datapoints are matched to the IAP node. The data is updated with the most recent datapoint update from any of those matched datapoints.
For example: If there are three sensors of the same device type in one context that one relative IAP node can match with, the resulting IAP node in the service flow is matched to all three of the sensors in that context. The value of that node is updated with the most recent datapoint update from any of these three sensors with the payload consisting of the datapoint path and context. If the polling interval is set to 1s, the IAP node should poll all three datapoints in 1s resulting in 3 polls per second.
For a matched node in a service flow, if the node is matched to a specific datapoint on a device, this status message reports Connected, Matched and is followed by the fully qualified instance name as shown in the example below.
This status message indicates that the node is not connected to the IAP MQTT broker as shown in the example below.
No selected datapoint
This status message indicates that the node does not have a datapoint selected as shown in the example below.
Once a flow is successfully deployed, this flow will appear in the flow menu. The flow menu provides the following features described in the sections that follow.
- Open a flow in a new tab on the browser
- View associated contexts and devices for a flow
- Apply contexts and devices to a flow
- Remove associated contexts and devices from a flow
- Update a flow
- Edit a flow
- Clone a flow
- Remove a flow
To open the flow menu, click the Open Sidebar button ( ) on the Sequencing widget.
The flow menu appears.
Note: Use the Close Sidebar button ( ) to return to the flow workspace. Use the Refresh Flow List button () to update the flow menu.
Refer to the sections that follow for information on using the flow menu features.
Opening a Flow in a New Tab
To open a flow in a new, Node-RED tab in the browser, click the Open New Tab button (1482624 for the desired flow as shown in the example below.
) from the
The selected flow opens in a new tab.
Viewing Associated Contexts and Devices for a Flow
To view associated contexts and devices for a flow, click the View Associated button (1482624 for the desired flow.
) from the
Use the ASSOCIATED CONTEXTS and ASSOCIATED DEVICES tabs to display the contexts and devices that are associated with the selected flow.
Associated Contexts Display
Associated Devices Display
Click CANCEL to return to the flow workspace.
Changing a Flow
Updating a Flow
The Update a Flow action (
) is not yet available.
Editing a Flow
To edit a flow, click the Edit button (1482624 for the desired flow as shown in the following example.
) from the
The selected flow appears in the Sequencing widget as shown in the following example.
Click the Close Sidebar button (1482624 to return to the workspace and to edit the selected flow.
) from the
Cloning a Flow
To clone a flow, click the Clone button (1482624 for the desired flow as shown in the example below.
) from the
A copy of the flow appears in a new tab on the Sequencing widget and in the flow menu (use the Refresh Flow List button [
] to update the flow menu).
Click the Close Sidebar button (1482624 to return to the workspace and to use the copied flow.
) from the
Removing a Flow
To remove a flow, click the Delete button (1482624 for the desired flow.
) from the
Using a Flow Target
Flows can be defined with a construct called a flow target. A flow target specified the type of context that will be applied to the flow. For example, the flow target could be a building, floor, room, or an area. When a flow target exists, context application algorithms limit themselves to the defined context type. Flow target can greatly reduce the number of context you have to apply to a flow. For example, if you want to apply all 100 rooms in a building to a particular flow, you can select the room floor target and apply the building context to the flow. This will have the same result as selecting all 100 rooms and applying to the flow.
The flow target node used to tell the context application algorithm which context it should look for matches within the parent context that was applied to that flow is available from the node palette (with the common nodes) as shown below.
To use the flow target node, perform the following steps:
- Drag-and-drop the flow target node from the palette to the workspace.
- Double-click on the node.
The Edit flow-target node view appears.
- Set the Flow target parameter to Context or Device.
If Context is selected, set the context type (i.e., Floor, Campus, Building, Room, or Area) as shown in the following example:
- Click Done on the Edit flow-target node view.
The workflow view appears.
- Click Deploy to save flow changes.
Importing and Exporting Node-RED Flows
Importing and exporting flows can be done using the Node-RED Import/Export features.
Re-assigning datapoints for imported flows
If you import a flow from another system, or if you import a flow from same system that was restarted and rebuilt with a new database, then you need to re-assign the datapoints on the IAP Input/Output nodes that appear on the flow.
To use these features, click the Node-RED button (
Select the Import or Export action as needed.
For more information and next steps, see Node-RED's Importing and Exporting Flows.
Payload is information that is contained within the MQTT message, which provides a lot of useful data including details about where information is coming from. To access this information, you can add a debug node to flows and monitor the data on the Sequencing widget. The debug tab provides payload, datapoint, device, and context information.
The example steps below demonstrate how to use a debug node that is connected to an IAP Input node.
- Drag the debug node and connect it to an IAP Input node (LON Temp in this example) to log the datapoint value in the console.
- Double-click the debug node.
The Edit debug node view appears.
- Set the Output field as complete msg object and select the node status checkbox.
- Click Done.
- Click Deploy to save your changes.
Datapoint values will appear in the debug console as they are updated.
To switch to the console view, click the Debug button ( ) on the Sequencing widget.
Expand the datapoint object to see details, as well as device and context information.
Example device information is shown below:
scName: "SmartServer IoT"
Example context information is shown below:
name: "Mango HQ / Building 2 / Floor 1 / Office 1"
- Click the Clear Logs button () on the debug console to clear debugging information.
- To deactivate (or later reactivate) debugging, click the end of the node, and then click Deploy to save your changes.