---
sidebar_position: 0
---

# 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.

<details>
    <summary>Wi-Fi Management Capabilities</summary>
		| 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()`](https://developers.signageos.io/sdk/sos_management/#supports).
</details>

## 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.
:::

```ts expandable
connect(ssid: string, password?: string, options?: IWifiConnectOptions): Promise<void>;
// show-more
interface IWifiConnectOptions {
    hidden?: boolean;
    securityType?: WifiEncryptionType;
}

type WifiEncryptionType = 'OPEN' | 'WEP' | 'WPA2' | 'WPA2_WPA_MIXED' | 'WPA3' | '802.1X_EAP';

```

#### Params

| Name                   | Type                  | Required         | Description                                                  |
|------------------------|-----------------------|------------------|--------------------------------------------------------------|
| `ssid`                 | `string`              |  <div>Yes</div>  | Name of the network, max. allowed length is 32 characters.   |
| `password`             | `string`              |  <div>No</div>   | Password of the device, must be between 8 and 32 characters. |
| `options`              | `IWifiConnectOptions` |  <div>No</div>   | Additional options for the connection.                       |
| `options.hidden`       | `boolean`             |  <div>No</div>   | If the network is hidden, defaults to `false`.               |
| `options.securityType` | `WifiEncryptionType`  |  <div>No</div>   | The security type of the network.                            |

#### 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

```ts
// 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' });
```

<Separator />

### 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.

```ts expandable
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

```ts
await sos.management.wifi.disable();
```

<Separator />

### 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.

```ts expandable
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

```ts
await sos.management.wifi.disconnect();
```

<Separator />

### 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")`
:::

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

#### Params

| Name       | Type     | Required         | Description                                                  |
|------------|----------|------------------|--------------------------------------------------------------|
| `ssid`     | `string` |  <div>Yes</div>  | Name of the network, max. allowed length is 32 characters.   |
| `password` | `string` |  <div>Yes</div>  | 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.

:::note[GitHub Example]

- [ Example applet with Wi-Fi access point](https://github.com/signageos/applet-examples/tree/master/examples/management-js-api/wifi-access-point)

:::

<Separator />

### enableClient()

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

```ts expandable
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.

<Separator />

### getConnectedTo()

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

```ts expandable
getConnectedTo(): Promise<IWifiDevice | null>;
// show-more
interface IWifiDevice {
    ssid: string;
    strength?: number;
    encrypted?: boolean;
}

```

#### 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

```ts
// 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}`);
```

<Separator />

### 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.

```ts expandable
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

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

<Separator />

### isAPEnabled()

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

```ts expandable
isAPEnabled(): Promise<boolean>;
```

#### Return value

If AP mode is enabled.

<Separator />

### isClientEnabled()

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

```ts expandable
isClientEnabled(): Promise<boolean>;
```

#### Return value

if client mode is enabled.

#### Possible errors

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

#### Example

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

<Separator />

### on()

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

```ts expandable
on(event: WifiEvent, listener: () => void): void;
// show-more
enum WifiEvent {
    /**
     * Wi-Fi was set to CLIENT state.
     */
    CLIENT_ENABLED = "client_enabled",
    /**
     * Wi-Fi is in CLIENT state and have connected to a network.
     */
    CLIENT_CONNECTED = "client_connected",
    /**
     * Wi-Fi is in CLIENT state and failed to connect to a network.
     */
    CLIENT_CONNECT_REJECTED = "client_connect_rejected",
    /**
     * Wi-Fi is in CLIENT state and disconnected from a network.
     */
    CLIENT_DISCONNECTED = "client_disconnected",
    /**
     * Wi-Fi was set to AP state.
     */
    AP_ENABLED = "ap_enabled",
    /**
     * Wi-Fi was set to DISABLED state.
     */
    DISABLED = "disabled"
}

```

#### Params

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

#### Return value

Resolves when the listener is set up.

#### Example

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

<Separator />

### once()

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

```ts expandable
once(event: WifiEvent, listener: () => void): void;
// show-more
enum WifiEvent {
    /**
     * Wi-Fi was set to CLIENT state.
     */
    CLIENT_ENABLED = "client_enabled",
    /**
     * Wi-Fi is in CLIENT state and have connected to a network.
     */
    CLIENT_CONNECTED = "client_connected",
    /**
     * Wi-Fi is in CLIENT state and failed to connect to a network.
     */
    CLIENT_CONNECT_REJECTED = "client_connect_rejected",
    /**
     * Wi-Fi is in CLIENT state and disconnected from a network.
     */
    CLIENT_DISCONNECTED = "client_disconnected",
    /**
     * Wi-Fi was set to AP state.
     */
    AP_ENABLED = "ap_enabled",
    /**
     * Wi-Fi was set to DISABLED state.
     */
    DISABLED = "disabled"
}

```

#### Params

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

#### Return value

Resolves when the listener is set up.

#### Example

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

<Separator />

### removeAllListeners()

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

```ts expandable
removeAllListeners(event?: WifiEvent): void;
// show-more
enum WifiEvent {
    /**
     * Wi-Fi was set to CLIENT state.
     */
    CLIENT_ENABLED = "client_enabled",
    /**
     * Wi-Fi is in CLIENT state and have connected to a network.
     */
    CLIENT_CONNECTED = "client_connected",
    /**
     * Wi-Fi is in CLIENT state and failed to connect to a network.
     */
    CLIENT_CONNECT_REJECTED = "client_connect_rejected",
    /**
     * Wi-Fi is in CLIENT state and disconnected from a network.
     */
    CLIENT_DISCONNECTED = "client_disconnected",
    /**
     * Wi-Fi was set to AP state.
     */
    AP_ENABLED = "ap_enabled",
    /**
     * Wi-Fi was set to DISABLED state.
     */
    DISABLED = "disabled"
}

```

#### Params

| Name    | Type        | Required        | Description                                                                                                  |
|---------|-------------|-----------------|--------------------------------------------------------------------------------------------------------------|
| `event` | `WifiEvent` |  <div>No</div>  | 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.

<Separator />

### removeListener()

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

```ts expandable
removeListener(event: WifiEvent, listener: () => void): void;
// show-more
enum WifiEvent {
    /**
     * Wi-Fi was set to CLIENT state.
     */
    CLIENT_ENABLED = "client_enabled",
    /**
     * Wi-Fi is in CLIENT state and have connected to a network.
     */
    CLIENT_CONNECTED = "client_connected",
    /**
     * Wi-Fi is in CLIENT state and failed to connect to a network.
     */
    CLIENT_CONNECT_REJECTED = "client_connect_rejected",
    /**
     * Wi-Fi is in CLIENT state and disconnected from a network.
     */
    CLIENT_DISCONNECTED = "client_disconnected",
    /**
     * Wi-Fi was set to AP state.
     */
    AP_ENABLED = "ap_enabled",
    /**
     * Wi-Fi was set to DISABLED state.
     */
    DISABLED = "disabled"
}

```

#### Params

| Name       | Type         | Required         | Description                                 |
|------------|--------------|------------------|---------------------------------------------|
| `event`    | `WifiEvent`  |  <div>Yes</div>  | The event for which to remove the listener. |
| `listener` | `() => void` |  <div>Yes</div>  | The listener function to remove.            |

#### Return value

Resolves when the listener is removed.

<Separator />

### scanDevices()

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

```ts expandable
scanDevices(): Promise<IScannedDevice[]>;
// show-more
/**
 * Interface representing a scanned Wi-Fi device.
 */
interface IScannedDevice {
    ssid: string;
    encrypted: boolean;
}

```

#### 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

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

<Separator />

### 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.
:::

```ts expandable
setCountry(countryCode: string): Promise<void>;
```

#### Params

| Name          | Type     | Required         | Description                                       |
|---------------|----------|------------------|---------------------------------------------------|
| `countryCode` | `string` |  <div>Yes</div>  | 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

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