Overview
Device Events allows devices to notify the server of low-recurring important events that might help the End Customers better operate and trouble-shoot their devices. While events are queryable via a log, they do not generate an Incident that will be pushed to the End Customer.
Sample events:
- Printer tray opened
- Power surge detected
Limitations
Unlike Telemetry Messages which are used to synchronize the Device's internal state with the server. Events are one-off messages that should be sent only when an unusual event happens.
Events are limited to 100 events per device per day.
To handle reporting of events happening at very high frequency during a period, it is suggested to send those type of events on 1 minute (or similar boundary).
Example
To track multiple, short power surges, the firmware should hold a counter of total power surge time. The firmware should check once a minute (or similar) if the value of the counter is positive and if so zero it and send an event "Power surge" with "int_key_1" set to the counter.
This will allow to track power surges without overloading the events log.
Event Structure
Events are single messages that must contain a name and category and optionally include additional parameters:
| Field | Required | |
|---|---|---|
| name | Yes | Unique name for each event type |
| category | Yes | Allow grouping of events |
| int_key_1 | No | Optional integer parameter Example: Power surge duration in ms |
| int_key_2 | No | Optional integer parameter |
| str_key_1 | No | Optional string (max 255 characters) |
| str_key_2 | No | Optional string (max 255 characters) |
| timestamp | Yes | Timestamp of the event's occurrence |