BACnet/IP Example

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

Preconfiguration

The BACnet Device Service can communicate on both BACnet/IP and BACnet/MSTP. You must configure the device service to run in the correct mode before starting.

To configure the BACnet Device Service to use BACnet/IP 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-ip:
    environment:
      BACNET_BBMD_ADDRESS: bacnet-sim

  bacnet-sim:
    environment:
      RUN_MODE: "IP"

• The BACNET_BBMD_ADDRESS indicates the IP address of the BACnet Broadcast Management Device (BBMD) that the device service will register to as a foreign device.

• Set RUN_MODE to "IP" to run the BACnet simulated device in IP mode. Refer to BACnet Sim for further details.

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

Start the BACnet/IP Device Service and Simulator

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

edgexpert up device-bacnet-ip bacnet-sim

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

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

Device Onboarding

Once the BACnet/IP 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

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 sim device:

   Field	Example Value	Description	Required
   Name	bacnet-ip-sim	The unique name used to identify the device	Required
   Description	Simulated BACnet device	Any additional information about the device	Optional
   Label	BACnet	Any additional information to help identify the device	Optional
   Protocol	BACnet-IP	The name of the protocol	Required
   Device Instance	123	Unique device identifier across the BACnet network	Required if Address and Port not set
   Address	192.168.60.123	IP address of the device	Required if Device Instance not set
   Port	47809	Port of the device	Required if Device Instance not set
   Device Profile	bacnet-sim-profile	The name of the device profile uploaded above	Required
   Device Service	device-bacnet-ip	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:

The DeviceInstance protocol property can be used to specify the BACnet device instance network ID. If BACnet devices are required that run on different subnets or ports and a BBMD cannot be used, then these devices can be addressed directly. The Address protocol property specifies the IP address of the device and Port can be set if the device is running on a different port.

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

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

Device Data Flow

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.

Once the device is onboarded to Edge Xpert, there are a number of ways to verify data flow between the Device Service and the connected device.

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

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

curl http://localhost:59882/api/v2/device/name/bacnet-ip-sim/analog_input_0-present-value

For more information on this, see the Core Command Microservice.

Any data collected by the Device Service can then be processed 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.