This article describes how to add, select and edit data sources in Site Builder. The section also discusses tagging and templating both in and out of the Platform.
Overview of Site Builder
Site Builder manages the entire site commissioning process, connecting to the building data sources such as physical gateways, IoT providers and APIs, through to registering the set of points the rest of the platform uses. User activity in Site Builder is saved to the Platform and can be updated in the future.
Navigate to Site Builder through:
→ Site Builder
The Site Builder interface consists of two main tabs - the 'Diagram' tab and the 'Grid' tab. The Diagram tab gives access to site architecture documentation, while the Grid tab gives access to imported points. Each tab and its features are covered in the following sections.
Figure 16. The Site Builder Landing Page.
Buildings generate enormous amounts of untapped data. Extracting this data from your equipment, service providers and control systems is the first step to taking control of your building performance. The Platform is data source agnostic. This means that whether you use a Switch Gateway, a 3rd-party gateway, independent IoT sensors, a data acquisition service, a managed API or .CSV files, the Switch Platform collects, manages and analyzes your building data.
Data sources are ingested into the Platform through drivers, which are like format converters that ingest source data and convert it into a standardized format both the Platform and users can understand.
Adding Data Sources to Site Builder
The Platform supports a diverse range of data sources and import formats. These can be added to a site using the Library in the Diagram tab of Site Builder. The Diagram tab creates a simplified line diagram of the data architecture of your site, representing where data comes from and how it gets sent into the Platform. The Library contains blocks that represent data sources, network switches, and gateways that can be used to construct data models.
Figure 17. Library Menu in Site Builder.
Selecting and Editing Points
Once the data line diagram is complete, users can identify and select points of interest from the incoming data and make them available to the rest of the features on the Platform. This selection process differs with each data source, but the general concept remains the same.
Identify points → Select points of interest → Apply Switch templates → Apply tags → Import onto the Platform
The next section discusses this process for a typical BACnet/IP site in depth. Once a user is familiar with this process, applying it to other data sources and site architectures is straightforward.
Adding a Typical BACnet/IP Site
Most commercial buildings use the BACnet/IP protocol to share equipment information over a network. This is the most common type of site integration that Switch performs, detailed in the following section.
Don’t hesitate to get in touch if you need help bringing your building online - our engineers are happy to lend a hand.
Creating the Network Diagram
Figure 18. Simple BACnet Site.
In the example site shown above, the building equipment is connected through the BACnet/IP network protocol and a Switch Gateway is installed onsite to capture this data, sending it to the cloud. The diagram above shows that the Switch Gateway communicates with the BACnet/IP equipment over the building LAN, with the connection being handled through a network switch, just like on site.
Building this line diagram is straightforward. Users can search the Library for specific blocks, and then drag and drop them on the canvas. The specific blocks used in this example site were:
- Generic Network Switch (12 port)
- Switch - Gateway 2
Blocks can be connected together by dragging a line from one node to another. Please note that connector lines cannot wrap around a block - the connection nodes need to be on sides facing each other. Nodes can be moved to any edge of a block by right-clicking and selecting 'move node to 'x' side'.
Once basic blocks are added to the diagram they then need to be configured.
The BACnet/IP protocol operates over the Ethernet network and sometimes are routed through relay devices called BBMDs (BACnet/IP Broadcast Management Device). The IP addresses for the BBMDs and other configuration information concerning the BACnet protocol can be set in the Properties tab of this block.
The network diagram reflects the architecture of the equipment on site. In order to pull data, the Switch Gateway block in the diagram needs to be linked to the physical gateway installed onsite. This is a process called 'Commissioning to Server'. Perform the following steps to link the Switch Gateway block to the physical gateway:
- Right-click the 'Ethernet' node and select 'Commission to Server'.
- In the pop-up that shows, a list will appear showing gateways connected to the Platform but not yet assigned to a site. Select the gateway with the MAC address that corresponds to your installed gateway and click 'Commission.'
Please note that the MAC address of the physical gateway is stamped on the device.
Once the network diagram is complete, we can move on to discovering and importing device and points.
Importing Devices and Points
The terminology distinctions that follow are important when discussing the BACnet site import process.
A 'Device' is any object with its own address on the BACnet/IP network. It is generally a controller that controls a single piece of equipment, but it can be a controller that controls multiple pieces of equipment, so pay close attention to this when analyzing the points. A device could also be a meter, sensor array or some other object.
BACnet Objects (Points)
A 'Point' is a sensor or data point that is polled and/or controlled by a device. Each device will have one or more points, each with their own sub-address.
'Equipment' is the term generally used to describe a piece of building apparatus, such as an AHU, VAV or fan. A device typically represents a single piece of equipment, but can represent more than one depending on the site architecture.
Both devices and points are components of the BACnet protocol. Equipment is the rational way points are grouped together. Sometimes the terms ‘device’ and ‘equipment’ are interchangeable, but there are instances where this is not a one-to-one relationship and as such, it is not recommended that these terms are used interchangeably when discussing a site.
The device and point import process consists of five key steps:
- Discovering all the devices and points that the new gateway can connect with on the building network.
- Selecting the relevant points and renaming them, if required.
- Applying Platform templates to each point for logic deployment.
- Tagging points to support logic deployment and aid in future filtering and analysis.
- Importing the filtered, templated, tagged and renamed points onto the platform.
Selecting, Templating and Tagging
Users can select, template and tag points outwith the Platform. Once the points have been discovered, they can be exported off platform and opened with any data manipulation tool (i.e. Excel, PowerBI, Notepad++ etc.). The cleaned, templated and tagged points can then be easily uploaded back into the Platform. Users should utilize the software that they're most comfortable with.
Point discovery is where the Gateway sends out a signal that requests all building equipment connected to the network to provide a list of their available data points. This process is conducted in the Diagram view of the Site Builder feature. The steps are as follows:
- Right click the 'Ethernet' node of the BACnet/IP block on the canvas.
- Select 'Discovery'.
- In the resulting Discovery window, run either the 'Basic' or 'Advanced' discovery routine:
Basic: Discovers all devices on the network and then automatically discovers the points for each device.
Advanced: Discovers all devices on the network, then allows users to choose a subset of devices to discover points for. This is recommended for larger or slower networks.
- Once the discovery has finished running, the discovered points can be imported onto the platform directly, but it is recommended that users export them to a .CSV file for further processing.
While many data points are available to the Platform through BACnet and BMS, users must decide which points are valuable to their cause. The Platform is not intended to replace the existing BMS, so bringing in all available points, while possible, will not be of great value to the user.
Some air handling unit controllers include points for heating and heating coils even when a unit does not have heating capabilities. These points are best left out of the import to the Platform because they are not used.
Instead, the user should choose a subset of points that enable our scoring and logic modules to be deployed. We are interested in space performance, equipment operation performance, such as timings, commands, demand, and data quality.
After the discovery has been conducted, point selection simply refers to selecting a subset of these discovered points to import into the Platform. There are no limitations to the number of point imports the Platform will accept, so selections can be made for as few or as many points at one time. For example, if only the AHU points are selected and imported initially, the VAV points can be selected and imported at a later date. The selection process, and the subsequent templating and tagging processes, occur in two ways:
The points of interest are selected in the Discovery page and imported onto the Platform. All subsequent point templating and tagging will be conducted in the Site Builder Grid page.
The Discovery file is exported as a .CSV file. Users can edit this file in their preferred data manipulation tool (Excel, PowerBI, Notepad++, etc.) to select, template and tag the points. Users can then import this file back onto the Platform and conduct any additional point templating and tagging in the Site Builder Grid page, if required.
Selecting points simply means choosing a subset of them to import into the platform. Using the off-platform method as an example, users can simply delete the rows of the .CSV file that are not of interest.
The reasoning for, and intuition behind, templating is explored in the Templating section of this document. This section covers the basic differences between in-platform and off-platform templating.
In-platform templating is conducted in the Grid view of the Site Builder feature. Here users can search, filter and manipulate the text in the cells. The Templates column is data-validated, so users can either select their desired template from a drop-down list or input it directly, as long as it matches a predefined template name.
Figure 19. Site Builder Grid Page.
Off-platform templating is essentially the same as in-platform templating. Users simply fill in the Template columns of the exported discovery. It is important that the templates entered are valid templates on the Platform. If not, then when invalid points are imported their templates will be reverted to default generic templates and must be reselected in the Grid view of the Site Builder feature.
Below are the basic differences between in-platform and off-platform tagging.
Tagging should be conducted in the tagging feature of the platform. Here users can create tag groups and tags, and assign sensors and devices to them. Once a tag group has been created in the tagging feature, it appears as a column in the Site Builder Grid view. Users then have the option to tag devices and sensors under that tag group using the Grid view of the Site Builder feature.
Off-platform tagging is slightly different than in-platform tagging. To add tag groups, the user simply adds columns to the .CSV file with each header being the tag group name, and then they can tag each device by simply writing a tag name under the relevant Tag Group (column) for each data point (row).
For off-platform edited points, users will need to import them back onto the Platform. This happens with the Diagram view of the Site Builder feature:
- Navigate to the Diagramview of the Site Builder.
- Right-click on the Proprietary node of the BACnet/IP device.
- Select 'Import Devices' from the list.
- In the pop-up, drag and drop the edited .CSV from your computer into the indicated region, then click 'Add'.
- A new view will appear showing all valid points from the .CSV file. If these points have been read satisfactorily, click the check box to select all, then click the 'Import' button in the top right-hand corner of the view.
Please note, if the grid does not populate, there is an error in the import file. If this is the case, verify file format and column headers.
- The points will now begin to import. Please remain on the page until all rows turn green and the number of imported points matches the count of points reported at the upper left of the grid.
- Repeat these steps for multiple imports, if needed.
- Once all points have been imported, navigate to Remote Management and find the site, then select Restart/SST under Gateway in the menu on the far right:
- Navigating to the Gridview of Site Builder, the points imported into the Platform will now be available for use.
Checking for data
Once the points are imported, it’s important to check that they are now posting data. Navigate to the Grid view of Site Builder and select the Sensor view from the drop-down menu. The last column of this table view is title 'Last Record' and shows the time stamp for the last reading received for that data point. The 'Property Value' column will show the value. It may take between 30 minutes and an hour following an import to see data posting, depending on count of imported points and number of tags.
Figure 20. Last Record in Site Builder.