Skip to content

MQTT Management API

Edge XRT provides an MQTT API with an associated set of messages and supporting topic hierarchy through which to manage devices and their data. This bi-directional API makes is easy to integrate Edge XRT into third party platforms, applications or management systems, for example Edge Xpert.

The API supports the following groups of MQTT messages that can be used to manage XRT devices and their data:

  • Device Management – messages provide CRUD (Create, Read, Update, Delete) operations for Devices registered with XRT

  • Profile Management – messages provide CRUD operations for Device Profiles used to configure XRT Device Services

  • Schedule Management – messages provide CRUD operations for Schedules used to control data polling rates associated with Device Resources

  • Discovery Management – messages provide operations that control the triggering of device auto discovery for protocols (e.g. BACNet, OPC UA, BLE) that provide such features

Note

Devices, profiles, and schedules have unique names scoped to a device service instance. This is also true for topics used to manage them. To understand how to configure a device service component and their topics please see: Device Service Component Configuration

All messages are encoded as JSON. Devices, Profiles, and Schedules have unique names scoped to a device service instance. Most operations are in the form of an RPC over MQTT.

Request Format

The RPC requests are represented as a JSON object with the following common fields:

client Client identity. The client value supplied by the request
request_id The request id supplied by the request
result A map containing data resulting from the request

Result Map Format

success A boolean value. A true value indicates the request succeeded. A false value indicates the request failed
error A string value that describes the reason for the failure. This is only present if the success value is false

Additional fields may be present in the result map depending upon the specific operation.

Example “Get Resource” Reply

{
  "client": "client1",
  "request_id": "94178bb8-a0ba-465f-ab31-77f1ba81537f",
  "result": {
    "readings": {
      "BinaryInput1": {
        "origin": 1611161894180636200,
        "value": true,
        "type": "bool"
      }
    },
    "success": true
  }
}

Device Management

Usage Topic Example Topic Name
Device request RequestTopic xrt/device/bacnet_ip_device_service/request
Device reply ReplyTopic xrt/device/bacnet_ip_device_service/reply
Device Telemetry Topic xrt/device/bacnet_ip_device_service/data

Device telemetry is controlled by schedules below.

Request operations

List devices

Return a list of device names.

Operation: device:list

Request arguments: none

Reply: vector of device names

{
  "client": "client1",
  "request_id": "fa7cdd1a-c0ee-4578-b33b-444d777f2301",
  "op": "device:list"
}
{
  "client": "client1",
  "request_id": "fa7cdd1a-c0ee-4578-b33b-444d777f2301",
  "result": {
    "devices": [ "4d8f72a9-fa9c-44f4-922f-71913ecb1384", "bfb090fa-7869-4075-980c-b49e858f8077",
                 "a18342fe-5c53-451e-829e-2b7063397caf", "c73cee57-05cd-4fac-9d8b-987026831927",
                 "3befe158-ed46-4afc-b838-7bcf96b4e414", "8eaa06d0-1cd6-43fc-b57a-1a8c5b1b4797",
                 "4bf7d20f-5a4d-42ab-a939-bfbabdf17500", "855458fd-9cdd-4022-97d3-d1b79d3653bd",
                 "892db3be-73ff-43fb-9525-ca84a919952c", "cc9a85ee-e944-4430-9eeb-b29beea29301" ],
    "success": true
  }
}

Add Device

Adds a device.

Operation: device:add

Request arguments: device name, device info map. If no profile is supplied and discovery is available and enabled then a profile will be discovered and added. The discovery process can be controlled by supplying an “options” field

Reply: boolean success status and optional error message

{
  "client": "client1",
  "request_id": "404be6e3-e171-4547-bacb-151dfe0ae483",
  "op": "device:add",
  "device": "3befe158-ed46-4afc-b838-7bcf96b4e414",
  "device_info":  {
    "profile": "AI 4xU/I 2-wire ST_1",
    "protocols": {
      "Profinet": {
        "I-base": "0",
        "Q-base": "0"
      }
    }
  }
}
{
  "client": "client1",
  "request_id": "404be6e3-e171-4547-bacb-151dfe0ae483",
  "result": {
    "success": true
  }
}

Example request with discovery:

{
  "client": "client1",
  "request_id": "5f0731ec-d941-4ebd-9ccf-30d5ab5f6af9",
  "op": "device:add",
  "device": "f02f87c9-6248-45e6-ac0f-1d74e20049ba",
  "device_info": {
    "protocols": {
      "BACnet-IP": {
        "Port": "47808",
        "DeviceInstance": "123"
      },
      "BACnetSupportedServices": {
        "DS-WPM-B": "true",
        "DS-RPM-B": "true"
      }
    },
    "properties": {
      "ObjectName": "SimpleServer",
      "VendorName": "BACnet Stack at SourceForge",
      "VendorID": 260,
      "ApplicationSoftware": "1.0",
      "Firmware": "1.0.0",
      "ModelName": "GNU",
      "InstanceID": "123",
      "DeviceType": "BACnet-IP"
    }
  },
  "options": {
    "DiscoveryMode": "PresentValue"
  }
}

Scan Device

This operation checks a device profile for updates. If the profile has changed a new profile with a unique ID will be generated.

Operation: device:scan

Request arguments: device name, discovery options

Reply: profile ID

{
  "client": "client1",
  "request_id": "f07be237-8928-429c-b236-6fa1c59da216",
  "op": "device:scan",
  "device": "f02f87c9-6248-45e6-ac0f-1d74e20049ba",
  "options": {
    "DiscoveryMode": "PresentValue"
  }
}
{
  "client": "client1",
  "request_id": "f07be237-8928-429c-b236-6fa1c59da216",
  "result": {
    "profile": "a3269a76-fc83-44ac-b3ca-2ecb7a7c4965",
    "success": true
  }
}

Read Device Info

Returns meta-data information on a named device.

Operation: device:read

Request arguments: device name

Reply: device map, boolean success status and optional error message

{
  "client": "client1",
  "request_id": "73450fca-abdc-44af-be7d-65ca9fe3ffc1",
  "op": "device:read",
  "device": "3befe158-ed46-4afc-b838-7bcf96b4e414"
}
{
  "client": "client1",
  "request_id": "73450fca-abdc-44af-be7d-65ca9fe3ffc1",
  "result": {
    "device": {
      "name": "3befe158-ed46-4afc-b838-7bcf96b4e414",
      "profile": "AI 4xU/I 2-wire ST_1",
      "protocols": {
        "Profinet": {
          "I-base": "0",
          "Q-base": "0"
        }
      },
      "properties": {
        "name" : "AI 4xU/I 2-wire ST",
        "description" : "Analog input module AI4 x U/I 2-wire ST; 16-bit, common mode voltage 10 V; configurable diagnostics; supports PROFIenergy",
        "vendor": "SIEMENS"
      }
    },
    "success": true
  }
}

Update Device

Changes properties on a named device.

Operation: device:update

Request arguments: device_info a map of device properties to update

Reply: boolean success status and optional error message

{
  "client": "client1",
  "request_id": "815cf17b-1c19-4d66-b0fa-ff217dbca97e",
  "op": "device:update",
  "device": "3befe158-ed46-4afc-b838-7bcf96b4e414",
  "device_info":  {
    "profile": "AI 4xU/I 2-wire ST_2"
  }
}
{
  "client": "client1",
  "request_id": "815cf17b-1c19-4d66-b0fa-ff217dbca97e",
  "result": {
    "success": true
  }
}

Delete Device

Removes a named device.

Operation: device:delete

Request arguments: device name

Reply: boolean success status and optional error message

{
  "client": "client1",
  "request_id": "ae813a79-c11c-459b-bf27-874699774025",
  "op": "device:delete",
  "device": "3befe158-ed46-4afc-b838-7bcf96b4e414"
}
{
  "client": "client1",
  "request_id": "ae813a79-c11c-459b-bf27-874699774025",
  "result": {
    "success": true
  }
}

Get Resources

Read resource values

Operation: resource:get

Request arguments: device name, resource name or vector of resource names

{
  "client": "client1",
  "request_id": "94178bb8-a0ba-465f-ab31-77f1ba81537f",
  "op": "device:get",
  "device": "damocles-0002b503c1ec",
  "resource": ["BinaryInput1:present-value"]
}
{
  "client": "client1",
  "request_id": "94178bb8-a0ba-465f-ab31-77f1ba81537f",
  "result": {
    "readings": {
      "BinaryInput1": {
        "origin": 1611161894180636200,
        "value": true,
        "type": "bool"
      }
    },
    "success": true
  }
}

Put Resources

Write resource values

Operation: resource:put

Request arguments: device name, resource values and optional protocol specific options

Reply: boolean success status and optional error message.

{
  "client": "client1",
  "request_id": "37d6faf3-8e0b-4f52-b02c-cdd833cbb528",
  "op": "device:put",
  "device": "damocles-0002b503c1ec",
  "values": {
    "BinaryOutput2:present-value": false,
    "BinaryOutput1:present-value": false
  },
  "options": { "Priority":5 }
}
{
  "client": "client1",
  "request_id": "37d6faf3-8e0b-4f52-b02c-cdd833cbb528",
  "result": {
    "success": true
  }
}

Profile Management

Usage Topic Example Topic Name
Profile CRUD request ProfileRequestTopic xrt/profile/bacnet_ip_device_service/request
Profile CRUD reply ProfileReplyTopic xrt/profile/bacnet_ip_device_service/reply

Request operations

List

Return a list of profile names.

Operation: profile:list

Request arguments: none

Reply: vector of profile names

{
  "client": "client1",
  "request_id": "4fe9d670-eba7-474a-9f2a-8f22b695d32a",
  "op": "profile:list"
}
{
  "client": "client1",
  "request_id": "4fe9d670-eba7-474a-9f2a-8f22b695d32a",
  "result": {
    "profiles": [ "fe04cd4b-1330-460e-bae9-eb75c8c0d556",
                  "dd609c4d-a170-4289-a7f1-4ea0957423a3",
                  "2c6323c1-4dc2-4291-b840-9510b5f41970",
                  "2f440ca0-f8b7-4e50-8b3f-fc5989012d94",
                  "4f114da4-5a82-44b8-addd-ab29ee086b51",
                  "8c795e00-5415-4f31-be36-0361acf2ed41",
                  "5c3b2e8b-376b-4387-b871-7fe2f890841d",
                  "842300fb-209f-48ef-90cf-60837061d686",
                  "9ef618cc-2cce-4305-a577-3548344456a2",
                  "912692af-8fcc-4174-812c-06db9617dfda" ],
    "success": true
  }
}

Add Profile

Adds a profile.

Operation: profile:add

Request arguments: profile

Reply: boolean success status and optional error message

{
  "client": "client1",
  "request_id": "66961ca5-d962-44d6-92d9-3f6c76ffc63a",
  "op": "profile:add",
  "profile": {
    "description": "Digital input module DI8 x 24VDC ST; configurable diagnostics; input delay 0 to 20ms; input type 3 (IEC 61131); supports PROFIenergy",
    "labels": [],
    "deviceResources": [
      {
        "description": "Inputs",
        "properties": {
          "value": {
            "type": "uint8",
            "readWrite": "R"
          }
        },
        "name": "Inputs",
        "attributes": {
          "I-offset": "0"
        }
      }
    ],
    "name": "6c52903d-e942-4275-8f48-e8d927f3d2a6",
    "model": "DI 8x24VDC ST V1.0"
  }
}
{
  "client": "client1",
  "request_id": "66961ca5-d962-44d6-92d9-3f6c76ffc63a",
  "result": {
    "success": true
  }
}

Read Profile Info

Returns information on a named profile.

Operation: profile:read

Request arguments: profile name

Reply: profile, boolean success status and optional error message

{
  "client": "client1",
  "request_id": "ae87de5c-3dd8-45c6-9101-2e0f7a92e402",
  "op": "profile:read",
  "profile": "6c52903d-e942-4275-8f48-e8d927f3d2a6"
}
{
  "client": "client1",
  "request_id": "ae87de5c-3dd8-45c6-9101-2e0f7a92e402",
  "result": {
    "profile": {
      "description": "Digital input module DI8 x 24VDC ST; configurable diagnostics; input delay 0 to 20ms; input type 3 (IEC 61131); supports PROFIenergy",
      "labels": [],
      "deviceResources": [
        {
          "description": "Inputs",
          "properties": {
            "value": {
              "type": "uint8",
              "readWrite": "R"
            }
          },
          "name": "Inputs",
          "attributes": {
            "I-offset": "0"
          }
        }
      ],
      "name": "6c52903d-e942-4275-8f48-e8d927f3d2a6",
      "model": "DI 8x24VDC ST V1.0"
    },
    "success": true
  }
}

Update Profile

Replaces a named profile.

Operation: profile:update

Request arguments: profile

Reply: boolean success status and optional error message

{
  "client": "client1",
  "request_id": "7502b4e0-178d-4adc-961a-a312d28f1b0c",
  "op": "profile:update",
  "profile": {
    "description": "Digital input module DI8 x 24VDC ST; configurable diagnostics; input delay 0 to 20ms; input type 3 (IEC 61131); supports PROFIenergy",
    "labels": [],
    "deviceResources": [
      {
        "description": "Inputs",
        "properties": {
          "value": {
            "type": "uint16",
            "readWrite": "R"
          }
        },
        "name": "Inputs",
        "attributes": {
          "I-offset": "0"
        }
      }
    ],
    "name": "6c52903d-e942-4275-8f48-e8d927f3d2a6",
    "model": "DI 8x24VDC ST V1.1"
  }
}
{
  "client": "client1",
  "request_id": "7502b4e0-178d-4adc-961a-a312d28f1b0c",
  "result": {
    "success": true
  }
}

Delete Profile

Removes a named profile.

Operation: profile:delete

Request arguments: profile name

Reply: boolean success status and optional error message

{
  "client": "client1",
  "request_id": "bddf5eba-db8c-442b-bd68-c7b505e8095c",
  "op": "profile:delete",
  "profile": "6c52903d-e942-4275-8f48-e8d927f3d2a6"
}
{
  "client": "client1",
  "request_id": "bddf5eba-db8c-442b-bd68-c7b505e8095c",
  "result": {
    "success": true
  }
}

Schedule Management

Usage Topic Example Topic Name
Schedule CRUD request ScheduleRequestTopic xrt/schedule/bacnet_ip_device_service/request
Schedule CRUD reply ScheduleReplyTopic xrt/schedule/bacnet_ip_device_service/reply

Request operations

List

Return a list of schedule names.

Operation: schedule:list

Request arguments: none.

Reply: vector of schedule names.

{
  "client": "client1",
  "request_id": "1e92b97e-47b0-4cc0-a4d1-5f927c2d87d9",
  "op": "schedule:list"
}
{
  "client": "client1",
  "request_id": "1e92b97e-47b0-4cc0-a4d1-5f927c2d87d9",
  "result": {
    "schedules": [ "5d9e8fbd-6e02-49fa-9d87-7ecfefc6f564",
                   "b7883904-fe0c-4352-9e93-9c4225dc3daa",
                   "1f07f632-f99c-4e5e-b37b-2e4cee7c11bf",
                   "3915b293-beeb-4b2a-9961-1db887dcb60a",
                   "940b4cd3-c583-4305-a9c8-ea581a5d7e8d",
                   "eedd0583-af3c-4d32-9fc1-f1a6fa157daa" ],
    "success": true
  }
}

Add Schedule

Adds a schedule.

Operation: schedule:add

Request arguments: schedule map. The schedule can contain an “options” field that will supply device service specific settings e.g. BacNET COV configuration

Reply: boolean success status and optional error message

{
  "client": "client1",
  "request_id": "a5755ee5-d937-4043-ba2b-39ac6bef3418",
  "op": "schedule:add",
  "schedule": {
    "name": "1c28183b-837f-466d-84c5-42a6bcfcf428",
    "device": "15d6b69e-2d9a-48a3-a433-cb6e42929804",
    "resource": ["Universal Input 2:present-value","Universal Input 2:units"],
    "interval": 5000000,
    "options": {
      "COV": {
        "Confirmed": true,
        "Lifetime": 360
      }
    }
  }
}
{
  "client": "client1",
  "request_id": "a5755ee5-d937-4043-ba2b-39ac6bef3418",
  "result": {
    "success": true
  }
}

Read Schedule Info

Returns information on a named schedule.

Operation: schedule:read

Request arguments: schedule name

Reply: schedule, boolean success status and optional error message

{
  "client": "client1",
  "request_id": "a5755ee5-d937-4043-ba2b-39ac6bef3418",
  "op": "schedule:read",
  "schedule": "a5755ee5-d937-4043-ba2b-39ac6bef3418"
}
{
  "client": "client1",
  "request_id": "a5755ee5-d937-4043-ba2b-39ac6bef3418",
  "result": {
    "schedule": {
      "id": "a5755ee5-d937-4043-ba2b-39ac6bef3418",
      "device": "15d6b69e-2d9a-48a3-a433-cb6e42929804",
      "resource": [ "BinaryInput1:present-value", "BinaryInput2:present-value" ],
      "interval": 5000000
    },
    "success": true
  }
}

Update Schedule

Replaces a named schedule.

Operation: schedule:update

Request arguments: schedule

Reply: boolean success status and optional error message

{
  "client": "client1",
  "request_id": "99baccaf-2fbc-4377-80da-56bc16555cb9",
  "op": "schedule:update",
  "schedule": {
    "name": "1c28183b-837f-466d-84c5-42a6bcfcf428",
    "device": "15d6b69e-2d9a-48a3-a433-cb6e42929804",
    "resource": [ "BinaryInput1:present-value" ],
    "interval": 5000000
  }
}
{
  "client": "client1",
  "request_id": "99baccaf-2fbc-4377-80da-56bc16555cb9",
  "result": {
    "success": true
  }
}

Delete Schedule

Removes a named schedule.

Operation: schedule:delete

Request arguments: schedule name

Reply: boolean success status and optional error message

{
  "client": "client1",
  "request_id": "f7ad39e4-5b39-4293-b4ba-723c46872469",
  "op": "schedule:delete",
  "schedule": "1c28183b-837f-466d-84c5-42a6bcfcf428"
}
{
  "client": "client1",
  "request_id": "f7ad39e4-5b39-4293-b4ba-723c46872469",
  "result": {
    "success": true
  }
}

Discovery Management

Usage Topic Example Topic Name
Discovery request DiscoveryRequestTopic xrt/discovery/bacnet_ip_device_service/request
Discovery reply DiscoveryReplyTopic xrt/discovery/bacnet_ip_device_service/reply
Discovered devices DiscoveryTopic xrt/discovery/bacnet_ip_device_service/devices

Request operations

Read Discovery

Returns the current discovery and re-discovery modes and scheduled interval.

Operation: discovery:read

Request arguments: none

Reply: discovery mode (unavailable, enabled, disabled), interval

{
  "client":"client1",
  "request_id": "abb2fa4f-68b8-4129-9df9-801c63e1d05f",
  "op": "discovery:read"
}
{
  "client": "client1",
  "request_id": "abb2fa4f-68b8-4129-9df9-801c63e1d05f",
  "result": {
    "mode": "enabled",
    "interval": 0,
    "success": true
  }
}

Update Discovery

Changes discovery mode, re-discovery mode and scheduled interval.

Operation: discovery:update

Request arguments: boolean enable and interval (seconds)

Reply: boolean success status and optional error message

{
  "client":"client1",
  "request_id": "b2d4710e-a6dc-4102-a9f7-e67cdfbb9c27",
  "op": "discovery:update",
  "enable": true,
  "interval": 3600
}
{
  "client": "client1",
  "request_id": "b2d4710e-a6dc-4102-a9f7-e67cdfbb9c27",
  "result": {
    "success": true
  }
}

Trigger Discovery

Triggers an immediate device discovery. Discovered devices are published to the discovered devices topic.

Operation: discovery:trigger

Request arguments: none

Reply: boolean success status and optional error message

{
  "client":"client1",
  "request_id": "a40c10f6-8489-401a-ac5f-5bd9942e995c",
  "op": "discovery:trigger"
}
{
  "client": "client1",
  "request_id": "a40c10f6-8489-401a-ac5f-5bd9942e995c",
  "result": {
    "success": true
  }
}

API Usage Patterns

There are multiple usage patterns that can be achieved using the XRT message API.

Auto Registered Devices

Auto registration of new discovered devices can be enabled by setting the “AutoRegister” configuration property to true. The following sequence diagram show the sequence of messages exchanged to publish data from a newly discovered device.

AutoRegister

Manual Device Registration

ManualRegister

Back to top