---
title: networkdiagnostics
slug: develop/networkdiagnostics
docTags: 
createdAt: 2025-03-26T14:45:31.685Z
---

The *networkdiagnostics *object allows you to retrieve information about network interfaces and Internet connectivity.

**networkdiagnostics IDL**

```javascript
interface NetworkDiagnostics {
    Promise<NetworkDiagnosticsResult> testInternetConnectivity()
    Promise<NetworkDiagnotsticsResult> testNetworkInterface(String interface_name)
    Promise<PingResult> ping(String host_name, PingConfig config)
    Promise<TracerouteResult> traceroute(String host_name, TracerouteConfig config)
    //< For BrightSign internal use. Behaviour subject to change without notice.
};

interface InterfaceTestResult {
    String diagnosis;
    bool    ok;
    Array<Log> log;
};

interface Log {
    String name;
    bool pass;
    String result;
    Array<String> info;
    //< For BrightSign internal use. Behaviour subject to change without notice.
};

interface PingConfig {
    unsigned? short count; // default 10
    unsigned long? interval; // in milliseconds, default 100
    unsigned long? timeout; // in seconds, default 10000
    unsigned long? packetsize; // in bytes, default 56
    bool? ipv4; // enable pinging IPv4 addresses, default true
    bool? ipv6; // enable pinging IPv6 addresses, default false
    bool? allAddresses; // if true then ping all addresses returned from DNS query,
                        // if false then each will be pinged in turn until one responds, default false
};

interface PingResult {
    String hostname; // host name or literal address pinged
    PingResults results;
};

interface PingResults {
    bool up; // true if at least one address responded to at least 50% of the echo requests
    Array<ProtocolPingResult>? ipv4;
    Array<ProtocolPingResult>? ipv6;
};

interface ProtocolPingResult {
    String address; // IP address pinged
    bool up; // true if the address responded to at least 50% of the echo requests
    ProtocolPingReport report;
};

interface ProtocolPingReport {
    unsigned short transmitted; // number of echo requests sent
    unsigned short received; // number of echo replies received
    ProtocolPingStats stats;
};

interface ProtocolPingStats {
    unsigned long quickest; // quickest reply received
    unsigned long average; // average time across all replies from address
    unsigned long slowest; // slowest reply received
    String units; // always "us" to indicate microseconds
};
```

## Object Creation

To create a *networkdiagnostics* object, first load the `brightsign/networkdiagnostics`  module using the `require()` method. Then create an instance of the *networkdiagnostics* class.

```javascript
var NetworkDiagnosticsClass = require("@brightsign/networkdiagnostics");
var networkDiag = new NetworkDiagnosticsClass();
```

## NetworkDiagnostics

Use this interface to retrieve diagnostic information.

:::hint{type="danger"}
The testInternetConnectivity() method generates a large amount of network traffic (e.g. DNS lookups) that may degrade the performance of a player, create network congestion, or be perceived as abusive by the network's upstream DNS provider. This method is intended for one-time use to validate network connectivity or to diagnose a suspected problem.
:::

**testInternetConnectivity()**

```javascript
Promise<InterfaceTestResult> testInternetConnectivity()
```

Performs various tests on the Internet connection (via any available network interface) to determine whether it appears to be working correctly. This method returns an `InterfaceTestResult` interface when diagnostics are complete.

**testNetworkInterface()**

```javascript
Promise<InterfaceTestResult> testNetworkInterface(String interface_name)
```

Performs tests on the specified network interface to determine whether it appears to be working correctly. Interface name values are the same as those used with the [roNetworkConfiguration](docId\:U6ZceYQddlz9xdAKtTmJs) object. This method returns an `InterfaceTestResult` interface when diagnostics are complete.

**ping()**

```javascript
Promise<PingResult> ping(String host_name, PingConfig config)
```

Pings a device with the specified `host_name` to determine if there are connection issues.

**traceroute()**

```javascript
Promise<InterfaceTestResult> traceroute(String host_name, TraceRouteConfig config)
```

**For BrightSign internal use. Behavior subject to change without notice.&#x20;**

Performs a standard traceroute diagnostic on the specified `host_name`.

## InterfaceTestResult

This interface contains diagnostic results:

- `diagnosis` <font color="#6554c0">String</font>:  A single-line diagnosis of the first problem identified with the network interface or Internet connection
- `ok`<font color="#6554c0"> bool</font>:  Whether the network interface or Internet connection passed diagnostic tests
- `log` <font color="#6554c0">Log</font>:  A Log object containing diagnostic information related to the network interface or Internet connection

## Log

This interface contains a list of diagnostic logs. Each log contains the following attributes:

- `name` <font color="#6554c0">String</font>: A description of the diagnostic 
- `pass` <font color="#6554c0">bool</font>: Whether the diagnostic was successful
- `result` <font color="#6554c0">String</font>: A description of the diagnostic result
- `info` <font color="#6554c0">StringList</font>: A string list containing diagnostic data

## PingConfig

This interface is not recommended unless you are using BrightSign OS v8.3.45 and later.

- `count` <font color="#6554c0">unsigned short</font>: The default value is 10.
- `interval` <font color="#6554c0">unsigned long</font>:  The interval value in milliseconds. The default is 100.
- `timeout`  <font color="#6554c0">unsigned long</font>: The timeout value in seconds. The default is 10000.
- `packetsize` <font color="#6554c0">unsigned long</font>: The packet size in bytes. The default is 56.
- `ipv4` <font color="#6554c0">bool</font>:  Enable pinging IPv4 addresses. The default is `true`.
- `ipv6` <font color="#6554c0">bool</font>:  Enable pinging IPv6 addresses. The default is `true.`
- `allAddresses`<font color="#6554c0"> bool:</font>  If `true` then ping all addresses returned from the DNS query. If `false`, then each will be pinged in turn until one responds. The default is `false`.

## PingResult

This interface is not recommended unless you are using BrightSign OS v8.3.45 and later.

- `hostname` <font color="#6554c0">String</font>: The host name or literal address pinged.
- `results` <font color="#6554c0">PingResults</font>:

## PingResults

This interface is not recommended unless you are using BrightSign OS v8.3.45 and later.

- `up` <font color="#6554c0">bool:</font> This value is `true` if at least one address responded to at least 50% of the echo requests.
- `ipv4` <font color="#6554c0">Array&lt;ProtocolPingResult&gt;:</font>
- `ipv6` <font color="#6554c0">Array&lt;ProtocolPingResult&gt;:</font>

## ProtocolPingResult

This interface is not recommended unless you are using BrightSign OS v8.3.45 and later.

- `address` <font color="#6554c0">string</font>: The IP address pinged
- `up` <font color="#6554c0">bool</font>: If `true`, the address responded to at least 50% of the echo requests
- `report` <font color="#6554c0">ProtocolPingReport:</font>

## ProtocolPingReport

This interface is not recommended unless you are using BrightSign OS v8.3.45 and later.

- `transmitted` <font color="#6554c0">unsigned short</font>: The number of echo requests sent
- `received` <font color="#6554c0">unsigned short</font>: The number of echo replies received
- `stats` <font color="#6554c0">ProtocolPingStats:</font>

## ProtocolPingStats

This interface is not recommended unless you are using BrightSign OS v8.3.45 and later.

- `quickest` <font color="#6554c0">unsigned long</font>: The quickest reply received
- `average` <font color="#6554c0">unsigned long</font>: The average time across all replies from address
- `slowest` <font color="#6554c0">unsigned long</font>: The slowest reply received
- `units` <font color="#6554c0">string</font>: The value is always "us", to indicate microseconds

## Example

The following script creates a *networkdiagnostics&#xA0;*&#x69;nstance and logs Internet diagnostic data to the console:

```javascript
var NetworkDiagnosticsClass = require("@brightsign/networkdiagnostics");
var nd = new NetworkDiagnosticsClass();
nd.testInternetConnectivity().then(
        function(data) {
            console.log(JSON.stringify(data));
        })
    .catch(
        function(data) {
            console.log(JSON.stringify(data));
        });
```