Quick Start - DRIVR Docs

Create Events with MQTT APIs

Let's use the MQTT APIs to create an Event in DRIVR. For that we need to create an EventModel first with an Entity type of SYSTEM or COMPONENT, to which the event will be attached.

You can generate the device certificate and key pair using the MQTT Authentication Guide. They can be used to connect to the MQTT broker. Additionally, you need to create an eventModel and system in DRIVR before creating an event.

Use the previous steps to create an EventModel and System in DRIVR from the create eventModel & entity guide.

We have created all the prerequisites, now let's create an event using MQTT APIs. To create an Event in DRIVR, you need to publish a message to the appropriate topic with the required payload. To connect the MQTT client to the MQTT broker, use the following command. Ensure you have the client.key, certificate.pem, and ca.pem files generated in the earlier steps:

mqttx conn -h mqtt.drivr.cloud -l mqtts -p 8883 --key client.key --cert certificate.pem --ca ca.pem

Response: bash ✔ Connected

Refer to the MQTT docs for all the topics related to the event: https://docs.drivr.cloud/mqtt/system/event/

To create an event using MQTT, publish the following payload to this topic:

Look for the following topic in MQTT API documentation to create an event, using https://docs.drivr.cloud/mqtt/system/event/#operation-receive-publishSystemEventJson :

drivr/v1/{slug}/input/event/s/{systemUuid}/json

Replace {slug} and {systemUuid} with your specific domain slug and system UUID. In the payload, replace {eventModelUuid} with the uuid of the eventModel you have created earlier.

mqttx pub -t 'drivr/v1/{slug}/input/event/s/{systemUuid}/json' -h mqtt.drivr.cloud -l mqtts -p 8883 --key client.key --cert certificate.pem --ca ca.pem -f json -m '{
  "eventModelUuid": "{eventModelUuid}",
  "time": "2022-01-01T00:00:00Z",
  "endTime": "2022-01-01T01:00:00Z"
}'

Example:

mqttx pub -t 'drivr/v1/example-company/input/event/s/3c10f7cc-3205-46ac-99d9-71e31a192cb5/json'  -h mqtt.drivr.cloud -l mqtts -p 8883 --key client.key --cert certificate.pem --ca ca.pem -f json -m '{
  "eventModelUuid": "3ee13db9-cbbe-4724-96c6-ee9aad4c8d25",
  "time": "2025-05-01T00:00:00",
  "endTime": "2030-01-01T01:00:00"
}'

Response:

✔ Connected
✔ Message published

When you create an event using the MQTT API, the error topic is used to publish the error message should the event creation fail. In order to receive these responses, you need to subscribe to the error topic before publishing an event.

drivr/v1/{slug}/input/event/s/{systemUuid}/json/error

Open another terminal and subscribe to the error topic as follows:

mqttx sub -t 'drivr/v1/example-company/input/event/s/3c10f7cc-3205-46ac-99d9-71e31a192cb5/json/error'  -h mqtt.drivr.cloud -l mqtts -p 8883 --key client.key --cert certificate.pem --ca ca.pem 

✔ Connected

When you publish a payload with incorrect field entityCode:

mqttx pub -t 'drivr/v1/example-company/input/event/s/3c10f7cc-3205-46ac-99d9-71e31a192cb5/json'  -h mqtt.drivr.cloud -l mqtts -p 8883 --key client.key --cert certificate.pem --ca ca.pem -f json -m '{
  "eventModelUuid": "3ee13db9-cbbe-4724-96c6-ee9aad4c8d25", 
  "entityCode": "SystemCode1",
  "time": "2025-01-01T00:00:00Z",
  "endTime": "2030-01-01T01:00:00Z"
}'

Response: bash ✔ Connected ✔ Message published

You will get an error message on the error topic:

✔ Subscribed to drivr/v1/example-company/input/event/s/3c10f7cc-3205-46ac-99d9-71e31a192cb5/json/error
topic: drivr/v1/example-company/input/event/s/3c10f7cc-3205-46ac-99d9-71e31a192cb5/json/error, qos: 0
{"code": "SOME_DATA_incorrect", "message": "Some Events couldn't be imported/updated.", "stats": {"total": 1, "errors": 1, "imported": 0}, "errors": {"0": [{"code": "validation_error", "message": {"entityCode": ["Unknown field."]}}]}}

You can also use MQTTX desktop client to publish the event to the MQTT broker.

Event Error on MQTTX App

Acknowledging an Event signifies that it has been noticed or addressed by a User. Multiple Users can acknowledge an Event and acknowledgement will result into a message on the MQTT Broker. Let's acknowledge the event we have created earlier.

Let's subscribe to the event ack topic to get the notification when the event is acknowledged.

mqttx sub -t 'drivr/v1/{slug}/systems/{systemUuid}/events/{eventUuid}/ack'  -h mqtt.drivr.cloud -l mqtts -p 8883 --key client.key --cert certificate.pem --ca ca.pem

Lets acknowledge the event using the acknowledgeEvent mutation.

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

Response:

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

Check the topic where you have subscribed to get the acknowledgment message:

mqttx sub -t 'drivr/v1/example-company/systems/3c10f7cc-3205-46ac-99d9-71e31a192cb5/events/d509e860-dead-4f4b-b6c6-7ffd82750ac6/ack'  -h mqtt.drivr.cloud -l mqtts -p 8883 --key client.key --cert certificate.pem --ca ca.pem
✔ Connected
✔ Subscribed to drivr/v1/example-company/systems/3c10f7cc-3205-46ac-99d9-71e31a192cb5/events/d509e860-dead-4f4b-b6c6-7ffd82750ac6/ack

topic: drivr/v1/example-company/systems/3c10f7cc-3205-46ac-99d9-71e31a192cb5/events/d509e860-dead-4f4b-b6c6-7ffd82750ac6/ack, qos: 0
{"time": "2025-03-31T14:43:10.181113", "userUuid": "3348037a-9f5d-425e-b593-11e6e7437b74"}

With the MQTTX desktop client, you can publish the acknowledgment message to the MQTT broker.

Event Acknowledgment on MQTTX App

Now you know how to create an event and acknowledge it using MQTT APIs. You can also use the desktop client to establish a connection.

Create Events with MQTT APIs

For further information