ON THIS PAGE

Firmware Version 6.1

This object provides various methods for configuring the network interfaces on a BrightSign player.

Object Creation: The roNetworkConfiguration object is created with a single parameter.

CreateObject("roNetworkConfiguration", network_interface as Integer)

The network_interface parameter is used to distinguish between the following:

0: The Ethernet port (if available) on the rear of the BrightSign player
1: The optional internal WiFi

Some of the settings are specific to the network interface, while others are used by the BrightSign host for all network interfaces.

BrightSign players support most commonly used wireless encryption formats: WEP (64 & 128), WPA (TKIP), and WPA2 (AES). WPA Enterprise is also supported using DER, PEM, or PKCS#12 certificates. Wired authentication via 802.1x is not supported for WPA/WPA2 Enterprise, nor are other modes such as PEAPv0/MSCAPv2.

ifNetworkConfiguration

"Set" methods do not take effect until Apply() is called.

SetupDWS(settings As roAssociativeArray) As Boolean

Configures the Diagnostic Web Server (DWS). By default, the Diagnostic Web Server is enabled on port 80, with the player serial number as password. Settings for the DWS are specified in an associative array. These properties are written to the registry and persist after reboot:

port: The port number of the Diagnostic Web Server, located at the IP address of the player. Setting this value to 0 will disable the DWS, while setting it to "default" will make the DWS accessible on the default port (80). Specifying only this parameter in the associative array is equivalent to enabling the DWS without password protection.
password: An obfuscated password for the DWS. This method uses digest access authentication. Specifying this parameter without setting a port number will make the DWS accessible on the default port.
open: An unobfuscated password for the DWS. This method uses digest access authentication. Specifying this parameter without setting a port number will make the DWS accessible on the default port.
basic: A flag indicating whether basic authentication should be used or not. Setting this parameter to True allows the password set with the{{open}} parameter to be validated using basic authentication, rather than digest access authentication. This option allows for backwards compatibility with older platforms; most, if not all, modern browsers require basic authentication to be disabled in order to communicate with the DWS.

The user name is "admin" for all authentication configurations.

EnableLEDs(enable As Boolean) As Boolean

Enables or disables the Ethernet activity LED (i.e. flashing during link and activity behavior). The Ethernet LED is enabled by default. Changes to this setting do not persist across reboots. This method returns True upon success and False upon failure. Note that this method is not available on HDx10, HDx20, and LSx22 models.

GetClientIdentifier() As String

GetProxy() As String

SetClientIdentifier(a As String) As Boolean

SetLoginPassword(password As String)

Specifies a login password for the SSH connection (if SSH has been enabled in the registry). This method accepts a plain-text password.

SetObfuscatedLoginPassword(password As String)

Specifies a login password for the SSH connection (if SSH has been enabled in the registry). This method accepts a password that has been obfuscated using a shared secret.

Note

Contact support@brightsign.biz to learn more about generating a key for obfuscation and storing it on the player.

SetInboundShaperRate(rate As Integer) As Boolean

Sets the bandwidth limit for inbound traffic in bits per second. For the default bandwidth limit, pass -1 to the method; for no bandwidth limit, pass 0 (though these two settings are functionally the same). You will need to call Apply() for this setting to take effect, and changing this setting at any time will cause the network interface to be taken down and reinitialized.

Note

Because of overhead on the shaping algorithm, attempting to limit the bandwidth at rates greater than approximately 2Mbit/s will reduce speeds to less than the specified rate.

SetRoutingMetric(a As Integer) As Boolean

Configures the metric for the default gateway on the current network interface. Routes with lower metrics are preferred over routes with higher metrics. This function returns True upon success.

SetDHCP() as Boolean (interface)

Enables DHCP and disables all other settings. This function returns True if successful.

SetIP4Address(ip As String) As Boolean (interface)

SetIP4Netmask(netmask As String) As Boolean (interface)

SetIP4Broadcast(broadcast As String) As Boolean (interface)

SetIP4Gateway(gateway As String) As Boolean (interface)

Sets the IPv4 interface configuration. All values must be specified explicitly. Unlike the ifconfig shell command, there is no automatic inference. The parameter is a string dotted decimal quad (i.e. "192.168.1.2" or similar). It returns True upon success.

Example

nc.SetIP4Address("192.168.1.42")
nc.SetIP4Netmask("255.255.255.0")
nc.SetIP4Broadcast("192.168.1.255")
nc.SetIP4Gateway("192.168.1.1")

SetWiFiESSID(essid as String) as Boolean

Configures the WiFi ESSID of the wireless network that the player will connect to. This method returns True on success.

GetWiFiESSID() As String

Retrieves the configured WiFi ESSID, even if the player is not currently connected to that wireless network. Use the GetCurrentConfig().wifi_essid value to retrieve the ESSID of the wireless network that the player is currently connected to.

SetWiFiPassphrase(passphrase as String) as Boolean

Configures the passphrase or key for the wireless network. This method accepts a plain-text passphrase. It returns True if the passphrase is successfully set.

SetWiFiPassphraseAndObfuscate(a As String) As String

Configures the passphrase or key for the wireless network. This method accepts a plain-text passphrase and returns the obfuscated result. If the passphrase is not set, an empty string is returned instead.

SetObfuscatedWiFiPassphrase(password As String) As Boolean

Configures the passphrase or key for the wireless network. This method accepts a passphrase that has been obfuscated using a shared secret. It returns True if the password is successfully set.

Note

Contact support@brightsign.biz to learn more about generating a key for obfuscation and storing it on the player.

SetDomain(domain As String) As Boolean (host)

Sets the device domain name. This will be appended to names to fully qualify them, though it is not necessary to call this. This method returns True on success.

Example

nc.SetDomain("brightsign.biz")

AddDNSServer(server As String) (host)

Adds another server to the list when the object is created and there are no DNS servers. There is currently a maximum of three servers, but adding more will not cause any errors. This method returns True on success. There is no way to remove all the servers; it will be easier to recreate the object instead.

GetFailureReason() As String

Returns additional information when a member function returns False.

Apply() As Boolean

Applies the requested changes to the network interface. This may take several seconds to complete.

SetTimeServer(time_server As String) As Boolean (host)

Sets the default time server, which is "time.brightsignnetwork.com". You can disable the use of NTP by calling SetTimeServer(""). You can use URL syntax to specify that the player use an HTTP or HTTPS server to synchronize the clock. The following are valid time server addresses:

http://time.brightsignnetwork.com/
https://time.brightsignnetwork.com/
ntp://time.brightsignnetwork.com/
time.brightsignnetwork.com

Note

The last two addresses are equivalent.

GetTimeServer() As String

Retrieves the (host) time server currently in use.

SetTimeServerIntervalSeconds(interval_in_seconds As Integer) As Boolean

Specifies how often the player should communicate with the time server and adjust its clock via NTP. The default interval is 12 hours; passing a value of 0 specifies the default interval. The minimum interval allowed is 120 seconds.

GetTimeServerIntervalSeconds() As Integer

Returns the current interval for NTP time-server renewal (in seconds).

SetHostName(name as String) as Boolean (host)

Sets the device host name. If no host name has been explicitly set, then a host name is automatically generated based on the device serial number. Passing an empty string to this method resets the device host name to its automatically generated value.

GetHostName() As String (host)

Retrieves the host name currently in use.

SetProxy(proxy as String) As Boolean (host)

Sets the name or address of the proxy server used for HTTP and FTP requests. The proxy string should be formatted as "http://user:password@hostname:port". It can contain up to four "*" characters; each "*" character can be used to replace one octet from the current IP address. For example, if the IP address is currently 192.168.1.2, and the proxy is set to "proxy-*-*", then the player will attempt to use a proxy named "proxy-192.168".

SetProxyBypass(hostnames As Array) As Boolean

Exempts the specified hosts from the proxy setting. The passed array should consist of one or more hostnames. The player will attempt to reach the specified hosts directly rather than using the proxy that has been specified with the SetProxy() method. For example, the hostname "example.com" would exempt "example.com", "example.com:80", and "www.example.com" from the proxy setting.

GetProxyBypass() As roArray

Returns an array of hostnames that have been exempted from the proxy setting using the SetProxyBypass() method.

GetRecoveryUrl() As String

Returns the current recovery URL stored in the registry. The recovery URL can be configured by modifying the registry entry or via DHCP Option 43.

GetCurrentConfig() As Object

Retrieves the entire current configuration as an associative array containing the following members:

metric	Integer	Interface	Returns the current routing metric for the interface. See the `SetRoutingMetric()` entry for more details.
dhcp	Boolean	Interface	Returns True if the system is currently configured to use DHCP. Returns False otherwise.
hostname	String	Host	The currently configured host name
mdns_hostname	String	Host	The Zeroconf host name currently in use. This may be longer than the host name if there is a collision on the current network.
ethernet_mac	String	Interface	The Ethernet MAC address
ip4_address	String	Interface	The current IPv4 address. If none is currently set, the string will be empty.
ip4_netmask	String	Interface	The current IPv4 network mask. If none is currently set, the string will be empty.
ip4_broadcast	String	Interface	The current IPv4 broadcast address. If none is currently set, the string will be empty.
ip4_gateway	String	Interface	The current IPv4 gateway address. If none is currently set, the string will be empty.
domain	String	Host	The current domain suffix
dns_servers	roArray of Strings	Host	The currently active DNS servers
time_server	String	Host	The current time server
configured_proxy	String	Host	The currently configured proxy. This may contain magic characters as explained under `SetProxy()` above.
current_proxy	String	Host	The currently active proxy. Any magic characters will have been replaced as explained under `SetProxy()` above.
shape_inbound	Integer	Interface	The current bandwidth shaping for inbound traffic determined by the `SetInboundShaperRate()` method.
type	String	Interface	Either "wired" or "wifi"
link	Boolean	Interface	Indicates whether the network interface is currently connected.
wifi_essid	String	Interface	The name of the current Wi-Fi network (if any)
wifi_signal	Integer	Interface	An indication of the received signal strength. The absolute value of this field is usually not meaningful, but it can be compared with the reported value on other networks or in different locations.

TestInterface() As Object

Performs various tests on the network interface to determine whether it appears to be working correctly. It reports the results via an associative array containing the following members:

ok	Boolean	This value is True if the tests find no problems, or False if at least one problem was identified.
diagnosis	String	A single-line diagnosis of the first problem identified in the network interface.
log	roArray of strings	A complete log of all the tests performed and their results.

TestInternetConnectivity() As Object

Performs various tests on the Internet connection (via any available network interface, not necessarily the one specified when the roNetworkConfiguration object was created) to determine whether it appears to be working correctly. It reports the results via an associative array containing the following members:

ok	Boolean	This value is True if the tests find no problems, or False if at least one problem was identified.
diagnosis	String	A single line diagnosis of the first problem identified with the Internet connection.
log	roArray of strings	A complete log of all the tests performed and their results.

GetNeighborInformation() As roAssociativeArray

Retrieves location information from the network infrastructure using the LLDP-MED protocol. The information is returned as an associative array of strings corresponding to civic-address types, which are defined as follows according to the LLDP-MED specification:

CAtype	Label	Description
1	A1	national subdivisions (state, region, province, prefecture)
2	A2	county, parish, gun(JP), district(IN)
3	A3	city, township, shi(JP)
4	A4	city division, borough, city district, ward, chou(JP)
5	A5	neighborhood, block
6	A6	street

CAtype	NENA	PIDF	Description	Examples
0			language	i-default [3]
16	PRD	PRD	leading street direction	N
17	POD	POD	trailing street suffix	SW
18	STS	STS	street suffix	Ave, Platz
19	HNO	HNO	house number	123
20	HNS	HNS	house number suffix	A, 1/2
21	LMK	LMK	landmark or vanity address	Columbia University
22	LOC	LOC	additional location information	South Wing
23	NAM	NAM	name (residence and office occupant)	Joe's Barbershop
24	ZIP	PC	postal/ZIP code	10027-1234
25			building (structure)	Low Library
26			unit (apartment, suite)	Apt 42
27		FLR	floor	4
28			room number	450F
29			placetype	office
30	PCN		postal community name	Leonia
31			post office box (P.O Box)	12345
32			additional code	13203000003
128			script	Latn
255			reserved

ifWiFiConfiguration

ScanWiFi() As roArray

Scans for available wireless networks. The results are reported as an roArray containing one or more associative arrays with the following members:

essid	String	Network name
bssid	String	Access point BSSID
signal	Integer	Received signal strength indication. The absolute value of this field is not usually relevant, but it can be compared with the reported value on other networks or in different locations.

Browser not supported