wifi

The sos.management.wifi API groups together methods for managing Wi-Fi.

info

Use sos.management.supports('WIFI') to check if the device supports managing Wi-Fi setup.

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 is persistent between reboots and will be switched to DISABLED state.

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

Methods

connect()

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

warning

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

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

info

Security type of Wi-Fi is mandatory for Tizen.

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

Params

Name	Type	Description
ssid	string	Name of the network, max. allowed length is 32 characters.
password (optional)	string	Password of the device, must be between 8 and 32 characters.
options (optional)	IWifiConnectOptions	Additional options for the connection, such as hidden or securityType.

Return value

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

Possible errors

The method throws an error error If the Wi-Fi state is not in the client state.

Example

// To connect on open Wi-Fi network ex. WebOS
await sos.management.wifi.connect('MyOpenNetwork');

// To connect on open Wi-Fi network with 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 on encrypted Wi-Fi network with WPA2 security
await sos.management.wifi.connect('MyEncryptedNetwork', 'my-password', { securityType: 'WPA2' });

disable()

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

All previously configured networks will be forgotten.

disable(): Promise<void>;

disconnect()

The disconnect() method disconnects the device from Wi-Fi network.

disconnect(): Promise<void>;

Possible errors

The method throws an error error If the Wi-Fi state is not in the client state.

enableAP()

The enableAP() method switches the Wi-Fi state from disabled to ap state.

info

Use sos.management.supports('WIFI_AP') to check if the device is able to be in the ap mode.

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

Params

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

Possible errors

The method throws an error error If the Wi-Fi state is in the client state.

enableClient()

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

enableClient(): Promise<void>;

Possible errors

The method throws an error error If the Wi-Fi state is in the ap state.

getConnectedTo()

The getConnectedTo() method returns a 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

The method throws an error 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 to. Different countries may have different regulations, when it comes to the Wi-Fi networks. Under normal circumstances, everything should work with default settings. However, if you experience any problems, you might want to try changing Wi-Fi country configuration to your country.

getCountry(): Promise<string | null>;

Return value

The 2-letter country code from the ISO 3166 standard, or null if not set.

Possible errors

The method throws an error error If the Wi-Fi state is not in the client state.

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

The method throws an error error If the Wi-Fi state is in the ap state.

on()

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

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

once()

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

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

removeAllListeners()

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

removeAllListeners(event?: WifiEvent): void;

removeListener()

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

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

scanDevices()

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

info

Use sos.management.supports('WIFI_SCAN') to check if the device supports scanning for devices.

scanDevices(): Promise<IScannedDevice[]>;

Possible errors

The method throws an error error If the Wi-Fi state is not in the client state.

setCountry()

The getCountry() 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 default settings. However, if you experience any problems, you might want to try changing Wi-Fi country configuration to your country.

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

Params

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

Possible errors

The method throws an error error If the Wi-Fi state is not in the client state.