Overview

This guide explains how to:

• Create and manage IoT Systems (devices or device collections) i.e Energy Management System
• Register and manage Components (sub-devices) i.e Smart Meters
• Monitor and control the System and its Components.
• Handle real-time state changes and errors.
• Use JSON for efficient data transfer, you can also use MsgPack(https://msgpack.org/) format with the corresponding msgpack topics.

Please go through the Introduction and Prerequisite sections before proceeding with the use-case. Here: Introduction Guide For MQTT Setup

System Management Workflow:

Let's create a use-case for system management using MQTT APIs. The following operations will be covered:

Real-Time Use Case: Smart Building Energy Management System

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.

1.System Initialization: Energy Management System

• Create a System in DRIVR:

  The building's energy management system is registered as a System. In this case, lets create a system with the name Energy Management System via DRIVR UI as mentioned in the prerequisite.

2. Update and Monitor System:

• Update fields for the System:

  Once a system is created you can update the fields using this PUB MQTT topic. The fields like description, name, connectionState and status etc. can be updated using the MQTT API.

  MQTT Topics:

  PUB drivr/v1/{slug}/input/system/{systemUuid}/json
  

  PUB drivr/v1/{slug}/input/system/{systemUuid}/msgpack
  

  Sample Json Example:

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

  Request:

  {
    "description": "This is an energy management system.",
    "name": "ESM-system",
    "status": "ACTIVATED",
    "connectionState": "CONNECTED"
  }
  

  Response:

  Topic: drivr/v1/company-example/input/system/792b6149-1daa-488f-b07a-f684503b0586/json QoS: 1
  {
    "description": "This is an energy management system.",
    "name": "ESM-system",
    "status": "ACTIVATED",
    "connectionState": "CONNECTED"
  }
  

• Monitor System:

  After creating the system, you can verify it using the SUB MQTT topic. The system will publish its initial configuration and status.

  MQTT Topics:

  SUB drivr/v1/{slug}/systems/{systemUuid}
  

  Sample Example:

  SUB drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586
  

  Response:

  Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586  QoS: 0 Retained
  {
    "uuid": "792b6149-1daa-488f-b07a-f684503b0586",
    "createdAt": "2025-04-15T08:46:14.998945",
    "updatedAt": "2025-04-15T08:52:12.620248",
    "code": "energy-management-system",
    "name": "ESM-system",
    "description": "This is an energy managment system.",
    "connectionState": "UNDEFINED",
    "connectionStateUpdatedAt": "2025-04-15T08:46:14.999275",
    "domainUuid": "7b6f629d-872b-48a0-9386-7c0ee61ceb0d",
    "ownerUuid": "3348037a-9f5d-425e-b593-11e6e7437b74",
    "status": "ACTIVATED",
    "metadata": {}
  }
  

• Monitor Error on System:

  If there are any errors for your request, you can monitor them by subscribing to the error MQTT topic for your system. All errors will be published there. Please subscribe to this topic before you make a request to DRIVR as messages are not retained for this topic.

  MQTT Topics:

  You can get the data in JSON or MsgPack format based on the request you have used for publishing your payload. Here, slug is domain unique identifier and systemUuid is the unique identifier of the system you created in the previous step.

  SUB drivr/v1/{slug}/input/system/{systemUuid}/json/error
  

  SUB drivr/v1/{slug}/input/system/{systemUuid}/msgpack/error
  

  Sample Json Example:

  Subscribe to Error topic:

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

  Error Request:

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

  {
    "connectionState" : "ErrorConnectionState"
  }
  

  Response on Error Topic:

  Topic: drivr/v1/company-example/input/system/792b6149-1daa-488f-b07a-f684503b0586/json/error  QoS: 0
  {
    "connectionState": [
      "Incorrect enum member ErrorConnectionState"
    ]
  }
  

• Monitor State/Status for a system:

  With this SUB MQTT topic, you can monitor the state of the system. Only status like ACTIVATED, DEACTIVATED, and ARCHIVED are allowed.

  MQTT Topics:

  SUB drivr/v1/{slug}/systems/{systemUuid}/state
  

  Sample Example:

  Request:

  SUB drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/state
  

  Response:

  Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/state  QoS: 0 Retained
  ACTIVATED
  

• Update Connection State for a System:

  • The system's connection state can be updated to one of the following predefined values: CONNECTED, DISCONNECTED, or UNDEFINED. This is an ENUM field, meaning only these specific values are allowed and must be provided in plain text format.
  • Use the PUB MQTT topic below to update the connection state of the system efficiently.

  MQTT Topics:

  PUB drivr/v1/{slug}/input/system/{systemUuid}/state/connection
  

  Sample Example:

  Request:

  PUB drivr/v1/company-example/input/system/792b6149-1daa-488f-b07a-f684503b0586/state/connection
  

    DISCONNECTED

  Response:

  Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/state/connection  QoS: 0
  DISCONNECTED
  

• Monitor Connection State for a system:

  With this SUB MQTT topic, you can monitor the connection state of the system.

  MQTT Topics:

  SUB drivr/v1/{slug}/systems/{systemUuid}/state/connection
  

  Sample Example:

  Request:

  SUB drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/state/connection
  

  Response:

  Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/state/connection  QoS: 0 Retained
  DISCONNECTED
  

• Monitor Connection State Errors for a System:

  If there are any errors for your request, you can monitor them by subscribing to the error MQTT topic for the connection state of your system. All errors will be published there. Please subscribe to this topic before you make a request to DRIVR as messages are not retained for this topic.

  MQTT Topics:

  SUB drivr/v1/{slug}/systems/{systemUuid}/state/connection/error
  

  Sample Example:

  Subscribe to Error topic:

  SUB drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/state/connection/error
  

  Error Request:

  PUB drivr/v1/company-example/input/system/792b6149-1daa-488f-b07a-f684503b0586/state/connection
  

    UNKNOWN

  Response on Error Topic:

  Topic: drivr/v1/company-example/input/system/792b6149-1daa-488f-b07a-f684503b0586/state/connection/error  QoS: 0
  {
    "connection_state": [
      "Incorrect enum member UNKNOWN"
    ]
  }
  

2. Register Components in System: Smart Meters

Prerequisite:

You need to create a componentModel before registering the components which acts as a template for the components you are going to register.

Create a Component Model:

Create a blueprint for all the smart meters components in DRIVR with ComponentModel. In this case, lets create a componentModel with name Smart Meter Model via DRIVR UI.

Go through the Component Model Creation guide to create a componentModel.

• Register Components:

  Devices like smart meters, HVAC controllers, and lighting systems are added as Components. In our example, lets go with Smart Meters as a component. The smart meters will be registered with the system using the PUB MQTT topic. The component will publish its configuration and state to the system.

  MQTT Topics:

  You can send the data in JSON or MsgPack format. Here, slug is domain unique identifier and systemUuid is the unique identifier of the system you created in the previous step. componentModelUuid will be the unique identifier of the componentModel you created in the previous step.

  PUB drivr/v1/{slug}/input/system/{systemUuid}/component/json
  

  PUB drivr/v1/{slug}/input/system/{systemUuid}/component/msgpack
  

  Sample Json Example:

  Request:

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

  {
    "componentModelUuid": "f2deb868-aec5-4976-91e0-262902f01d1e",
    "code": "smart-meter",
    "name": "Smart-Meter",
    "status": "ACTIVATED",
    "connectionState": "CONNECTED"
  }
  

  Response:

  Topic: drivr/v1/company-example/input/system/792b6149-1daa-488f-b07a-f684503b0586/component/json QoS: 1
  {
    "componentModelUuid": "f2deb868-aec5-4976-91e0-262902f01d1e",
    "code": "smart-meter",
    "name": "Smart-Meter",
    "status": "ACTIVATED",
    "connectionState": "CONNECTED"
  }
  

3. Component Monitor:

• Monitor all Component activities:

  • The component(smart meters) will publish their configuration and state to the system. The system will subscribe to the component's configuration updates. If you have more than 1 component, this endpoint will help you to subscribe to all the components under the system. You can use the # wildcard in the MQTT topic to subscribe to updates for all components within a system. This allows you to receive real-time notifications about the status, connection state, and metadata changes for every component under the specified system, making it efficient to monitor and manage multiple components efficiently.

    MQTT Topics:

    SUB drivr/v1/{slug}/systems/{systemUuid}/components/#/json
    

    SUB drivr/v1/{slug}/systems/{systemUuid}/components/#/msgpack
    

    Sample Example:

    Request:

    SUB drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/#
    

    Response:

    Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter  QoS: 0
    {
      "uuid": "6204964f-0636-4613-9875-eda244e1a1d9",
      "createdAt": "2025-04-15T13:01:44.387740",
      "updatedAt": "2025-04-15T13:01:44.396418",
      "code": "smart-meter",
      "name": "Smart-Meter",
      "systemUuid": "792b6149-1daa-488f-b07a-f684503b0586",
      "connectionState": "UNDEFINED",
      "connectionStateUpdatedAt": "2025-04-15T13:01:44.396118",
      "status": "ACTIVATED",
      "componentModel": {
        "uuid": "f2deb868-aec5-4976-91e0-262902f01d1e",
        "code": "smart-meter-model",
        "isConnective": true
      },
      "metadata": {}
    }
    

    Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter/state  QoS: 0 Retained
    ACTIVATED
    

    Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter/state/connection  QoS: 0 Retained
    UNDEFINED
    

For specific details on each component, you can use the componentCode in the topic.

• Monitor Component State/Status:

  • The component smart meters will publish their state to the system. The system will subscribe to the component's state updates.
  • We will use the componentCode to subscribe to the specific component which is smart-meter in this case.
  • Allowed states are ACTIVATED, DEACTIVATED, and ARCHIVED.

  MQTT Topics:

  SUB drivr/v1/{slug}/systems/{systemUuid}/components/{componentCode}/state
  

  Sample Example:

  Request:

  SUB drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter/state
  

  Response:

  Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter/state  QoS: 0 Retained
  ACTIVATED
  

• Monitor Component Connection State:

  • The component (smart meters) will publish their connection status to the system. The system will subscribe to the component's connection updates.
  • Allowed connection states are CONNECTED, DISCONNECTED, and UNDEFINED.

  MQTT Topics:

  SUB drivr/v1/{slug}/systems/{systemUuid}/components/{componentCode}/state/connection
  

  Sample Example:

  Request:

  SUB drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter/state/connection
  

  Response:

  Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter/state/connection  QoS: 0 Retained
  UNDEFINED
  

4. Monitor Component Error:

• Monitor Error for Component:

  • If there are any errors for your request, you can monitor them by subscribing to the error MQTT topic for your component. All errors will be published there. Please subscribe to this topic before you make a request to DRIVR as messages are not retained for this topic.

  MQTT Topics:

  SUB  drivr/v1/{slug}/input/system/{systemUuid}/component/json/error
  

  SUB  drivr/v1/{slug}/input/system/{systemUuid}/component/msgpack/error
  

  Sample Example:

  Request:

  SUB drivr/v1/company-example/input/system/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter/json/error
  

  Response:

  Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter/json/error  QoS: 0
    {
      "connectionState": [
        "Incorrect enum member ErrorConnectionState"
      ]
    }
  

5. Component Update:

• Update the Component:

  • You can update the values of an existing component using this PUB MQTT topic. This includes changing name, state, connectionState, and metadata etc.
  • You can also do mass creation and update of components using this PUB MQTT topic.

  MQTT Topics:

1. Update component with given componentCode for a component within a system:

   PUB  drivr/v1/{slug}/input/system/{systemUuid}/component/{componentCode}/json
   

   PUB drivr/v1/{slug}/input/system/{systemUuid}/component/{componentCode}/msgpack
   

   Sample Example:

   Request:

   PUB drivr/v1/company-example/input/system/792b6149-1daa-488f-b07a-f684503b0586/component/smart-meter/json
   

   {
     "name": "Smart-Meter-Updated"
   }
   

   Response:

   Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter  QoS: 0 Retained
   {
     "uuid": "6204964f-0636-4613-9875-eda244e1a1d9",
     "createdAt": "2025-04-15T13:01:44.387740",
     "updatedAt": "2025-05-06T14:29:49.445921",
     "code": "smart-meter",
     "name": "Smart-Meter-Updated",
     "systemUuid": "792b6149-1daa-488f-b07a-f684503b0586",
     "connectionState": "UNDEFINED",
     "connectionStateUpdatedAt": "2025-04-15T13:01:44.396118",
     "status": "ACTIVATED",
     "componentModel": {
       "uuid": "f2deb868-aec5-4976-91e0-262902f01d1e",
       "code": "smart-meter-model",
       "isConnective": true
     },
     "metadata": {}
   }
   

2. Update multiple components at the same time within a system using componentCode within payload:

   PUB drivr/v1/{slug}/input/system/{systemUuid}/component/json
   

   PUB drivr/v1/{slug}/input/system/{systemUuid}/component/msgpack
   

   Sample Example:

   Request:

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

   [
     {
       "code": "smart-meter",
       "name": "Smart-Meter-Updated"
     },
     {
       "code": "smart-meter-v2",
       "name": "Smart-Meter-v2-Updated"
     }
   ]
   

   Response:

   Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter  QoS: 0
   {
     "uuid": "6204964f-0636-4613-9875-eda244e1a1d9",
     "createdAt": "2025-04-15T13:01:44.387740",
     "updatedAt": "2025-05-07T08:39:45.034821",
     "code": "smart-meter",
     "name": "Smart-Meter-Updated",
     "systemUuid": "792b6149-1daa-488f-b07a-f684503b0586",
     "connectionState": "UNDEFINED",
     "connectionStateUpdatedAt": "2025-04-15T13:01:44.396118",
     "status": "ACTIVATED",
     "componentModel": {
       "uuid": "f2deb868-aec5-4976-91e0-262902f01d1e",
       "code": "smart-meter-model",
       "isConnective": true
     },
     "metadata": {}
   }
   

   Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter-v2  QoS: 0
   {
     "uuid": "6d6eb245-599e-42c6-b1a6-009805655fbd",
     "createdAt": "2025-05-07T08:32:15.566260",
     "updatedAt": "2025-05-07T08:39:45.082120",
     "code": "smart-meter-v2",
     "name": "Smart-Meter-v2-Updated",
     "systemUuid": "792b6149-1daa-488f-b07a-f684503b0586",
     "connectionState": "CONNECTED",
     "connectionStateUpdatedAt": "2025-05-07T08:32:15.571446",
     "status": "ACTIVATED",
     "componentModel": {
       "uuid": "f2deb868-aec5-4976-91e0-262902f01d1e",
       "code": "smart-meter-model",
       "isConnective": true
     },
     "metadata": {}
   }
   

• Update Component Connection State:

  The smart meters will publish their connection status to the system. The system will subscribe to the component's connection updates.

  MQTT Topics:

  PUB drivr/v1/{slug}/input/system/{systemUuid}/component/{componentCode}/json/state/connection
  

  Sample Example:

  Request:

  PUB drivr/v1/company-example/input/system/792b6149-1daa-488f-b07a-f684503b0586/component/smart-meter/json/state/connection
  

  DISCONNECTED
  

  Response:

  Topic: drivr/v1/company-example/input/system/792b6149-1daa-488f-b07a-f684503b0586/component/smart-meter/json/state/connection  QoS: 0
  DISCONNECTED
  

This guide should serve as a comprehensive resource for those looking to manage IoT systems and components using a real-time, structured approach.

Additional:

Metadata on Components

If you have any additional metadata to be added to the component, you can do that using the createMetadataType{DataType} mutation on DRIVR Graphiql APIs, you can create metadata of type STRING, INTEGER, FLOAT, BOOLEAN, DATE and DATETIME etc. This metadata can be used to store additional information about the component or any other supported entity.

This can also be created on system level.

Graphiql API:

Let's create metadata for Manufacturer and Version for the all the component using the Graphiql API.

Request:

mutation create_metadata_on_component_manufacturer {
  createMetadataTypeString(
    key: "Manufacturer",
    entityType: COMPONENT,
    default: "Not Defined"
  ) {
    key
    entityType
    dataType
    uuid
    unique
  }
}

Response:

{
  "data": {
    "createMetadataTypeString": {
      "key": "Manufacturer",
      "entityType": "COMPONENT",
      "dataType": "STRING",
      "uuid": "effc785a-6c82-46f2-a2d8-637f2c1a41d2",
      "unique": false
    }
  }
}

Request:

mutation create_metadata_on_component_version{
 createMetadataTypeString( 
   key:"Version",
   entityType: COMPONENT,
    unique:true
    ){
    key
    entityType
    dataType
    uuid
    unique
  }
}

Response:

{
  "data": {
    "createMetadataTypeString": {
      "key": "Version",
      "entityType": "COMPONENT",
      "dataType": "STRING",
      "uuid": "2bf0d4e7-37f5-471d-a69d-7e003b9f0685",
      "unique": true
    }
  }
}

Request:

query metadata{
  metadataTypes{
    items{
      uuid
      key
      dataType
      entityType
    }
  }
}

Response:

{
  "data": {
    "metadataTypes": {
      "items": [
        {
          "uuid": "effc785a-6c82-46f2-a2d8-637f2c1a41d2",
          "key": "Manufacturer",
          "dataType": "STRING",
          "entityType": "COMPONENT"
        },
        {
          "uuid": "2bf0d4e7-37f5-471d-a69d-7e003b9f0685",
          "key": "Version",
          "dataType": "STRING",
          "entityType": "COMPONENT"
        }
      ]
    }
  }
}

Once the metadata is created, you can use the PUB MQTT topic to use metadata fields in create, update component. Here you see the Version and Manufacturer metadata is used in the component update.

MQTT Topics:

PUB drivr/v1/company-example/input/system/792b6149-1daa-488f-b07a-f684503b0586/component/smart-meter/json

{
  "name": "Smart-Meter-Updated",
  "metadata": {
    "Version": "V2",
    "Manufacturer": "TM"
  }
}

Response: 

Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter QoS: 0
{
  "uuid": "6204964f-0636-4613-9875-eda244e1a1d9",
  "createdAt": "2025-04-15T13:01:44.387740",
  "updatedAt": "2025-05-06T14:29:49.445921",
  "code": "smart-meter",
  "name": "Smart-Meter-Updated",
  "systemUuid": "792b6149-1daa-488f-b07a-f684503b0586",
  "connectionState": "UNDEFINED",
  "connectionStateUpdatedAt": "2025-04-15T13:01:44.396118",
  "status": "ACTIVATED",
  "componentModel": {
    "uuid": "f2deb868-aec5-4976-91e0-262902f01d1e",
    "code": "smart-meter-model",
    "isConnective": true
  },
  "metadata": {
    "Version": "V2",
    "Manufacturer": "TM"
  }
}