...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
| borderColor | #3D3D3D |
|---|---|
| bgColor | #F4F4F4 |
| titleColor | #3D3D3D |
| borderWidth | 0 |
| titleBGColor | #3D3D3D |
| borderStyle | solid |
...
ON THIS PAGE
| Table of Contents | ||
|---|---|---|
|
...
...
...
...
...
...
SetClientIdentifier(a As String) As Boolean
Sets the DHCP client identifier.
GetClientIdentifier() As String
Returns the DHCP client identifier.
...
...
SetObfuscatedLoginPassword(password As String) As Boolean
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.
...
| title | Note |
|---|
...
...
| title | Note |
|---|
...
...
...
...
...
...
...
...
...
| title | Note |
|---|
...
...
...
...
...
| title | Note |
|---|
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
| title | Example |
|---|
...
...
...
Value | Type | Host/Interface | Description |
|---|---|---|---|
metric | Integer | Interface | Returns the current routing metric for the interface. See the |
dhcp | Boolean | Interface | Returns |
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 | A whitespace-separated list of domains that will be appended to unqualified names when resolving them |
domains | roArray of Strings | Host | The |
...
domains that will be appended to uniqualified names when resolving name | |||
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 |
current_proxy | String | Host | The currently active proxy. Any magic characters will have been replaced as explained under |
shape_inbound | Integer | Interface | The current bandwidth shaping for inbound traffic determined by the |
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:
Value | Type | Description |
|---|---|---|
ok | Boolean | This value is |
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:
Value | Type | Description |
|---|---|---|
ok | Boolean | This value is |
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:
| Anchor | ||||
|---|---|---|---|---|
|
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
...
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:
Value | Type | Description |
|---|---|---|
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. |
ScanWiFi may fail if a previous scan has not completed, or a background scan is in progress. This potential failure should be handled in the script, and the script should retry ScanWifi if it does fail.
ReassociateWiFi(enable As Boolean) As Boolean
This method takes no parameters and attempts to disconnect from and reconnect to the currently-configured WiFi network. This should not normally be necessary, but could be useful when diagnosing network problems. Returns true on success or false on failure. When false is returned calling GetFailureReason() may provide more information as to why.
This method is present in BOS 8.4.20 and above, BOS 8.5.26 and above, and in all BOS 9.0 versions.
Note that this function may return before the network has been reconnected. Use roNetworkHotplug to determine when reconnection is complete.
Network Authentication
BrightSign players support most commonly used wireless encryption formats: WEP (64 & 128), WPA (TKIP), and WPA2 (AES).
WPA Enterprise is supported using EAP-TLS (with DER, PEM, or PKCS#12 certificates) and PEAPv0/MSCHAPv2 (with a username and passphrase). Wired authentication via 802.1x is also supported. The configuration instructions below apply to both WiFi and wired authentication via 802.1x; the only difference is the wired/wireless parameter (0/1) passed during roNetworkConfiguration initialization.
EAP-TLS
EAP-TLS authentication requires a client certificate and private key. There are two ways to accomplish this:
Packaging the client certificate and private key in a single file in PKCS#12 format (using PEM or DER encoding), usually with a .p12 file extension. To do this, set the PKCS#12 file using the
SetWiFiPrivateKey()method and pass a blank string to theSetWiFiClientCertificate()method.Packaging the client certificate as a X.509 certificate (using PEM or DER encoding) and optionally securing the key with a passphrase (instead of the usual WiFi passphrase). To do this, set the client certificate using the
SetWiFiClientCertificate()method and the key using theSetWiFiPrivateKey()method. If the key is protected with a passphrase, you should then callSetWiFiPassphrase().
Certificate keys may contain binary data if not PEM formatted. In this case, they must be provided as an roByteArray object. Text formats may be passed using a string or roByteArray.
...
Example: Setting EAP-TLS with a .p12 file
| Code Block |
|---|
nc = CreateObject("roNetworkConfiguration",1)
p12 = CreateObject("roByteArray")
p12.ReadFile("client.p12")
nc.SetWiFiClientCertificate("")
nc.SetWiFiPrivateKey(p12)
nc.SetWiFiPassphrase("passwordgoeshere") |
During authentication, the Radius server is passed an identity. By default, the identity will be taken from the client certificate. If the certificate has a "subjectAltName", it will be used; otherwise, the "CommonName" is used. If neither of these are correct, the identity may be overridden. This default behavior can be overridden by calling SetWiFiIdentity(), or it can be specified by passing a blank string to SetWiFiIdentity().
PEAP/MSCHAP
This mode requires an identity (username) and passphrase, rather than a client certificate. There may also be a second, "outer", identity–see the Special Cases section below for configuration details.
| Code Block |
|---|
nc = CreateObject("roNetworkConfiguration",1)
nc.SetWiFiIdentity("user@brightsign-example.com")
nc.SetWifiPassphrase("passwordgoeshere") |
Common Variants
Additional Certificates
Additional CA certificates are often
...
required when using a private or internal CA for authentication
...
. Also, some CA hierarchies require intermediate certificates, which are sometimes supplied via EAP. If the server does not supply them, they may be added to the CA file using the SetWiFiCACertififcates() method. This method supports PEM
...
certificates.
If a CA is not supplied, no peer verification will be done and an unvalidated authentication/connection will occur.
| Code Block |
|---|
nc = CreateObject("roNetworkConfiguration",1)
ca = CreateObject("roByteArray")
ca.ReadFile("ca.pem")
nc.SetWiFiCACertificates(ca) |
Obfuscated WiFi Passphrase
If an obfuscated WiFi passphrase is required, you can substitute the SetObfuscatedWiFiPassphrase() method for the SetWiFiPassphrase() method. Contact support@brightsign.biz to learn more about generating a key for obfuscation and storing it on the player.
TKIP/CCMP Encryption
By default, both WPA (TKIP) and WPA2 (CCMP) encryption is permitted. You can alter this behavior using the SetSecurityMode() method, which accepts a space-separated, case-insensitive list of allowed modes ("ccmp" and "tkip"). If both CCMP and TKIP are allowed, CCMP always has priority.
| Code Block |
|---|
nc = CreateObject("roNetworkConfiguration",1)
nc.SetWiFiSecurityMode("") 'Sets the default mode
nc.SetWiFiSecurityMode("ccmp tkip") 'Explicitly allows both modes (same as the default mode)
nc.SetWiFiSecurityMode("ccmp") 'Requires the use of CCMP |
Special Cases
MD5 Support
MD5 support is enabled by default for backwards-compatibility reasons. This behavior can be modified by passing the "md5=enable" or "md5=disable" string to the SetWiFiEapTlsOptions() method.
| Code Block |
|---|
nc = CreateObject("roNetworkConfiguration",1)
nc.SetWiFiEapTlsOptions("md5=disable") |
Anonymous Identity
Some EAP-PEAP/MSCHAP configurations require an anonymous identity. By default, the BrightSign player uses the same inner and outer identity. An anonymous identity can be configured with the SetWiFiEaptTlsOptions() method:
| Code Block |
|---|
nc = CreateObject("roNetworkConfiguration",1)
nc.SetWiFiEapTlsOptions("anonymous_identity=anon@brightsign.biz") |
| Tip |
|---|
...
Tip If neither MD5 or identity options are being used, the setting should be cleard by passing a blank string to the |
Validity Dates
Validity dates are required for both EAP-TLS and PEAP/MSCHAP. The current time is required to check the certificate. If the player clock has not been set, it will typically set its time using the network, but this requires EAP authentication first. To avoid this problem, there are two special exceptions:
EAP-TLS: When the clock is not set, the time is set to ten seconds after the client certificate becomes valid, which is usually sufficient to authenticate (though this may not be sufficient for servers with newer certificates than the client).
PEAP/MSCHAP: There is no client certificate, and the server certificate time is not checked when the date is not set.
The clock can also be set via the Diagnostic Web Server, which prevents either of the above exceptions from being used. Typically, the clock is also set from the network once it is available, so these exceptions are only used on first boot or when the clock battery has been completely emptied.
Examples
The following script disables WPA Enterprise configuration (which is otherwise persistent):
| Code Block |
|---|
nc = CreateObject("roNetworkConfiguration", 1)
nc.SetWiFiSecurityMode("")
nc.SetWiFiESSID("")
nc.SetWiFiIdentity("")
nc.SetWiFiCaCertificates("")
nc.SetWiFiClientCertificate("")
nc.SetWiFiPrivateKey("")
nc.SetWiFiPassphrase("")
nc.SetWiFiEapTlsOptions("")
ok = nc.Apply() |
The following script configures the WiFi for EAP-TLS using a PKCS#12 (.p12) file, without additional CA certificates:
| Code Block |
|---|
essid = "brightwifi"
pkcs12file = "client.p12"
pkcspass = "passwordgoeshere"
nc = CreateObject("roNetworkConfiguration", 1)
nc.SetWiFiESSID(essid)
p12 = CreateObject("roByteArray")
ok = p12.ReadFile(pkcs12file)
if ok then
nc.SetWiFiClientCertificate("")
nc.SetWiFiPrivateKey(p12)
nc.SetWiFiPassphrase(pkcspass)
nc.SetWiFiCaCertificates("")
nc.SetWiFiSecurityMode("")
nc.SetWiFiIdentity("")
nc.SetWiFiEapTlsOptions("")
ok = nc.Apply()
end if |
The following script configures the WiFi for EAP-TLS with additional certificates:
| Code Block |
|---|
essid = "brightwifi"
cafile = "cacert.pem"
pkcs12file = "client.p12"
pkcspass = "passwordgoeshere"
nc = CreateObject("roNetworkConfiguration", 1)
nc.SetWiFiESSID(essid)
p12 = CreateObject("roByteArray")
ok = p12.ReadFile(pkcs12file)
ca = CreateObject("roByteArray")
ok = ca.ReadFile(cafile) and ok
if ok then
nc.SetWiFiClientCertificate("")
nc.SetWiFiPrivateKey(p12)
nc.SetWiFiPassphrase(pkcspass)
nc.SetWiFiCaCertificates("")
nc.SetWiFiSecurityMode("")
nc.SetWiFiIdentity("")
nc.SetWiFiEapTlsOptions("")
ok = nc.Apply()
end if |
The following script configures the WiFi for PEAP/MSCHAP with additional CA files:
| Code Block |
|---|
essid = "brightwifi"
cafile = "ca.pem"
user = "someuser@brightsign.biz"
pass = "whatever"
ca = CreateObject("roByteArray")
ok = ca.ReadFile(cafile)
if ok then
nc = CreateObject("roNetworkConfiguration", 1)
nc.SetWiFiESSID(essid)
nc.SetWiFiIdentity(user)
nc.SetWiFiPassphrase(pass)
nc.SetWiFiCaCertificates(ca)
nc.SetWiFiClientCertificate("")
nc.SetWiFiPrivateKey("")
'Use this if an anonymous outer identity is required
'nc.SetWiFiEapTlsOptions("anonymous_identity=anon@brightsign.biz")
nc.SetWiFiEapTlsOptions("")
ok = nc.Apply()
if not ok then
fail = "Unable to set configuration: " + nc.GetFailureReason()
end if
else
fail = "Unable to read file " + cafile
end if
' if not ok, do something with the failure message |
The following script performs various VLAN configurations on the Ethernet interface:
| Code Block |
|---|
' Configure the VLANs first. Use defaults for VLAN6
n6=CreateObject("roNetworkConfiguration", "eth0.6")
print n6.ResetInterfaceSettings()
print n6.Apply()
' Use defaults for VLAN11
n11=CreateObject("roNetworkConfiguration", "eth0.11")
print n11.ResetInterfaceSettings()
print n11.Apply()
' Use static IP for VLAN15
n15=CreateObject("roNetworkConfiguration", "eth0.15")
print n15.SetIP4Address("192.168.15.100")
print n15.SetIP4Netmask("255.255.255.0")
print n15.Apply()
' Now enable VLANs 6, 11 and 15 on eth0.
n0=CreateObject("roNetworkConfiguration", "eth0")
print n0.SetVlanIds([6, 11, 15])
print n0.Apply() |