IoT: onboard devices, ingest readings, alerts and commands

#Purpose and scope

This chapter covers the IoT module: the device registry, the gateway ingest feed, telemetry, alert rules and alerts, commands to devices and firmware tracking. Telemetry is what devices report; alerts are raised when a rule is breached.

#Before you start

1. The IoT module installed for your tenant and the gateway-ingest feature enabled.
2. Permission to create devices (the IOT-ADMIN role is seeded for provisioning and device credentials). Issuing and cancelling commands, acknowledging, resolving and reopening alerts, and provisioning devices each have their own permission (iot.command.issue, iot.command.cancel, iot.alert.acknowledge, iot.alert.resolve, iot.alert.reopen, iot.device.provision).
3. A superuser account for the Gateway Ingest page, which is restricted to superusers.

#1. Device types and groups

1. Open Device types and create a type with a code, name and category (GPS, Environment, Meter, Energy, Access, Machine or Other).
2. Set the Expected interval (seconds) if devices of this type should be considered offline when silent. Leave it blank and they are never considered offline.
3. Optionally create Device groups so a single rule can cover a named set of devices.

#2. Onboard devices

1. Open Onboarding. The wizard has four steps: Identity, Binding, Credential, First reading.
2. Enter a code and name, pick a device type, and the external device id (the id the gateway sends; it defaults to the code). Optionally add the provider and the entity the device is bound to (asset, vehicle, warehouse, room and so on).
3. Choose Create device & generate credential. The credential is generated by the server and shown once; only its hash is stored. Copy it, tick I have saved the credential and continue.
4. The last step polls every 5 seconds and shows a tick when the first reading arrives.
5. For many devices, use the bulk import: Download template, fill the CSV, Validate (dry run), then Import & generate credentials. Download the credentials CSV straight away; credentials are shown once.

#3. Connect the gateway (Gateway Ingest)

1. Open Gateway ingest as a superuser. Other users see a notice that the page is restricted.
2. Check that Accepting telemetry is on. Turning it off stops ingestion without changing the token; readings are refused until it is turned on again.
3. Configure the gateway to POST to the ingest URL shown, with the tenant token in the X-IoT-Key header. If the device has a credential, also send it in X-IoT-Device-Key. The sample payload is on the page.
4. To revoke the token, choose Rotate token and confirm. Every gateway using the old token stops being able to post at once and must be updated with the new one.

#4. Watch what needs attention

1. Open Overview. It refreshes every 30 seconds and shows counts for active, offline and never-reported devices, devices without a credential, and command counts (pending, delivered awaiting acknowledgement, failed and unconfirmed in 7 days, expired in 24 hours), plus open alerts by severity.
2. Use the lists under it: Open alerts, Offline devices, Failed and unconfirmed commands, and the onboarding checklist of devices that have never reported.
3. Open a device to chart a metric over 6 hours to 90 days. Short windows show raw readings; long windows show hourly minimum, maximum and average. See also Telemetry for raw readings (read-only) and Device map for devices with a GPS fix.

#5. Alert rules

1. Open Rules and choose the rule type: Threshold (Min or Max value on a metric), Rate of change (delta threshold within a window in seconds) or Offline (applies to the device as a whole, so leave Metric blank).
2. Choose the scope: a specific device, a device type or a device group. A more specific scope narrows the rule.
3. Set the severity (Info, Warning, Critical) and the cooldown in minutes (default 30), which suppresses repeat alerts for the same device and rule.
4. Optionally list the users to notify (comma-separated user ids) and an Approval Record Type code. A breach then starts that record type’s approval workflow.

#6. Work alerts

1. Open Alerts. Each row shows its severity and status (open, acknowledged, resolved).
2. Choose Acknowledge to take ownership, then Resolve when fixed.
3. A resolved alert shows Reopen; you must give a reason.

#7. Commands to devices

1. Open Commands and choose Issue command. The device must be active, otherwise BSuit refuses with “Device is … and cannot accept commands”.
2. The command starts Pending with an expiry (default 15 minutes, between 1 minute and 24 hours). If the device is offline the screen warns that it expires undelivered if it does not reconnect in time.
3. When the device collects it the command becomes Sent; the device then reports success (Acked) or failure (Failed).
4. Use the status filter and the timeline on a row to follow it; retry or cancel from there.

#8. Firmware drift

Firmware records known versions per device type and one target version per type, with an optional vendor checksum kept for verification only. It reports drift (devices not on the target) but does not deliver updates; there is no over-the-air delivery.

#Housekeeping done for you

A background worker flags devices silent for longer than their type’s expected interval (raising an alert where an offline rule exists), evaluates rate-of-change rules, builds hourly rollups, expires stale commands, marks unacknowledged ones Unconfirmed, and trims raw telemetry past the retention window once its rollup exists. A retention of 0 days keeps everything.