Overview
Device Events let a Device notify the server of low-frequency, noteworthy occurrences that help End Customers operate and troubleshoot their Devices. Events are stored in a queryable log, but — unlike Rule-driven Incidents — they do not push a notification to the End Customer.
Examples:
- Printer tray opened.
- Power surge detected.
Limitations
Unlike Telemetry Messages, which continuously sync the Device's internal state with the server, Events are one-off messages reserved for unusual occurrences.
Events are capped at 100 per Device per day.
For events that occur at very high frequency during short bursts, batch them into a single Event on a fixed window (one minute is a good default).
Example
To track multiple short power surges, the firmware keeps a running counter of total power-surge time. Once a minute, if the counter is positive, the firmware emits a single Power surge Event with int_key_1 set to the counter and resets it.
This pattern captures the surge activity without overloading the Event 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 |