set_wifi

Reference·Audience: API consumer·Use: create or modify a Wi-Fi profile on the reader

Overview

set_wifi writes a Wi-Fi profile to the reader — it creates a new saved profile or modifies an existing one (selected by wifiConfig.operation = CREATE / MODIFY). One payload configures the interface, the access point (ESSID, preference), the security type and its credentials (WPA2/WPA3 Personal or Enterprise), and DHCP IPv4. It is a state-changing command on the device-management (MGMT) endpoint. The response is status-only — it echoes no configuration and no credentials; confirm the result with get_wifi.

set_wifi is state-changing: accessPoint.connect: true switches networks and can sever the MQTT control session. Use connect: false to save a profile without switching. See the warning callout in Notes and Caveats.

Details

Property	Value
Interaction Pattern	Request / Response (app publishes a command; device publishes the correlated reply)
State Change	STATE-CHANGING (writes a saved profile; may switch the active connection)
Reversibility	REVERSIBLE (remove a created profile with delete_wifi_profile; re-send set_wifi MODIFY to change settings)
Supported Operations	CREATE (new profile), MODIFY (update existing, matched by essid)
Required Request Fields	command, requestId, wifiConfig (with operation and accessPoint; inside it, essid and isPreferred)
Applies To	Endpoint: Management (MGMT). Reader: RFD40 series, RFD90 series
API Version	V1.1 (API Version Reporting)
Related	get_wifi, delete_wifi_profile, install_certificate

When to Use

Use set_wifi to provision or update the reader's Wi-Fi — during onboarding, when a network changes, or to mark a profile preferred.

• CREATE: first-time provisioning of a new ESSID. Fails with code 18 if the ESSID already exists.
• MODIFY: update an existing profile (password, security, preference), matched by essid. Fails with code 15 if the ESSID is not found. A MODIFY can be a partial payload — e.g. just operation + accessPoint.{isPreferred, essid} to set the preferred flag.
• Pre-provision safely: send connect: false to save a profile without switching the active connection — the recommended pattern when managing a reader over the same Wi-Fi that carries the MDM session.

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

• wifiConfig.operation (request) — CREATE or MODIFY; determines whether a new profile is added or an existing one (matched by essid) is updated.
• wifiConfig.accessPoint.essid (request) — the network name; the create target / modify key (case-sensitive).
• wifiConfig.accessPoint.connect (request) — ⚠️ true switches the active connection (can sever the MDM session); false just saves. See the notes below.
• wifiConfig.accessPoint.security.securityType (request) — selects which securityDetails key you populate (WPA2/WPA3 Personal or Enterprise).
• response.code (response) — read this to determine success vs failure (see Response Codes).

Request Payload

The request envelope is command, requestId, and the wifiConfig payload. Use the Schema tab for the full field reference and the Example tab for a ready-to-send WPA2-Personal CREATE (enterprise variants are in Examples).

Credentials in the examples are the contract's sample values, not real secrets — passwords, passphrases, and identities are write-only (see Request Semantics).

Pick a profile scenario below; the Example and Schema update together. Use the Schema tab for the full field reference and the Example tab for the concrete payload.

Profile scenarioCreate WPA2 personalModify WPA2 personalSet preferred APCreate WPA2 enterprise TLSCreate WPA2 enterprise TTLSCreate WPA2 enterprise PEAPCreate WPA3 enterprise TLSCreate WPA3 enterprise TTLSCreate WPA3 enterprise PEAPCreate WPA2 personalModify WPA2 personalSet preferred APCreate WPA2 enterprise TLSCreate WPA2 enterprise TTLSCreate WPA2 enterprise PEAPCreate WPA3 enterprise TLSCreate WPA3 enterprise TTLSCreate WPA3 enterprise PEAP

Example

Request payload

Example: WPA2-Personal CREATE

{

"command": "set_wifi",

"requestId": "abc123",

"wifiConfig": {

"interfaceName": "wlan0",

"enableInterface": true,

"operation": "CREATE",

"accessPoint": {

"connect": false,

"isPreferred": false,

"autoConn": true,

"essid": "TestAP1",

"enableSecurity": true,

"security": {

"securityType": "WPA2Personal",

"securityDetails": {

"WPA2Personal": {

"password": "test@123"

}

}

}

}

}

}

Schema

Request payload

* required— not applicableColored badge = JSON type

#	Field	Type	Enum / Units	Example	Description
1	command*	string	—	set_wifi	Fixed command name.
2	requestId*	string	—	abc123	A unique identifier for the request; echoed back in the response.
3	wifiConfig*	object	—	—	The Wi-Fi profile to configure. Required by the contract, so a request without it is invalid rather than merely useless.
4	interfaceName, nesting level 2	string	—	wlan0	Wireless interface name (e.g. wlan0). Typically sent for CREATE.
5	enableInterface, nesting level 2	boolean	—	true	Whether to enable the interface.
6	operation*, nesting level 2	enum	CREATEMODIFY	CREATE	CREATE a new profile or MODIFY an existing one (matched by essid). Required within wifiConfig.
7	accessPoint*, nesting level 2	object	—	—	Access-point connection settings, security, and (DHCP) IP config. Required within wifiConfig.
8	connect, nesting level 3	boolean	—	false	⚠️ If true, disconnect the current profile and connect to this one; if false (or omitted), just save it. See the connect caveat in Notes.
9	isPreferred*, nesting level 3	boolean	—	false	Mark this profile preferred (always connect when in range). Required within accessPoint.
10	autoConn, nesting level 3	boolean	—	true	Deprecated — reserved for backward compatibility; will be removed.
11	essid*, nesting level 3	string	—	ZWireless	The network name (ESSID). Case-sensitive. Required within accessPoint.
12	enableSecurity, nesting level 3	boolean	—	true	Whether to enable security for this access point.
13	ipv4Configuration, nesting level 3	object	—	—	IPv4 network configuration. Use DHCP (enableDhcp: true), the supported mode; static IP is not supported in the current API version. See Request Semantics.
14	ipAddress, nesting level 4	string	ipv4	192.168.1.81	Static IPv4 address (modeled; not supported yet).
15	subnetMask, nesting level 4	string	ipv4	255.255.255.0	Subnet mask (modeled; not supported yet).
16	gateway, nesting level 4	string	ipv4	192.168.1.144	Gateway (modeled; not supported yet).
17	enableDhcp, nesting level 4	boolean	—	true	Use DHCP for automatic IPv4 assignment (the supported mode).
18	dnsServer, nesting level 4	string	ipv4	192.168.1.78	DNS server (modeled; not supported yet).
19	domainName, nesting level 4	string	—	example.test.com	Domain name (modeled; not supported yet).
20	security, nesting level 3	object	—	—	Security type and credentials. Required keys: securityType, securityDetails.
21	securityType*, nesting level 4	enum	WPA2PersonalWPA3PersonalWPA2EnterpriseWPA3Enterprise	WPA2Personal	Selects which securityDetails key you must populate.
22	securityDetails*, nesting level 4	object	—	—	Credentials for the chosen securityType — populate only the matching key.
23	WPA2Personal, nesting level 5	object	—	—	WPA2-Personal credentials: the password.
24	password*, nesting level 6	string	—	test@123	Pre-shared key (write-only).
25	WPA3Personal, nesting level 5	object	—	—	WPA3-Personal credentials: the password.
26	password*, nesting level 6	string	—	—	Pre-shared key (write-only).
27	WPA2Enterprise, nesting level 5	object	—	—	802.1X credentials. Requires authentication.
28	authentication*, nesting level 6	enum	tlsttlspeap	peap	Outer EAP method.
29	innerAuthentication, nesting level 6	enum	nonemschapv2	mschapv2	Inner (phase-2) method. Omit it when authentication is tls; for ttls and peap it must be mschapv2, the default.
30	identity, nesting level 6	string	—	test	EAP identity / username (write-only).
31	anonymousIdentity, nesting level 6	string	—	test	Anonymous/outer identity (write-only).
32	password, nesting level 6	string	—	test@123	EAP password (write-only).
33	passphrase, nesting level 6	string	—	test@123	Passphrase (write-only).
34	certificate, nesting level 6	array	—	—	Certificate references as {key, value} — the certs must already be installed via install_certificate.
35	key, nesting level 7	enum	ca_certclient_keyclient_certcert_key_password	ca_cert	Certificate role.
36	value, nesting level 7	string	—	wifi_ca_cert	Installed certificate reference name.
37	protocol, nesting level 6	enum	WPA2_Enterprise_CCMP	WPA2_Enterprise_CCMP	WPA2-Enterprise protocol.
38	WPA3Enterprise, nesting level 5	object	—	—	802.1X credentials for WPA3. Requires authentication.
39	authentication*, nesting level 6	enum	tlsttlspeap	peap	Outer EAP method.
40	innerAuthentication, nesting level 6	enum	nonemschapv2	mschapv2	Inner (phase-2) method. Omit it when authentication is tls; for ttls and peap it must be mschapv2, the default.
41	identity, nesting level 6	string	—	test	EAP identity / username (write-only).
42	anonymousIdentity, nesting level 6	string	—	test	Anonymous/outer identity (write-only).
43	password, nesting level 6	string	—	test@123	EAP password (write-only).
44	passphrase, nesting level 6	string	—	test@123	Passphrase (write-only).
45	certificate, nesting level 6	array	—	—	Certificate references as {key, value} — the certs must already be installed via install_certificate.
46	key, nesting level 7	enum	ca_certclient_keyclient_certcert_key_password	ca_cert	Certificate role.
47	value, nesting level 7	string	—	wifi_ca_cert	Installed certificate reference name.
48	protocol, nesting level 6	enum	WPA3_Enterprise_CCMPWPA3_Enterprise_CCMP_256WPA3_Enterprise_GCMP_128WPA3_Enterprise_GCMP_256_SHA256WPA3_Enterprise_GCMP_256_SUITEB_192	WPA3_Enterprise_CCMP	WPA3-Enterprise protocol suite.

Request Semantics

• CREATE vs MODIFY. CREATE adds a new profile (fails 18 if the essid exists); MODIFY updates an existing profile matched by essid (fails 15 if not found). The device enforces a maximum number of saved profiles — exceeding it returns 19; delete unused profiles with delete_wifi_profile. For Enterprise TLS, the ca_cert / client_cert / client_key referenced in certificate must already be installed via install_certificate.
• Credentials are write-only — mask them. Supply passwords, passphrases, and identities in the request (the examples carry sample values); the device never echoes them — set_wifi's response carries no credentials, and get_wifi returns stored secrets masked.
• Enterprise inner authentication. For ttls and peap, innerAuthentication must be mschapv2 and defaults to mschapv2 when omitted; for tls it is not applicable and can be omitted, as the tls variants on this page do.
• IPv4 only, DHCP only. In the current API version, set_wifi supports IPv4 with DHCP assignment only. The ipv4Configuration static fields (ipAddress / subnetMask / gateway / dnsServer) are modeled in the schema but not supported yet (planned for a future release), and IPv6 is not available. Use enableDhcp: true.

Response Payload

set_wifi returns a status-only envelope — command, requestId, apiVersion, and response. There is no configuration echo and no credential in the response; to confirm the saved profile, follow up with get_wifi.

Example

Response payload

{

"command": "set_wifi",

"requestId": "abc123",

"apiVersion": "V1.1",

"response": {

"code": 0,

"description": "Success"

}

}

Schema

Response payload

* required— not applicableColored badge = JSON type

#	Field	Type	Enum / Units	Example	Description
1	command*	string	—	set_wifi	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	response*	object	—	—	Status-only result — set_wifi echoes no configuration and no credentials.
5	code*, nesting level 2	integer	0–101	0	0 = Success; non-zero = error. Required by the contract. See Response Codes below.
6	description*, nesting level 2	string	—	Success	Human-readable status.

Response Codes

set_wifi 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 profile was created or modified.
2	Invalid payload (IOT_ERROR_INVALID_PAYLOAD) — the JSON is malformed or has invalid field values. Validate against the schema and correct.
15	WIFI Error - SSID not found (IOT_ERROR_SSID_NOT_FOUND) — a MODIFY targeted an essid that is not saved. Verify the name or CREATE it first.
17	WIFI Error - SSID missed (IOT_ERROR_SSID_MISSED) — the required essid field is missing from the payload.
18	WIFI Error - SSID already exist (IOT_ERROR_SSID_ALREADY_EXIST) — a CREATE used an essid that already exists. Use MODIFY, or delete the existing profile first.
19	WIFI Error - SSID count overflow (IOT_ERROR_SSID_LIMIT_OVERFLOW) — the saved-profile limit is reached. Delete an unused profile with delete_wifi_profile.
20	Wifi is not supported (IOT_ERROR_WIFI_INTER_NOT_SUPPORTED) — the device has no Wi-Fi interface; use Ethernet.
23	Invalid enum value (IOT_ERROR_INVALID_ENUM) — a field (e.g. operation, securityType, authentication) is outside its allowed set.
101	Default error — generic catch-all.

Examples

Publish a set_wifi request; the device replies with the status-only envelope shown under Response Payload. Every contract example is in the Profile scenario dropdown under Request Payload:

• Create WPA2 personal and Modify WPA2 personal — a pre-shared key.
• Set preferred AP — a partial MODIFY that needs only operation plus accessPoint.{isPreferred, essid}.
• Create WPA2 enterprise TLS / TTLS / PEAP and Create WPA3 enterprise TLS / TTLS / PEAP — installed certificates referenced as {key, value}, an EAP authentication method and a protocol; the TTLS and PEAP variants add innerAuthentication.

Notes and Caveats

connect: true can sever the control session

accessPoint.connect: true disconnects the currently connected profile and connects to the target ESSID. If the reader manages itself over the same Wi-Fi that carries its MQTT/MDM session, switching to a different network drops the control channel and can strand the device. When managing a reader over Wi-Fi, use connect: false (save without switching), and undo an unwanted profile with delete_wifi_profile rather than connecting onto it.

Because the response is status-only, verify the result with get_wifi — check that the profile was saved (and its isPreferred / accessPoint.status). For the concept-level view, see Network Configuration.

Related: 📕 Network Configuration · 📕 get_wifi · 📕 delete_wifi_profile · 📕 install_certificate · 📕 Response Codes