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

:::info
- The security type of Wi-Fi is mandatory for Tizen.
- Please note, that Brightsign players use USB drive to read certificates for EAP authentication. For more information check our documentation [How to use Wi-Fi Enterprise](https://developers.signageos.io/docs/device/wifi-enterprise/brightsign).
:::

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

type IEAPConfig = IEAP_PEAP | IEAP_TTLS | IEAP_TLS;

interface IEAP_PEAP extends IEAPBase {
    method: 'PEAP';
    anonymousIdentity?: string;
    phase2Auth?: EAPPhase2Auth;
    useCACert: boolean;
    caCertificate?: string;
}

type EAPPhase2Auth = 'PAP' | 'MSCHAP' | 'MSCHAPV2' | 'GTC' | 'CHAP';

interface IEAPBase {
    identity: string;
    identityPassword?: string;
    domain?: string;
}

interface IEAP_TTLS extends IEAPBase {
    method: 'TTLS';
    anonymousIdentity?: string;
    phase2Auth?: EAPPhase2Auth;
    useCACert: boolean;
    caCertificate?: string;
}

interface IEAP_TLS extends IEAPBase {
    method: 'TLS';
    caCertificate: string;
    clientCertificate: string;
    privateKey: string;
    privateKeyPassword?: string;
}

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<IEAPConfig>` |  <div>No</div>   | Additional options for the connection.                                           |
| `options.hidden`                 | `boolean \| undefined`            |  <div>No</div>   | If the network is hidden, defaults to `false`.                                   |
| `options.securityType`           | `WifiEncryptionType \| undefined` |  <div>No</div>   | The security type of the network.                                                |
| `options.eap`                    | `IEAPConfig \| undefined`         |  <div>No</div>   | Authentication details for networks that require EAP.                            |
| `options.eap.method`             | `"TLS"`                           |  <div>Yes</div>  | The type of EAP authentication to use.                                           |
| `options.eap.identity`           | `string`                          |  <div>Yes</div>  | Username or identity for authentication.                                         |
| `options.eap.identityPassword`   | `string`                          |  <div>No</div>   | Identity password for authentication.                                            |
| `options.eap.anonymousIdentity`  | `string`                          |  <div>No</div>   | Anonymous identity for authentication, if required by the EAP method.            |
| `options.eap.phase2Auth`         | `EAPPhase2Auth`                   |  <div>No</div>   | Secondary authentication method, if required by the EAP method.                  |
| `options.eap.useCACert`          | `boolean`                         |  <div>Yes</div>  | Whether to use a CA certificate for authentication.                              |
| `options.eap.caCertificate`      | `string`                          |  <div>Yes</div>  | The CA certificate to use for authentication, if `useCACert` is `true`.          |
| `options.eap.clientCertificate`  | `string`                          |  <div>Yes</div>  | The client certificate to use for authentication, if required by the EAP method. |
| `options.eap.privateKey`         | `string`                          |  <div>Yes</div>  | The private key to use for authentication, if required by the EAP method.        |
| `options.eap.privateKeyPassword` | `string`                          |  <div>No</div>   | The password for the private key, if it's encrypted.                             |

#### 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
- 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 an open Wi-Fi network with an empty password
await sos.management.wifi.connect('MyOpenNetwork', undefined, { securityType: 'OPEN' });

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

// 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', 'identity-password', {
  securityType: '802.1X_EAP',
  eap: {
    method: 'PEAP',
    identity: 'my-username',
    phase2Auth: 'MSCHAPV2',
    useCACert: true,
    caCertificate: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----',
  },
});

// To connect to an enterprise Wi-Fi network using EAP-TTLS with a CA certificate
await sos.management.wifi.connect('MyEnterpriseNetwork', 'identity-password', {
  securityType: '802.1X_EAP',
  eap: {
    method: 'TTLS',
    identity: 'my-username',
    useCACert: true,
    caCertificate: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----',
  },
});
```

<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 {
    CLIENT_ENABLED = "client_enabled",
    CLIENT_CONNECTED = "client_connected",
    CLIENT_CONNECT_REJECTED = "client_connect_rejected",
    CLIENT_DISCONNECTED = "client_disconnected",
    AP_ENABLED = "ap_enabled",
    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 {
    CLIENT_ENABLED = "client_enabled",
    CLIENT_CONNECTED = "client_connected",
    CLIENT_CONNECT_REJECTED = "client_connect_rejected",
    CLIENT_DISCONNECTED = "client_disconnected",
    AP_ENABLED = "ap_enabled",
    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 {
    CLIENT_ENABLED = "client_enabled",
    CLIENT_CONNECTED = "client_connected",
    CLIENT_CONNECT_REJECTED = "client_connect_rejected",
    CLIENT_DISCONNECTED = "client_disconnected",
    AP_ENABLED = "ap_enabled",
    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 {
    CLIENT_ENABLED = "client_enabled",
    CLIENT_CONNECTED = "client_connected",
    CLIENT_CONNECT_REJECTED = "client_connect_rejected",
    CLIENT_DISCONNECTED = "client_disconnected",
    AP_ENABLED = "ap_enabled",
    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 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');
```