This document serves as a guide for accessing the BrightSign Shell and BrightScript Debugger of BrightSign players. Both of these can be accessed via a physical serial connection or over the network via SSH or Telnet. For the physical serial connection, certain cables are recommended as described below. If you already have compatible cables, however, you can jump ahead to the BrightSign Shell or the BrightScript Debugger.
What is the BrightSign Shell?
The BrightSign Shell is a command-line interface (CLI) that enables interaction with the BrightSignOS (BOS), the operating system that powers all BrightSign players. The BrightSign Shell is denoted by the command-line prompt BrightSign> and can be used to troubleshoot and debug issues with the player as well as accessing things like network settings, display details, the BrightScript Interpreter, the BrightScript Debugger, a Node.js runtime, and player logs.
What is the BrightScript Debugger?
| Info |
|---|
The BrightScript Debugger is sometimes referred to as the BrightScript Debug Console. However, in an effort to maintain consistency and to avoid any potential confusion, users are encouraged to use the term BrightScript Debugger. |
...
| Note |
|---|
Since enabling the BrightScript Debugger will cause the player to hang when runtime errors are encountered, the BrightScript Debugger should only be used in development environments or debugging situations; it should be disabled for production deployments. |
What is the BrightSign Console?
The BrightSign Console (or more simply, Console) enables access to the BrightSign Shell, BrightScript Debugger, and logs over the 3.5mm serial port.
Serial Cable vs. Telnet or SSH
Immunity from network connectivity issues is one of the primary advantages of a serial cable connection over Telnet or SSH connections. Additionally, in situations where the player is stuck in a boot loop and neither the Shell nor BrightScript Debugger are accessible, a serial port connection can provide access to Console messages.
Serial Cable Hardware
The Shell can be accessed over the 3.5mm serial port that is present on Extended I/O player models when the BrightSign Console is turned on as described below.
Serial cable assemblies compatible with all Series 3, Series 4, and Series 5 Extended I/O players are described below. LS models require another adapter cable that is also described below.
Cable Assembly 1 (Recommended)
This cable assembly has been verified to work and is the simplest and most straightforward option for a physical serial connection. As long as the individual cables required can be procured, this is the recommended cable assembly to use.
...
Cable A (cablestogo.com) - 3.5mm Male to DB-9 Female
Cable B (plugable.com) - DB-9 Male to USB (Prolific PL2303GT chipset)
Cable B (Amazon) - DB-9 Male to USB (Prolific PL2303GT chipset)
Cable B (Walmart) - DB-9 Male to USB (Prolific PL2303GT chipset)
Cable B (Amazon) - DB-9 Male to USB (FTDI FT232RL chipset)
Cable Assembly 2
This cable configuration uses a 3.5mm Male to DB-9 Male cable which in some cases may be more readily available than the 3.5mm Male to DB-9 Female cable of Cable Assembly 1. However, this configuration necessitates an additional gender changer part which results in a more complex cable assembly.
...
Cable C (cablestogo.com) - 3.5mm Male to DB-9 Male
Gender Changer (Amazon) - DB-9 Female/Female Gender Changer
Gender Changer (Walmart) - DB-9 Female/Female Gender Changer
Cable B (plugable.com) - DB-9 Male to USB (Prolific PL2303GT chipset)
Cable B (Amazon) - DB-9 Male to USB (Prolific PL2303GT chipset)
Cable B (Walmart) - DB-9 Male to USB (Prolific PL2303GT chipset)
Cable B (Amazon) - DB-9 Male to USB (FTDI FT232RL chipset)
Additional Cable for LS Models
For LS players (e.g., LS425, LS445, LS424, LS423), you will need an additional cable, Cable D, as shown below. This can be procured from the BrightSign Store.
...
The Console output emitted from the 3.5mm serial port is intended for development purposes and is not intended for production use.
Connecting Player to Computer
A terminal app on your computer is required to interface with the Shell. Terminal apps can either be command-line based or GUI (Graphical User Interface) based. Popular terminal apps include:
...
If it’s unclear which tty device is the player, unplug the cable and run the command again. The device that disappears is the player.
Enabling the BrightSign Console
Follow these steps to enable/turn on the BrightSign Console:
...
| Info |
|---|
The Console will continue to emit logs, even after a reboot, until either the Console is explicitly disabled (entering |
Accessing the BrightSign Shell
The BrightSign Shell is accessible through a serial cable, Telnet, or SSH. It is denoted by the BrightSign> prompt.
Navigate to the BrightSign Shell through one of the methods described below.
Shell Access Methods
The bulleted items shown below are not steps, i.e., each item shown is an independent method for accessing the Shell.
...
Command | Description |
|---|---|
| Display the list of available commands. |
| Provide more information about a command. |
| Clear the terminal window. |
| Exit the shell. |
| List the contents of the current directory or the specified directory. |
| Measure the performance of file reading. |
| Measure the performance of file writing. |
| Measure simultaneus file read/write performance. |
| Play an audio snippet. |
| Start the BrightScript Debugger. Can also be used to run a script from a file if passed the filename. |
| Perform a manufacturing test. |
| Set the serial baud rate. |
| Reboot the system. |
| Shut down the system. |
| Display the date and time. |
| Set the date and time. |
| Display the time zone. |
| Display a list of accepted time zones. |
| Set the time zone. |
| Change the current directory. |
| Delete files or or directories recursively. |
| Display software versions. |
| Display license information. |
| Access the device registry. |
| Display device uptime. |
| Write a boot file to flash. |
| Erase a boot file in flash. |
| Display device identification information. |
| Determine a file type. |
| Cryptographically hash a file. |
| Reset the system to factory defaults. |
| Format a drive using one of the following file systems: |
| Eject a drive. |
| Display the system log. |
| Clear the real time clock (RTC). Note that this action does not modify the system clock. |
| Probe a file. |
| Analyze a file. |
| Display the PTP status. |
| Display a list of discovered USB devices. |
| Dump BVN status for debugging. |
| SoC AVS Information. |
| Invoke Node.js Interpreter. |
| Turn mouse cursor on or off. |
| Report MMC Health. |
| Send echo request to remote host and wait for reply. |
| Configure the network interface. Type |
| Scan for WiFi networks. |
| Measure the download performance from the specified URL. If a destination file is not specified, the contents are discarded. |
| Look up the hostname in the DNS. |
| Flush DNS cache. |
| Play a video snippet. |
| Display an image. |
| Display an HTML Site. |
| Change the current video mode |
| Read the EDID from the attached monitor. |
| Set the VGA power saving mode. |
Enabling the BrightScript Debugger
The BrightScript Debugger is enabled by writing a registry key to the player’s registry. This can be done in several ways as described below.
From the BrightSign Shell
Type the following from the BrightSign Shell:
| Code Block |
|---|
script debug on |
DWS Registry Tab
From the DWS Registry tab in BrightAuthor:connected, submit the following command:registry write brightscript debug 1
BrightScript Debugger Prompt or autorun.brs
The following lines can either be entered at the BrightScript Debugger prompt or included as part of an autorun.brs file:
| Code Block |
|---|
reg = CreateObject("roRegistrySection", "brightscript")
reg.write("debug","1") |
Accessing the BrightScript Debugger
When enabled, the BrightScript Debugger is denoted by the prompt BrightScript Debugger> and is accessible through a serial cable, Telnet, or SSH.
...
If you have not enabled the BrightScript Debugger, any interruption to the BrightScript Interpreter execution will not give access to the Debugger. Instead, the player will reboot to attempt a clean execution.
During Runtime
Press CTRL-C on your keyboard while the player is powered on.
Runtime Stop Statement
If the BrightScript Debugger has been enabled, the player will enter the Debugger if a runtime error occurs or a STOP statement is encountered while a script is running.
Access at Bootup
Power off the player.
Power on the player and wait 5-15 seconds.
Press and hold the SVC button on the player for 15-30 seconds until the
BrightSign>prompt appears in the serial/Telnet/SSH terminal app. TheBrightSign>prompt indicates that you are in the BrightSign Shell. You can now release the SVC button.
If you are using Telnet or SSH, you will need to restart the Telnet or SSH instance.
Additional Methods
Press CTRL-C in your terminal app that is connected to the player.
Remove the microSD card and press either the SVC button on the player or CTRL-C on your computer.
If the serial console has been enabled (either temporarily or persistently),
Starting BrightSign Application...will appear after the player reboots (note that this can take up to 30 seconds). Press and hold the SVC button until theBrightSign>prompt displays.If you have removable storage such as a microSD card, eject it. Reboot the player and press the SVC button. If you are accessing the player through Telnet, you will have to restart the Telnet connection after the player reboots using the telnet {{your player IP address}} 23 command.
Place an autorun.brs file containing only the word “end” (without the quotes) on the storage device. The script will execute and when it ends as instructed you’ll be left at the
BrightSign>prompt.
...
From the BrightScript Debugger> prompt, type exit to navigate to the BrightSign Shell:
| Code Block |
|---|
exit |
Telnet
| Note |
|---|
For security reasons, it is recommended to use SSH over Telnet. |
Enabling Telnet
Telnet can be used to access both the BrightSign Shell and the BrightScript Debugger, if enabled.
...
Further info regarding Telnet can be found here.
Accessing Telnet
Telnet is useful when the 3.5mm serial port (the default I/O for the BrightSign Shell) is inaccessible. It can be accessed through a terminal app.
...
Further info regarding Telnet can be found here.
SSH
Enabling SSH
SSH is useful when the 3.5mm serial port (the default I/O for the BrightSign Shell) is inaccessible. It can be used to access both the BrightSign Shell and the BrightScript Debugger, if enabled.
...
Further info regarding SSH can be found here.
Accessing SSH
The following SSH commands can be used:
...
| Info |
|---|
Although the registry key is labeled “serial_with_telnet”, it applies to both Telnet and SSH configurations. |
Additional info here.
Accessing Logs
This section covers the accessing of logs from the player.
...
Player logs can be useful for analytics, troubleshooting, and debugging issues with the player. They can also be useful for accessing things like the network settings, display details, the BrightScript Interpreter and Debugger, and connected peripherals. Information from your application or presentations can also be logged.
Logs from BrightSign Shell
Enable the BrightSign Shell through using a physical set of cables to establish a serial connection with the player. Refer to the BrightSign Shell section for information on the required cables and how to enable the BrightSign Shell.
Logs accessed from the BrightSign Shell will be captured by your terminal application. The logs can be redirected to a file or saved to a file through the terminal app.
Logs from Telnet or SSH
Enable Telnet or SSH through BrightScript to establish a Telnet or SSH connection in order to access the logs. See the Telnet or SSH sections above for information on how to enable Telnet or SSH.
Logs accessed from Telnet or SSH will be captured by your terminal application. The logs can be redirected to a file or saved to a file through the terminal application.
Logs from Local Diagnostic Web Server
When enabled, the Local Diagnostic Web Server (Local DWS or LDWS) is a web server that runs on the BrightSign player. It can be accessed through a web browser. The LDWS can be used to access logs, network settings, display details, and connected peripherals. The logs can be viewed or downloaded from the LDWS.
Logs from Remote Diagnostic Web Server
When enabled, the Remote Diagnostic Web Server (Remote DWS or RDWS) is a web server that runs on the BrightSign player and is accessed by BSN.cloud or BrightAuthor:connected. It can be accessed through a web browser. The RDWS can be used to access logs, network settings, display details, and connected peripherals. The logs can be viewed or downloaded from the RDWS.
Logs from syslog server
When enabled, the BrightSign player can send logs to a syslog server using the standard syslog protocol (RFC 3164) running on a pre-configured machine the BrightSign has access to. It can be accessed through a syslog client. The syslog server can be used to access logs.
...
The syslog server can either be referenced by its IP address or its hostname.
Logs from Local Diagnostic Web Server APIs
When enabled, the Local Diagnostic Web Server (Local DWS or LDWS) is a web server that runs on the BrightSign player. The Local DWS REST APIs expose access to the BrightSignOS and accessible via clients on the local network who have authenticated using Basic or Digest Authentication. The Local DWS can be used to access logs, network settings, display details, and connected peripherals. The logs can also be viewed or downloaded from the Local DWS.
See LDWS API Logs Endpoints for more information.
Logs from Remote Diagnostic Web Server APIs
When enabled, the Remote Diagnostic Web Server (Remote DWS or RDWS) is a web server that runs on the BrightSign player. The Remote DWS REST APIs expose access to the BrightSignOS and accessible via authorized requesting clients with a OAuth token. The logs can also be viewed or downloaded from the Remote DWS.
See Remote DWS APIs for more information.
Debugging BrightScript Code
This section will cover how to debug BrightScript code on a BrightSign player assuming the BrightScript Debugger has been enabled and is accessible.
...
See BrightScript for information regarding BrightSign’s documentation for BrightScript. Our interpreter forked from Roku’s BrightScript language many years ago and have since diverged.
How to Debug BrightScript
To begin stepping through or debugging BrightScript code, add a stop statement to the line of code you want to start debugging from.
...
Type help in the BrightScript Debugger to see a list of available commands. Type vars to see the variables and their values.
Debugging JavaScript or Node.js
To enable the Chrome Devtools and add BrightSign’s remote inspector, see Debugging Webpages.
Navigate to chrome://inspect adding the IP Address of your player on the same network as your Computer.
Troubleshooting
If you’re encountering difficulties connecting your terminal application to the BrightSign player, below are some steps you can take to troubleshoot.
Verify the tty Profile is Correct
Refer to the Connecting Player to Computer section for establishing a serial connection between the player and your computer. If the profile is incorrect, the terminal app will not be able to connect to the player.
Serial port details can be found here.
Is the Terminal App Configured Properly?
If the profile appears correct, determine if the terminal app is configured properly by connecting to the Serial Device cable or SSH/Telnet. If the terminal app is configured properly, and the player either has Shell enabled by holding the SVC and applying power for this boot cycle, or if Shell has been enabled, the terminal app should display the BrightSign Shell output.
Is the BrightSign Shell Enabled?
If the profile appears correct, determine if the Shell is on by rebooting the player. Assuming power is properly applied to the player, and your computer is properly reading from the Serial Device or SSH/Telnet, Shell output from the player should be seen within ~2-5 seconds.
...
More information found here.
The BrightSign Shell is Not Displaying
If the BrightSign Shell is inaccessible yet it has been activated for this boot cycle or enabled persistently across boot cycles, try to access it through one of the following means:
...
If these steps don’t work, the Shell may not be enabled. Please refer to the section about the BrightSign Shell to enable it.
Resetting your Mac Serial Terminal Connection
In some situations, the computer may think it’s connected to another serial device when physically it is not; in others, the terminal connection may not be properly associated with the existing serial connection. When this occurs and the computer tries to connect to the device, an error may occur along the lines of:
...
Additional info can be found here.
Still Having Issues?
If you’ve tried the above steps and are still have issues, you may need to factory reset the player. If troubles persist, please contact support@brightsign.biz.
Additional Serial Topics
Here are some additional topics that may be useful during troubleshooting.
...