Hub Events represent devices and routes events or errors. They are reported in your Hub using a default topic prefix $SCW/events.
The event topic is built on the template $SCW/events/<severity>/<object-type>/<object-id>, where:
object-type is the type of the object concerned by the event (device or route),object-id is the id of the objectseverity is one of error, warn, info or debugEvent payload is a json string, similar to:
{
"time": "2020-03-24T09:02:12Z"
"severity": "error",
"object-type": "device",
"object-id": "my-device-id",
"msg": "unauthorized topic [foo/bar]",
"packet": "PUBLISH: dup: false qos: 0 retain: false rLength: 10",
}
Here are the different fields of an event JSON payload:
time: timestamp of the eventseverity: message severity, same value as in event topicobject-type: type of the objectobject-id: id of the objectmsg: event messageThere is also an optional field:
packet: summary of the MQTT packet that triggered this event (specific to device events)Note: Depending on the error, there might be other optional fields.
To demonstrate the use of Hub Events, here is a tutorial that will make you generate an error, and show you how to receive this error:
1 . First, we need a device to receive the hub event we want to generate. To do that, add a new insecure device to a Hub, called logger.
2 . In order to receive the hub event, we need to subscribe to all the errors: In a terminal, use the previously created device to subscribe to the $SCW/events/error/# topic: mosquitto_sub -h iot.fr-par.scw.cloud -p 1883 -i <logger-device-id> -t '$SCW/events/error/#'.
3 . Now, we want to generate an mTLS error. To do that, we will use a device configured to Deny Insecure connect, and try to connect with it. Create that second secured device, and call it secured device.
4 . With the device created, we can now trigger the error: In a second terminal, connect the secured device to your Hub, but without using any security: mosquitto_pub -h iot.fr-par.scw.cloud -i secured-device-id -t foo/bar -m 'This wont work'.
5 . In the first terminal, the logger device will then receive a message having a topic that looks like $SCW/events/error/device/<secured-device-id>, and following payload:
{
"time":"2020-01-17T15:01:29Z",
"severity": "error",
"object-type": "device",
"object-id": "secured-device-id",
"msg": "mutual TLS authentication is required",
"packet":"CONNECT: dup: false qos: 0 retain: false rLength: 12"
}
This section gathers example messages that can be received in the IoT Hub events.
Devices messages:
Deny Insecure device in an insecure mode (non mTLS).Deny Insecure, it will be disconnected.object-id is unknown as the device was not found.object-id is unknown as the device was not found.severity info, the object-id will be the one allocated to this new device. The message will also include the following keys:object-name: the device name taken from the client certificate common name.source-address: the IP address and port of the TLS connection that triggered the device creation.Routes messages:
"'BUCKET_NAME' s3 bucket write failed. Error HTTP_STATUS_CODE: ERROR_CODE (request-id: REQUEST_ID)": The route failed to write to the specified s3 bucket. BUCKET_NAME is the name of the bucket route attempt to write to, HTTP_STATUS_CODE and ERROR_CODE are standard [S3 error codes](https://docs.aws.amazon.com/AmazonS3/latest/API/ErrorResponses.html#ErrorCodeList]"failed to connect to database. Error ERRNO: ERRMSG": The route could not connect to your database. ERRNO and ERRMSG are respectively PostgreSQL standard error codes and messages. See PostgreSQL documentation"failed to prepare 'QUERY' query. Error ERRNO: ERRMSG": The query preparation failed (rejected by PostgreSQL). ERRNO and ERRMSG are respectively PostgreSQL standard error codes and messages. See PostgreSQL documentation"failed to execute query. Error ERRNO: ERRMSG": Query execution failed. You will find the payload assotiated to this query in the field named payload. ERRNO and ERRMSG are respectively PostgreSQL standard error codes and messages. See PostgreSQL documentation