BrightSign Shell

this page serves as a guide for accessing the brightsign shell of brightsign players the brightsign shell 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 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 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 image 20240417 220412 png cable a (cablestogo com) https //www cablestogo com/usb and pc/computer cables/serial rs232/1 5ft 0 46m velocity db9 female to 3 5mm male adapter cable/p/cg 02445 3 5mm male to db 9 female cable b (plugable com) https //plugable com/products/pl2303 db9 db 9 male to usb (prolific pl2303gt chipset) cable b (amazon) https //www amazon com/gp/product/b00425s1h8/ref=oh aui detailpage o01 s01?ie=utf8\&psc=1 db 9 male to usb (prolific pl2303gt chipset) cable b (walmart) https //www walmart com/ip/plugable usb to serial adapter compatible with windows mac linux rs 232 db9 dte male connector prolific pl2303hx rev d chipset/47500195 db 9 male to usb (prolific pl2303gt chipset) cable b (amazon) https //www amazon com/dp/b0759hslp1?psc=1\&ref=ppx yo2ov dt b product details 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 image 20240417 220458 png cable c (cablestogo com) https //www cablestogo com/cables/pc/serial rs232 cables/1 5ft 0 46m velocity db9 male to 3 5mm male serial rs232 adapter cable/p/cg 02444 3 5mm male to db 9 male gender changer (amazon) https //www amazon com/c2g cables serial changer coupler/dp/b00005111m/ref=sr 1 4?s=pc\&ie=utf8\&qid=1467322225\&sr=1 4\&keywords=gender%2bchanger\&th=1 db 9 female/female gender changer gender changer (walmart) https //www walmart com/ip/gender changer sub 9 pin pack of 2 socket to 9 pin female to 9 pin serial rs232 gender changer converter adaptor/2249966965?wmlspartner=wlpa\&selectedsellerid=101294820\&adid=22222222227000000000\&wl0=\&wl1=g\&wl2=c\&wl3=42423897272\&wl4=pla 51320962143\&wl5=9032144\&wl6=\&wl7=\&wl8=\&wl9=pla\&wl10=736876983\&wl11=online\&wl12=2249966965\&veh=sem\&gclid=cjwkcajww7kmbhayeiwa5 pusidg83bmbfsqa6 b5qiibcocgeavitkwhr7miadhbbfguoyx3mgbmhoc4xyqavd bwe db 9 female/female gender changer cable b (plugable com) https //plugable com/products/pl2303 db9 db 9 male to usb (prolific pl2303gt chipset) cable b (amazon) https //www amazon com/gp/product/b00425s1h8/ref=oh aui detailpage o01 s01?ie=utf8\&psc=1 db 9 male to usb (prolific pl2303gt chipset) cable b (walmart) https //www walmart com/ip/plugable usb to serial adapter compatible with windows mac linux rs 232 db9 dte male connector prolific pl2303hx rev d chipset/47500195 db 9 male to usb (prolific pl2303gt chipset) cable b (amazon) https //www amazon com/dp/b0759hslp1?psc=1\&ref=ppx yo2ov dt b product details 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 https //store brightsign biz/ image 20240415 185336 png 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 https //ftdichip com/products/ft232rl/ prolific pl2303gt https //www prolific com tw/us/showproduct aspx?p id=382\&pcid=41 prolific pl2303hxd https //www prolific com tw/us/showproduct aspx?p id=225\&pcid=41 when using these cables, associated drivers may need to be installed ftdi ft232rl drivers https //ftdichip com/drivers/vcp drivers/ prolific pl2303gt drivers https //www prolific com tw/us/showproduct aspx?pcid=41\&showlevel=0017 0037 0041 prolific pl2303hxd drivers https //www prolific com tw/us/showproduct aspx?pcid=41\&showlevel=0017 0037 0041 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 https //www prolific com tw/us/showproduct aspx?p id=155\&pcid=41 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 serial port configuration docid\ zen3qywtjohoeotkbrx2a 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 https //iterm2 com/ serial https //www decisivetactics com/products/serial/ macos terminal app windows putty https //www putty org/ minicom https //salsa debian org/minicom team/minicom linux tio https //github com/tio/tio here are details on the serial port configuration docid\ zen3qywtjohoeotkbrx2a 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 ls /dev/tty 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 screen /dev/tty usbserial 115200 from here, a blank screen in the terminal app should appear if your session reported any errors, please refer to the brightsign shell /#troubleshooting section refer to the brightsign shell /#accessing the brightsign shell section to access the brightsign shell the following was set up using the details outlined in serial port configuration docid\ zen3qywtjohoeotkbrx2a 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 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 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 screen /dev/tty usbserial 115200 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 brightsign shell /#troubleshooting section 3\ from here, we will enable the brightsign console 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” 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 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 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 console on reboot example secure> console on command status = 0 secure> reboot 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) the console will continue to emit logs, even after a reboot, until either the console is explicitly disabled (entering console off and reboot from the boot loader prompt) or a factory reset is performed on the player 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 note if a storage device is present and it does not contain an autorun brs file, the svc button event will not be registered if no storage device is present, the svc button event will be registered shell commands the following commands are currently available in the brightsign shell command description ? display the list of available commands help provide more information about a command clear clear the terminal window exit exit the shell dir or dir \<directory> list the contents of the current directory or the specified directory readperf measure the performance of file reading writeperf measure the performance of file writing rwperf measure simultaneus file read/write performance audioplay play an audio snippet script start the brightscript debugger can also be used to run a script from a file if passed the filename mfg perform a manufacturing test serialbaud set the serial baud rate reboot reboot the system shutdown shut down the system date display the date and time date \<yyyy/mm/dd hh\ mm\ ss> set the date and time timezone display the time zone timezone list display a list of accepted time zones timezone \<zone> set the time zone chdir \<path> or cd \<path> change the current directory delete \<filename> delete files or or directories recursively version display software versions licenses display license information registry access the device registry uptime display device uptime writebootfile write a boot file to flash erasebootfile erase a boot file in flash id display device identification information file \<filename> determine a file type hash cryptographically hash a file factoryreset reset the system to factory defaults format \<drive> \[\<filesystem>] format a drive using one of the following file systems vfat , ext3 , ext4 eject \<drive> eject a drive log display the system log unsetrtc clear the real time clock (rtc) note that this action does not modify the system clock probe probe a file analyze analyze a file ptpstatus display the ptp status usblist display a list of discovered usb devices bvn dump bvn status for debugging avsinfo soc avs information node invoke node js interpreter cursor turn mouse cursor on or off mmchealth report mmc health ping send echo request to remote host and wait for reply ifconfig configure the network interface type help ifconfig for a full list of configuration options also see default routing metrics docid 0jdtagrv4albwlyfjnj45 wifiscan scan for wifi networks httpgetperf \<url> \[\<destination file>] measure the download performance from the specified url if a destination file is not specified, the contents are discarded nslookup \<hostname> look up the hostname in the dns flushdns flush dns cache videoplay play a video snippet imageplay display an image htmlplay display an html site videomode change the current video modes docid\ qpml112mbhek7lbdguxnv edid hdmi read the edid from the attached monitor powersave set the vga power saving mode telnet for security reasons, it is recommended to use ssh over telnet telnet can be used to access both the brightsign shell and the brightscript debugger, if enabled while 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 access can be useful when the 3 5mm serial port (the default interface for the brightsign shell) is inaccessible enabling telnet telnet is enabled by writing a registry key to player’s registry the player must be rebooted for telnet to take effect from the brightsign shell registry write networking telnet 23 reboot alternatively, the following lines can either be entered at the brightscript debugger prompt or included as part of an autorun brs file reg = createobject("roregistrysection", "networking") reg write("telnet","23") rebootsystem() further info regarding telnet can be found telnet and ssh docid\ l0l gyihavtdbci9ffcqh accessing telnet once telnet has been enabled, it can be accessed through a terminal app telnet \<ip address> further info regarding telnet can be found telnet and ssh docid\ l0l gyihavtdbci9ffcqh ssh ssh can be used to access both the brightsign shell and the brightscript debugger, if enabled while it is sometimes preferred to use a serial cable instead of ssh for reliability reasons (e g , network stability or when an application has forced the player into a reboot loop), ssh access can be useful when the 3 5mm serial port (the default interface for the brightsign shell) is inaccessible enabling ssh 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 reg = createobject("roregistrysection", "networking") reg write("ssh","22") n=createobject("ronetworkconfiguration", 0) n setloginpassword("password") n apply() reg flush() rebootsystem() further info regarding ssh can be found telnet and ssh docid\ l0l gyihavtdbci9ffcqh accessing ssh once ssh has been enabled, the following ssh commands can be used ssh brightsign@\<ip address> ssh brightsign\@brightsign \<serial number> local useful telnet and ssh flags here are some tips for enabling serial output for various circumstances refer telnet and ssh docid\ l0l gyihavtdbci9ffcqh for info on telnet \[networking]telnet 22 enables ssh ( ronetworkconfiguration docid\ u6zceyqddlz9xdakttmjs 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 reg = createobject("roregistrysection", "networking") print "trying to enable serial with telnet/ssh" print reg write("serial with telnet", "1") reg flush() although the registry key is labeled “serial with telnet”, it applies to both telnet and ssh configurations additional info telnet and ssh docid\ l0l gyihavtdbci9ffcqh 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 /#accessing 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 brightsign shell /#telnet or brightsign shell /#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 registry = createobject("roregistrysection", "networking") registry write("syslog", "my syslog server") registry flush() 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 logs endpoints docid\ gvrltps3clnqwbf6nmepm 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 docid\ kku9e7f7chc5lwofxs9e0 for more information 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 brightsign shell /#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 serial port configuration docid\ zen3qywtjohoeotkbrx2a 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 brightsign shell /#accessing the brightsign shell 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 /#accessing 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 https //discussions apple com/thread/6078814?answerid=6078814021#6078814021 still having issues? if you’ve tried the above steps and are still have issues, you may need to factory reset a player docid\ yncf7p2pyzo2qedf1jyim if troubles persist, please contact support\@brightsign biz mailto\ 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 a player docid\ yncf7p2pyzo2qedf1jyim without access to the brightsign prompt and without the use of a script, the player can be factory reset by performing the following steps hold both svc and reset while applying power hold these 2 buttons until the err light flashes repeatedly red 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 the player will be factory reset next, power down the player hold svc while applying power 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 during an os update, both the brightsign shell and “debug mode” (script debug) are reset to disabled