Activity events
The API emits diagnostic events on a web socket. This is useful when debugging and diagnosing while developing the firmware.
Events are not persisted in the API; they are delivered on a best-effort basiss so they should not be part of a production system. The web socket is authenticated in the same fashion as the upstream message websocket.
The follwing events might be emitted by the service:
| Event | Description |
|---|---|
| imeiMismatch | An IMEI mis-configuration is detected on a device that is trying to connect. This typically happen if you configure both IMSI and IMEI on a device and move the SIM card to a new device. Clear the IMSI field from the old device to fix the error. |
| imsiMismatch | An IMSI mis-configuraiton is detected on a device that is trying to connect. This typically happens if you switch the SIM card on a device and attempts to reconnect. Clear the IMSI field or replace it with the new value. |
| ciotConnect | A device has authenticated on the mobile network. When it connects to the network it is online but has not attempted to connect to Span yet. |
| clientConnected | A device has connected to Span, either via the UDP interface, the CoAP interfaces or the DTLS interface |
| clientDisconnected | A device has disconnected from Span. This event typically only appears for devices that connect via the Internet |
| upstreamMessage | A device has sent a message to Span, either via the Internet or the mobile network |
| downstreamMessage | A message is sent to a device |
| firmwareRequested | A device has requested to download a firmwware image |
| firmwareCheck | A device has reported its firmware version |
| firmwareUpdateRequired | Span has detected that the device needs a new firmware version |
| firmwareCurrent | The device has reported its version and it’s up to date |
| firmwareStateChange | The firmware state field has changed. This is emitted multiple times while the device is updating its firmware |
| blobUpload | A device has uploaded a new blob |
| deviceCreated | A device is created via the API |
| deviceUpdated | A device is updated via the API |
| deviceRemoved | A device is removed via the API |
| deviceMoved | A device is moved from one collection to another |
| gatewayConnected | A gateway has connected to the gateway API endpoint |
| gatewayDisconnected | A gateway has disconnected from the gateway API endpoint |
| gatewayDeviceUpdate | A gateway has received device updates |
| gatewayUpstreamMessage | A message is sent from a device via a gateway |
| gatewayDownstreamMessage | A message is sent to a device via a gateway |
| gatewayConfigUpdate | A gateway has received a configuration update |
| gatewayCommError | There was an error communicating with a gateway. The gateway might have disconnected abruptly or there’s some kind of network error |
Event structure
The events are returned as JSON objects, one object per line. A typical session might look like this:
{"collectionId":"17dj5j4ce8bkci","data":{"id":"certificate"},"deviceId":"17kl14hm46h4c2","event":"clientConnected","time":"2024-04-25 20:23:36"}
{"collectionId":"17dj5j4ce8bkci","data":{"bytes":"9","transport":"unspecified"},"deviceId":"17kl14hm46h4c2","event":"upstreamMessage","time":"2024-04-25 20:23:36"}
{"collectionId":"17dj5j4ce8bkci","deviceId":"17kl14hm46h4c2","event":"clientDisconnected","time":"2024-04-25 20:23:37"}
The data object contains relevant metadata about the event and varies depending on the event type.