get_current_region

Reference·Audience: API consumer·Use: read the reader's active regulatory region

Overview

get_current_region retrieves the reader's active regulatory / RF region configuration in a single round trip: the country and governing regulatory standard, the channel plan (the frequencies the radio may use), the transmit-power limits, and whether Listen-Before-Talk (LBT) and frequency hopping are enabled. It is a read-only query on the device-management (MGMT) endpoint.

The region governs whether — and how — the reader is legally allowed to transmit, so this read is the compliance gate before any radio operation. Note that the region can only be read over MQTT; it is set with a 123RFID application, 123RFID Desktop or 123RFID Mobile, typically at bootstrap. See also Management.

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
Applies To	Endpoint: Management (MGMT). Reader: RFD40 series, RFD90 series
API Version	V1.1 (API Version Reporting)
Related	get_status, get_version

When to Use

Use get_current_region when you need to confirm the reader's regulatory configuration before it transmits — typically in provisioning verification, a pre-inventory check, or a fleet compliance audit.

• Confirm the region: verify country and regulatoryStandard match the deployment location before starting inventory.
• Validate the RF envelope: check maxTxPowerSupported / minTxPowerSupported, channelData, lbtEnabled, and frequencyHopping against the constraints your operation expects.
• Audit compliance across a fleet: read the region on each device to confirm consistent, compliant settings.
• After provisioning or a region change: run get_current_region to confirm the new settings took effect before relying on the radio.

Topic Mapping

Message	Direction	Topic	Note
Request	App → Reader	<tenantId>/MGMT/clients/cmnd/<serial>	On the management endpoint.
Response	Reader → App	<tenantId>/MGMT/clients/resp/<serial>	Correlated reply to the request above; 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.

Credentials are presented once at CONNECT. The requestId you send is echoed in the response so you can pair reply to request. The endpoint's mqttParams govern QoS and retain, not this command.

See Topics and Channels.

Key Fields

• requestId (request) — your correlation token; make it unique per request. The device echoes it in the response so you can pair reply to request.
• currentRegion.country / regulatoryStandard (response) — the configured country and governing standard (e.g. FCC, ETSI); confirm they match the deployment location.
• currentRegion.maxTxPowerSupported (response) — the power ceiling (dBm); validate transmit-power settings against it before inventory.
• currentRegion.lbtEnabled / frequencyHopping (response) — compliance behaviors that affect how (and whether) inventory can start.
• response.code (response) — read this to determine success vs failure (see Response Codes).

Request Payload

The request envelope is just command and requestId — there is no payload wrapper. Use the Schema tab for the field reference and the Example tab for a ready-to-send, copy-pasteable request.

Example

Request payload

{

"command": "get_current_region",

"requestId": "abc123"

}

Schema

Request payload

* required— not applicableColored badge = JSON type

#	Field	Type	Enum / Units	Example	Description
1	command*	string	—	get_current_region	Fixed command name. Retrieves the current region configuration.
2	requestId*	string	—	abc123	A unique identifier for the request, allowing tracking and debugging. Echoed back unchanged in the response.

Response Payload

The response envelope is command, requestId, apiVersion, response, and a currentRegion object. On the Schema tab, expand currentRegion to see every field — its type, whether it is required, its enum/units, an example value, and a description; the Example tab shows the full JSON. currentRegion is optional at the envelope level, but on a successful read it is the operative payload and all seven of its members are required. country and regulatoryStandard are free-form (device-driven) — the schema does not constrain them to a fixed vocabulary.

Example

Response payload

{

"command": "get_current_region",

"requestId": "abc123",

"apiVersion": "V1.1",

"currentRegion": {

"frequencyHopping": true,

"channelData": [

"915750",

"915250",

"903250",

"926750",

"926250",

"904250",

"927250",

"920250",

"919250",

"909250",

"918750",

"917750",

"905250",

"904750",

"925250",

"921750",

"914750",

"906750",

"913750",

"922250",

"911250",

"911750",

"903750",

"908750",

"905750",

"912250",

"906250",

"917250",

"914250",

"907250",

"918250",

"916250",

"910250",

"910750",

"907750",

"924750",

"909750",

"919750",

"916750",

"913250",

"923750",

"908250",

"925750",

"912750",

"924250",

"921250",

"920750",

"922750",

"902750",

"923250"

],

"country": "United States",

"lbtEnabled": false,

"maxTxPowerSupported": 30,

"minTxPowerSupported": 0,

"regulatoryStandard": "FCC"

},

"response": {

"code": 0,

"description": "Success"

}

}

Schema

Response payload

* required— not applicableColored badge = JSON type

#	Field	Type	Enum / Units	Example	Description
1	command*	string	—	get_current_region	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	currentRegion	object	—	—	The active regulatory region configuration. Optional at the envelope level; when present, all seven members below are required.
5	frequencyHopping*, nesting level 2	boolean	—	true	Whether the radio hops across the channel plan (vs a fixed channel). Required in most regions.
6	channelData*, nesting level 2	array	—	["915750", …]	Channel center frequencies the reader may transmit on, as strings in kHz (e.g. 865700 = 865.7 MHz). Count and values are region-specific.
7	country*, nesting level 2	string	—	USA	The country the device is configured for. Free-form (device-driven) — e.g. India, United States.
8	lbtEnabled*, nesting level 2	boolean	—	false	Whether Listen-Before-Talk is enabled (required in some ETSI regions; affects inventory start behavior).
9	maxTxPowerSupported*, nesting level 2	number	—	30	Maximum transmit power supported in the region. Documented in dBm — confirm the scale against your firmware if precise power matters.
10	minTxPowerSupported*, nesting level 2	number	—	0	Minimum transmit power supported in the region (dBm).
11	regulatoryStandard*, nesting level 2	string	—	FCC_USA	The regulatory standard governing transmission rules — e.g. FCC, ETSI, and sometimes a more specific plan identifier such as ETSI_EU_800M_900M_3_CHANNEL. Free-form (device-driven).
12	response*	object	—	—	Result wrapper.
13	code*, nesting level 2	integer	0–101	0	0 = Success; non-zero = error. Required by the contract. See Response Codes below.
14	description*, nesting level 2	string	—	Success	Human-readable status.

Response Semantics

• channelData is a list of channel center frequencies in kHz, as strings — e.g. "865700" = 865.7 MHz. The count and values depend on the configured region: US / FCC has ~50 channels across 902–928 MHz; ETSI regions typically have fewer, in the 865–868 MHz band. country and regulatoryStandard are free-form, device-driven strings (no fixed enum).
• maxTxPowerSupported / minTxPowerSupported are documented in dBm (e.g. 30 dBm ≈ 1 W). If precise transmit power matters to your integration, confirm the scale against your firmware.

Response Codes

get_current_region 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 — region configuration retrieved and returned.
3	Not able to retrieve information (IOT_ERROR_INFO_NOT_AVAILABLE) — the device could not gather the region information at this time. Retry after a short delay; if it persists, reboot the device.
101	Default error — generic catch-all.

An unconfigured region surfaces as code 6 (IOT_STATUS_REGION_NOT_CONFIGURED) at connect / bootstrap time — it is not returned by get_current_region itself. If a device has no region set, configure it with 123RFID Desktop or 123RFID Mobile before connecting.

Examples

get_current_region is a single request/response exchange. Publish the standard {command, requestId} request shown under Request Payload; the device replies on the response topic with the correlated reply — the requestId you send (abc123) is echoed back so you can pair reply to request. The full reply, field by field, is shown under Response Payload above.

The response shown throughout is the contract's United States / FCC example (50 channels across the 902–928 MHz band). The channelData list and the country / regulatoryStandard / power values are region-specific — an ETSI region, for example, typically reports fewer channels, in the 865–868 MHz band.

Notes and Caveats

A wrong region can put the reader outside local radio regulations

The region is set with 123RFID Desktop or 123RFID Mobile, not by any MQTT command — get_current_region only reads it. A reader will not transmit at all until a region is set, and a reader set to the wrong region will operate but may violate local regulations. If a freshly provisioned reader reports the wrong country, redo region setup in 123RFID Desktop or 123RFID Mobile. See Management and RF Regions and Regulations.

• Read-only over MQTT. get_current_region returns the active region and takes no payload. The region is set with 123RFID Desktop or 123RFID Mobile. This documentation covers 123RFID Desktop, which connects over USB-C before the reader joins a broker.

Run get_current_region after device provisioning or a region change to confirm the regulatory settings are correct before starting inventory operations.

Related: 📕 Management · 📕 get_status · 📕 get_version · 📕 RF Regions and Regulations · 📕 Response Codes