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?

The BrightScript Debugger is a CLI which enables interaction with the BrightScript Interpreter. It is denoted by the prompt BrightScript Debugger> and is a powerful tool for troubleshooting and debugging issues with BrightScript scripts or interacting with BrightScript objects. It is similar to the JavaScript console in web browsers as well as other popular debuggers (e.g., GDB). Developers can set stop statements (a breakpoint), step through a BrightScript script, and gain access to the current scope or initialized variables.

If the BrightScript Debugger has not been enabled, runtime errors will often cause the player to reboot. When the BrightScript Debugger is enabled, runtime errors will cause the BrightSignOS to stop on the line of the runtime error, allowing a step-through of the script.

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.

Open

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

Open

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

Serial Cable Considerations

USB-to-Serial Chipsets and Drivers

BrightSign has tested and verified the cable assemblies described above and have found that USB-to-Serial cables with one of the following chipsets work best:

• FTDI FT232RL

• Prolific PL2303GT

• Prolific PL2303HXD

When using these cables, associated drivers may need to be installed:

• FTDI FT232RL drivers

• Prolific PL2303GT drivers

• Prolific PL2303HXD drivers

When qualifying cable assemblies, be aware that your computer’s OS, OS Version, and general setup (this includes computer settings as well as any installed security software) can all affect whether or not your computer is able to detect the player. BrightSign has seen largely positive results from both the FTDI Chipsets as well as the Prolific Chipsets. However, if you are unsure about compatibility with your computers, it may be best to acquire and test cable assemblies with both chipsets prior to making larger purchases.

Counterfeit Cables

There is a wide variance in USB-to-Serial cables, and many cables contain chipsets which may not be compatible with our players. In addition, counterfeit and/or low-quality cables are prevalent (see Prolific’s message regarding counterfeits of their products). For this reason, we recommend that cables be procured directly from the sources provided or from a manufacturer-authorized reseller.

If deviating from the provided sources, we recommend confirming the pinout and chipset with the manufacturer prior to purchase and to qualify any cables thoroughly before making larger purchases.

Pinout and Null Modems

When designing systems that use the serial connection, careful consideration must be paid to the pinouts of all connections involved. This includes pinouts for any cables as well as any hardware devices that the cable(s) will connect to.

Whether a Null Modem is needed or not depends upon the specified pinout of the cable. Refer to the 3.5mm Serial page for details on how the tip, ring, and sleeve of the 3.5mm pin are mapped to the DB-9 pins. To determine the pinout of the 3.5mm to DB-9 or DB-9 to USB, refer to the manufacturer’s specification to ensure the cable meets the specifications of BrightSign’s 3.5mm serial port.

Connector Genders

Be sure to confirm that the connector genders, both on the cables themselves as well as on the device(s) the cables are connecting to, are compatible. Validate that all cables meet your system requirements before making larger purchases.

Using the 3.5mm Port in Production

If the 3.5mm serial port is intended to be used as part of the end experience (e.g., connecting the player to a serial controller), it is recommended to use Telnet or SSH when connecting to the player during development. Developing and testing with the intended serial device attached to the player will provide a better representation of the final production configuration.

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:

• Mac

  • iTerm2

  • Serial

  • macOS Terminal App

• Windows

  • PuTTY

  • miniCom

• Linux

  • tio

Here are details on the Serial Port Configuration.

From your terminal app, the first step is to confirm that the USB-to-Serial cable (Cable B above) is detected by your computer. Note that the computer should be able to detect the USB-to-Serial cable even without a serial device (e.g., the player) connected on the other end. Simply attaching this cable to the computer is the quickest and easiest way to verify that the cable’s connection is detected by the computer.

After attaching the cable assembly to the player, the player can be found by running the following command:

The player should be named along the lines of /dev/tty.usbserial on macOS or /dev/ttyUSB0 on Linux.

The screen command can be used to establish a connection. The command to establish a connection is as follows:

From here, a blank screen in the terminal app should appear. If your session reported any errors, please refer to the Troubleshooting section. Refer to the BrightSign Shell section for accessing the BrightSign Shell.

The following was set up using the details outlined in Serial Port Configuration with the following settings:

• Baud rate: 115200

• Data: 8 bit

• Parity: none

• Stop: 1 bit

• Flow control: Hardware flow control is available on the 4Kx42, XDx32, and HDx22 models. Software flow control is not supported on any model.

• Return Key: CR + LF

• Send Mode: Interactive (line buffered may also work)

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:

1. Connect the aforementioned cable assembly from the player to your computer. The 3.5mm connector should be plugged into the player’s 3.5mm serial port and the USB connector plugged into the computer.

2. Once the cables are connected, open a terminal app to establish a connection.

   The player should be named along the lines of /dev/tty.usbserial on macOS or /dev/ttyUSB0 on Linux:

   ls /dev/tty.usb*

   The player can be found by running the following command:

   From here, a blank screen in the terminal app should appear. Note that the player’s name may be different depending on the type of computer and serial cable used. If your session reported any errors, please refer to the Troubleshooting section.

3. From here, we will enable the BrightSign Console.

   1. Power down the player.

      For the next few steps, pay close attention to the terminal app and watch the logs during the boot process. Specifically, watch for a message along the lines of “Press CTRL-C to stop automatic startup”.

   2. Press and hold down the SVC button while applying power to the player. This instructs the player to emit logs through the 3.5mm serial port.

   3. After ~3-5 seconds, the terminal app will ask you to press CTRL-C to stop automatic startup and will present a 3-second countdown. To stop automatic startup, press CTRL-C on your computer’s keyboard within the countdown window.

   4. Depending on the version of BrightSignOS installed on the player, you will see one of the following boot loader prompts: BOLT>, SECURE>, INSECURE> Enter the following at the boot loader prompt:

   
   Example:

This reboots the player with the Console enabled/on which results in the player displaying a continuous scroll of logs emitted from the 3.5mm serial port. You can pause the scrolling of logs at any time using the keyboard (different terminals have different setups for how to do this).

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.

• With the player off, remove any storage device connected to the player. Power on the player and wait for the splash screen to appear over HDMI, and then press either the SVC button on the player or CTRL-C on your computer.

• Place an autorun.brs file containing only the word “end” (without the quotes) on the storage device. The script will execute and bring you to the BrightSign Shell.

Shell Commands

The following commands are currently available in the BrightSign Shell.

Enabling the BrightScript Debugger

The BrightScript Debugger is enabled by writing a registry key to the player’s registry.

From the BrightSign Shell:

The following lines can either be entered at the BrightScript Debugger prompt or included as part of an autorun.brs file:

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.

Navigate to the BrightSign Debugger through one of the methods described below.

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

1. Power off the player.

2. Power on the player and wait 5-15 seconds.

3. 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. The BrightSign> 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 the BrightSign> 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.

This will break out of the application running at the moment and redirect to the BrightSign prompt.

BrightScript Debugger Commands

The following Shell commands are currently available in the BrightScript Debugger:

*BrightScript print messages are routed to the BrightSignOS which is accessible via the primary serial port or Telnet/SSH.

Switch Between the BrightSign Shell and the BrightScript Debugger

From the BrightSign> prompt, type script to navigate to the BrightScript Debugger:

From the BrightScript Debugger> prompt, type exit to navigate to the BrightSign Shell:

Telnet

Enabling Telnet

Telnet can be used to access both the BrightSign Shell and the BrightScript Debugger, if enabled.

It is sometimes preferred to use a serial cable instead of Telnet for reliability reasons (e.g., network stability or when an application has forced the player into a reboot loop).

Telnet is enabled through writing a registry key to player’s registry. The player must be rebooted for Telnet to take effect.

From the BrightSign Shell:

The following lines can either be entered at the BrightScript Debugger prompt or included as part of an autorun.brs file:

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.

It is sometimes preferable to use a serial cable instead of SSH for reliability reasons (e.g., network stability or an application has forced the player into a reboot loop).

SSH is enabled by writing a registry key to player’s registry and a BrightScript Object, roNetworkConfiguration. The player must be rebooted for SSH to take effect.

The following lines can either be entered at the BrightScript Debugger prompt or included as part of an autorun.brs file:

Further info regarding SSH can be found here.

Accessing SSH

The following SSH commands can be used:

Useful Telnet and SSH flags

Here are some tips for enabling serial output for various circumstances.

Refer here for info on Telnet.

• [networking]telnet 22 - enables SSH (roNetworkConfiguration SetLoginPassword() must be set)

• [networking]telnet 23 - enables Telnet

• [networking]telnet_log_level 7 - sets the Linux log output to the same level as what we see with the 3.5mm serial connector, allowing the Linux log output to be sent to Telnet.

• [networking]serial_with_telnet 1 - allows communication with the player through both the 3.5mm serial connector and Telnet.

• [brightscript]debug 1 - (value is any truthy/positive value) can be used to enable the Debugger.

Using SSH or Telnet with a Connected Serial Device

By default, enabling debugging output via Telnet or SSH will disable such output over serial. The 3.5mm serial port can still be used for interaction with serial devices via the roSerialPort object.

It is possible to enable debugging output over both Telnet/SSH and serial. However, interaction with serial devices via the roSerialPort object will become highly unreliable. To enable debugging output over serial as well, run a script containing the following code after Telnet/SSH has been enabled:

Additional info here.

Accessing Logs

This section covers the accessing of logs from the player.

There are several methods for accessing player logs:

• A physical serial connection

• SSH /Telnet

• Local Diagnostic Web Server (LDWS)

• Remote Diagnostic Web Server (RDWS)

• syslog server

• Local HTTP REST APIs

• BSN.cloud HTTP REST APIs

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.

To enable the syslog server, the following BrightScript code can be used:

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.

Refer to the BrightSign Shell and BrightScript Debugger sections for info on enabling and accessing the BrightSign Shell and BrightScript Debugger.

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.

A stop statement is a breakpoint in the BrightScript code. When the BrightSign player encounters a stop statement, it will break and enter the BrightScript Debugger when the debugger is enabled.

The BrightScript Debugger is similar to many other debuggers, e.g., gdb. It allows you to step through the code, inspect variables, and evaluate expressions.

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.

If there is no output, unplug the power cable, hold down the SVC button on the player and apply power. Within 2-5 seconds, the Shell should output something like Hit CTRL-C to stop... or Automatic startup in 3 seconds, press Ctrl-C to interrupt.." Note that this approach enables Shell output for this boot only.

To persistently enable the Shell, at the boot loader prompt, type console on and then reboot.

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:

• Press SVC

• Press CTRL-C

• Remove microSD, reboot, after ~45-60 seconds press SVC without the microSD card inserted

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:

“Cannot open line ’tty.usbserial’ resource for R/W, resource busy”

This can mean that a process on the computer is already allocated to listening on the same serial connection. Here are a couple of ways to fix this problem:

Kill the process and re-open a new process:

lsof | grep 'usbserial'

sudo kill -9 <pid>

Alternatively, you can attach to the existing process ID:

lsof | grep 'usbserial'

screen -x <pid>

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.

• For Console access, the SVC button should only be held down long enough to see Console output. If the SVC button is held down too long after Console output appears, the player will go into “rescue mode” which is most likely not the intended mode if you’re reading this document. Rescue mode may be initiated if the SVC button is held for 15 seconds or more while power was applied. While in rescue mode, the error LED will continue flashing for about fifteen minutes before rebooting. During that time, if an OS update is present on an attached storage device (or if a storage device is subsequently attached), the OS update will be applied.

• The SVC and Reset buttons are physically close to each other on most players. Make sure that it’s the SVC button being pressed and not the Reset button.

• Make sure that neither the SVC button nor the Reset button are stuck in the pressed down state. While this is rare, it has been known to occur.

If the Console is still inaccessible, it may be best to perform a factory reset. Without access to the BrightSign prompt and without the use of a script, the player can be factory reset by performing the following steps:

1. Hold both SVC and Reset while applying power.

2. Hold these 2 buttons until the ERR light flashes repeatedly red.

3. Release these buttons which will cause the player to boot up again. The player should be left untouched for ~2 minutes while it factory resets itself.

4. The player will be factory reset.

5. Next, power down the player.

6. Hold SVC while applying power.

7. If your computer’s serial physical connection and application are properly configured to associate with the Serial Device, you should now have Shell output at which point hit CTRL-C when the message “Hit CTRL-C to stop …” appears.