Skip to content

BACnet/MSTP Example

The BACnet/MSTP Device Service example demonstrates onboarding the BACnet Server device simulation that is provided with Edge Xpert.

Required Configuration

Since the BACnet Device Service can run both BACnet/IP and BACnet/MSTP, it must be configured for the correct mode prior to it starting.

To configure the BACnet Device Service to use BACnet/MSTP and the simulated device, you must first create a local docker-compose.yml file. This can be achieved by copying the following content and saving it to your working directory.

version: '3.7'

services:
  device-bacnet-mstp:
    entrypoint: > 
       sh -c "
       socat pty,link=/tmp/virtualport,raw,echo=0 tcp:bacnet-server:55000 
       & /docker-entrypoint.sh"
    read_only: false
    environment:
      BACNET_SERIAL_INTERFACE: /tmp/virtualport

  bacnet-server:
    environment:
      RUN_MODE: "MSTP"
  • The socat command creates a tunnel for transferring data to the simulator.
  • We use /tmp/virtualport to transfer data, so we want read_only to be set to false.
  • Set RUN_MODE to MSTP to run the BACnet simulated device with BACnet/MSTP. Refer to BACnet Server for further details.

You can configure any specific options for running the Device Service in the environment section of the device-bacnet-mstp entry of your local docker-compose.yml file. A listing of available environment variables can be found here.

Start the BACnet/MSTP Device Service and Simulator

To start the BACnet/MSTP Device Service with the simulator, enter the following command:

edgexpert up device-bacnet-mstp bacnet-server

As demonstrated below, Edge Xpert will override the default configuration with a local docker-compose.yml file:

$ edgexpert up device-bacnet-mstp bacnet-server
Overriding configuration with local docker-compose.yml
Creating network "edgexpert_edgex-network" with driver "bridge"
...
Creating bacnet-server ... done
Creating device-bacnet-mstp ... done

Note

In order for your local changes to be used, you must start Edge Xpert from the directory in which your local docker-compose.yml is saved.

Device Onboarding

Once the BACnet/MSTP Device Service has been started, BACnet devices can be onboarded to Edge Xpert using either the Edge Xpert Manager UI or through Edge Xpert REST API commands. Instructions on how to use both methods are described below.

Device Onboarding with the Edge Xpert Manager UI

Note

Please refer to the Edge Xpert Manager UI Device Management capability for full details.

  1. Ensure the Edge Xpert Manager UI is started, for example:

    edgexpert up xpert-manager
    

  2. Open a browser and go to localhost:9090. The default username and password is admin.

  3. Using the device profile upload capability, upload the provided BACnet example device profile at /usr/share/edgexpert/examples/device-services/bacnet/bacnet-sim-profile.yml

  4. Onboard the BACnet device using the device onboarding capability. The following values can be used to provision the example BACnet Server device:

    Field Example Value Description Required
    Name bacnet-mstp-sim The unique name used to identify the device Required
    Description Simulated BACnet device Additional information about the device Optional
    Label BACnet Any additional information to help identify the device Optional
    Protocol BACnet-MSTP The name of the protocol Required
    Device Instance 123 The unique device identifier across the BACnet network Required
    Device Profile bacnet-sim-profile The name of the device profile uploaded above Required
    Device Service device-bacnet-mstp The name of the appropriate device service Required
    Auto Events Interval: 5s
    OnChange: false
    ResourceName: analog_input_0-present-value
    Automated events to retrieve the data at specific frequencies

    Note: If OnChange is set to true, values will only be pushed if a change in value has occurred during the specified interval. If set to false, values will be sent on the specified interval regardless of if there has been a change.
    Optional

Device Onboarding with the Edge Xpert REST API

  1. Upload the provided BACnet example device profile:

    curl http://localhost:59881/api/v2/deviceprofile/uploadfile -F "file=@/usr/share/edgexpert/examples/device-services/bacnet/bacnet-sim-profile.yml"
    

  2. Onboard the device using similar values as explained above:

    curl http://localhost:59881/api/v2/device -H "Content-Type:application/json" -X POST \
        -d '[ {
                "apiVersion": "v2",
                 "device": {
                   "name" :"bacnet-mstp-sim",
                   "description":"Simulated BACnet device",
                   "labels":[ 
                      "BACnet"
                   ],
                   "serviceName": "device-bacnet-mstp",
                   "profileName": "bacnet-sim-profile",
                   "protocolName": "BACnet-MSTP",
                   "protocols":{
                      "BACnet-MSTP":{
                        "DeviceInstance": "123"
                      }
                   },
                   "adminState":"UNLOCKED",
                   "operatingState":"UP",
                   "autoEvents": [
                      {
                        "interval": "5s",
                        "onChange": false,
                        "sourceName": "analog_input_0-present-value"
                      }
                    ]
                }
            }
        ]'
    

Device Data Flow

Once the device is onboarded to Edge Xpert, data flow between the Device Service and the connected device can be verified in a number of ways.

The Edge Xpert Manager UI supports Read and Write functionality for each device. Readings can also be viewed and queried within the Edge Xpert Manager UI Data Center.

Alternatively, you can read and write data with cURL commands or through REST API applications, such as Postman.

Both the GET and PUT commands can be made to the following address:

http://localhost:59981/api/v2/device/name/{deviceName}/{commandName}

Using the example above, this could be:

http://localhost:59981/api/v2/device/name/bacnet-mstp-sim/analog_input_0-present-value

For more information on the GET and PUT commands, see the Core Command Microservice.

Note

59981 is the default port for the BACnet/MSTP device service

Any data collected by the Device Service can then be treated like all other Edge Xpert sensor data. The data readings can be exported for data processing in a number of other applications and services. See the Supporting Services and Application Services documentation for more details.

Back to top