get_operating_mode

Reference·Audience: API consumer·Use: read back the reader's current RFID operating-mode configuration

Overview

get_operating_mode reads back the reader's current RFID operating-mode configuration — the active profile, radio start/stop conditions, Gen2 query parameters, select pre-filters, armed access operations, and tag-metadata reporting flags — under operatingMode.operatingModes. It is read-only. It is a control-plane (CTRL) command — configure the mode with set_operating_mode.

This is a CTRL-endpoint command: it is published on the control endpoint (<tenantId>/CTRL/clients/cmnd/<serial>) and answered only there (not on the MGMT/MDM channel). Returning a response requires an active CTRL endpoint (configured with config_endpoint, epType: CTRL, activate: true). See Topic Mapping.

Details

Property	Value
Interaction Pattern	Request / Response (app publishes a command; device publishes the correlated reply)
State Change	READ-ONLY
Required Request Fields	command, requestId (no other payload)
Applies To	Endpoint: Control (CTRL). Reader: RFD40 series, RFD90 series
API Version	V1.1 (API Version Reporting)
Related	set_operating_mode, control_operation, config_endpoint, reboot

When to Use

Use get_operating_mode to inspect or audit the reader's RFID configuration:

• Before an inventory — confirm the profile, query parameters, and trigger conditions are what you expect.
• After set_operating_mode — verify the mode was applied (there is no configuration echo on the set command's response).
• After a reboot — the operating mode reverts to default on reboot (see the volatility note); read it back to confirm the current state.
• Check reporting — see which tagMetaDataToEnable fields the reader will include on tag reads.

Topic Mapping

Message	Direction	Topic	Note
Request	App → Reader	<tenantId>/CTRL/clients/cmnd/<serial>	On the control endpoint. Requires an active CTRL endpoint.
Response	Reader → App	<tenantId>/CTRL/clients/resp/<serial>	Correlated reply; the in-payload requestId links the twin topics.

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.

Unlike the MGMT commands, control commands are answered only on the CTRL endpoint — publishing get_operating_mode to the MGMT/MDM command topic produces no reply.

If no CTRL endpoint is active, add or activate one with config_endpoint (epType: CTRL, activate: true) before sending control commands. The requestId you send is echoed in the response.

See Topics and Channels.

Key Fields

• operatingMode.operatingModes.profiles (response) — the active profile (e.g. BALANCED_PERFORMANCE); ADVANCED surfaces advancedConfigurations.
• query (response) — the Gen2 session / inventory-state / SL-flag / tag-population parameters driving inventory.
• radioStartConditions / radioStopConditions (response) — the trigger semantics for starting/stopping inventory.
• tagMetaDataToEnable (response) — which metadata fields (RSSI, EPC, TID, …) the reader reports on each tag read.
• response.code (response) — read this to determine success vs failure. The contract requires it; note the reported success-path omission. See Response Codes.

Request Payload

The request is a minimal envelope — just command (pinned to get_operating_mode) and requestId. There are no parameters.

Example

Request payload

{

"command": "get_operating_mode",

"requestId": "abc123"

}

Schema

Request payload

* required— not applicableColored badge = JSON type

#	Field	Type	Enum / Units	Example	Description
1	command*	enum	get_operating_mode	get_operating_mode	Fixed command name (pinned by the schema enum).
2	requestId*	string	—	abc123	A unique identifier for the request; echoed back in the response. There is no other payload.

Response Payload

On success the device returns the envelope (command, requestId, apiVersion, response) with the current mode under operatingMode.operatingModes. The device returns only the configured sub-objects — advancedConfigurations, accessOperations, and select appear only when configured. The Example tab shows a default BALANCED_PERFORMANCE read-back.

Example

Response payload

{

"command": "get_operating_mode",

"requestId": "abc123",

"apiVersion": "V1.1",

"operatingMode": {

"operatingModes": {

"profiles": "BALANCED_PERFORMANCE",

"inventoryProtocol": "GEN2",

"radioStartConditions": {

"trigger": "IMMEDIATE",

"startDelay": 0,

"repeat": false

},

"radioStopConditions": {

"trigger": "IMMEDIATE"

},

"query": {

"session": "SESSION_1",

"inventoryState": "STATE_A",

"slFlag": "ALL",

"tagPopulation": 30

},

"tagMetaDataToEnable": {

"RSSI": true,

"PHASE": false,

"SEENCOUNT": true,

"CHANNEL": false,

"PC": false,

"XPC": false,

"CRC": false,

"EPC": false,

"TID": false,

"USER": false,

"MAC": false,

"HOSTNAME": false

}

}

},

"response": {

"code": 0,

"description": "Success"

}

}

Schema

Response payload

* required— not applicableColored badge = JSON type

#	Field	Type	Enum / Units	Example	Description
1	command*	string	—	get_operating_mode	Echoes the executed command.
2	requestId*	string	—	abc123	Echoes the request's requestId — pairs reply to request.
3	apiVersion*	enum	V1.0V1.1V1.2V1.21V1.22	V1.1	API version reported by this command. Emitted per-handler, not device-wide.
4	operatingMode	object	—	—	The current operating-mode snapshot. Present on success (not in the envelope required set).
5	operatingModes, nesting level 2	object	—	—	The reader operating mode.
6	profiles, nesting level 3	enum	FAST_READCYCLE_COUNTDENSE_READERSOPTIMAL_BATTERYBALANCED_PERFORMANCEADVANCED	BALANCED_PERFORMANCE	Active profile (default BALANCED_PERFORMANCE): CYCLE_COUNT reads as many unique tags as possible, DENSE_READERS for multiple readers in proximity, OPTIMAL_BATTERY for best battery life, BALANCED_PERFORMANCE balances performance and battery life. FAST_READ (configures the radio for maximum read speed within short range) is enumerated but not currently supported (see Response Semantics). ADVANCED uses custom advancedConfigurations.
7	advancedConfigurations, nesting level 3	object	—	—	Custom RF settings — present only when profiles is ADVANCED.
8	transmitPower, nesting level 4	number	0–300	270	Transmit power level.
9	linkProfile, nesting level 4	enum	M4_256KM2_240KM2_256KM2_320KM4_240KM4_320KFM0_0KFM0_320KM8_240KM8_256KM8_320K	M2_240K	RF link profile.
10	session, nesting level 4	enum	SESSION_0SESSION_1SESSION_2SESSION_3	SESSION_1	Gen2 session.
11	dynamicPower, nesting level 4	boolean	—	true	Whether dynamic power is enabled.
12	inventoryProtocol, nesting level 3	enum	GEN2GEN2XHYBRID	GEN2	Specifies the inventory protocol to be used by the reader.
13	accessOperations, nesting level 3	array	—	—	Armed tag access operations (present only if configured). config.password is echoed empty ("") in the read-back — the stored value is never returned (see Response Semantics).
14	operationType, nesting level 4	enum	READWRITEACCESSLOCKKILL	READ	The access operation type.
15	config, nesting level 4	object	—	—	Parameters for the operation.
16	memoryBank, nesting level 5	enum	EPCTIDUSERRESERVED	EPC	Target memory bank.
17	offset, nesting level 5	integer	—	1	Start word position.
18	length, nesting level 5	integer	—	2	Word count.
19	data, nesting level 5	string	—	FFFFEEEE	Words to write (WRITE); a whole number of 16-bit words.
20	password, nesting level 5	string	—	00000000	8-hex-char access/lock/kill password. The read-back echoes it as empty ("") — the stored value is never returned.
21	lockMemBank, nesting level 5	enum	EPCACCESS_PWDKILL_PWDTIDUSERALL	TID	Bank to lock/unlock (LOCK).
22	lockAction, nesting level 5	enum	READ_AND_WRITEPERMANENT_LOCKPERMANENT_UNLOCKUNLOCK	UNLOCK	Lock action (LOCK).
23	radioStartConditions, nesting level 3	object	—	—	When inventory starts. Absent → starts immediately on start.
24	trigger, nesting level 4	enum	PRESSEDRELEASEDIMMEDIATE	IMMEDIATE	Start trigger.
25	startDelay, nesting level 4	integer	—	3000	Delay before starting (any trigger, when > 0).
26	repeat, nesting level 4	boolean	—	false	Whether the trigger can restart inventory.
27	radioStopConditions, nesting level 3	object	—	—	When inventory stops. Absent → runs until stop.
28	trigger, nesting level 4	enum	PRESSEDRELEASEDIMMEDIATE	IMMEDIATE	Stop trigger.
29	tagCount, nesting level 4	integer	—	10	Stop after N unique tags.
30	stopTimeout, nesting level 4	integer	—	10000	Stop after this duration.
31	inventoryCount, nesting level 4	integer	—	0	Stop after N inventory cycles.
32	query, nesting level 3	object	—	—	Gen2 query parameters.
33	session, nesting level 4	enum	SESSION_0SESSION_1SESSION_2SESSION_3	SESSION_1	Gen2 session.
34	inventoryState, nesting level 4	enum	STATE_ASTATE_BSTATE_AB	STATE_A	Inventory flag state (STATE_AB flips).
35	slFlag, nesting level 4	enum	ALLASSERTEDDEASSERTED	ALL	SL (select) flag filter.
36	tagPopulation, nesting level 4	integer	min 0	30	Estimated tag count (tunes the Q parameter).
37	select, nesting level 3	array	—	—	Select pre-filters (present only if configured). Each item requires enable, tagPattern, memoryBank, offset, action, target, length.
38	enable*, nesting level 4	boolean	—	true	Whether this pre-filter is enabled.
39	tagPattern*, nesting level 4	string	—	2222EEEEFFFF1111AAAABBBB	Bit pattern to match.
40	memoryBank*, nesting level 4	enum	EPCTIDUSER	EPC	Memory bank to match against.
41	offset*, nesting level 4	integer	—	32	Start bit position.
42	action*, nesting level 4	enum	INV_A_NOT_INV_B_OR_ASRT_SL_NOT_DSRT_SLINV_A_OR_ASRT_SLNOT_INV_B_OR_NOT_DSRT_SLINV_A2BB2A_NOT_INV_A_OR_NEG_SL_NOT_ASRT_SLINV_B_NOT_INV_A_OR_DSRT_SL_NOT_ASRT_SLINV_B_OR_DSRT_SLNOT_INV_A_OR_NOT_ASRT_SLNOT_INV_A2BB2A_OR_NOT_NEG_SL	INV_B_NOT_INV_A_OR_DSRT_SL_NOT_ASRT_SL	How to set the SL/inventory flag on match/mismatch (Gen2 select action).
43	target*, nesting level 4	enum	SESSION_SLSESSION_0SESSION_1SESSION_2SESSION_3	SESSION_1	Session/SL flag to set.
44	length*, nesting level 4	integer	—	16	Number of bits to compare.
45	tagMetaDataToEnable, nesting level 3	object	—	—	Which tag-metadata fields are reported on a read (each a boolean).
46	RSSI, nesting level 4	boolean	—	true	Report signal strength.
47	PHASE, nesting level 4	boolean	—	false	Report phase angle.
48	SEENCOUNT, nesting level 4	boolean	—	true	Report detection count.
49	CHANNEL, nesting level 4	boolean	—	false	Report the RF channel.
50	PC, nesting level 4	boolean	—	false	Report the Protocol Control word.
51	XPC, nesting level 4	boolean	—	false	Report the Extended Protocol Control (XPC) word, if the tag has one.
52	CRC, nesting level 4	boolean	—	false	Report the tag CRC.
53	EPC, nesting level 4	boolean	—	false	Report the EPC.
54	TID, nesting level 4	boolean	—	false	Report the TID.
55	USER, nesting level 4	boolean	—	false	Report USER memory.
56	MAC, nesting level 4	boolean	—	false	Report the reader's MAC.
57	HOSTNAME, nesting level 4	boolean	—	false	Report the reader's hostname.
58	response*	object	—	—	Status envelope for the read.
59	code*, nesting level 2	integer	0–101	0	0 = Success; non-zero = error. Required by the contract. Readers have been reported to omit it on success — see Response Payload and Response Codes below.
60	description*, nesting level 2	string	—	Success	Human-readable status.

The contract requires response.code. Readers have been reported to omit it on a successful reply, returning just response: { "description": "Success" } — treat that as success too. See Success without a code.

As reported, a successful read can arrive with code omitted — the same envelope and operatingMode payload. This form does not validate against the contract; the reply with code: 0 above is the documented form. The mode object is abridged here:

Response — success reported without code (not accepted by the contract; operatingMode abridged)

{

"command": "get_operating_mode",

"requestId": "abc123",

"apiVersion": "V1.1",

"operatingMode": {

"operatingModes": {

"profiles": "BALANCED_PERFORMANCE"

}

},

"response": {

"description": "Success"

}

}

Response Semantics

• The read-back masks access passwords. When access operations are armed, get_operating_mode returns their structure but echoes config.password as empty ("") — the stored credential is never returned. The real password is carried only in the set_operating_mode request (mask it there). A default read-back has no accessOperations at all.
• FAST_READ is enumerated but not supported. The profiles enum lists FAST_READ, but it is currently not supported by the firmware (per the schema's own description). Use CYCLE_COUNT, DENSE_READERS, OPTIMAL_BATTERY, BALANCED_PERFORMANCE, or ADVANCED.
• Conditional sub-objects. advancedConfigurations appears only when profiles is ADVANCED; accessOperations and select appear only when configured. A default read-back typically returns just profiles, inventoryProtocol, radioStartConditions, radioStopConditions, query, and tagMetaDataToEnable.

Response Codes

get_operating_mode returns response.code. The codes applicable to this command are below; for the full table see the Response Codes and Correlation and Request/Response Pairing.

Code	Description
0	Success — the operating mode was retrieved.
3	Not able to retrieve information (IOT_ERROR_INFO_NOT_AVAILABLE) — the device could not gather the operating mode at this time. Retry after a short delay; if persistent, reboot.
101	Default error — generic catch-all.

The contract requires response.code; readers have been reported to omit it on success — see Success without a code.

Examples

Publish get_operating_mode over the CTRL endpoint (with an active CTRL endpoint); the device replies with the snapshot shown under Response Payload. There are no request variants — the command takes no parameters.

Notes and Caveats

• Operating mode is volatile. The operating mode resets to default (BALANCED_PERFORMANCE, armed accessOperations cleared) on reboot. Read it back after a reset to confirm the current state; re-apply with set_operating_mode if you were relying on a non-default configuration.

Read get_operating_mode to confirm the reader's RF configuration before running an inventory with control_operation, and to verify a change applied by set_operating_mode. For the concept-level view, see Operating Mode.

Related: 📕 set_operating_mode · 📕 control_operation · 📕 config_endpoint · 📕 reboot · 📕 Response Codes