---
sidebar_position: 0
---

# network

The `sos.management.network` API groups together networking methods. For Wi-Fi setup, use the [Wi-Fi API](https://developers.signageos.io/sdk/sos_management/wifi).

<details>
    <summary>Network Management Capabilities</summary>
		| Capability | Description |
		|:------------|:-------------|
		| `NETWORK_INFO` | If device supports returning network information |

		If you want to check if the device supports this capability, use [`sos.management.supports()`](https://developers.signageos.io/sdk/sos_management/#supports).
</details>

## Methods

### disableInterface()

The `disableInterface()` turns off a selected network interface.

:::warning
Don't use this method to disable Wi-Fi. Use [Wi-Fi API](https://developers.signageos.io/sdk/sos_management/wifi) to turn Wi-Fi on/off.
:::

```ts expandable
disableInterface(interfaceName: string): Promise<void>;
```

#### Params

| Name            | Type     | Required         | Description                                                                                          |
|-----------------|----------|------------------|------------------------------------------------------------------------------------------------------|
| `interfaceName` | `string` |  <div>Yes</div>  | The interface name which can be retrieved from the list of interfaces returned by `listInterfaces()` |

#### Return value

A promise that resolves when the network interface is disabled.

#### Possible errors


- If the interface name is invalid.
- If the device does not support network management.

#### Example

```ts
await sos.management.network.disableInterface('eth0');
```

<Separator />

### importCertificate()

The `importCertificate()` method imports a certificate to the device. The certificate can then be used when connecting to a Wi-Fi network using the [Wi-Fi API and EAP authentification](https://developers.signageos.io/sdk/sos_management/wifi).

:::note
- This API supports only PEM formatted certificates.
- Only EAP certificates are supported for now.
:::

```ts expandable
importCertificate(details: CertificateEapDetails): Promise<void>;
// show-more
interface CertificateEapDetails {
    type: EAPType;
    caCertificate?: string;
    clientCertificate?: string;
    clientKey?: string;
    clientCertificatePassword?: string;
}

type EAPType = 'EAP-TLS' | 'PEAP' | 'EAP-TTLS';

```

#### Params

| Name                                | Type                    | Required         | Description                                                                       |
|-------------------------------------|-------------------------|------------------|-----------------------------------------------------------------------------------|
| `details`                           | `CertificateEapDetails` |  <div>Yes</div>  | The certificate details.                                                          |
| `details.type`                      | `EAPType`               |  <div>Yes</div>  | The type of the certificate is for.                                               |
| `details.caCertificate`             | `string`                |  <div>No</div>   | The CA certificate in PEM format. Required for 'PEAP' and 'EAP-TTLS'.             |
| `details.clientCertificate`         | `string`                |  <div>No</div>   | The client certificate in PEM format. Required for 'EAP-TLS'.                     |
| `details.clientKey`                 | `string`                |  <div>No</div>   | The private key for the client certificate in PEM format. Required for 'EAP-TLS'. |
| `details.clientCertificatePassword` | `string`                |  <div>No</div>   | The password for the private key, if it's encrypted. Optional.                    |

#### Return value

A promise that resolves when the certificate is imported.

#### Possible errors


- If the certificate details are invalid.
- If the device does not support certificate import.

#### Example

```ts
// Importing an EAP-TLS certificate
const certDetails = {
  type: 'EAP-TLS',
  caCertificate: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----',
  clientCertificate: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----',
  clientKey: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----',
  clientCertificatePassword: 'your_password', // if the key is encrypted
};
await sos.management.network.importCertificate(certDetails);

// Importing a PEAP certificate
const certDetailsEapPeap = {
  type: 'PEAP',
  caCertificate: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----',
};
await sos.management.network.importCertificate(certDetailsEapPeap);

// Importing an EAP-TTLS certificate
const certDetailsEapTtls = {
  type: 'EAP-TTLS',
  caCertificate: '-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----',
};
await sos.management.network.importCertificate(certDetailsEapTtls);
```

<Separator />

### listInterfaces()

The `listInterface()` method returns a list of all network interfaces, and their information like MAC address, IP address, etc.
Wi-Fi connection strength is described as a percentage in the range from 0 to 100, linearly converted from dBm -90 to -30, respectively, based on the platform.

```ts expandable
listInterfaces(): Promise<INetworkInterface[]>;
// show-more
interface INetworkInterface {
    type: NetworkInterface;
    name: string;
    macAddress: string;
    localAddress?: string;
    gateway?: string;
    netmask?: string;
    dns?: string[];
    disabled?: boolean;
    /**
     * Number in range from 0 to 100 (percentage)
     * mapped from -90 dBm unusable signal
     * to -30 dBm excellent signal.
     */
    wifiStrength?: number;
    wifiSsid?: string;
}

type NetworkInterface = 'wifi' | 'ethernet';

```

#### Return value

Resolves to an array of network interfaces with their information.

#### Example

```ts
const interfaces = await sos.management.network.listInterfaces();
interfaces.forEach((iface) => {
   console.log(`Interface: ${iface.name}, IP: ${iface.ipAddress}, MAC: ${iface.macAddress}`);
});
```

:::note[GitHub Example]

- [ Applet Example with Network Interfaces](https://github.com/signageos/applet-examples/tree/master/examples/management-js-api/network)

:::

<Separator />

### setDHCP(interfaceName)

The `setDHCP()` method configures a selected network interface to use DHCP.

:::warning
Wi-Fi interface can be configured with this method, but it has to be first enabled via the [Wi-Fi API](https://developers.signageos.io/sdk/sos_management/wifi#enableclient).
:::

```ts expandable
setDHCP(interfaceName: string): Promise<void>;
```

#### Params

| Name            | Type     | Required         | Description                                                                                          |
|-----------------|----------|------------------|------------------------------------------------------------------------------------------------------|
| `interfaceName` | `string` |  <div>Yes</div>  | The interface name which can be retrieved from the list of interfaces returned by `listInterfaces()` |

#### Return value

A promise that resolves when the network interface is set to use DHCP.

#### Example

```ts
await sos.management.network.setDHCP('eth0');
```

<Separator />

### setManual(interfaceName, options)

The `setManual()` method manually configures a network interface.

:::warning
Wi-Fi interface can be configured with this method, but it has to be first enabled via the [Wi-Fi API](https://developers.signageos.io/sdk/sos_management/wifi#enableclient).
:::

```ts expandable
setManual(interfaceName: string, options: INetworkOptions): Promise<void>;
// show-more
interface INetworkOptions {
    localAddress: string;
    gateway: string;
    netmask: string;
    dns: string[];
}

```

#### Params

| Name                   | Type              | Required         | Description                                                                                          |
|------------------------|-------------------|------------------|------------------------------------------------------------------------------------------------------|
| `interfaceName`        | `string`          |  <div>Yes</div>  | The interface name which can be retrieved from the list of interfaces returned by `listInterfaces()` |
| `options`              | `INetworkOptions` |  <div>Yes</div>  | The network configuration options.                                                                   |
| `options.localAddress` | `string`          |  <div>Yes</div>  | The local IP address to be set.                                                                      |
| `options.gateway`      | `string`          |  <div>Yes</div>  | The gateway IP address to be set.                                                                    |
| `options.netmask`      | `string`          |  <div>Yes</div>  | The netmask to be set.                                                                               |
| `options.dns`          | `string[]`        |  <div>Yes</div>  | The DNS server array of IP addresses to be set.                                                      |

#### Return value

A promise that resolves when the network is set.

#### Possible errors


- If the network options are invalid.
- If the device does not support network management.

<Separator />

### ~getActiveInfo()~

:::danger Deprecated

This method was deprecated. Use `sos.management.network.listInterfaces()` instead.

:::

```ts expandable
getActiveInfo(): Promise<INetworkInfo>;
// show-more
/**
 * @deprecated use `INetworkInterface` instead
 */
interface INetworkInfo {
    localAddress: string;
    ethernetMacAddress: string;
    wifiMacAddress: string;
    activeInterface: NetworkInterface;
    gateway?: string;
    netmask?: string;
    dns?: string[];
    interfaceName?: string;
    /**
     * Number in range from 0 to 100 (percentage)
     * mapped from -90 dBm unusable signal
     * to -30 dBm excellent signal.
     */
    wifiStrength?: number;
    wifiSsid?: string;
}

type NetworkInterface = 'wifi' | 'ethernet';

```

<Separator />

### ~setDHCP(networkInterface)~

:::danger Deprecated

This method was deprecated. Use `sos.management.network.setDHCP(interfaceName)` instead.

:::

```ts expandable
setDHCP(networkInterface: NetworkInterface): Promise<void>;
// show-more
type NetworkInterface = 'wifi' | 'ethernet';

```

<Separator />

### ~setManual(options)~

:::danger Deprecated

This method was deprecated. Use `sos.management.network.setManual(interfaceName, options)` instead.

:::

```ts expandable
setManual(options: INetworkOptionsLegacy): Promise<void>;
// show-more
interface INetworkOptionsLegacy {
    interface: NetworkInterface;
    localAddress: string;
    gateway: string;
    netmask: string;
    dns: string[];
}

type NetworkInterface = 'wifi' | 'ethernet';

```