Skip to main content
Version: 6.4.2

Wi-Fi

Wi-Fi API allows you to configure Wi-Fi, if the device supports it.

warning
  • Before using this API, ensure that the device supports Wi-Fi via sos.management.supports("WIFI").
  • More info about how to check it, you can find THERE

State management

Wi-Fi can be in several states. Depending on which state it is in, its behavior will vary. The 3 possible states are:

  • DISABLED
  • CLIENT
  • AP
info

It is only allowed to switch to another state when in the DISABLED state. It is not allowed to go directly from CLIENT to AP or vice versa.

DISABLED

Wi-Fi is disabled. The DISABLED 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. CLIENT 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. AP state is not persistent and on reboot the device will be in DISABLED state.

Country settings

Different regulations apply to Wi-Fi communication in different countries. 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. See getCountry() and setCountry() methods.

All methods

MethodsDescriptionSupported since
isClientEnabled()Is in CLIENT state?4.3.0
enableClient()Switch to CLIENT state4.3.0
isAPEnabled()Is in AP state?4.3.0
enableAP()Switch to AP state4.3.0
disable()Switch to DISABLED state4.3.0
getConnectedTo()When in CLIENT state, return which network it is connected to4.3.0
connect()When in CLIENT state, connect to a network4.3.0
disconnect()When in CLIENT state, disconnect from a network4.3.0
getCountry()Get which country Wi-Fi is configured for4.3.0
setCountry()Configure Wi-Fi for a specific country4.3.0
scanDevices()When in CLIENT or AP states, scan available networks4.3.0
on()Call listener anytime an event is emitted4.3.0
once()Call listener the first time an event is emitted4.3.0
removeListener()Remove a listener previously registered via on() or once() methods4.3.0
removeAllListeners()Remove all listeners4.3.0

Events

EventDescription
client_enabledWi-Fi was set to CLIENT state
client_connectedWi-Fi is in CLIENT state and connected to a network
client_disconnectedWi-Fi is in CLIENT state and disconnected from a network
ap_enabledWi-Fi was set to AP state
disabledWi-Fi was set to DISABLED state

Examples

isClientEnabled()

Returns true, if Wi-Fi is in CLIENT state. Otherwise, returns false.

Javascript example

const isClientEnabled = await sos.management.wifi.isClientEnabled();
if (isClientEnabled) {
// do something
}

enableClient()

Sets Wi-Fi to CLIENT state, meaning it has the ability to connect to a Wi-Fi network or scan available networks in the area.

info

It is not allowed to call this method, when in AP state. You must first switch to DISABLED state.

Javascript example

await sos.management.wifi.enableClient();

isAPEnabled()

Returns true, if Wi-Fi is in AP state. Otherwise, returns false.

Javascript example

const isAPEnabled = await sos.management.wifi.isAPEnabled();
if (isAPEnabled) {
// do something
}

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 password that other devices will use to connect.

info
  • It is not allowed to call this method when in CLIENT state. You must first switch to DISABLED state.
  • Before calling this method, make sure the device supports Wi-Fi AP via sos.management.supports("WIFI_AP")
ParamTypeRequiredDescription
ssidString
Yes
Device will be visible as a Wi-Fi network with this name. Max. allowed length is 32 characters.
passwordString
Yes
Devices that wish to connect to this network will use this password. Must be between 8 and 32 characters.

Javascript example

await sos.management.wifi.enableAP("my_network", "secretPassword123#");

disable()

Sets Wi-Fi to DISABLED state. All previously configured networks will be forgotten.

Javascript example

await sos.management.wifi.disable();

getConnectedTo()

If connected to a Wi-Fi network, returns the name of the network. Otherwise, returns null.

info

It is only allowed to call this method in CLIENT state.

Javascript example

const connectedTo = await sos.management.wifi.getConnectedTo();

connect()

Connect to a network.

info

It is only allowed to call this method in the CLIENT state.

ParamTypeRequiredDescription
ssidString
Yes
Name of the network you want to connect to.
passwordString
No
Network's password.
optionsObject
No
Additional options.

Javascript example

// network without password
await sos.management.wifi.connect('network1');

// or network with password
await sos.management.wifi.connect('network2', 'password123');

// connect to a hidden network
await sos.management.wifi.connect('network3', 'password123', { hidden: true });

disconnect()

Disconnect from the network, if connected to one.

info

It is only allowed to call this method in the CLIENT state.

Javascript example

await sos.management.wifi.disconnect();

getCountry()

Get currently configured country code.

info

It is not allowed to call this method in the DISABLED state.

Javascript example

const countryCode = await sos.management.wifi.getCountry();

setCountry()

Configure Wi-Fi for country-specific regulations.

info

It is not allowed to call this method in the DISABLED state.

ParamTypeRequiredDescription
countryCodeString
Yes
2-letter country code. See this list of countries and their codes.

Javascript example

await sos.management.wifi.setCountry('ES');

scanDevices()

Get list of available Wi-Fi networks in the area.

info
  • It is only allowed to call this method in the CLIENT state.
  • Before calling this method, make sure the device supports scanning via sos.management.supports("WIFI_SCAN")

Javascript example

const devices = await sos.management.wifi.scanDevices();

on()

Call a callback everytime an event is emitted.

ParamTypeRequiredDescription
eventString
Yes
Event name. See events for valid event names.
listenerMethod
Yes
Callback that will be called everytime the given event is emitted

Javascript example

sos.management.wifi.on('client_connected', () => {
console.log('Wi-Fi is connected');
});
sos.management.wifi.on('client_disconnected', () => {
console.log('Wi-Fi is disconnected');
});

once()

Call a callback the first time an event is emitted.

ParamTypeRequiredDescription
eventString
Yes
Event name. See events for valid event names.
listenerMethod
Yes
Callback that will be called everytime the given event is emitted

Javascript example

sos.management.wifi.once('client_connected', () => {
console.log('Wi-Fi is connected');
});
sos.management.wifi.once('client_disconnected', () => {
console.log('Wi-Fi is disconnected');
});

removeListener()

Remove an event listener previously registered via on or once.

ParamTypeRequiredDescription
eventString
Yes
Event name. See events for valid event names.
listenerMethod
Yes
Callback that was previously registered

Javascript example

// first register a listener
const listener = () => {
console.log('Wi-Fi is connected');
};
sos.management.wifi.on('client_connected', listener);

// then remove it
sos.management.wifi.removeListener('client_connected', listener);

// now if client_connected is emitted, the listener callback wouldn't be called anymore

removeAllListeners()

Remove all listeners previously registered via on or once, either for a specific event or for all events.

ParamTypeRequiredDescription
eventString
No
Event name. See events for valid event names.

Javascript example

// first register a listener
sos.management.wifi.on('client_connected', () => {
console.log('Wi-Fi is connected');
});

// then remove it
sos.management.wifi.removeAllListeners('client_connected');
// now if client_connected is emitted, the listener callback wouldn't be called anymore

// next remove all listeners
sos.management.wifi.removeAllListeners();
// now if any event is emitted, no listener callbacks would be called

FAQ

  • Do I need to reboot my RPi for the Wi-Fi changes to take place?
    No, the device will automatically adapt to any saved changes

  • How can I tell if the device has successfuly connected to the network?
    Once the device starts the connecting process and sucessfully connects, 2 events will be emmited:

    1. client_enabled
    2. client_connected