System and Event Usecase with MQTT APIs

This guide explains how to:

  • Trigger and monitor Events for IoT systems EMS i.e Overload Events and components Smart Meter i.e Malfunction Events.
  • Handle real-time state changes and acknowledgments
  • Leverage JSON or MsgPack formats for optimized data transmission.

Please go through the Introduction Guide For MQTT Setup sections before proceeding with the use-case. To understand the Events better, please refer to the Event Guide documentation.

Before diving into the use case, ensure the following prerequisites are met:

  • System: Energy Management System (EMS)
  • Component: Smart Meter
  • Certificates for MQTT communication are generated and configured on the System EMS, so need to create again.

Define an EventModel: A blueprint ensuring all IoT events follow a consistent format with essential details for effective monitoring and management.

Let's create EventModel for system and component events with the help of DRIVR's Graphql API:

  • For our usecase, we will create an event model for a energy-overload events. The event model will be used to trigger events when energy overload is detected on EMS.

    Mutation Request to create EventModel on System 
    mutation event_model_on_system {
  createEventModel(
    code: "energy-overload-model",
    eventType: SINGLE_POINT,
    eventLevel: ERROR,
    entityType: SYSTEM
  ) {
    uuid
    code
    status
    eventType
    eventLevel
    entityType
  }
}

    Response: 

    {
  "data": {
    "createEventModel": {
      "uuid": "c867ee9d-52f1-4819-9bfc-b64d6321a04b",
      "code": "energy-overload-model",
      "status": "ACTIVATED",
      "eventType": "SINGLE_POINT",
      "eventLevel": "ERROR",
      "entityType": "SYSTEM"
    }
  }
}

  • For our usecase, we will create an event model for a smart-meter-malfunction-event. The event model will be used to trigger events when malfunction is detected on smart-meter.

    Mutation Request to create EventModel on Component 
    mutation event_model_component {
  createEventModel(
    code: "smart-meter-malfunction-event",
    eventType: RANGED,
    eventLevel: ERROR,
    entityType: COMPONENT
  ) {
    uuid
    code
    status
    eventType
    eventLevel
    entityType
  }
}

    Response: 

    {
  "data": {
    "createEventModel": {
      "uuid": "6b5e0830-6d7d-4871-9c1a-4a6e899aa5c7",
      "code": "smart-meter-malfunction-event",
      "status": "ACTIVATED",
      "eventType": "RANGED",
      "eventLevel": "ERROR",
      "entityType": "COMPONENT"
    }
  }
}

Let's create a use-case for event management using 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. Events are used to notify administrators about critical conditions, such as energy overloads or device malfunctions.

  • The energy management system triggers an event when an energy overload is detected.

    Note: The response will only be received if you have subscribed to the topic before publishing. Use the command below to subscribe to the topic.

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

    Request: 

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

    {
  "eventModelCode": "energy-overload-model",
  "time": "2025-05-09T13:28:42.611276+00:00"
}

    Response: 

    Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/events/a707aa3a-b44f-42e0-9ab8-b8efe13409c8 QoS: 0
{
  "uuid": "a707aa3a-b44f-42e0-9ab8-b8efe13409c8",
  "createdAt": "2025-05-09T13:28:42.658581",
  "updatedAt": "2025-05-09T13:28:42.658962",
  "entityUuid": "792b6149-1daa-488f-b07a-f684503b0586",
  "time": "2025-05-09T13:28:42.611276+00:00",
  "endTime": null,
  "status": null,
  "acknowledged": false,
  "eventModel": {
    "uuid": "c867ee9d-52f1-4819-9bfc-b64d6321a04b",
    "entityType": "SYSTEM",
    "eventType": "SINGLE_POINT",
    "eventLevel": "ERROR",
    "code": "energy-overload-model",
    "message": null
  },
  "metadata": {}
}

  • Subscribe to the event to monitor its details.

    SUB drivr/v1/{slug}/systems/{systemUuid}/events/{eventUuid}
    Sample Example:

    Request: 

    SUB drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/events/a707aa3a-b44f-42e0-9ab8-b8efe13409c8

    Response: 

    Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/events/a707aa3a-b44f-42e0-9ab8-b8efe13409c8 QoS: 0
{
  "uuid": "a707aa3a-b44f-42e0-9ab8-b8efe13409c8",
  "createdAt": "2025-05-09T13:28:42.658581",
  "updatedAt": "2025-05-09T13:28:42.658962",
  "entityUuid": "792b6149-1daa-488f-b07a-f684503b0586",
  "time": "2025-05-09T13:28:42.611276+00:00",
  "endTime": null,
  "status": null,
  "acknowledged": false,
  "eventModel": {
    "uuid": "c867ee9d-52f1-4819-9bfc-b64d6321a04b",
    "entityType": "SYSTEM",
    "eventType": "SINGLE_POINT",
    "eventLevel": "ERROR",
    "code": "energy-overload-model",
    "message": null
  },
  "metadata": {}
}

  • Track the state of the event (e.g., ACTIVE, RESOLVED).

    SUB drivr/v1/{slug}/systems/{systemUuid}/events/{eventUuid}/state
    Sample Example:

    Request: 

    SUB drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/events/a707aa3a-b44f-42e0-9ab8-b8efe13409c8/state

    Response: 

    ACTIVE

  • Acknowledge the system event to confirm it has been received.

    Note: Acknowledgment is only possible via DRIVR's GraphQL API or UI at the moment. So, you need to use the ackEvent mutation for acknowledgment via DRIVR's GraphQL API or DRIVR UI. Use the uuid of the event you want to acknowledge.

    mutation ackEvent {
  ackEvent(uuid: "d509e860-dead-4f4b-b6c6-7ffd82750ac6") {
    ok
  }
}

    Response:

    {
  "data": {
    "ackEvent": {
      "ok": true
    }
  }
}

    You can SUB subscribe to the acknowledgment topic to receive updates when the event is acknowledged. 

    SUB drivr/v1/{slug}/systems/{systemUuid}/events/{eventUuid}/ack
    Sample Example:

    Request: 

    SUB drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/events/a707aa3a-b44f-42e0-9ab8-b8efe13409c8/ack

    Response: 

    {
    "time": "2025-05-06T14:39:44.368252+00:00",
    "userUuid": "8718ca2a-5134-41bb-ab81-b65cec310ab9"
}

  • Subscribe to the error topic to monitor any errors that occur when an events is triggered on system.

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

    Subscribe to Error topic: 

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

    Error Request:

    Here eventModel is an incorrect field as we can only pass either code or uuid. 

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

    {
  "eventModel": "energy-overload-model",
  "time": "2025-05-09T13:28:42.611276+00:00"
}

    Response on Error Topic: 

    Topic: drivr/v1/company-example/input/event/s/792b6149-1daa-488f-b07a-f684503b0586/json/error QoS: 0
{
  "code": "SOME_DATA_INVALID",
  "message": "Some Events couldn't be imported/updated.",
  "stats": {
    "total": 1,
    "errors": 1,
    "imported": 0
  },
  "errors": {
    "0": [
      {
        "code": "validation_error",
        "message": {
          "eventModel": ["Unknown field."]
        }
      }
    ]
  }
}

  • A smart meter (component) triggers an event when it detects a malfunction.

    PUB drivr/v1/{slug}/input/event/c/{componentUuid}/json
    Sample Example:

    Request: 

    PUB drivr/v1/company-example/input/event/c/6d6eb245-599e-42c6-b1a6-009805655fbd/json

    {
  "eventModelUuid": "6b5e0830-6d7d-4871-9c1a-4a6e899aa5c7",
  "time": "2025-05-07T10:02:00Z"
}

    Response: 

    Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter-v2/events/5c39a4e0-9813-4e7e-90dd-ac621ae8c6dd QoS: 0

    {
  "uuid": "5c39a4e0-9813-4e7e-90dd-ac621ae8c6dd",
  "createdAt": "2025-05-12T08:50:57.901967",
  "updatedAt": "2025-05-12T08:50:57.902972",
  "entityUuid": "6d6eb245-599e-42c6-b1a6-009805655fbd",
  "time": "2025-05-12T08:50:57.847702+00:00",
  "endTime": null,
  "status": "ACTIVE",
  "acknowledged": false,
  "eventModel": {
    "uuid": "6b5e0830-6d7d-4871-9c1a-4a6e899aa5c7",
    "entityType": "COMPONENT",
    "eventType": "RANGED",
    "eventLevel": "ERROR",
    "code": "smart-meter-malfunction-event",
    "message": null
  },
  "metadata": {}
}

  • Subscribe to the event to monitor its details.

    SUB drivr/v1/{slug}/systems/{systemUuid}/components/{componentCode}/events/{eventUuid}
    Sample Example:

    Request: 

    SUB drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter-v2/events/5c39a4e0-9813-4e7e-90dd-ac621ae8c6dd QoS: 0

    Response: 

    Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter-v2/events/5c39a4e0-9813-4e7e-90dd-ac621ae8c6dd QoS: 0
  {
  "uuid": "5c39a4e0-9813-4e7e-90dd-ac621ae8c6dd",
  "createdAt": "2025-05-12T08:50:57.901967",
  "updatedAt": "2025-05-12T08:50:57.902972",
  "entityUuid": "6d6eb245-599e-42c6-b1a6-009805655fbd",
  "time": "2025-05-12T08:50:57.847702+00:00",
  "endTime": null,
  "status": "ACTIVE",
  "acknowledged": false,
  "eventModel": {
    "uuid": "6b5e0830-6d7d-4871-9c1a-4a6e899aa5c7",
    "entityType": "COMPONENT",
    "eventType": "RANGED",
    "eventLevel": "ERROR",
    "code": "smart-meter-malfunction-event",
    "message": null
  },
  "metadata": {}
  }

  • Track the state of the component event (e.g., ACTIVE, RESOLVED).

    SUB drivr/v1/{slug}/systems/{systemUuid}/components/{componentCode}/events/{eventUuid}/state
    Sample Example:

    Request: 

    SUB drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter-v2/events/5c39a4e0-9813-4e7e-90dd-ac621ae8c6dd/state QoS: 0

    Response: json ACTIVE

  • Acknowledge the component event to confirm it has been received.

    Note: Acknowledgment is only possible via DRIVR's GraphQL API or UI at the moment. So, you need to use the ackEvent mutation for acknowledgment via DRIVR's GraphQL API or DRIVR UI. Use the uuid of the event you want to acknowledge.

    mutation ackEventComponent {
  ackEvent(uuid: "5c39a4e0-9813-4e7e-90dd-ac621ae8c6dd") {
    ok
  }
}

    Response:

    {
  "data": {
    "ackEvent": {
      "ok": true
    }
  }
}

    You can SUB subscribe to the acknowledgment topic to receive updates when the event is acknowledged. 

    SUB drivr/v1/{slug}/systems/{systemUuid}/components/{componentCode}/events/{eventUuid}/ack
    Sample Example:

    Request: 

    SUB drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter-v2/events/123e4567-e89b-12d3-a456-426614174001/ack

    Response: 

    Topic: drivr/v1/company-example/systems/792b6149-1daa-488f-b07a-f684503b0586/components/smart-meter-v2/events/5c39a4e0-9813-4e7e-90dd-ac621ae8c6dd/ack QoS: 0
    {
    "time": "2025-05-12T08:50:57.902972",
    "userUuid": "3348037a-9f5d-425e-b593-11e6e7437b74"
    }

  • Subscribe to the error topic to monitor any errors that occur when an event is triggered on a component.

    SUB drivr/v1/{slug}/input/event/c/{componentUuid}/json/error
    Sample Example:

    Subscribe to Error topic: 

    SUB drivr/v1/company-example/input/event/c/6d6eb245-599e-42c6-b1a6-009805655fbd/json/error

    Error Request:

    Here eventModelCode has incorrect value which doesnot exist.

    PUB drivr/v1/company-example/input/event/c/6d6eb245-599e-42c6-b1a6-009805655fbd/json

    {
  "eventModelCode": "en",
  "time": "2025-05-09T13:28:42.611276+00:00"
}

    Response on Error Topic: 

    Topic: drivr/v1/company-example/input/event/c/6d6eb245-599e-42c6-b1a6-009805655fbd/json/error QoS: 0

  {
   "code": "SOME_DATA_INVALID",
   "message": "Some Events couldn't be imported/updated.",
    "stats": {
      "total": 1,
      "errors": 1,
      "imported": 0
      },
    "errors": {
      "0": [
        {
          "code": "event_model_does_not_exist",
          "message": "An event model with the code en does not exist"
        }]
      }
  }
→ Continue← BackUpdated at November 14, 2025