IoT Hub Events

IoT Hub Events Overview

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 object
  • severity is one of error, warn, info or debug

Event 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 event
  • severity: message severity, same value as in event topic
  • object-type: type of the object
  • object-id: id of the object
  • msg: event message

There 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.

How to generate an error and receive an event

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"
}

Understanding IoT Hub Events Messages

This section gathers example messages that can be received in the IoT Hub events.

Devices messages:

  • Malformed packet or network errors:
    • “cannot read MQTT header”
    • “cannot write MQTT packet”
    • “cannot decode MQTT header”
    • “failed to unpack message body”
  • Protocol errors:
    • “unknown MQTT message type: TYPE”: TYPE is not a valid MQTT message type.
    • “invalid MQTT QoS value: QOS”: Valid QoS values are 0, 1 or 2.
    • “empty topics are not authorized”: It’s not possible to publish or subscribe to an empty topic.
  • Security errors:
    • “invalid device certificate”: The device certificate is not valid. It may be because the certificate doesn’t match any device or certificate authority, or that the certificate is not the one expected for that device.
    • “mutual TLS authentication is required”: It’s not possible to connect a Deny Insecure device in an insecure mode (non mTLS).
    • “unauthorized topic TOPIC”: It’s not possible to publish or subscribe to a topic forbidden by a device filter rule.
    • “hub is not ready”: It’s not possible to connect to a Hub that is not ready.
    • “hub is deleted”: It’s not possible to connect/stay connected to a deleted Hub.
    • “hub is locked”: It’s not possible to connect/stay connected to a locked Hub.
    • “device is deleted”: It’s not possible to connect/stay connected using a deleted device.
    • “device is not enabled”: It’s not possible to connect/stay connected using a disabled device.
    • “hub product plan has changed”: The Hub product plan has been changed and requires a reconnection.
    • “device security has changed, requires authentication”: Changing the device security requires a reconnection if the security has been upgraded. If device is connected without TLS authentication and the security has been upgrade to Deny Insecure, it will be disconnected.
  • Custom Certificate Authority and Auto-Provisionning messages:
    • “certificate common name cannot be empty”: The device certificate is signed by the Hub Certificate Authority but its common name field is empty. In this case the object-id is unknown as the device was not found.
    • “could not identify device”: The device certificate correspond to a custom Certificate Authority but the device does not exists (and auto-provisioning is disabled). In this case the object-id is unknown as the device was not found.
    • “device was auto-provisioned”: A new device was created following a sucessful TLS authentication, the message will be of 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.
  • Product plan related errors:
    • “service level: “clean session” flag is mandatory to connect to a shared Hub”: It’s not possible keep track of the client state over connections when using a shared hub. A clean session must be used on a shared Hub.
    • “service level: publishing retained messages is forbidden on a shared Hub”: It’s not possible to publish retained messages when using a shared hub.
    • “service level: publishing QoS 2 messages is forbidden on a shared Hub”: It’s not possible to publish QoS 2 messages when using a shared hub.
    • “service level: subscribing with QoS 1-2 is forbidden on a shared Hub”: It’s not possible to subscribe using QoS 1-2 when using a shared hub.
    • “service level: message payload is too large”: See limitations for the maximum allowed messages payload size.

Routes messages:

  • S3 route errors:
    • "'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]
  • Database errors:
    • "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

Examples and tutorials

Discover the Cloud That Makes Sense