Events and commands
The events that move a Device (a Hub or a Module) between its statuses, and the commands a user can send. This page is a reference: for how the statuses fit together, with diagrams, see Device lifecycle.
- An event is a fact: it already happened. "Device Paired" means the Device is now Paired.
- A command is a request: it can be refused. "Pair Device" asks for a Device to be paired, and is refused if that isn't allowed.
A command that succeeds leads to an event. For example, the Pair Device command leads to Pairing Started, and later Device Paired or Pairing Failed.
All names on this page are (proposed): they aren't part of the Glossary yet, and may change before the API is built.
Events
Grouped by the Device Status field they change. The Rules column points to the lifecycle rules the event follows.
Pairing Status
See Pairing Status in the lifecycle.
| Event | Changes | Raised by | Rules |
|---|---|---|---|
| Device Detected | Pairing → Unpaired | Hub software (Module) or API (Hub) | 12, 13 |
| Pairing Started | Pairing → Pairing | API, after the Pair Device command | 3 |
| Device Paired | Pairing → Paired; Connection starts at Connecting | Hub software | 1, 2 |
| Pairing Failed | Pairing → Unpaired | Hub software | – |
| Device Dismissed | Leaves the lifecycle | API, after the Dismiss Device command | – |
| Device Removed | Leaves the lifecycle | API, after the Remove Device command | 8 |
Connection Status
See Connection Status in the lifecycle.
| Event | Changes | Raised by | Rules |
|---|---|---|---|
| Device Connected | Connection → Connected | Hub software or API | – |
| Device Went Stale | Connection → Stale | Staleness Policy (Telemetry) | 6 |
| Reading Recorded | Connection Stale → Connected | Telemetry | 6 |
| Device Disconnected | Connection → Disconnected | API (link lost) or Hub software (Module unplugged) | 4, 5 |
| Connection Timed Out | Connection → Disconnected | API | – |
| Reconnect Started | Connection → Connecting | Hub software or API | 4 |
Fault
See Fault in the lifecycle.
| Event | Changes | Raised by | Rules |
|---|---|---|---|
| Fault Raised / Fault Cleared | Adds or clears one Fault Code | Hub software (the Device reports it) | 7, 11 |
Hub placement
See Hub placement in the lifecycle.
| Event | Changes | Raised by | Rules |
|---|---|---|---|
| Hub Placed | The Hub's Space | API, after the Place Hub command | – |
Commands
| Command | Who sends it | Refused when | Leads to | Rules |
|---|---|---|---|---|
| Pair Device | User | The Device isn't Unpaired, or it's a Module whose Hub isn't Paired | Pairing Started | 3 |
| Dismiss Device | User | The Device isn't Unpaired | Device Dismissed | – |
| Remove Device | User | The Device isn't Paired | Device Removed | 8, 10 |
| Place Hub | User | The Hub isn't Paired, or the Space is in a Site the user doesn't own | Hub Placed | – |
Only a Site's owner can send these commands for its Devices. Accounts the Site is shared with can only view it.
Related
- Device lifecycle: the statuses, the diagrams and the rules.
- Data model: what a Device, a Hub and a Module are, and the rules the diagrams can't show.
- Glossary: every term used on this page.