In this class, you will become familiar with the SmartServer CMS Planning widget and how IAP nodes are used.

This section consists of the following:

Class Contents

Understanding Contexts

Context Hierarchy Overview

A context is a digital representation of a real world region, area, or space. Defining a digital model of a physical world allows for easier navigation, control, and management of devices that are installed in a building or campus facility. A context can be linked to one or more system entities, such as devices or device groups, and can be of the following types:

Campus – defines a physical facility and is comprised of multiple buildings, and is the highest level entity in the context hierarchy
Building – defines a physical building and is comprised of multiple floors
Floor – defines a physical floor in a building and is comprised of multiple rooms
Room – defines a physical room entity in a building and is comprised of multiple areas
Area – a free context defined by a polygon on a campus or a floor. Areas can intersect each other and other contexts. All devices that fall within an area belong to that area.

In Node-RED, context refers to information shared between nodes. In this tutorial, context is used as previously described and not with the meaning used in Node-RED reference web pages.

For the purposes of this tutorial, a hypothetical campus called Mango HQ will be used. This campus comprises two buildings, two floors per building, and four offices per floor (as shown below).

To begin working with the Mango HQ context, you can either:

Download the sample context hierarchy file from the SmartServer GitHub Repository → Node-RED Tutorial folder and import it using the Import / Export button () on the CMS for SmartServer 4.0 and higher, or using the Import button () on the Planning widget for releases prior to SmartServer 4.0.
OR
Create your own context as described in the section Step 2 - Define Contexts, and provision the devices on the campus as described in the section Defining Device Types. You will need to create a context that comprises one campus and two buildings, with each building containing two floors, and each floor having four rooms and two VAV areas.

Once the Mango HQ context hierarchy is created or imported, it will appear similar to the SmartServer Planning widget shown below. For SmartServer 4.0 and higher, the top level geozone for all context types is the World geozone, and the Import button () is no longer available on the Planning widget. To import contexts for SmartServer 4.0 and higher, use the Import / Export button () on the SmartServer CMS.

SmartServer example prior to 4.0

Context Hierarchy Workflow

The general workflow for creating a context hierarchy is as follows:

The system plan and blueprints are received from the building facilities contractor. Map these plans to the appropriate contexts (i.e., campus, building, floor, room, area).
Create this digital representation as described in Defining and Using Contexts.
Create a campus context if the project comprises multiple buildings, or a single building context if the project comprises only one building.
Upload the blueprints on a floor-by-floor basis, creating the floor and the nested room contexts.
If a building contains multiple, identical floors, clone the floor contexts and nested room and area contexts multiple times to easily represent the floors. Alternatively, you can clone the floor contexts and make minor edits as needed per the blueprints.
Once the context hierarchies are set up, export the context hierarchy and import it into other SmartServer’s so that all have a similar view of the system. The context hierarchy then forms the basis for the system where each SmartServer has a unified view yet only operates on the devices that are then provisioned in the scope of these contexts

Creating a new context involves using the Planning widget, and is described in the section Defining and Using Contexts.

Understanding IAP Input and Output Nodes

The Node-RED editor installed in the SmartServer IoT comes with 2 custom nodes used to connect flows with IAP datapoints available in SmartServer IoT.

IAP Input Nodes

IAP Input nodes connect to an MQTT broker and subscribe to messages from the specific topic. On the SmartServer CMS Sequencing widget, the IAP Input node appears as shown below:

IAP Input node properties settings 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 Fixed and Relative Datapoints 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:
- Protocol
- 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).
Datapoints – unfiltered list of all the datapoints, sorted alpha-numerically by context/device/datapoint name; device type datapoints for relative and device datapoints for fixed; appearing in the format: /<block_name>/<block_index>/<datapoint_name>. When a fixed node is selected, the datapoint path is exact, with reference to the device that the datapoint belongs to. When a relative node is selected, the datapoint path is for the device type rather than the actual device.

IAP Output Nodes

IAP Output nodes connect to an MQTT broker and publish messages. These nodes include a single input that when updated, will update the selected datapoint or datapoint field. On the SmartServer CMS Sequencing widget, the IAP Output node appears as shown below:

IAP Output node properties settings are as follows:

Broker – path to the IAP message broker
QoS – Quality of Service. Valid values are: 0, 1, 2
Output – valid values are: auto, buffer, utf8, json, base64
Name – name of the node
Throttle – time interval in seconds specifying the minimum time between updates to the specified output datapoints, with a default of 300 seconds.
Fixed – fixed if checkbox is enabled; otherwise, relative (see Fixed and Relative Datapoints 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:
- Protocol
- 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 Output 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>.
Datapoints – unfiltered list of all the datapoints, sorted alpha-numerically by context/device/datapoint name; device type datapoints for relative and device datapoints for fixed; appearing in the format: /<block_name>/<block_index>/<datapoint_name>. When a fixed node is selected, the datapoint path is exact, with reference to the device that the datapoint belongs to. When a relative node is selected, the datapoint path is for the device type rather than the actual device.

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 shown below sets write priority to 15.

let msg1=msg;
msg1.payload.prio = 15;
return msg1;

Fixed and Relative Datapoints

Both IAP Input and Output nodes provide users with the option to select between relative (default/disabled checkbox) and fixed (enabled checkbox) datapoints, as shown the IAP Input node properties view shown below.

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.

For example: A flow may contain a fixed datapoint for an outdoor air temperature sensor. This datapoint is common across the many contexts the flow is associated with. As a result, all the contexts share the outdoor air temperature sensor value. The same flow may have a context-relative indoor air temperature sensor in a room, and a context-relative VAV controller in an area. When the flow is deployed to a new area and set of four rooms in the area, the temperature sensors will be changed to the equivalent temperature sensors in the new rooms, and the VAV controller will be changed to the VAV controller in the new area. Matching will be based on device type per selected datapoint.

Exercise 2.1 – Using IAP Nodes

In this exercise, you will interact with real IAP datapoints that exists in the SmartServer IoT using Node-RED. For all datapoints that are being used, be sure to enable monitoring and polling in the Datapoints Properties widget → MONITORING AND LOGGING CONFIGURATION settings, and set Poll Interval to 10 seconds and Publish Minimum Delta Value to Always.

As part of this exercise, you will need to:

Provision LON devices using the Devices widget (see Provisioning, Deprovisioning, and Replacing Devices).
Use the IAP Input and Output nodes on the Sequencing widget to read from and write to the datapoints in the actual device

We will use the Starter Kit's LON Room Sensor (SC 100-MP) for input datapoints and LON VAV Controller (FT 6050 EVB) for output datapoints. The figures and block diagrams below represent the model for this exercise.

To create this flow, perform the following steps:

Download Exercise 2.1 from the SmartServer GitHub Repository → Node-RED Tutorial folder and import it into the Sequencing widget.

This downloaded flow will serve as a template for the flow that you will be creating in this exercise, and will look similar to the following in your workspace:
Click Deploy to save the flow.
Click the Add Flow button () to begin creating a new flow.

A new flow tab is added to the workspace.
Double-click the new tab on the workspace.

The Edit flow view appears.
Enter the flow name.
Click Done.
Create and provision the LON room sensor if you have not already done so:
1. Import the Lon Channel.dtp.zip from the Starter Kit archive → LON Channel folder using the Device Types widget.
2. Create a new device using the Devices widget (see Discovering, Defining, or Importing Devices).
  1. Name: DIO-01
  2. Integration method: Guided discovery
  3. Context: Mango HQ/Building 1/Floor 1/Office 1
  4. UID: leave empty (will be filled in by guided discovery)
  5. Driver: leave empty (will be filled in by guided discovery)
  6. Device type: leave empty (will be filled in by guided discovery)
3. Press the service button located on the lower left portion of the SC 100-MP device.
4. Provision the SC 100-MP device on your Starter Kit.
  
  See SmartServer IoT's Starter Kit User's Guide → Setting up the LON Channel section for more information about creating and setting up this device.
Create and provision the VAV controller (the DTP file that was previously imported also contains the VAV application and the XIF files).
1. Create a new device using the Devices widget, and (see Discovering, Defining, or Importing Devices).
  1. Name: VAV sim
  2. Integration method: Guided discovery
  3. Context: Mango HQ/Building 1/Floor 1/Office 1
  4. UID: leave empty (will be filled in by guided discovery)
  5. Driver: leave empty (will be filled in by guided discovery)
  6. Device type: leave empty (will be filled in by guided discovery)
2. Press the service button located on the upper right portion of the FT 6050 EVB board; doing so populates this field.
3. Provision the FT 6050 EVB device on your Starter Kit using the Provisioning, Deprovisioning, and Replacing Devices.
  
  See SmartServer IoT's Starter Kit User's Guide → Setting up the LON Channel section for more information about creating and setting up this device.
Drag the IAP Input node onto the workspace.
Double-click the IAP Input node.

The Edit iap-input node view appears.
Enter SC100 nvoTempSensor in the Name field.
Select the Fixed checkbox to indicate that a specific datapoint on a specific device is being selected.
Apply filters to select the datapoint nvoTempSensor (the reading from the temperature sensor in the SC 100-MP device) for the DIO-01 device. You may need to deselect the View all datapoints checkbox.
Click Done.
Click Deploy.
Drag the debug node and connect it to the SC100 nvoTempSensor node in order to log the datapoint value in the console.
Double-click the debug node.

The Edit debug node view appears.
Set the Output field as msg.payload.data 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 ().

To deactivate debugging, click the end of the node, and then click Deploy to save your changes.
Try setting different values in the Properties → Polling interval field on the Edit iap-input node view to see how often the data gets updated in the debug node. Polling interval specifies the time in seconds that you want to see the data updated from the device on-demand.
The polling rate is always determined by the polling setting in the Datapoint Properties widget. The interval setting in the IAP Input node allows you to specify a shorter interval. Specifying a longer interval in the IAP Input node will have no effect.

For example:
If IAP Input node polling interval = 1 second and Datapoint Properties widget polling interval = 10 seconds, the datapoint will be polled every 1 second (set by the IAP Input node polling interval).
If IAP Input node polling interval = 10 seconds and Datapoint Properties widget polling interval = 1 second, the datapoint will be polled every 1 second (set by the Datapoint Properties polling interval).
Drag another IAP Input node onto the workspace.
Double-click the IAP Input node.

The Edit iap-input node view appears.
Enter SC100 0/nvoDI (Occ) in the Name field.
Select the Fixed checkbox to indicate that a specific datapoint on a specific device is being selected.
Apply filters to select the datapoint nvoDI (the reading for occupancy in the SC 100-MP device) for the DIO-01 device. With multiple nvoDI datapoints, be sure to select [SC100-MP/Digital Input/0/nvoDI]. You may also need to deselect the View all datapoints checkbox.
Click Done.
Click Deploy to save your changes.

With the IAP Input nodes and debug node created in the flow, the steps that follow are to create the IAP Output nodes.
To write the datapoint in SmartServer IoT via IAP message broker, drag the IAP Output node onto the workspace.
Double-click the IAP Output node.

The Edit iap-output node view appears.
Enter VAV_sim nviSpaceTemp in the Name field.
Apply filters to select the datapoint nviSpaceTemp (the reading from the temperature sensor in the FT 6050 EVB) for the VAV sim device.
Click Done.
Click Deploy to save your changes.

The next set of steps will add and configure an inject node. This node will be used to inject some values into the IAP Output node (VAV_sim nviSpaceTemp) in order to demonstrate that it works.
Drag the inject node onto the workspace and connect it to the VAV_sim nviSpaceTemp node.
Double-click the inject node.

The Edit inject node view appears.
Select {}JSON from the msg.payload dropdown list.
Enter {"data":25} in the msg.payload field.
Enter ev/data in the msg.topic field.
Click Done.
Click Deploy to save your changes.
Drag another IAP Output node onto the workspace.
Double-click the IAP Output node.

The Edit iap-output node view appears.
Enter VAV_sim nviOccSensor in the Name field.
Apply filters to select the datapoint nviOccSensor (the reading for occupancy in the FT 6050 EVB device) for the VAV sim device.
Click Done.
Click Deploy to save your changes.
Connect the SC100 nvoTempSensor and VAV_sim nviSpaceTemp nodes, and click Deploy.

With this connection, you should be able to observe temperature changes on the FT 6050 EVB LCD display by touching the LON sensor.
You can also observe temperature reading changes on the FT 6050 EVB LCD display by clicking the end of the inject node.

The FT 6050 EVB LCD display should show a temperature reading of 25 degrees Celsius.

Well done! You are now interacting with real devices at the datapoint level with the completion of this exercise, which the basic step for starting to build your IoT application.

Next Step

Once you have completed the exercise in this section, continue with Class 3 - Dataflows.

Class 2 - Contexts and IAP Nodes