Contents


Overview

Skill Level: Any Skill Level

Basic knowledge of BACnet and Watson IoT Platform

In this recipe, you will learn how to configure the go-iot.io BACnet-gateway to publish BACnet property values to IBM Watson IoT Platform. You will also learn how to configure it to accept commands via the Watson IoT Platform.
No programming is needed!

Ingredients

  1. Hardware platform to run the go-iot.io BACnet to Watson Gateway software (see 2 below).
    Those platforms are currently supported (for general about DINGO platform, click here...):
    1. DINGO RPi COM, datasheet...
    2. DINGO-RPi Zero (with a WiFi on USB), datasheet...
    3. DINGO-i.mx28, datasheet...
    4. RINGO Pi, a preconfigured, boxed and/or DIN-Rail mountable Raspberry Pi 
    5. Raspbery Pi 2
    6. Raspberry Pi 3
    7. For any other Linux or Windows based platform, please contact us...
  2. A valid BACnet to Watson Gateway license from go-iot.io
  3. Internet connection to your hardware platform (see 1 above).
    Note! The DINGO software stack for Raspberry Pi 2 supports this GSM-GPRS module.
    And of course there is full support for the DINGO GSM-GPRS 2G/3G plugins.
  4. An IBM Bluemix account with a running instance of the Watson IoT service.
  5. A suitable web browser supporting MS-Silverlight,
    for example Internet Explorer,  Mozilla FireFox or Google Chrome with IE Tab

Detailed Information on how to register and manage your Bluemix account can be found here...
A guide to getting started with the Watson IoT Platform can be found here...

Step-by-step

  1. Introduction

    Live Demo.
    First to mention there is a live dashboard demo showing what you will learn in Appendix A using Node-RED and this product. Feel free to play with the demo first and then come back to this recipe.
    Access the demo here…

    NodeRedDashboard

    What is go-iot.io BACnet to Watson Gateway?

    The go-iot.io BACnet to Watson gateway is implemented as a DINGO App in the DINGO software stack.

    This gateway software is used to link BACnet object-properties to Watson MQTT topics. The gateway publishes values to Watson IoT Platform as well as it can receive commands from the Watson IoT Platform, like switching a binary-output, etc.

    With this gateway you can do:

    1. Publish change in property values to Watson IoT Platform. It supports BACnet Change Of Value (COV) service as well as BACnet polling if COVs are not available.
    2. Receive “Write Property” and “Write Property Multiple” commands from Watson IoT Platform that are used to change value of commandable objects in a BACnet server. BACnet write-priorities are supported.
    3. Passthrough BACnet/WS commands (see details in “Step 5” below)
    4. Reinitialize device (if BACnet server supports that service).

    Note that with this gateway you can communicate with any BACnet device from any vendor in the BACnet network, where the gateway is running.

    What is IBM Watson IoT Platform?

    The IBM Watson Internet of Things Platform is a fully managed, cloud-hosted service that makes it simple to derive value from Internet of Things (IoT) devices. When combined with the IBM Bluemix platform, Watson IoT Platform provides simple, but powerful application access to IoT devices and data. You can rapidly compose analytics applications, visualization dashboards, and mobile IoT apps. Create IoT applications that feed insights to your backend enterprise applications.

    Note regarding availability and limitations.

    This product is brand new in January 2017. There are still some features under development and some limitations on current features.
    The current version of this product and list of limitations and features under development, expected in next release, is all listed in “Appendix D: Version Information” below.

    Videos

    This recipe also exists on a youtube video here…

    For other Go-IoT videos explaining DINGO-manager, etc. Refer to our video-page here…
    This includes Node-RED programming examples using the BACnet to Watson Gateway.

    A good BACnet introduction video series starts here…

  2. Architecture

    The schematic illustration below explains how the BACnet to Watson Gateway works.
    At the left side is the BACnet network(s) with all its BACnet enabled devices from any vendor. Those can be connected on an IP network, via Ethernet or WiFi. In addition BACnet enabled devices, sensors and actuators connected via WINGO or PINGO are supported, as well as BACnet devices on MS/TP RS485 if MS/TP RS485 router is present (future software feature in DINGO)

    The red DINGO BACKBONE runs the BACnet to Watson Gateway software, but can in addition function as a BACnet server itself. The BACnet to Watson gateway can also run on Raspberry Pi or other platforms supported.

    The BACnet to Watson gateway subscribes to BACnet Change of Value Events (COVs) from any of the BACnet devices on the network and forwards those as published events to Watson IoT Platform using MQTT.
    The BACnet to Watson Gateway also subscribes to commands from the Watson IoT Platform and applies those as “Write Property” and “Write Property Multiple” service requests to any of the BACnet devices in the BACnet network.

    What is published and what is subscribed is configured in DINGO Manager, a web based application used to configure the DINGO software stack.

    The xDSL can be replaced with any type of gateway connecting the BACnet to Watson Gateway to the Internet.
    For example the DINGO GSM-GPRS 2G/3G plug-in modules can be used (datasheet…).
    Or if using Raspberry Pi 2, the DINGO software stack supports this GSM-GPRS module.

  3. Step 1: Install BACnet to Watson Gateway

    If you have purchased a preinstalled DINGO with the BACnet to Watson Gateway, this step can be skipped.

    If you do not already have a valid BACnet to Watson Gateway license, please contact us for availability and pricing.
    Please specify on what platform you intend to run your license (See bulletin # 1 in “Ingredients” above).
    We will respond with an email within next 24 business hours.
    A 30 days trial is available on request.

    If you have a preconfigured image file for Raspberry Pi (2 or 3) from go-iot.io, you only have to write that image file to a uSD card and then put that uSD card into your Raspberry Pi.

    To install the BACnet to Watson gateway on your hardware platform, follow the installation instructions with your license.

     

     

  4. Step 2: Configure the IBM Watson IoT Platform

    It is only needed to specify your gateway device in the IBM Watson IoT Platform. After the gateway starts it will automatically register all needed BACnet devices within Watson IoT Platform.

    If you are unfamiliar of how to register a new gateway in Watson IoT follow the steps in the link below:
    https://developer.ibm.com/recipes/tutorials/how-to-register-gateways-in-ibm-watson-iot-platform/

    You are free to choose any Gateway Type Name you want. But we recommend using “dingo”. That will simplify all support from us, if/when you need it. Fill out other information about the Gateway Type you think is appropriate for your use.

    When creating the gateway itself in Watson IoT Platform we recommend using auto-generated token in the Security page.

    When you are finished you will get a summary information like shown below:

    gw-info2

    Keep this information because you will need it all in the next step, when configuring the BACnet to Watson Gateway.

     

  5. Step 3: Configure the BACnet to Watson Gateway

    Next step involves configuring your BACnet to Watson Gateway on your hardware platform. This step is very detailed so you don't get stuck anywhere. But when you have done it first time, it is very simple to configure more gateways.

    Make sure your hardware platform (DINGO or Raspberry Pi) is turned on, with a network connection and the DINGO server software stack running. To be sure that the DINGO server software stack is running, do as follow in a Linux terminal (do not use “sudo” if running on DINGO i.mx28 platform).

    sudo /etc/init.d/DinGo status

    If the stack is running you should get this response:

    [ ok ] DinGo is running.

    If it is not running you will get this response:

    [FAIL] DinGo is not running … failed!

    To start it issue this command:

    sudo /etc/init.d/DinGo start

    You should get this response on successfull start:

    [ ok ] Starting DinGo from Rational Network: DinGo.

    You will now log on to our DINGO Manager that is integrated into the Control2Net Platform, a modular platform for managing large volumes of IoT devices, hundreds and thousands of buildings, street-lighting setups, huge data-timeseries etc. It is designed to guarantee instant response and speed independent of data-volume.

    When the DINGO server software stack is successfully running, go to Control2Net web site to configure your BACnet to Watson Gateway: 

    https://apps.control2net.com/Silver/

    Log on with your valid user-id and password provided from go-iot with your license or trial license.

    1. On the left side tree explode the tree and select “My Company Name” leaf. This is your default “Gateway Group”. Edit the information as you want. Then press the “Save” button in the upper left corner.

      C2Net01

    2. Click the gateway group in the tree (“My Company Name”). The C2Net-buttonNew button should become enabled.
      Press the “New” button. A popup dialog will appear.
    3. In the “Properties” page you only have to fill out the two first fields.
      Be sure the “Gateway Type:” selected is “DinGo gateway”.
      Pick any name you want for the “Gateway name:” field.

      C2Net02

    4. Click on the “Connection” tab at the top of the dialog.
      You should only need to fill out the “IP address/domain:” field properly with the IP address of your gateway (DINGO or Raspberry Pi). You can also use domain name if applicable. For example “my-dingo.mysite.com”. 
      Only change the “Port:” field if using port forwarding via a router or similar.
      Default “User ID” is “admin” and default “Password” is “admin”.

      C2Net03

    5. When finished press the “Ok” button. Your gateway connection information will be created and a “blue DINGO” icon will appear in the main tree for your newly created gateway.

      C2Net04
      Press the C2Net-buttonSave button to save your changes permanently in Control2Net database.

    6. Select your newly created gateway in the main tree and change details at the right side as appropriate or needed.
      Just leave things you don't understand as is.
    7. Select the “DINGO manager” tab and press the “Connect” button. DINGO manager will now connect to your DINGO or Raspberry Pi. If unsuccessful, check and correct the connection settings by pressing the “Settings…” button.
      When connected “DINGO Manager” will show many tabs; “General”, “Network”, etc. All of those tabs are out of the scope of this recipe, except the “Apps” tab.

      C2Net05

    8. Click the “Apps” tab.
      Press the C2Net-buttonNewApp button in the “Apps” tab.
      In the dialog that appears select “IBM-Watson to BACnet” and press the “Ok” button. You will see the details of your newly created App at the right side.

      C2Net06 
      Fill out fields similar as shown in the screenshot below. 
      The data in the “Configuration” section has to match exactly the information you have from the Watson IoT Platform when you created the gateway there. (see the previous step).

      C2Net07
      If you are having more than one “Peripheral setup”, take extra care the active one is selected.

    9. If you are an advanced user only interested in using the BACnet/WS passthrough capability of the gateway skip “10.” below.
    10. Now you have to specify what BACnet objects shall publish events to the Watson IoT Platform, as well as what BACnet Objects are commandable (writable) from Watson IoT Platform. For that purpose you use the “BACnet to MQTT” and MQTT to BACnet” buttons. The first one is for publishing, the second is for subscribing (receiving commands).
      Press one of those buttons. A dialog will pop up.
      Press the “New” button.

      C2Net08
      If you are not familiar with BACnet or want to browse to the wanted BACnet object, press the “…” button. This will open a BACnet browser for you where you can navigate to the BACnet object you want to refer too. To only navigate in the current device (DINGO BACKBONE), leave “Device” field set to “Current” before pressing the “…” button. If you want to browse all BACnet devices on the network set the “Device” field to “Remote” before pressing the “…” button. Loading the total BACnet tree can take few seconds. The dialog-screen-shot below shows an example.

      C2Net09
      Create as many links as you want for both “publishing to Watson” as well as “Subscribing from Watson”.

    11. After all is done press the “Save” button in the upper left corner of the browser. This will save all your setup to a local database in your gateway (DINGO or Raspberry Pi). 
      Press “OK” on all information and possible warning dialogs that might appear.
    12. Your gateway has now been activated with your new BACnet to Watson gateway configured (as a DINGO App).
      For details how the gateway creates topics for MQTT and what it publishes in the payload, refer to 
      “Appendix B: Payload Definitions”.
      and
      “Appendix C: BACnet/WS Tunnel Payload Definitions”
  6. Step 4: Test your setup with IBM Watson IoT Boards

    Navigate back to you IBM Watson IoT Dashboard and select “Devices” from the left menu. You will now see your BACnet to Watson Gateway as connected WatsonConnectedGwIcon .
    Your BACnet to Watson Gateway has also added some devices if you have selected BACnet objects from other BACnet devices in the step above.
    In our example we have selected objects from two other devices at the BACnet network that pop up as WatsonDeviceIcon devices; “submeter-a” and “temperatures”

    WatsonIoT-Platfrm-01

    Important to understand: Notice the “Device ID” and “Device Type” columns. The values of those columns for devices WatsonDeviceIcon come from your BACnet configuration such:

    Device ID is taken from the “device-name” property of the BACnet Device Object.

    Device Type is made from “vendor-id” and “model-name” properties of the BACnet Device Object. The “vendor-id” as 4 digit decimal number. In the example above this is 0710 for “Rational Network”. The BACnet “model-name” of the device above is “mingo-dds238_1_z1” for the first device and “analog-inputs” for the second one.

    All 3 BACnet properties used are required BACnet Device Object properties, and therefore always exist in every BACnet device from any vendor. You can easily browse for those properties using any BACnet browser or DINGO Manager.

    On the IBM Watson IoT Platform Dashboard click “Boards” on the left-side menu then the “+ Create New Board” button on the right hand side.
    Fill out all fields as you think is appropriate in the wizard that appears.

    You will now see your board as newly created. Click on it. Your new board will be empty.  

    Click on the “+ Add New Card” button at the upper right of your board. You will be asked to select a card type.
    Click on “Gauge”

    The example below will be different from your setup as you are probably working with different BACnet devices than us. However you can use the example to guide you through making your first card. The steps are the same.

    Select one of your devices as shown by example below and press the “Next” button.

    WatsonIoT-Platfrm-06

    In the wizard dialog that appears fill/select out all fields as appropriate for your setup. An example is shown below.

    WatsonIoT-Platfrm-07
    “Event” is always “COV” (shortcut for “Change Of Value”, commonly used phrase in BACnet).

    “Property” drop down is filled with BACnet Object-Names you selected when you configured publishing objects in the gateway configuration in the previous step. The Object-Names are appended with a '_' and then the property name published. In most cases that is “present-value” referring to BACnet Present Value. If you have selected to publish status flags, in the previous step, those also exist in the “Property” drop down as “your-bacnet-object-name_status-flags”.
    An example of the “Property” drop down is shown below to explain this.

    WatsonIoT-Platfrm-08
    When you have filled out all fields of this dialog press the “Next” button.
    The dialog that appears is for graphics setup. Choose any graphics you want. An Example is shown below.

    WatsonIoT-Platfrm-09

    Press “Next” button when you have selected your graphics.
    The next wizard page is self-explanatory. Change the Title and color as you want.
    Press the “Submit” button.
    You should now see live data in your first card. You can add more cards by pressing the “+ Add New Card” in the upper right of your board. An example with 4 cards is shown below:

    WatsonIoT-Platfrm-10

    If you are not interested in using BACnet Web Services via MQTT tunnel (mostly for advanced users), feel free to skip next section in this recipe. 
    However the test application used there might interest you to play with. You can find the test application here…

     

  7. Step 5 (optional): Test BACnet Web Services via BACnet/WS - Watson Tunnel

    Introduction

    BACnet/WS is probably the most advanced WoT (Web of Things) standard defined today, based on HTTP REST API.
    You can do the simple things with the approach described above based on MQTT publishing and subscribing. But when it comes to more complex things like complex queries and commands from/to a Building Management System or Factory Floor, more powerful approach is needed. Go-IoTs implementation of the BACnet/WS cutting edge standard is among the first in the world. With it, Go-IoT has in fact taken BACnet to the level of IoT and WoT.
    To enable BACnet/WS for Watson IoT Platform the Go-IoT BACnet to Watson Gateway includes a BACnet/WS tunnel, such that you can send BACnet/WS requests to the BACnet network using Watson Commands and receive responses and events via MQTT publishing to Watson IoT Platform.

    If you are not familiar with BACnet/WS please brief through the standard definition available here… 
    You can also play with it from our “Try BACnet/IoT”  page here… by simply using your browser for sending BACnet requests to a physical setup in Iceland.

    How to use the BACnet/WS Watson Tunnel

    First to mention is that a detailed description of the payload for this tunnel is described in “Appendix C: BACnet/WS Tunnel Payload Definitions” below.

    To enable the tunnel you don't have to do anything. It is already enabled if you have followed steps 1, 2 and 3 above (we are now in step 5).

    To test and experiment with it use our test-bluemix application here…

    Yu need to fill in your “IBM IoT Platform connection properties” and optionally your “IBM Bluemix Cloudant noSQL connection properties”  as you enter the web-page first time, as shown in the screen-shot below.
    In addition be careful filling out the “BACnet/WS settings” correctly referring to your gateway. “Event ID” should always be “bacnet-ws”.

    TestApp04

    Now you can send some GET and PUT requests in the lower half of the application. For example to send a kind of “Who Is” request to your BACnet network, put this string into “BACnet/WS path” and press “Send” button:

    /bacnetws/.bacnet/.local/?alt=json&depth=1

    After few seconds (depending on how many devices are in the BACnet network and how fast those are), you should get something like:

    {“d”:{“ws”:{“103000″:{},”103301″:{},”103302″:{},”103801″:{},”103802”:{}}}}

    in the “Reply” box. Which is a list of device-ids of all the BACnet devices on the network. Try to change “depth” parameter in the path to “2” instead of “1” and press “Send” again. This will dig deeper into each device listing all its objects.

    Now try to turn on and off a binary output (relay or switch):
    Set “HTTP request method” to “PUT” instead of “GET”.

    Set “BACnet/WS path” to something similar to, where you replace the “2” in  “binary-output,2” with your BACnet binary output object instance number :
    /bacnetws/.blt/binary-output,2/present-value?alt=json

    Set this into the “BACnet/WS payload”:
    {“$value”: “1”}
    or
    {“$value”: “0”}

    Press “Send” button.

    Notice “Heat blower:” status above switching from “Off” to “On” and vice versa, if linked to the same BACnet object.

    Those are only the most simple things you can do with this BACnet/WS tunnel. But now you have the programming power to do whatever you like sending such BACnet/WS tunneled commands from your Watson IoT enabled application.
    You can of course also mix both methods; BACnet/WS tunneling and normal Watson MQTT communication as you can play with in the upper section of the test application.

    Viewing the source of the test applicaton can also help you start programming.
    In addition “Appendix A” below we shortly describe how you can use Node-RED to use the BACnet/WS tunnel.

  8. Conclusion

    This recipe has described how to:

    1. Install BACnet to Watson IoT Gateway software to your DINGO or Raspberry Pi.
    2. Set up a Gateway device type and Gateway device in the IBM Watson IoT Platform.
    3. Configure the BACnet to Watson IoT Gateway in your DINGO or Raspberry Pi, using go-iot DINGO manager.
    4. Visualized extracted event data on a IBM Watson IoT Board.
    5. How to tunnel BACnet Web Services (BACnet/WS) requests via MQTT from Watson IoT Platform to your BACnet network, and how to receive BACnet/WS responses and events from your BACnet network, via the tunnel.

    Where to go from here is totally your choice.
    You can for example start using Node-RED to create your awesome application using data from your BACnet Network(s). Or you can use the demo application source-code in the last step above as your starting point.

    Below are some appendixes to further help you programming.

    PLEASE NOTE: Future updates of both the Smart EnOcean Gateway and IBM Watson IoT Platform might slightly impact the screen captures.

  9. Appendix A: Programming with Node-RED

    Introduction.

    Node-RED is a visual tool for wiring the IoT, but it can also be used for other types of applications to quickly assemble flows of services. Node-RED is becoming a kind of de-facto standard for simple and fast IoT programming.
    This section explains very briefly how Node-RED can be used to implement a Watson IoT Platform client application. It is not intended as Node-RED course. You can install Node-RED at whatever platform that best suits you. For example if you want to install it on Raspberry Pi or DINGO (mostly preinstalled) you can follow the guidelines in the video tutorial here…

    However it might be the best alternative to use Node-RED at your IBM Bluemix account.

    Simple Demo.

    Below is a simple demo where we have a heat-blower with a temperature sensor in front of it as shown on the image below.
    We are going to enable the blower switch so you can turn it on and off and follow the temperature rises and fall in a real time graph from a web page.  

    If someone else is also switching the heat-blower on and off the button on the web-page should reflect that status change.

    The result of this demo is accessible online connected to real setup in Iceland. Feel free to test it here…

    Node-Red01   DINGO-Pi

    In this example the “Temp. Sensor” is a 1-Wire sensor on a large 1-Wire sensor network connected to the standard multiport of a DINGO Backbone. The DINGO software stack takes care of managing all the 1-Wire sensors as BACnet object, so you don't have to worry if it is a 1-Wire, Modbus, Zigbee or what-ever.
    The switch for the “Heat Blower” is relay #2 on the  DINGO Backbone baseboard type DINGO-BB-3ST-01  

    Below is a screen-shot of the Node-RED flow.
    At the left side are the ibmiot input nodes; the temperature and switch state published from BACnet to Watson Gateway.
    At the right are the outputs; a chart node to graph the temperature real time and an ibmiot output node for the switch (commanded from Watson to BACnet device).

    Between the inputs and outputs are functions to manipulate payload-data and a switch node.

    The reason we connect an ibmiot input node (“Blower ON/OFF (in)”) to the blower-switch is that we want to see if someone else changes the blower-switch also. The switch-button on the web page has to reflect that status change as well as the status change you perform by pressing the switch-button.

    Node-Red02

    First let us define the “Temp. Sensor (in)”. You drag it from the “input” section at the left.
    Then double click it to get the setup shown below.

    Node-Red03b

    As this is the first ibmiot node you configure you have to specify your API Key by pressing the pencil button, to reach the screen below.
    Carefully fill “API Key” and “API Token” as is from your IBM Watson account.
    Remember to check “Scalable” as we are going to reuse this API Key for the other two ibmiot nodes.

    Node-Red04b

    Next step is to drag in another ibmiot input node for “Blower ON/OFF (in)” and configure it such:

    Node-Red05b

    Note that you are sharing the same “API Key” as for the previous ibmiot input.

    Next drag in an ibmiot output node for “Blower ON/OFF (out)” and configure such:

    Node-Red06b

    Note that “Command Type” is set to “wp8”. When that command type is transformed to BACnet Write Property service in the BACnet device-network, it will write at BACnet priority 8+1 = 9.
    If someone else writes at BACnet priority higher than that, for example priority 6 it will override your commands and you will see no effect of pressing the switch button until the “other setter” writes NULL (“don't care”) to the same BACnet Binary Input (the switch) at BACnet priorty 6.

    Now drag in a switch node from the “Dashboard” section at the left side.
    If you don't have a dashboard section you need to install it by selecting “Manage palette…” from the drop-down menu in the right upper corner of your Node-RED page.

    Configure the switch as shown below.

    IMPORTATNT! Uncheck the “if msg arrives on input, pass through to output” to avoid endless circle.

    Node-Red07-1

    The chart node also from the “Dashboard” section is trivial. Just add it and configure as you want.

    The only left thing to do now is to make the three functions. Those are all very simple and self-explanatory for a basic Java-script programmer. Code of each function is below:

    FUNCTION “Get Temp.”:
    var temp = msg.payload.d[“office-temp_present-value”];
    if(temp !== undefined)
       return {topic: “Office Temp.”, payload: temp};

    FUNCTION “Get State”:
    var relayStatus = msg.payload.d[“relay-2_present-value”];
    if(relayStatus !== undefined)
        return {payload: relayStatus == “0” ? false : true};

    FUNCTION “Get Switch State”:
    var relayState = { payload : { d : { “relay-2_present-value” : msg.payload ? 1 : 0}}};
    return relayState;

    As a last step create a debug node as shown in the flow-diagram above and link all the nodes as shown with flows.

    The final step is to press the “Deploy” button in the upper right corner of your Node-RED page.

    The result should be immediately active at your Node-RED-ui page, which in our case is:
    https://dingo-demo-node-red.eu-gb.mybluemix.net/ui/#/0 
    and a more advanced version at:
    https://dingo-demo-node-red.eu-gb.mybluemix.net/ui/#/1
    Feel free to play with those as you want.

    C2Net08

    Conclusion

    You have now learned by example how to use Node-RED to access published data from a BACnet device-network. You have also learned how to send commands from Node-RED to Watson IoT that end up as Write Property BACnet service calls in a BACnet device far away.

    Node-RED can also be used to program with the BACnet/WS tunnel. This gives Node-RED extra power where you have all the powerful gidgets and gadgets from BACnet/WS at your fingertips using Node-RED.
    You can find some video-examples for this at our videos page here…

  10. Appendix B: Payload Definitions

    EVENT TYPE

    “COV” (Change Of Value) is the only published event-type for all BACnet objects except TrendLog (TL) and
    TrendLogMultiple (see below).

    “TLR” (Trend Log Record(s)) is used to publish log records from trend-log and trend-log-multiple BACnet objects.
    This event type is only supported in version 1.1 and higher. Check current version type in “Appendix D”

    DEVICE TYPE & DEVICE ID

    The Watson IoT Platform “Device Type” and “Device ID” are formed from BACnet properties such:

    For the gateway itself:

    “Device Type” = “dingo”, taken from the GW connection configuration, gateway-device type.
    “Device ID” = “my-dingo-something”, taken from the GW connection configuration, gateway-device ID.

    Note if you check the “Treat Gateway as Device” in the DINGO Manager Gateway configuration. The Gateway will be handled as any other device (see below)
    Only supported in version 1.1 and higher. Check current version type in “Appendix D”

    For other BACnet device types:

    “Device Type” = “xxxx-model-name”, where the “xxxx” part is taken from the required vendor-identifier property of the Device Object and the model-name part is taken from the required model-name property of the BACnet Device Object.
    For further information refer to clause “12.11.6 Vendor_Identifier” and “12.11.7 Model_Name” in the ANSI/ASHRE BACnet standard.
    “Device ID” = “device-name”, taken from the device-name of the Device Object.

    For structured-view-object (SVO, see ASHRE 12.29):

    “Device Type” = “0000-node-type”, where the “node-type” part is taken from the node-type required property of the Structured View Object (the bottom-most parent of the “real” object).
    According to the BACnet standard (ASHRE 12.29.5) this can only take one of the values below:
    { “unknown”, “system”, “network”, “device”, “organizational”, “area”, “equipment”, “point”, “collection”, “property”, “functional”, “other” }
    “Device ID” = “object-name|object-name|…”, taken from the object-names() of the SVO(s) parenting the “real” object.

    See example for SVO below.
    SVOs are supported in version 1.1 and higher. Check current version type in “Appendix D”.

    COV PAYLOAD

    COVs contain two properties in the payload “object-name_present-value” and “object-name_status-flags”
    In each COV publishing, the payload can hold one of those properties or both.

    The payload (JSON) looks like this (example):

    { “internal-temp_present-value”: “22.4375”, “internal-temp_status-flags”: “true,false,false,false” }

    The first part is the value itself. The name is made up of the BACnet Object Name plus BACnet Property Name with a '_' between them.

    The second part is the BACnet status-flags (unless you have configured the gateway not to publish those). The name of the status flags is made up of the BACnet Object Name plus “_status-flags”.
    As defined by the BACnet standard the four status flags are, in this order:

    IN_ALARM: Logical false if the event-state property has value of NORMAL, otherwise logical true.
    FAULT: Logical true if the reliability property is present and does not have a value of NO_FAULT_DETECTED, otherwise logical false.
    OVERRIDDEN: Logical true if the point has been overridden by some mechanism local to the BACnet Device. In this context “overridden” is taken to mean that the present-value and reliability properties are no longer tracking changes to the physical input. Otherwise, the value is logical false.
    OUT_OF_SERVICE: Logical true if the out-of-service property has a value of true, otherwise logical false.

    TLR PAYLOAD

    Current version does not support TLR event type. 

    STRUCTURED-VIEW-OBJECT EXAMPLE

    Let us assume  this structured-view-object (SVO) structure:
    “floor-5” SVO of node-type “area”
    —-> “inside-temp” Analog Input object
    —-> “machine-room” SVO of node-type “area”
    ——–> “generator” SVO of node-type “equipment”
    ————> “ignition” Binary Output object
    ————> “oil-pressure” Analog Input object
    ————> “engine-temp” Analog Input object

    If selecting the top level structured view object for Watson publishing. This would be published such:

    Device Type           Device ID                                               Payload property-id
    ———————————————————————————————————-
    “0000-area”             “floor 5”                                             “inside-temp_present-value”
    “0000-equipment”  “floor-5|machine-room|generator”  “ignition_present-value”
    “0000-equipment”  “floor-5|machine-room|generator”  “oil-pressure_present-value”
    “0000-equipment”  “floor-5|machine-room|generator”  “engine-temp_present-value”

    COMMANDS

    The only allowed command type for outputs is “WPx” with a valid value in payload. 'x' is the
    BACnet Write-Priority to use (0-F, where '0' is highest priority, and 'F' the lowest (hex F is 15 ).
    if 'x' is not specified the lowest priority of 'F' is used. The Watson write-priority range 0-15, maps to BACnet write-priority range 1 – 16.
    “WPx” is allowed with multiple properties in the payload, resembling to BACnet Write Property Multiple service.

    The “WPx” payload is formatted the same as “COV” payloads. 

    The example below shows a payload switching two binary-outputs, the first one to OFF and the second one to ON.

    { “relay-1_present-value”: “0”, “relay-2_present-value”: “1” }

  11. Appendix C: BACnet/WS Tunnel Payload Definitions

    EVENT TYPE

    When sending a BACnet/WS request via the BACnet to Watson Tunnel, “event type” is always “bacnet-ws”.

    Response to tunneled BACnet/WS requests is always published as “bacnet-ws-xxx” where “xxx” is the “client-id” property in the payload discussed below.

    DEVICE TYPE & DEVICE ID

    Tunneled BACnet/WS requests are always sent as gateway commands, although the BACnet/WS request itself can refer to any device on the BACnet network, even multiple devices in the same request.

    “Device Type” = “dingo”, taken from the GW connection configuration, gateway-device type.
    “Device ID” = “my-dingo-something”, taken from the GW connection configuration, gateway-device ID.

    REQUEST PAYLOAD

    When tunneling BACnet/WS request from a Watson IoT Platform client, the total payload string looks like the example below:

    {“d”:{“client-id”: “123”, “id”: “1” ,”ws”:{“path”: “/bacnetws/.blt/binary-output,2/present-value?alt=json”, “method”: “get”}}}

    “client-id” is an ID to make the response unique for the requesting client. If the request is sent as above the response published will be on “event-id” as “bacnet-ws-123”.

    “id” is optional. If specified in the request it will be returned in the published response. “id” can be used for sequencing correctly as a request and it's response will always have same value of “id”.

    “ws” is the BACnet/WS request. It has two properties:

    1. “path” the BACnet/WS request.
    2. “method” is set to either “get”, “put”, “post” or “delete” where “get” and “put” are the far most common.
      When writing to a BACnet object(s), use “put”.

    RESPONSE PAYLOAD

    When the BACnet to Watson Gateway has processed the tunneled BACnet/WS request, a response or error will be published as the following example explains:

    {“d”:{“id”: “1”,  “ws”:{“$value”:”inactive”}}}

    “id” is the same as the id from the original request.

    “seq” (see example below) is a sequence number if the response has to be published in more than one message, for example when the request is for a long sequence from a trend-log object, or a response from a “who-is”/”who-has” service request on a large BACnet network. “seq” always start as “0” and counts upwards as an one byte unsigned integer (rolls over from 128 to 0). If more packets is expected a '+' is appended to the “seq” number. This is explained in the trend-log request example below.

    Trend Log request to the local device for 100 first logs after or at 2017-01-16 00:00:00 (gateway itself, trend log object nr. 50):

    {“d”:{“client-id”: “123”, “id”: “1” ,”ws”:{“path”:/bacnetws/.blt/trend-log,50/log-buffer?published-ge=2017-01-16T00:00:00&max-results=100&alt=json, “method”: “get”}}}

    Responses:

    {“d”:{“id”:”1″,”seq”:”0+”,”ws”:{
    “55514”:{“timestamp”:”2017-01-16T12:06:55Z”,”log-datum”:{“real-value”:”38.625″},”status-flags”:”false,false,false,false”},
    “55515”:{“timestamp”:”2017-01-16T12:07:14Z”,”log-datum”:{“real-value”:”38.6875″},”status-flags”:”false,false,false,false”},
    “55516”:{“timestamp”:”2017-01-16T12:08:15Z”,”log-datum”:{“real-value”:”38.625″},”status-flags”:”false,false,false,false”},
    }}

    {“d”:{“id”:”1″,”seq”:”1+”,”ws”:{
    “55517”:{“timestamp”:”2017-01-16T12:08:35Z”,”log-datum”:{“real-value”:”38.6875″},”status-flags”:”false,false,false,false”},
    “55518”:{“timestamp”:”2017-01-16T12:09:15Z”,”log-datum”:{“real-value”:”38.625″},”status-flags”:”false,false,false,false”},
    “55519”:{“timestamp”:”2017-01-16T12:09:35Z”,”log-datum”:{“real-value”:”38.6875″},”status-flags”:”false,false,false,false”},
    }}
    …..
    {“d”:{“id”:”1″,”seq”:”27+”,”ws”:{
    “55594”:{“timestamp”:”2017-01-17T14:22:18Z”,”log-datum”:{“real-value”:”33.625″},”status-flags”:”false,false,false,false”},
    “55595”:{“timestamp”:”2017-01-17T14:22:38Z”,”log-datum”:{“real-value”:”33.75″},”status-flags”:”false,false,false,false”},
    “55596”:{“timestamp”:”2017-01-17T14:22:58Z”,”log-datum”:{“real-value”:”33.9375″},”status-flags”:”false,false,false,false”},
    }}

    {“d”:{“id”:”1″,”seq”:”28″,”ws”:{
    “55597”:{“timestamp”:”2017-01-17T14:23:18Z”,”log-datum”:{“real-value”:”34.0625″},”status-flags”:”false,false,false,false”},
    “55598”:{“timestamp”:”2017-01-17T14:23:38Z”,”log-datum”:{“real-value”:”34.125″},”status-flags”:”false,false,false,false”}
    }}

    Notice how the last packet published is with “seq” as “28” omitting the '+' sign to indicate the last sequence in the response.

    If the response is in only one sequence (most common) the “seq” property is omitted.

    USING METHOD “PUT” EXAMPLE

    Below is an example writing “1” (ON) to binary-output nr. 2 (a relay, switch or whatever). Notice the payload at the end of the request.

    Request:

    {“d”:{“client-id”: “123”, “id”: “43” ,”ws”:{“path”: “/bacnetws/.blt/binary-output,2/present-value?alt=json”, “method”: “put”, “payload”:{“$value”: “1”}}}}

    Response:
    {“d”:{“id”:”43″, “ws”:””}} 

  12. Appendix D: Version Information

    This recipe is for version 1.0.170112 of the Go-IoT BACnet to Watson Gatetway, which is the last available version.

    Limitations that are planned to be removed in next release (1.1):

    • Managed commands like Reset and Firmware Upload are not supported.
    • COV Event Type (Change Of Value) does not support polling BACnet objects. BACnet Objects Participating in COV publishing must be BACnet-COV enabled.
      In next release different polling frequency can be specified for different BACnet objects needed to be polled.
    • BACnet Devices participating in publishing or subscribing must support the BACnet Read Property Multiple (RPM service.
      Next release will allow devices that do not support RPM to participate.
    • Structured-view-object, SVOs (ASHRE 12.29), are not supported when not using BACnet/WS tunneling. 
    • Publishing Trend Log (TL) and Trend Log Multiple (TLM) objects is not supported. However TL and TLM objects can be accessed using the BACnet/WS tunnel.
    • The feature letting the Gateway Device publish with “Device Type” and “Device ID” as other devices is not supported. Current version publishes Gateway COV events on “Device Type” “dingo” and “Device ID” used for the gateway in the Watson IoT Platform definition of the gateway.
    • Using BACnet/WS tunnel, subscribing to BACnet COVs is not supported.
    • In a coming release  we will enable DINGO Manager to operate fully via the BACnet/WS tunnel. That is to say a DINGO Backbone (running BACnet to Watson Gateway) has not to be accessible from “the outside” to be configurable over the Internet.

3 comments on"BACnet Gateway to IBM Watson IoT Platform"

  1. As we have been asked a lot about a BACnet/WS Quick Starter, a good start could be here:
    http://dingo-iot.io/try-bacnetws/
    At this link you can play with BACnet/WS against a live BACnet network in Go-IoT laboratory.
    The BACnet/WS addendum can be found here:
    http://www.bacnet.org/Addenda/Add-135-2012am.pdf
    Do not hesitate asking questions here.

  2. As it has become quite popular to play with our BACnet to Watson IoT demo application, you may expect relays switch back and forth without your interaction.
    This is because someone else is also using the demo at the same time, possibly many users at the same time.
    Here it is: https://dingo-demo-node-red.eu-gb.mybluemix.net/ui/#/1
    Feel free to play with it.

  3. Hi,

    We need to purchase a BACnet client, From what I understand your gateway is a hardware device, which needs to be configured with our BACnet interface.Then we need to configure the gateway as a device in Watson IoT platform, Then using node red we can pull the data out. Is that so?

    And another clarification, you live demo is not loading properly in some networks. It is shown complete black colour, is their any limitations of the demo with regard to network?

    Awaiting reply.

Join The Discussion