IoT Hub Events

IoT Hub Events Overview

Hub Events represent devices and routes events or errors. They are reported on your Hub using a default topic prefix $SCW/events.

Event topic is like $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",
}

JSON fields are:

• 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

Optional field:

• packet: digest of the MQTT packet that triggered this event (specific to device events)

Some other optional fields are available to specific errors.

In the following example, we will:

1 . Add a new insecure device to your Hub, called logger 2 . In a terminal, use that device to subscribe to $SCW/events/error/# topic: mosquitto_sub -h iot.fr-par.scw.cloud -p 1883 -i <logger-device-id> -t '$SCW/events/error/#' 3 . Create a second secured device, called secured device 4 . In a second terminal, connect secured device to your Hub, but in insecured mode: mosquitto_pub -h iot.fr-par.scw.cloud -i secured-device-id -t foo/bar -m 'This wont work' 5 . First logger device will then receive a message with topic $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 you could receive 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”: you cannot publish or subscribe to an empty topic
• Security errors:
  • “invalid device certificate”: device certificate is not valid
  • “mutual TLS authentication is required”: you try to connect a secured-only device in insecure mode
  • “unauthorized topic TOPIC”: the topic you want to publish in or subscribe to is forbidden by a device filter rule
  • “hub is not ready”: the hub you are connecting or are already connected to is not ready
  • “hub is deleted”: the hub you are connecting or are already connected is deleted
  • “hub is locked”: the hub you are connecting or are already connected to is locked
  • “device is deleted”: you cannot connect with a deleted device
  • “device is not enabled”: you cannot connect with a disabled device
  • “hub product plan has changed”: hub plan change requires a reconnection
  • “device security has changed, requires authentication”: device security change requires a reconnection, if device is connected without TLS authentication
• Product plan related errors:
  • “service level: “clean session” flag is mandatory to connect to a shared Hub”: your Hub’s plan does not allow clean session
  • “service level: publishing retained messages is forbidden on a shared Hub”: your Hub’s plan does not allow retain messages
  • “service level: publishing QoS 2 messages is forbidden on a shared Hub”: your Hub’s plan does not allow publishing of QoS 2 messages
  • “service level: subscribing with QoS 1-2 is forbidden on a shared Hub”: your Hub’s plan does not allow subscribing to Qos 1 and 2 messages
  • “service level: message payload is too large”: see limitations for 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)”: BUCKET_NAME is the name of the bucket route attempt to write, 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”; Route cannot connect to your database. ERRNO and ERRMSG are respectively PostgreSQL standard error code and message, as listed on PostgreSQL documentation
  • “failed to prepare ‘QUERY’ query. Error ERRNO: ERRMSG”: Preparing query failed (rejected by PostgreSQL). ERRNO and ERRMSG are respectively PostgreSQL standard error codes, are listed on 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, are listed on PostgreSQL documentation

Examples and tutorials

• How to use IoT API with curl: IoT Hub Events