---
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: EAPMethod;
    caCertificate?: string;
    clientCertificate?: string;
    clientKey?: string;
    clientCertificatePassword?: string;
}

type EAPMethod = 'PEAP' | 'TLS' | 'TTLS';

```

#### Params

| Name                                | Type                    | Required         | Description                                                                       |
|-------------------------------------|-------------------------|------------------|-----------------------------------------------------------------------------------|
| `details`                           | `CertificateEapDetails` |  <div>Yes</div>  | The certificate details.                                                          |
| `details.type`                      | `EAPMethod`             |  <div>Yes</div>  | The type of the certificate is for.                                               |
| `details.caCertificate`             | `string \| undefined`   |  <div>No</div>   | The CA certificate in PEM format. Required for 'PEAP' and 'EAP-TTLS'.             |
| `details.clientCertificate`         | `string \| undefined`   |  <div>No</div>   | The client certificate in PEM format. Required for 'EAP-TLS'.                     |
| `details.clientKey`                 | `string \| undefined`   |  <div>No</div>   | The private key for the client certificate in PEM format. Required for 'EAP-TLS'. |
| `details.clientCertificatePassword` | `string \| undefined`   |  <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: '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: '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;
    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.type}, IP: ${iface.localAddress ?? 'Unknown'}, 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 />

### sendUdp()

The `sendUdp()` method sends a raw UDP datagram to the specified IP address and port.
This is a low-level network primitive that can be used for protocols like Wake-on-LAN.

```ts expandable
sendUdp(ip: string, port: number, data: number[]): Promise<void>;
```

#### Params

| Name   | Type       | Required         | Description                                                                                                           |
|--------|------------|------------------|-----------------------------------------------------------------------------------------------------------------------|
| `ip`   | `string`   |  <div>Yes</div>  | The destination IP address. Use `'255.255.255.255'` for broadcast.                                                    |
| `port` | `number`   |  <div>Yes</div>  | The destination UDP port number (1-65535).                                                                            |
| `data` | `number[]` |  <div>Yes</div>  | The payload as a byte array. Each element must be an integer between 0 and 255. Maximum 1500 elements (Ethernet MTU). |

#### Return value

A promise that resolves when the UDP packet has been sent.

#### Possible errors


- If the parameters are invalid.
- If the device does not support sending UDP packets.

#### Example

```ts
// Send a Wake-on-LAN magic packet
await sos.management.network.sendUdp('255.255.255.255', 9, [0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, ...]);
```

<Separator />

### sendWakeOnLan()

The `sendWakeOnLan()` method sends a Wake-on-LAN magic packet to wake a device with the given MAC address.
The target device must have Wake-on-LAN enabled and be on the same local network.

Internally, this generates a 102-byte magic packet (6×0xFF + 16× MAC address) and sends it
as a UDP broadcast to `255.255.255.255` on port 9 via `sendUdp()`.

```ts expandable
sendWakeOnLan(macAddress: string): Promise<void>;
```

#### Params

| Name         | Type     | Required         | Description                                                                                                       |
|--------------|----------|------------------|-------------------------------------------------------------------------------------------------------------------|
| `macAddress` | `string` |  <div>Yes</div>  | The MAC address of the target device. Accepted formats: `AA:BB:CC:DD:EE:FF`, `AA-BB-CC-DD-EE-FF`, `AABBCCDDEEFF`. |

#### Return value

A promise that resolves when the magic packet has been sent.

#### Possible errors


- If the MAC address format is invalid.
- If the device does not support sending UDP packets.

#### Example

```ts
// Wake a device by its MAC address
await sos.management.network.sendWakeOnLan('AA:BB:CC:DD:EE:FF');
```

<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
interface INetworkInfo {
    localAddress: string;
    ethernetMacAddress: string;
    wifiMacAddress: string;
    activeInterface: NetworkInterface;
    gateway?: string;
    netmask?: string;
    dns?: string[];
    interfaceName?: string;
    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';

```