System Datapoint & Setpoint Usecase with MQTT APIs

This guide explains how to:

  • Monitor Datapoints for real-time data updates on voltage.
  • Manage Setpoints for controlling the energy consumption of the system.
  • Handle acknowledgments and state changes.
  • Use JSON/MsgPack for efficient data transfer.

Please go through the Introduction Guide For MQTT Setup sections before proceeding with the use-case. Apart from systems and components, you have created services, characteristics, timestreams before you start with datapoints and setpoints.

Use the following to create service and characteristics:

You can use the DRVIR UI to create a Service and a Characteristic for your system.

  1. Let's create a service - electricity for our use case.

    Service Create Mutation 
    mutation service {
  createService(
    name: "Electricity Service",
    code: "electricity"
  ) {
    uuid
    name
    code
    status
  }
}

    Response:

    {
  "data": {
    "createService": {
      "uuid": "d6eb1c87-6407-47e1-86ae-e8a63d8241fd",
      "name": "Electricity Service",
      "code": "electricity",
      "status": "ACTIVATED"
    }
  }
}

  2. For a datapoint, the characteristicType must be set to MEASUREMENT, and the dataType should be STRING, which fits our example use case. Therefore, let's define a characteristic named voltage to be used for this datapoint.

    Characteristic Measurement Create Mutation 
    mutation characteristics {
  createCharacteristic(
    code: "voltage",
    name: "Voltage",
    characteristicType: MEASUREMENT,
    dataType: STRING
  ) {
    uuid
    code
    name
    characteristicType
    dataType
    status
  }
}

    Response: 

    {
  "data": {
    "createCharacteristic": {
      "uuid": "22200306-8ceb-476e-91df-6bb1a9fa8565",
      "code": "voltage",
      "name": "Voltage",
      "characteristicType": "MEASUREMENT",
      "dataType": "STRING",
      "status": "ACTIVATED"
    }
  }
}

  3. Additionally, you can also have energy consumption as a characteristic inside the electricity service which can be controlled by a user. For this, you would need to create a characteristic with a characteristicType of SETTING and a dataType of FLOAT. This characteristic can be used to control or configure energy consumption parameters in real-time.

    Characteristic Setting Create Mutation 
    mutation characteristicSetting {
  createCharacteristic(
    code: "energy-consumption",
    name: "Energy Consumption",
    characteristicType: SETTING,
    dataType: FLOAT
  ) {
    uuid
    code
    name
    characteristicType
    dataType
    status
  }
}

    Response: 

    {
  "data": {
    "createCharacteristic": {
      "uuid": "412baac3-56ba-4b76-b3cc-be04166c3196",
      "code": "energy-consumption",
      "name": "Energy Consumption",
      "characteristicType": "SETTING",
      "dataType": "FLOAT",
      "status": "ACTIVATED"
    }
  }
}

We need to link the service, characteristic and component to create a timestream.

You can use the DRVIR UI to link Service To ComponentModel and Characteristic To Service

  1. Add Characteristic Measurement To Service Mutation 
    mutation addCharacteristicToService {
  addCharacteristicToService(
    serviceCode: "electricity",
    characteristicCode: "voltage"
  ) {
    uuid
    status
  }
}

    Response:

    {
  "data": {
    "addCharacteristicToService": {
      "uuid": "7f57040c-21be-40d8-880e-9750b9f09869",
      "status": "ACTIVATED"
    }
  }
}
  2. Add Characteristic Setting To Service Mutation 
    mutation addCharacteristicToServiceSetpoint {
  addCharacteristicToService(
    serviceCode: "electricity",
    characteristicCode: "energy-consumption"
  ) {
    uuid
    status
  }
}

    Response:

    {
  "data": {
    "addCharacteristicToService": {
      "uuid": "a0230d8e-d5ac-4006-8c1b-4c96ebb77a07",
      "status": "ACTIVATED"
    }
  }
}
  3. Add Service To ComponentModel Mutation 
    mutation addServiceToComponentModel {
  addServiceToComponentModel(
    serviceCode: "electricity",
    componentModelCode: "smart-meter-model"
  ) {
    uuid
    status
  }
}

    Response:

    {
  "data": {
    "addServiceToComponentModel": {
      "uuid": "76694bee-1709-4da9-8440-cfcfa5cfb8f2",
      "status": "ACTIVATED"
    }
  }
}

  4. Let's query our timestream to see if all links are established correctly.

    Query Timestream With Where filter 
    query timestream {
  timeStreams(where: { service: { code: { _eq: "electricity" } } }) {
    items {
      uuid
      service {
        code
        uuid
      }
      component {
        code
        uuid
      }
      characteristic {
        uuid
        code
      }
    }
  }
}

    Response: 

    {
  "data": {
    "timeStreams": {
      "items": [
        {
          "uuid": "40277efc-c42d-51bb-80c1-68b84d58b430",
          "service": {
            "code": "electricity",
            "uuid": "d6eb1c87-6407-47e1-86ae-e8a63d8241fd"
          },
          "component": {
            "code": "smart-meter",
            "uuid": "6204964f-0636-4613-9875-eda244e1a1d9"
          },
          "characteristic": {
            "uuid": "412baac3-56ba-4b76-b3cc-be04166c3196",
            "code": "energy-consumption"
          }
        },
        {
          "uuid": "e5545147-7d6a-56c3-9911-d5fc9f2cc279",
          "service": {
            "code": "electricity",
            "uuid": "d6eb1c87-6407-47e1-86ae-e8a63d8241fd"
          },
          "component": {
            "code": "smart-meter",
            "uuid": "6204964f-0636-4613-9875-eda244e1a1d9"
          },
          "characteristic": {
            "uuid": "22200306-8ceb-476e-91df-6bb1a9fa8565",
            "code": "voltage"
          }
        }
      ]
    }
  }
}

Now, we have created a service, a characteristic and a timestream for our system.

Let's create a datapoint and a setpoint using the MQTT APIs. The following operations will be covered:

A smart building uses an IoT-based energy management system to monitor and control energy consumption in real-time. The system includes devices like smart meters, HVAC systems, lighting controllers, and occupancy sensors. Datapoints are used to monitor real-time data, while setpoints are used to control system and component behavior.

Within a energy management system, the voltage can be a datapoint that provides real-time updates on the electrical potential difference within the system (EMSs). Monitoring this datapoint ensures the system operates within safe and efficient parameters, enabling dynamic adjustments to maintain optimal performance and prevent potential issues.

Sending the voltage value (datapoint) to monitor the behavior of the energy management system(system). This datapoint is typically published by the smart-meter (component) or any other device.

  • Use componentCode, serviceCode, characteristicCode and value to publish datapoint.

    PUB drivr/v1/{slug}/input/dp/s/{systemUuid}/json
    Sample Example:

    Request: 

    PUB drivr/v1/company-example/input/dp/s/792b6149-1daa-488f-b07a-f684503b0586/json

    {
"componentCode": "smart-meter",
"serviceCode": "electricity",
"characteristicCode": "voltage",
"value": "24V"
}

    Response: 

    Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter/services/electricity/index/0/characteristics/voltage/dp QoS: 0
{
"timeStreamUuid": "e5545147-7d6a-56c3-9911-d5fc9f2cc279",
"time": "2025-05-12T12:22:44.355147+00:00",
"value": "24V"
}

    We can also use the timestreamUUID and a value to publish datapoints.

    Sample Example:

    Request: 

    PUB drivr/v1/company-example/input/dp/s/792b6149-1daa-488f-b07a-f684503b0586/json

    {
"timeStreamUuid": "e5545147-7d6a-56c3-9911-d5fc9f2cc279",
"value": "30V"
}

    Response: 

    Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter/services/electricity/index/0/characteristics/voltage/dp QoS: 0
{
"timeStreamUuid": "e5545147-7d6a-56c3-9911-d5fc9f2cc279",
"time": "2025-05-12T12:22:44.355147+00:00",
"value": "30V"
}

    Use the componentUuid, the serviceUuid, the characteristicUuid and a value to publish datapoint.

    Sample Example:

    Request: 

    PUB drivr/v1/company-example/input/dp/s/792b6149-1daa-488f-b07a-f684503b0586/json

    {
"componentUuid": "6204964f-0636-4613-9875-eda244e1a1d9",
"serviceUuid": "d6eb1c87-6407-47e1-86ae-e8a63d8241fd",
"characteristicUuid": "22200306-8ceb-476e-91df-6bb1a9fa8565",
"value": "40V"
}

    Response: 

    Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter/services/electricity/index/0/characteristics/voltage/dp QoS: 0
{
"timeStreamUuid": "e5545147-7d6a-56c3-9911-d5fc9f2cc279",
"time": "2025-05-12T12:28:06.052040+00:00",
"value": "40V"
}

  • Subscribe to the following topic to receive voltage value (datapoints) and monitor real-time data updates.

    SUB drivr/v1/{slug}/systems/{systemUuid}/components/{componentCode}/services/{serviceCode}/index/{serviceIndex}/characteristic/{characteristicCode}/dp
    Sample Example:

    Request:

    Use one of the above query to Publish the request.

    Response: 

    Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter/services/electricity/index/0/characteristics/voltage/dp QoS: 0
  {
  "timeStreamUuid": "e5545147-7d6a-56c3-9911-d5fc9f2cc279",
  "time": "2025-05-12T12:28:06.052040+00:00",
  "value": "40V" #based on request value might change
  }

  • When an error occure while creating a datapoint, that can be captured when you subscribe to the following topic. 

    SUB drivr/v1/{slug}/input/dp/s/{systemUuid}/json/error
    Sample Example:

    Subscribe to Error topic: 

    SUB drivr/v1/company-example/input/dp/s/792b6149-1daa-488f-b07a-f684503b0586/json/error

    Request with error:

    Create a datapoint with incorrect field characteristic instead of characteristicUuid or characteristicCode and monitor the subscribed error topic.

    PUB drivr/v1/company-example/input/dp/s/792b6149-1daa-488f-b07a-f684503b0586/json

    {
      "componentCode": "smart-meter",
      "serviceCode": "electricity",
      "characteristic": "voltage",
      "value": "24V"
  }

    Response on Error Topic: 

    Topic: drivr/v1/company-example/input/dp/s/792b6149-1daa-488f-b07a-f684503b0586/json/error QoS: 0

  {
      "code": "SOME_DATA_INVALID",
      "message": "Some datapoints couldn't be imported.",
      "errors": {
          "0": {
              "code": "TIME_STREAM_LOOKUP_FAILED",
              "message": "Not enough information available to lookup time stream."
          }
      },
      "stats": {
          "total": 1,
          "errors": 1,
          "imported": 0
      },
      "request_id": "2025-06-04T09:05:02.743275+00:00_TP8IOy6o"
  }

In a smart building energy management system, the energy consumption setpoint is used to control the energy usage of the building. For instance, during peak hours, the energy consumption setpoint can be adjusted to limit usage to 50 kWh to reduce costs, while during off-peak hours, it can be increased to 100 kWh to accommodate higher energy demands. This helps in optimizing energy efficiency and managing operational costs effectively.

Setting the energy consumption value (setpoint) to monitor and control the behavior of the energy management system (system). This setpoint is typically published by the user and is sent to the smart-meter or other device (component).

  • Publish a energy-consumption setpoint to control the smart-meter (component) behavior.

    PUB drivr/v1/{slug}/input/sp/s/{systemUuid}/json
    Sample Example:

    Request: 

    PUB drivr/v1/company-example/input/sp/s/792b6149-1daa-488f-b07a-f684503b0586/json

    {
"componentCode": "smart-meter",
"serviceCode": "electricity",
"characteristicCode": "energy-consumption",
"value": 45.2 #FLOAT TYPE 
}

    Response: 

    Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter/services/electricity/index/0/characteristics/energy-consumption/sp/e5aeb469c9 QoS: 0
{
"timeStreamUuid": "40277efc-c42d-51bb-80c1-68b84d58b430",
"time": "2025-05-12T13:27:07.518677+00:00",
"value": 45.2,
"receiptId": "e5aeb469c9"
}

    We can also use timestreamUUID and value to publish setpoint.

    Sample Example:

    Request: 

    PUB drivr/v1/company-example/input/sp/s/792b6149-1daa-488f-b07a-f684503b0586/json

    {
"timeStreamUuid": "40277efc-c42d-51bb-80c1-68b84d58b430",
"value": 50.5 #FLOAT TYPE 
}

    Response: 

    Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter/services/electricity/index/0/characteristics/energy-consumption/sp/e5aeb469c9 QoS: 0
{
"timeStreamUuid": "40277efc-c42d-51bb-80c1-68b84d58b430",
"time": "2025-05-12T13:27:07.518677+00:00",
"value": 50.5,
"receiptId": "e5aeb469c9"
}

    With componentUuid, serviceUuid, characteristicUuid and value to publish setpoint.

    Sample Example:

    Request: 

    PUB drivr/v1/company-example/input/sp/s/792b6149-1daa-488f-b07a-f684503b0586/json

    {
"componentUuid": "6204964f-0636-4613-9875-eda244e1a1d9",
"serviceUuid": "d6eb1c87-6407-47e1-86ae-e8a63d8241fd",
"characteristicUuid": "412baac3-56ba-4b76-b3cc-be04166c3196",
"value": 80.3
}

    Response: 

    Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter/services/electricity/index/0/characteristics/energy-consumption/sp/5d9817350c QoS: 0
{
"timeStreamUuid": "40277efc-c42d-51bb-80c1-68b84d58b430",
"time": "2025-05-12T13:29:25.130751+00:00",
"value": 80.3,
"receiptId": "5d9817350c"
}

  • If a device receives a setpoint/a request to adjust a setting or configuration it is able to respond with the receipt ID, state, and a message to DRIVR. This allows the System to inform the cloud if a sent setpoint was correctly processed and applied.

  • The following example will show to not accept a setpoint due to a value outside of a valid range for this setting.

    PUB drivr/v1/{slug}/input/sp/s/{systemUuid}/ack/json
    Sample Example:

    Request: 

    drivr/v1/company-example/input/sp/s/792b6149-1daa-488f-b07a-f684503b0586/ack/json

    {
"receiptId":"5d9817350c",
"state":"REJECTED",
"message":"Rejected as its out of valid range"
}

    Response: 

    Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter/services/electricity/index/0/characteristics/energy-consumption/sp/5d9817350c/message QoS: 0
{
"timeStreamUuid": "40277efc-c42d-51bb-80c1-68b84d58b430",
"time": "2025-05-12T13:44:48.009451+00:00",
"receiptId": "5d9817350c",
"message": "Rejected as its out of given range"
}

  • This state endpoint notifies the newly created setpoint state:

    SUB drivr/v1/{slug}/systems/{systemUuid}/components/{componentCode}/services/{serviceCode}/index/{serviceIndex}/characteristic/{characteristicCode}/sp/{receiptId}/state
    Sample Example:

    Request: 

    drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter/services/electricity/index/0/characteristics/energy-consumption/sp/5d9817350c/state

    Response:

    Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter/services/electricity/index/0/characteristics/energy-consumption/sp/5d9817350c/state QoS: 0
{
"timeStreamUuid": "40277efc-c42d-51bb-80c1-68b84d58b430",
"time": "2025-05-12T13:29:25.130751+00:00",
"receiptId": "5d9817350c",
"state": "CREATED"
}

    In case of acknowledgment for setpoint, the state will be REJECTED or ACCEPTED based on the acknowledgment. This allows the device to know if the acknowledgement sent to DRIVR was received.

    SUB drivr/v1/{slug}/systems/{systemUuid}/components/{componentCode}/services/{serviceCode}/index/{serviceIndex}/characteristic/{characteristicCode}/sp/{receiptId}/state
    Sample Example:

    Response

    Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter/services/electricity/index/0/characteristics/energy-consumption/sp/5d9817350c/state QoS: 0
{
"timeStreamUuid": "40277efc-c42d-51bb-80c1-68b84d58b430",
"time": "2025-05-12T13:44:48.009451+00:00",
"receiptId": "5d9817350c",
"state": "REJECTED"
}

  • Subscribe to the message of a setpoint.

    SUB drivr/v1/{slug}/systems/{systemUuid}/components/{componentCode}/services/{serviceCode}/index/{serviceIndex}/characteristic/{characteristicCode}/sp/{receiptId}/message
    Sample Example:

    Request:

    SUB drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter/services/electricity/index/0/characteristic/energy-consumption/sp/5d9817350c/message

    Response: 

    {
"receiptId": "5d9817350c",
"message": "Rejected as its out of given range",
"time": "2025-05-12T13:44:48.009451+00:00"
}

  • Subscribe to the response of a setpoint with all the Codes.

    SUB drivr/v1/{slug}/output/sp/s/{systemUuid}/c/json
    Sample Example:

    Use one of the above publish request from setpoint.

    SUB drivr/v1/company-example/output/sp/s/792b6149-1daa-488f-b07a-f684503b0586/c/json

    Response: 

    Topic: drivr/v1/company-example/output/sp/s/792b6149-1daa-488f-b07a-f684503b0586/c/json QoS: 0
{
"componentCode": "smart-meter",
"serviceCode": "electricity",
"characteristicCode": "energy-consumption",
"serviceIndex": 0,
"receiptId": "377224404b",
"value": 67, # value may change based on the request
"time": "2025-05-12T13:53:53.094997+00:00"
}

    Subscribe to the response of a setpoint with UUID.

    SUB drivr/v1/{slug}/output/sp/s/{systemUuid}/u/json
    Sample Example:

    Use one of the above publish request from setpoint.

    SUB drivr/v1/company-example/output/sp/s/792b6149-1daa-488f-b07a-f684503b0586/u/json

    Response: 

    Topic: drivr/v1/company-example/output/sp/s/792b6149-1daa-488f-b07a-f684503b0586/u/json QoS: 0
    {
    "componentUuid": "6204964f-0636-4613-9875-eda244e1a1d9",
    "serviceUuid": "d6eb1c87-6407-47e1-86ae-e8a63d8241fd",
    "characteristicUuid": "412baac3-56ba-4b76-b3cc-be04166c3196",
    "serviceIndex": 0,
    "receiptId": "377224404b",
    "value": 67, # value may change based on the request
    "time": "2025-05-12T13:53:53.094997+00:00"
    }

  • When an error occure while creating a Setpoint, that can be captured when you subscribe to the following topic. 

    SUB drivr/v1/{slug}/input/sp/s/{systemUuid}/json/error
    Sample Example:

    Make sure to subscribe to : 

    SUB drivr/v1/company-example/input/sp/s/792b6149-1daa-488f-b07a-f684503b0586/json/error

    Request:

    Create a setpoint with incorrect characteristic_type of MEASUREMENT and monitor the subscribed error topic.

    PUB drivr/v1/company-example/input/sp/s/792b6149-1daa-488f-b07a-f684503b0586/json

    {
      "componentCode": "smart-meter",
      "serviceCode": "electricity",
      "characteristicCode": "voltage", # MEASUREMENT TYPE
      "value": "24V"
  }

    Response: 

    Topic: drivr/v1/company-example/input/sp/s/792b6149-1daa-488f-b07a-f684503b0586/json/error QoS: 0
{
    "code": "SOME_DATA_INVALID",
    "message": "Some setpoints couldn't be imported.",
    "errors": {
        "0": {
            "code": "INVALID_CHARACTERISTIC_TYPE",
            "message": "Time stream has an invalid characteristic type for setpoint."
        }
    },
    "stats": {
        "total": 1,
        "errors": 1,
        "imported": 0
    },
    "request_id": "2025-06-04T09:16:27.965157+00:00_3uJ1S3D0"
}

  • When an error occure while acknowledging a Setpoint, that can be captured when you subscribe to the following topic. 

    SUB drivr/v1/{slug}/input/sp/s/{systemUuid}/ack/json/error
    Sample Example:

    Subscribe to Error Topic:

    SUB drivr/v1/company-example/input/sp/s/792b6149-1daa-488f-b07a-f684503b0586/ack/json/error

    Request with error:

    Acknowledge a setpoint with incorrect receieptID and monitor the subscribed error topic.

    PUB drivr/v1/company-example/input/sp/s/792b6149-1daa-488f-b07a-f684503b0586/ack/json/error

    {
     "receiptId":"5d98173eeeeeec",
     "state":"REJECTED",
     "message":"Rejected as its out of valid range"
  }

    Response on Error Topic: 

    Topic: drivr/v1/company-example/input/sp/s/792b6149-1daa-488f-b07a-f684503b0586/ack/json/error QoS: 0

{
    "code": "SOME_DATA_INVALID",
    "message": "Some setpoints couldn't be imported.",
    "errors": {
        "5d98173eeeeeec": {
            "code": "SOME_DATA_INVALID",
            "message": {
                "does_not_exist": "A time stream with the provided information does not exist or has an invalid status",
                "receipt_not_exist": "The receipt_id is either expired or does not exist"
            }
        }
    },
    "stats": {
        "total": 1,
        "errors": 1,
        "imported": 0
    },
    "request_id": "2025-06-04T09:24:40.103042+00:00_2cqvUVX1"
}

  • Use datapoints to monitor real-time data updates for systems and components.
  • Use setpoints to control system and component behavior effectively.
  • Ensure proper error handling by subscribing to error topics for both datapoints and setpoints.
→ Continue← BackUpdated at November 14, 2025