alerts

Reference·Audience: API consumer·Use: interpret the reader's structured alert / notification events

Overview

alerts is a device-emitted event that delivers structured, categorized alert information — the reader publishes it autonomously when a monitored condition changes state or crosses a threshold; no command triggers it. Each event is a fixed envelope (type, timestamp, state, id, priority) plus a category-specific alertDetails body selected by id. It is read-only telemetry and carries no credentials.

The same envelope carries two message classes, distinguished by type:

• ALERT — an autonomous monitoring alert (battery, power, network).
• NOTIFICATION — a command side-effect: FILE_DOWNLOAD (see install_certificate) and the FIRMWARE_UPDATE start (see set_os).

This page documents the full envelope and all seven alertDetails branch keys. config_events toggles (battery, power, network, firmwareUpdate, fileDownload) govern which alerts publish.

The id enum has five categories, all emitted on current V1.1 firmware: BATTERY, POWER, NETWORK_EVENT, FIRMWARE_UPDATE, and FILE_DOWNLOAD. The schema also declares a temperatureInfo branch, but there is no TEMPERATURE id and no temperature alert is emitted on current firmware. See Events.

Details

Property	Value
Event Type	Alert / notification (structured, categorized)
Trigger	State change / threshold (autonomous, on a monitored condition change or threshold crossing)
Enabled By	config_events with per-category eventConfiguration flags (battery, power, network, firmwareUpdate, fileDownload), applied on reboot
Applies To	Endpoint: Management (MGMT). Reader: RFD40 series, RFD90 series
Credentials	None (read-only telemetry, nothing to mask)
Interaction Pattern	Publish / Subscribe (device-emitted, unsolicited; no request/response, no response.code)
Related	heartBeatEVT, dataEVT, mqttConnEVT

When to Use

Subscribe to alerts when you want the reader to tell you about a monitored condition rather than asking for it — there is no command that returns this data on demand (no polling twin). Reach for it when you need to:

• React to device-health changes as they happen — battery state and health (BATTERY), power-source and power-mode transitions (POWER), and network interface connect/disconnect (NETWORK_EVENT).
• Track long-running command side-effects — the FIRMWARE_UPDATE stream during a set_os flash (a type: NOTIFICATION start, then in-progress notifications) and the FILE_DOWNLOAD result during an install_certificate transfer (type: NOTIFICATION), all on this same envelope.
• Triage by severity — the priority field (CRITICAL … LOW) lets you route alerts without inspecting each branch body.

Enable only the categories you consume with config_events — a disabled category never publishes, so leaving one off is how you silence it. For a periodic health snapshot rather than change-driven alerts, use heartBeatEVT.

Topic Mapping

alerts is device-emitted and flows on the management event topic — it has no cmnd/resp topics because no command produces it.

Message	Direction	Topic	Note
Event	Reader → App	<tenantId>/MGMT/clients/event/<serial>	The same event topic that carries heartBeatEVT and NOTIFICATION-type events.

Topics follow the pattern <tenantId>/<topic>/<serial> — the tenant id assigned to you at provisioning (a slot you fill in, never a literal), the base topic you configure on the endpoint, and the reader's serial number, which the reader appends itself in its model-prefixed form (for example RFD40-212735201D0053). App → Reader means your app publishes and the reader subscribes; Reader → App means the reader publishes and your app subscribes.

See Topics and Channels.

Key Fields

• type (event) — message class: ALERT (autonomous monitoring alert), NOTIFICATION (command side-effect), or the reserved EVENT. Route on this to separate alerts from notifications.
• timestamp (event) — ISO-8601 (format: date-time) instant the alert was generated.
• state (event) — SET (condition active/asserted), CLEAR (resolved), or ONESHOT (one-time, no matching CLEAR). Pair with id to track a condition's lifecycle.
• id (event) — the alert category (BATTERY, POWER, NETWORK_EVENT, FIRMWARE_UPDATE, FILE_DOWNLOAD); selects which alertDetails branch is populated.
• priority (event) — severity, CRITICAL / HIGH / LOW, for triage without inspecting the branch body.
• alertDetails (event) — the category-specific body (seven declared branch keys); exactly one branch is populated, matching id. Optional — not in the envelope required set.
• config_events category toggles (request) — the emission gate: the per-category eventConfiguration flags (battery, power, network, firmwareUpdate, fileDownload) set with config_events govern whether each id publishes at all. A disabled category is silent.

Event Payload

The envelope (type, timestamp, state, id, priority) is always present and required; alertDetails is optional and carries exactly one branch matching id. Pick an alert category below — the Example and Schema update together to show that category's alertDetails branch. Use the Schema tab for the field reference and the Example tab for the live payload.

Alert categoryBattery alertPower alertNetwork alert for WiFiNetwork alert for ethernetFirmware update alertFile download alertFile saved alertBattery alertPower alertNetwork alert for WiFiNetwork alert for ethernetFirmware update alertFile download alertFile saved alert

Example

Event payload

Example: BATTERY (live)

{

"type": "ALERT",

"timestamp": "2026-04-29T12:33:34.279Z",

"state": "ONESHOT",

"id": "BATTERY",

"priority": "LOW",

"alertDetails": {

"batteryAlert": {

"status": "CHARGING",

"stateOfHealth": "GOOD",

"chargePercentage": 100

}

}

}

Schema

Event payload

* required— not applicableColored badge = JSON type

#	Field	Type	Enum / Units	Example	Description
1	type*	enum	EVENTNOTIFICATIONALERT	ALERT	Message class. ALERT = autonomous monitoring alert; NOTIFICATION = command side-effect (file download, firmware-update start); EVENT is reserved (not observed). See Event Semantics.
2	timestamp*	string	date-time	2026-06-17T10:16:34.793Z	ISO-8601 time the alert was generated (format: date-time).
3	state*	enum	SETCLEARONESHOT	ONESHOT	SET = condition active/asserted; CLEAR = resolved; ONESHOT = one-time (no matching CLEAR).
4	id*	enum	BATTERYFILE_DOWNLOADFIRMWARE_UPDATENETWORK_EVENTPOWER	BATTERY	Alert category — selects the populated alertDetails branch. There is no TEMPERATURE value, although alertDetails declares a temperatureInfo branch (see Event Semantics).
5	priority*	enum	CRITICALHIGHLOW	CRITICAL	Severity of the alert.
6	alertDetails	object	—	—	Category-specific body — an object that declares seven branch keys. Optional — not in the envelope required set. Exactly one branch is populated, matching id — here batteryAlert.
7	fwUpdateStatus, nesting level 2	object	—	—	Populated when id = FIRMWARE_UPDATE.
8	updateStatus*, nesting level 3	enum	Starting FW updateFW update successupdatingfailedskipping	FW update success	Current firmware-update status, as opaque display text. Values known to occur include Starting FW update, FW update success, updating, failed and skipping, but the reader also sends free-form sentences. Test only for equality with FW update success.
9	overallProgress, nesting level 3	number	—	20	Percent of the update completed. Optional — absent on the start notification; present on the in-progress events that follow (see set_os). It is the value to branch on while an update runs, per Known Device Deviations from the Schema.
10	stage, nesting level 3	string	—	updating scanner fw	Individual image-update step / description. Optional, and it may be absent from every event of an update — the schema declares it (with the example updating scanner fw), but it appeared on no event of the one update recorded under Known Device Deviations from the Schema, so do not depend on it.
11	downloadInfo, nesting level 2	object	—	—	Populated when id = FILE_DOWNLOAD.
12	fileType*, nesting level 3	enum	FILE_TYPE_FWFILE_TYPE_CERT	FILE_TYPE_FW	Type of file — firmware or certificate.
13	fileName*, nesting level 3	string	—	mqtt_ca_cert	The internally-stored file name (the URL basename stem, not the full request name — see Event Semantics).
14	status*, nesting level 3	enum	DOWNLOAD SUCCESSDOWNLOAD FAILSAVE FAILSAVE SUCCESS	DOWNLOAD SUCCESS	Download / save operation status.
15	temperatureInfo, nesting level 2	object	—	—	Declared in the schema, but the id enum has no TEMPERATURE value to select it, and no temperature alert is emitted on current V1.1 firmware (see Event Semantics). Documented here for schema reference; no example.
16	nge*, nesting level 3	number	—	—	NGE radio temperature, in degrees Celsius.
17	pa*, nesting level 3	number	—	—	Power-amplifier temperature, in degrees Celsius.
18	ambient*, nesting level 3	number	—	—	Ambient temperature, in degrees Celsius.
19	networkInfo, nesting level 2	object	—	—	Populated when id = NETWORK_EVENT.
20	networkInterface*, nesting level 3	object	—	—	Per-interface status arrays.
21	ethStatus, nesting level 4	array	—	—	Ethernet interface statuses (array of items).
22	interface*, nesting level 5	string	—	eth0	Interface name. Note the key is interface, not the interfaceName the Wi-Fi and Ethernet commands use — see Event Semantics.
23	status*, nesting level 5	enum	CONNECTEDDISCONNECTED	CONNECTED	Connection status.
24	linkStatus*, nesting level 5	enum	UPDOWN	UP	Physical link status (Ethernet).
25	linkSpeed, nesting level 5	string	—	—	Link speed. Optional — often omitted by the device.
26	ipV4Address*, nesting level 5	string	—	192.168.0.165	IPv4 address assigned to the interface.
27	ipV6Address, nesting level 5	string	—	fe80::f299:9d51:864c:cff	IPv6 address. Optional — often omitted.
28	wifiStatus, nesting level 4	array	—	—	Wi-Fi interface statuses (array of items).
29	interface*, nesting level 5	string	—	wlan0	Interface name (key interface, not interfaceName — see Event Semantics).
30	status*, nesting level 5	enum	CONNECTEDDISCONNECTED	CONNECTED	Connection status.
31	ssid*, nesting level 5	string	—	IOT_TESTAP	SSID of the connected Wi-Fi network.
32	ipV4Address*, nesting level 5	string	—	192.168.0.145	IPv4 address assigned to the interface.
33	ipV6Address, nesting level 5	string	—	fe80::f299:9d51:86c:cff14	IPv6 address. Optional — often omitted.
34	btRemoteDevice, nesting level 3	object	—	—	Connected Bluetooth remote device. Sibling of networkInterface — optional (only networkInterface is in the leaf required set); absent unless a BT remote is paired (not in the live captures).
35	deviceName*, nesting level 4	string	—	—	Name of the Bluetooth remote device.
36	deviceMac*, nesting level 4	string	—	00:11:22:A3:B1:D2	MAC address of the Bluetooth remote device.
37	ntp, nesting level 2	object	—	—	Information about NTP-related events, such as synchronization status and errors.
38	offset, nesting level 3	number	—	—	Declared in the schema without a description or unit.
39	reach, nesting level 3	number	—	—	Declared in the schema without a description.
40	powerEvent, nesting level 2	object	—	—	Populated when id = POWER.
41	powerSource*, nesting level 3	enum	BATTERYUSBCRADLEWALL_CHARGER	BATTERY	Source of power for the device. On power events, current firmware reports BATTERY, USB, CRADLE or WALL_CHARGER; NONE appears in device status only.
42	lldp, nesting level 3	enum	successfailednegotiating	—	LLDP negotiation status. Optional — link-type-specific; absent on battery power (as here).
43	powerMode*, nesting level 3	enum	ACTIVELOWPOWER	LOWPOWER	Current power mode.
44	batteryAlert, nesting level 2	object	—	—	Populated when id = BATTERY.
45	status*, nesting level 3	enum	LOWCRITICALCHARGINGFULLHIGH	LOW	Current operational state of the battery.
46	stateOfHealth*, nesting level 3	enum	GOODCRITICALMODERATE	GOOD	Long-term battery capacity / health. The same value set as get_status.batteryStatus.stateOfHealth — see Field Support.
47	chargePercentage*, nesting level 3	integer	max 100	100	Current charge level as a percentage (maximum: 100).

state tells you whether a condition is active or resolved: SET = active/asserted, CLEAR = resolved, ONESHOT = a one-time event with no persistent state (it fires once and has no matching CLEAR). Every example on this page is ONESHOT, and so was every firmware-update notification recorded during one set_os run.

Event Semantics

Emission

The per-category eventConfiguration toggles you set with config_events govern which id categories publish: battery → BATTERY, power → POWER, network → NETWORK_EVENT, firmwareUpdate → FIRMWARE_UPDATE, and fileDownload → FILE_DOWNLOAD. A disabled category never publishes, so the absence of an alert is not proof of a healthy state. The FIRMWARE_UPDATE start and the FILE_DOWNLOAD result arrive as type: NOTIFICATION command side-effects (from set_os and install_certificate); the BATTERY / POWER / NETWORK_EVENT categories are autonomous type: ALERT events. The in-progress FIRMWARE_UPDATE events recorded during one set_os run were also NOTIFICATIONs. The config_events schema has a temperature toggle, but there is no TEMPERATURE id and no temperature alert is emitted, so enabling it has no effect.

Branches

alertDetails declares seven branch keys and carries one of them; id selects the populated key. Two keys have no id value that selects them:

id	alertDetails key	Body fields	Emitted on V1.1
BATTERY	batteryAlert	status, stateOfHealth, chargePercentage	✅
POWER	powerEvent	powerSource, powerMode, (lldp)	✅
NETWORK_EVENT	networkInfo	networkInterface.{ethStatus[], wifiStatus[]}, btRemoteDevice	✅
FIRMWARE_UPDATE	fwUpdateStatus	updateStatus, overallProgress, stage	✅
FILE_DOWNLOAD	downloadInfo	fileType, fileName, status	✅
— (no TEMPERATURE id)	temperatureInfo	nge, pa, ambient	⚠️ not emitted
— (no matching id)	ntp	offset, reach	⚠️ no example

Field Support

• type distinguishes alerts from notifications. type: ALERT is an autonomous monitoring alert; type: NOTIFICATION is a command side-effect — FILE_DOWNLOAD (during install_certificate / firmware download) and the FIRMWARE_UPDATE start (during set_os). EVENT is in the enum but was not observed. All three share this one envelope.
• FILE_DOWNLOAD fileName is the stored basename. downloadInfo.fileName is the name the reader stores internally — the URL basename stem (e.g. a source …/mqtt_ca_cert.pem yields fileName: "mqtt_ca_cert"), not your request name. Do not expect a 1:1 match to a get_installed_certificates entry name without the source URLs.
• The interface key is interface on these items. Each ethStatus/wifiStatus item names its interface with the key interface ("interface": "eth0"), while the Wi-Fi and Ethernet commands and their read-backs use interfaceName for the same concept. The key is required: an ethStatus item requires interface, status, linkStatus and ipV4Address, a wifiStatus item interface, status, ssid and ipV4Address.
• alertDetails is optional; envelope is required. The envelope required set is [type, timestamp, state, id, priority]; alertDetails is not required. Validate the envelope strictly.
• batteryAlert.stateOfHealth is the same health grade as get_status. The value set here is GOOD / CRITICAL / MODERATE, and get_status reports deviceStatus.batteryStatus.stateOfHealth from that same enum. One grade, so nothing needs translating when you share battery logic between the command and the event stream. The battery's charge state is the separate status field. See get_status.

Examples

Every contract example is in the Alert category dropdown under Event Payload, and all of them are the reader's own live captures. For the FIRMWARE_UPDATE category, the dropdown shows the NOTIFICATION that starts an update (from set_os); the in-progress notifications that follow are under set_os Progress. The two FILE_DOWNLOAD options come from an install_certificate transfer: one reports the download, the other the save.

Notes and Caveats

• Validate against the alert envelope on this page. It is the shape the reader publishes on the management event topic.
• No response envelope. alerts is a device-emitted event, so it carries no response/code — the command response-code table does not apply, and no response code is defined for any event.

alerts is read-only telemetry with no credentials. Remember emission is gated by config_events (see Event Semantics). For the concept-level view, see Alerts and Event Management.

Related: 📕 config_events · 📕 set_os · 📕 install_certificate · 📕 heartBeatEVT · 📕 Events · 📕 Alerts · 📕 Events