Device Events

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:

FieldRequired
nameYesUnique name for each event type
categoryYesAllow grouping of events
int_key_1NoOptional integer parameter
Example: Power surge duration in ms
int_key_2NoOptional integer parameter
str_key_1NoOptional string (max 255 characters)
str_key_2NoOptional string (max 255 characters)
timestampYesTimestamp of the event's occurrence