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.