wifi

The sos.management.wifi API groups together methods for managing Wi-Fi setup on the device.

Internal state

The sos.management.wifi API may be in 3 states:

• disabled - Wi-Fi is disabled. This state is persistent between reboots.
• client - Wi-Fi is in the client state, i.e., it is capable of connecting to a network, similarly to a phone or laptop. This state is persistent between reboots with all of its configuration.
• ap - Wi-Fi is in access point state, i.e., it itself becomes a Wi-Fi network that others can connect to. This state persists between reboots and will be switched to the DISABLED state.

You can use enableClient()/disable() method to enable or disable the client state, or you can use enableAP()/disableAP() to turn on or off the ap state. It is not possible to go from client state to ap state directly, the state has to be disabled first.

Wi-Fi Management Capabilities

Capability	Description
WIFI	If device supports Wi-Fi setup connection
WIFI_SCAN	If device supports Wi-Fi scanning
WIFI_AP	If device supports Wi-Fi Access Point setup
WIFI_STRENGTH	If device supports Wi-Fi signal strength measurement
WIFI_COUNTRY	If device supports Wi-Fi country code configuration

If you want to check if the device supports those capabilities, use sos.management.supports().

Methods

connect()

The connect() method connects the device to a specified Wi-Fi network.

danger

On Tizen, make sure that the connection credentials are correct. If the device fails to connect, it will not retry automatically. Make sure that you have a backup script or a checking mechanism in place, which will allow you to recover from the situation if the connection fails.

warning

Connecting to an OPEN Wi-Fi network for Tizen and WebOS is different.

• For Tizen, make sure that the password is an empty string ('') and in the options you have selected OPEN as encryption type.
• For WebOS, you can pass undefined as the password parameter.

info

The security type of Wi-Fi is mandatory for Tizen.

connect(ssid: string, password?: string, options?: IWifiConnectOptions): Promise<void>;

Params

Name	Type	Required	Description
ssid	string	Yes	Name of the network, max. allowed length is 32 characters.
password	string	No	Password of the device, must be between 8 and 32 characters.
options	IWifiConnectOptions	No	Additional options for the connection.
options.hidden	boolean	No	If the network is hidden, defaults to false.
options.securityType	WifiEncryptionType	No	The security type of the network.
options.eap	{ method: EAPMethod; identity: string; anonymousIdentity?: string | undefined; passphrase: string; phase2Auth?: EAPPhase2Auth | undefined; useCACert?: boolean | undefined; }	No	Authentication details for networks that require EAP.
options.eap.method	EAPMethod	Yes	The type of EAP authentication to use.
options.eap.identity	string	Yes	Username or identity for authentication.
options.eap.passphrase	string	Yes	Password or passphrase for authentication.
options.eap.phase2Auth	EAPPhase2Auth	No	Secondary authentication method, if required by the EAP method. Not needed for TLS.
options.eap.useCACert	boolean	No	Whether to use a CA certificate for authentication. Not needed for TLS.

Return value

A promise that resolves when the connection is established or if the connection fails.

Possible errors

• Error If the Wi-Fi state is not in the client state.
• Error If the ssid is not a string or is empty.
• Error If the password is not a string or is empty (if required).
• Error If the options is not an object or does not match the expected schema.
• Error If the securityType is not one of the allowed values.

Example

// To connect to an open Wi-Fi network, e.g., WebOS
await sos.management.wifi.connect('MyOpenNetwork');

// To connect an open Wi-Fi network with an empty password (Tizen)
await sos.management.wifi.connect('MyOpenNetwork', '', { securityType: 'OPEN' });

// If the network is hidden
await sos.management.wifi.connect('MyOpenNetwork', undefined, { hidden: true });

// To connect to an encrypted Wi-Fi network with WPA2 security
await sos.management.wifi.connect('MyEncryptedNetwork', 'my-password', { securityType: 'WPA2' });

// To connect to an enterprise Wi-Fi network using EAP
await sos.management.wifi.connect('MyEnterpriseNetwork', undefined, {
  securityType: '802.1X_EAP',
  eap: {
    method: 'PEAP',
    identity: 'my-username',
    passphrase: 'my-password',
    phase2Auth: 'MSCHAPV2',
    useCACert: false,
  },
});

disable()

The disable() method switches the Wi-Fi state to disabled and disconnects from the connected Wi-Fi.

All previously configured networks will be forgotten.

disable(): Promise<void>;

Return value

A promise that resolves when the Wi-Fi is disabled.

Possible errors

Error If the Wi-Fi state is in the client or ap state.

Example

await sos.management.wifi.disable();

disconnect()

The disconnect() method disconnects the device from the Wi-Fi network. This method will not disable the Wi-Fi client; it will just disconnect from the currently connected network.

disconnect(): Promise<void>;

Return value

A promise that resolves when the device is disconnected from the network.

Possible errors

Error If the Wi-Fi state is not in the client state.

Example

await sos.management.wifi.disconnect();

enableAP()

Sets Wi-Fi to AP state, meaning the device will become a Wi-Fi network that other devices can connect to. It will run in WPA-Personal mode. As such, it requires an SSID (network name) and a password that different devices will use to connect.

note

• This method is only available on the Linux platform.
• It is not allowed to call this method when in the CLIENT state. You must first switch to the DISABLED state.
• Before calling this method, make sure the device supports Wi-Fi AP via sos.management.supports("WIFI_AP")

enableAP(ssid: string, password: string): Promise<void>;

Params

Name	Type	Required	Description
ssid	string	Yes	Name of the network, max. allowed length is 32 characters.
password	string	Yes	Password of the device, must be between 8 and 32 characters.

Return value

A promise that resolves when the Wi-Fi is enabled in AP mode.

Possible errors

Error If the Wi-Fi state is in the client state.

GitHub Example

• Example applet with Wi-Fi access point

enableClient()

The enabledClient() method switches the Wi-Fi state from disabled to client state.

enableClient(): Promise<void>;

Return value

A promise that resolves when the Wi-Fi is enabled in client mode.

Possible errors

Error If the Wi-Fi state is in the ap state.

getConnectedTo()

The getConnectedTo() method returns the network the device is currently connected to.

getConnectedTo(): Promise<IWifiDevice | null>;

Return value

An object containing the SSID, whether the network is encrypted, and the signal strength. If the device is not connected to any network, it returns null.

Possible errors

Error If the Wi-Fi state is not in the client state.

Example

// To get the network the device is currently connected to
const connectedTo = await sos.management.wifi.getConnectedTo();
console.log(`Connected to SSID: ${connectedTo?.ssid}, Strength: ${connectedTo?.strength}`);

getCountry()

The getCountry() method returns the 2-letter country code to which Wi-Fi regulations the device adheres. Different countries may have different regulations when it comes to the Wi-Fi networks. Under normal circumstances, everything should work with the default settings. However, if you experience any problems, you might want to try changing the Wi-Fi country configuration to your country.

getCountry(): Promise<string | null>;

Return value

A promise that resolves to the 2-letter country code from the ISO 3166 standard, or null if not set.

Possible errors

Error If the Wi-Fi state is not in the client state.

Example

const countryCode = await sos.management.wifi.getCountry();
console.log(`Current Wi-Fi country code is: ${countryCode}`); // e.g. 'US', 'CZ', etc.

isAPEnabled()

The isAPEnabled() method checks whether the Wi-Fi is in ap state.

isAPEnabled(): Promise<boolean>;

Return value

If AP mode is enabled.

isClientEnabled()

The isClientEnabled() method checks whether the Wi-Fi is in client state.

isClientEnabled(): Promise<boolean>;

Return value

if client mode is enabled.

Possible errors

Error If the Wi-Fi state is in the ap state.

Example

const isClientEnabled = await sos.management.wifi.isClientEnabled();
if (!isClientEnabled) {
	await sos.management.wifi.enableClient();
}

on()

The on() method sets up a listener, which is called whenever the specified event occurs.

on(event: WifiEvent, listener: () => void): void;

Params

Name	Type	Required	Description
event	WifiEvent	Yes	The event for which to set up the listener.
listener	() => void	Yes	The listener function to call when the event occurs.

Return value

Resolves when the listener is set up.

Example

sos.management.wifi.on(WifiEvent.CLIENT_ENABLED, () => {
  console.log('Wi-Fi client is enabled');
});

once()

The on() method sets up a one-time listener, which is called whenever the specified event occurs.

once(event: WifiEvent, listener: () => void): void;

Params

Name	Type	Required	Description
event	WifiEvent	Yes	The event for which to set up the listener.
listener	() => void	Yes	The listener function to call when the event occurs.

Return value

Resolves when the listener is set up.

Example

sos.management.wifi.once(WifiEvent.CLIENT_CONNECTED, () => {
	console.log('Wi-Fi client is connected');
});

removeAllListeners()

The removeAllListeners() method removes all listeners for a specified event or all events.

removeAllListeners(event?: WifiEvent): void;

Params

Name	Type	Required	Description
event	WifiEvent	No	The event for which to remove all listeners. If not specified, all listeners for all events will be removed.

Return value

Resolves when all listeners are removed.

removeListener()

The removeListener() method removes a listener previously set up by on() or once() methods.

removeListener(event: WifiEvent, listener: () => void): void;

Params

Name	Type	Required	Description
event	WifiEvent	Yes	The event for which to remove the listener.
listener	() => void	Yes	The listener function to remove.

Return value

Resolves when the listener is removed.

scanDevices()

The scanDevices() method initializes a new network scan and available networks.

scanDevices(): Promise<IScannedDevice[]>;

Return value

A promise that resolves to an array of scanned devices.

Possible errors

Error If the Wi-Fi state is not in the client state.

Example

const scannedDevices = await sos.management.wifi.scanDevices();
scannedDevices.forEach(device => {
	console.log(`Found Wi-Fi network: ${device.ssid}, Encrypted: ${device.encrypted}`);
});

setCountry()

The setCountry() method sets the 2-letter country code for the Wi-Fi settings. Different countries may have different regulations when it comes to the Wi-Fi networks. Under normal circumstances, everything should work with the default settings. However, if you experience any problems, you might want to try changing the Wi-Fi country configuration to your country.

note

This method is only available on the Linux platform.

setCountry(countryCode: string): Promise<void>;

Params

Name	Type	Required	Description
countryCode	string	Yes	2-letter country code from the ISO 3166 standard.

Return value

A promise that resolves when the country code is set.

Possible errors

Error If the Wi-Fi state is not in the client state.

Example

// To set the country code to the United States
await sos.management.wifi.setCountry('US');