network

The sos.management.network API groups together networking methods. For Wi-Fi setup, use the Wi-Fi API.

Network Management Capabilities

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

Methods

disableInterface()

The disableInterface() turns off a selected network interface.

warning

Don't use this method to disable Wi-Fi. Use Wi-Fi API to turn Wi-Fi on/off.

disableInterface(interfaceName: string): Promise<void>;

Params

Name	Type	Required	Description
interfaceName	string	Yes	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

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

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.

note

• This API supports only PEM formatted certificates.
• Only EAP certificates are supported for now.

importCertificate(details: CertificateEapDetails): Promise<void>;

Params

Name	Type	Required	Description
details	CertificateEapDetails	Yes	The certificate details.
details.type	EAPMethod	Yes	The type of the certificate is for.
details.caCertificate	string | undefined	No	The CA certificate in PEM format. Required for 'PEAP' and 'EAP-TTLS'.
details.clientCertificate	string | undefined	No	The client certificate in PEM format. Required for 'EAP-TLS'.
details.clientKey	string | undefined	No	The private key for the client certificate in PEM format. Required for 'EAP-TLS'.
details.clientCertificatePassword	string | undefined	No	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

// 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);

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.

listInterfaces(): Promise<INetworkInterface[]>;

Return value

Resolves to an array of network interfaces with their information.

Example

const interfaces = await sos.management.network.listInterfaces();
interfaces.forEach((iface) => {
   console.log(`Interface: ${iface.type}, IP: ${iface.localAddress ?? 'Unknown'}, MAC: ${iface.macAddress}`);
});

GitHub Example

• Applet Example with Network Interfaces

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.

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

Params

Name	Type	Required	Description
ip	string	Yes	The destination IP address. Use '255.255.255.255' for broadcast.
port	number	Yes	The destination UDP port number (1-65535).
data	number[]	Yes	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

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

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().

sendWakeOnLan(macAddress: string): Promise<void>;

Params

Name	Type	Required	Description
macAddress	string	Yes	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

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

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.

setDHCP(interfaceName: string): Promise<void>;

Params

Name	Type	Required	Description
interfaceName	string	Yes	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

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

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.

setManual(interfaceName: string, options: INetworkOptions): Promise<void>;

Params

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

getActiveInfo()

Deprecated

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

getActiveInfo(): Promise<INetworkInfo>;

setDHCP(networkInterface)

Deprecated

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

setDHCP(networkInterface: NetworkInterface): Promise<void>;

setManual(options)

Deprecated

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

setManual(options: INetworkOptionsLegacy): Promise<void>;