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 objectseverity
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