/pps/services/wifi/control

The WLAN service listens for commands on this object

Publishers
WLAN service; any app
Subscribers
Any app
Note: This type of object is known as a server object, a special PPS object designed for point-to-point communication between a server and one or more clients. For details, see "Server objects" in the Persistent Publish/Subscribe Developer's Guide.

Message/response format

Commands sent to the /pps/services/wifi/control object are of the form:

msg::command_string\nid::ID_number\ndat:json:{JSON_data}

Responses always reflect the command_string and ID_number that were sent in the message, along with any errors:

res::command_string\nid::ID_number\ndat:json:{JSON_data}\nerr::error_description

Commands

The control object accepts the following commands:

Command Values for dat field Description
Scan n/a

Request a connection scan. Note that scan results are not returned immediately. When the results are available, they're updated in the /pps/services/wifi/status object (or can be retrieved with the scan_results command).
scan_results n/a

Request the last available scan results. This command doesn't initiate a new scan. See the /pps/services/wifi/status object for details.
wifi_power One of the following:
  • on (station power on)
  • off (station power off)
  • graceful_shutdown (WLAN standby state)
  • low_power (regular WLAN operation mode)
  • default (WLAN default power mode)
 Configure WLAN radio power modes.
Wnet netID

Query for a saved profile with specified network ID. Note that password-type attributes are returned with null entries for security purposes.
wnet_delete netID

Delete the specified profile. If the profile is the currently connected network, the network will be disconnected and the profile deleted.
wnet_disable netID

Disable the specified saved profile. If the profile is the currently connected network, the network will be disconnected.
wnet_disableall n/a Disable all saved profiles.
wnet_enable netID Enable the specified saved profile. This may trigger a new connection to the enabled profile.
wnet_enableall n/a Enable all saved profiles.
wnet_new {JSON_profile_attributes} (See "Profile attributes" below.) Add a new profile to the list of saved networks.
wnet_select netID

Select the specified saved profile for connection, enabling the specified profile and disabling all other profiles. If a different profile is connected, it will be disconnected from that network.
wnet_update netID{JSON_profile_attributes}

Update the attributes of an existing network profile. If the profile is the currently connected network, the network will be disconnected and the profile updated.

Note that profile must be pushed again in the dat (can be first queried), even for those attributes that aren't modified. The timestamp of the provided profile must match the existing profile being updated to ensure it's the same network that the client wants updated (otherwise, EINVAL is returned).

To update a protected attribute (i.e., password, psk, or wep_key0), precede the attribute name with new. For example, to change psk, send the field newpsk.
Note: The wnet_update doesn't affect the _enable attribute. To change _enable, use wnet_enable or wnet_disable.

Profile attributes

Attribute Values Description
ap_handover 0 | 1

Specify whether to perform handovers between access points. If set to 1, the profile will use roaming.
auth_alg OPEN Authentication type for a WEP network.
band_select 0 | 1 | 2 Indicates which band the profile should connect on:
  • 0 = dual
  • 1 = 2.4G only
  • 2 = 5G only
ca_cert file_path Full path to the server certificate.
ca_path dir_path Full path to the certificate store.
client_cert file_path Full path to the client certificate.
eap
  • AKA (Authentication and Key Agreement)
  • FAST (Flexible Authentication via Secure Tunneling)
  • PEAP (Protected Extensible Authentication Protocol)
  • SIM (Subscriber Identity Module)
  • TLS (Transport Layer Security)
  • TTLS (Tunneled Transport Layer Security)
 Type of EAP used by this network.
_editability
  • editable
  • credentials_only
  • uneditable
 Controls whether the user can edit the profile.
_enable 0 | 1 Determines whether the profile is enabled (1) or disabled and won't be used (0).
enterprise true | false Indicates whether this is an enterprise profile (EMA/BDS).
group_id alphanumeric_id

An ID value used by wpa_pps clients to identify the group this profile belongs to. This is not used by wpa_pps itself.
identity alphanumeric_id Username for the EAP session.
key_mgmt
  • NONE
  • WPA-EAP
  • WPA-PSK
 Security type used by the network.
_name alphanumeric_name Arbitrary name of the profile.
owner
  • BRIDGE
  • CARRIER_MNGR
  • EMA
  • UI
  • WPS

Indicates which client owns the profile. This field is used to determine the precedence for new profiles added and for profile priority.
pac_file file_path Path to the PAC file.
password alphanumeric_password

The password for the EAP session. Note that this is a protected attribute.
phase1 FAST_PROVISIONING=1 Authenticates using PAC and sets up tunnel key.
phase2
  • MSCHAPV2 (Microsoft Challenge Handshake Authentication Protocol version 2)
  • GTC (Generic Token Card)
 Authentication method for the inner tunnel of an EAP connection.
pin number PIN for the EAP-SIM or EAP-AKA connection.
private_key file_path Full path to the client private key.
private_key_passwd alphanumeric_password Password for the client private key.
psk alphanumeric_or_hex

The WPA passkey. Note that this is a protected attribute.
_saved 0 | 1
Controls how the UI recognizes the profile:
  • 0 = UI won't display the profile
  • 1 = Profile is "saved" and recognized by the UI as valid
scan_ssid 0 | 1
Controls whether WLAN will do active scans to locate the network:
  • 0 = No active scans
  • 1 = Active scans (profile is marked "hidden")
ssid alphanumeric_name Name of the network to connect to.
_user_enable 0 | 1

Determines whether the profile is enabled by the user (1) or is disabled and won't be used (0).
_visibility visible Determines whether the profile is visible to the user.
wep_key0 hex_characters

WEP key used by this network. Note that this is a protected attribute.

Examples

  1. If we want to observe responses from the WLAN service, we need to force the shell to keep the file descriptor open (because this is a server object). First we send a wnet_new command to set up a new profile: 
    (exec 3<>/pps/services/wifi/control && cat >&3 && cat <&3)<<END
msg::wnet_new
id::123
dat:json:{"ssid":"wifi_test","key_mgmt":"NONE"}
END
    The control object might now look like this: 
    @control
res::wnet_new
id::123
dat::3
  2. We can now use the netID that was returned (i.e., 3) in further commands, such as wnet_select: 
    (exec 3<>/pps/services/wifi/control && cat >&3 && cat <&3)<<END
msg::wnet_select
id::124
dat::3
END