Skip to main content

config_events

ReferenceAudience: API consumerUse: enable/disable the reader's event streams and configure the heartbeat

Overview​

config_events enables or disables which device-management events the reader emits, sets the heartbeat interval and payload, and configures alert thresholds. You send a single eventConfiguration object of boolean flags (plus heartbeatConfiguration and thresholds). It is a state-changing management-plane (MGMT) command and carries no credentials.

Two things make this command distinctive:

  • Changes take effect after a reboot. The configuration is stored immediately (visible via get_endpoint_config), but the reader only starts emitting the configured events after a reboot. The command's schema states it plainly: "To apply the changes, a device reboot is required." Do not assume events are live until the reader has rebooted.
  • Accept-but-drop. The reader accepts the whole payload with code 0 even if it contains flags it does not support. Of the declared flags, 7 are functional today; the other 13 are reserved: accepted, stored and returned in the read-back, but with no effect on v1.1 firmware. Always read back with get_endpoint_config to see what was stored — but note a stored reserved flag has still not taken functional effect.

Details​

PropertyValue
Interaction PatternRequest / Response (app publishes a command; device publishes the correlated reply)
State ChangeSTATE-CHANGING (updates the endpoint's stored event configuration)
ReversibilityREVERSIBLE (re-send config_events with the desired flags to restore a prior configuration)
Required Request Fieldscommand, requestId, eventConfiguration (with the flags)
Applies ToEndpoint: Management (MGMT). Reader: RFD40 series, RFD90 series
API VersionV1.1 (API Version Reporting)
Relatedget_endpoint_config (read back what applied), config_endpoint, reboot, get_status

When to Use​

Use config_events to control the reader's management-event surface:

  • Turn event streams on/off — enable terminalConnection, firmwareUpdate, network, power, battery, fileDownload, or heartbeat.
  • Shape the heartbeat — set heartbeatConfiguration.interval and choose whether each heartbeat carries inventory / battery status.
  • Reduce noise — disable streams you do not consume so the reader emits less telemetry.

Then reboot to activate emission, and get_endpoint_config to confirm the stored configuration.

Topic Mapping​

config_events is a management-plane command — answered on the MGMT/MDM endpoint, not the control endpoint.

MessageDirectionTopicNote
RequestApp → Reader<tenantId>/MGMT/clients/cmnd/<serial>On the management endpoint that carries your session.
ResponseReader → App<tenantId>/MGMT/clients/resp/<serial>Correlated reply; the in-payload requestId links the twin topics.
EventReader → App<tenantId>/MGMT/clients/event/<serial>Where the enabled events flow, after a reboot.

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.

config_events configures the event configuration of the management endpoint on which it is received — other endpoints' event settings (set via config_endpoint) are left untouched.

See Topics and Channels.

Key Fields​

  • command (request) — the command name; send exactly config_events. The schema does not enum-constrain it, so a wrong string is not caught by validation.
  • requestId (request) — a unique identifier for the request; echoed back in the response to pair reply to request.
  • eventConfiguration (request) — the event configuration to store; treat it as a wholesale set and send the complete configuration you want. The contract requires it.
  • enable flags (request) — the boolean toggles inside eventConfiguration (terminalConnection, firmwareUpdate, network, heartbeat, power, battery, fileDownload, plus the reserved flags) that turn each event stream on or off; heartbeatConfiguration shapes the heartbeat when heartbeat: true.
  • response.code (response) — 0 = Success (present on success for this management command); non-zero = error. See Response Codes.

Request Payload​

The envelope is command, requestId, and the eventConfiguration. Pick an event set below; the Example and Schema update together. Use the Schema tab for the full field reference (with the supported/reserved status per field) and the Example tab for the concrete payload.

Request payload
Example: enable all supported events
{
"command": "config_events",
"requestId": "abc123",
"eventConfiguration": {
"terminalConnection": true,
"firmwareUpdate": true,
"network": true,
"heartbeat": true,
"power": true,
"battery": true,
"temperature": true,
"fileDownload": true,
"heartbeatConfiguration": {
"interval": 100,
"inventoryStatus": true,
"batteryStatus": true
}
}
}

When heartbeat: true, heartbeatConfiguration shapes each heartbeat message — lower interval means more telemetry at higher battery cost, and inventoryStatus / batteryStatus toggle which sub-blocks each heartbeat carries (see the Schema tab above for per-field detail; userApps is ⚠️ reserved, not functional on V1.1). See MQTT Connectivity for the heartbeat event shape.

Request Semantics​

Field Support. Seven of the flags below are functional on current V1.1 firmware; every flag is declared in the schema. The reader accepts a reserved flag (returns code 0) but it has no effect. The API developer has declared these for future support; treat them as not currently supported. Reserved flags are accepted, stored and echoed back in the read-back while remaining unemitted — always read back with get_endpoint_config, remembering that a reserved flag appearing there is stored, not functional; only the 7 supported flags take effect.

Event flagStatusStream
terminalConnection✅ SupportedTerminal (cradle / USB-C) connect / disconnect
firmwareUpdate✅ SupportedFirmware-update progress / completion
network✅ SupportedNetwork interface / connectivity changes
heartbeat✅ SupportedPeriodic heartbeat (shaped by heartbeatConfiguration)
power✅ SupportedPower-source change (battery / external)
battery✅ SupportedBattery state (low, critical, full)
temperature⚠️ ReservedTemperature alert — declared in the schema but never sent by the reader, so switching it on is accepted and does nothing
fileDownload✅ SupportedFile-download progress / completion
antenna⚠️ ReservedNot emitted on V1.1
gpi⚠️ ReservedNot emitted on V1.1
exceptions⚠️ ReservedNot emitted on V1.1
ntp⚠️ ReservedNot emitted on V1.1 (may be stored/echoed)
userApp⚠️ ReservedNot emitted on V1.1
cpuUsage⚠️ ReservedNot emitted on V1.1
flashUsage⚠️ ReservedNot emitted on V1.1
ramUsage⚠️ ReservedNot emitted on V1.1

The four threshold fields (cpuThreshold, ramThreshold, flashThreshold, temperatureThreshold) and heartbeatConfiguration.userApps are likewise reserved — declared but not honored on V1.1. Enabling any reserved field is accepted (returns code 0) but has no effect. For the emitted-event catalog, see Events.

  • Send every flag you want set. Nothing in eventConfiguration is required and no flag has a documented default. Send the complete set of flags you intend, then check the eventConfiguration block in get_endpoint_config.

Response Payload​

config_events returns a status-only envelope — command, requestId, apiVersion, and response. There is no configuration echo; confirm the stored configuration with get_endpoint_config.

Response payload
{
"command": "config_events",
"requestId": "abc123",
"apiVersion": "V1.1",
"response": {
"code": 0,
"description": "Success"
}
}

The contract's success example includes code: 0. command, requestId, apiVersion and response — with both code and description — are required on every reply.

Response Codes​

The API contract lists no command-specific error codes for config_events — only the universal codes apply. In practice the command is highly permissive (it accepts unsupported flags with code 0 rather than rejecting them; see Request Semantics), so success is by far the common outcome.

CodeDescription
0Success — the configuration was stored (code present, description: "Success"). Emission activates on the next reboot.
101Default error — generic catch-all for an unhandled failure.

The contract scopes the invalid-payload code (2) to other commands, not to config_events. For the full table see the Response Codes and Correlation and Request/Response Pairing.

Examples​

Publish config_events over the MGMT endpoint; the device replies with the status envelope under Response Payload, stores the supported subset immediately, and begins emitting after a reboot. The Event set dropdown under Request Payload shows both contract examples: Enable all events, with a 100 s heartbeat, and Selective events, which turns some streams off (heartbeat: false, no heartbeatConfiguration).

Notes and Caveats​

  • Stored immediately, emitted after a reboot. config_events writes the configuration right away — you can confirm it with get_endpoint_config before rebooting — but the reader only starts emitting the enabled events after a reboot. Plan a reboot into any event-configuration change.
  • Global and per-endpoint settings. An endpoint can also carry its own eventConfiguration, set with config_endpoint. Which of the two wins when they disagree is not specified in the available sources.

config_events carries no credentials — only event flags and thresholds, so there is nothing to mask. It is reversible: re-send with the desired flags to restore a prior configuration (followed by a reboot). For the concept-level view, see Event Management.

Related: 📕 get_endpoint_config · 📕 config_endpoint · 📕 reboot · 📕 Events · 📕 MQTT Connectivity · 📕 Event Management · 📕 Response Codes

Was this helpful?