Debugging Webpages

Web Inspector

You can use the Web Inspector to debug webpages over the local network.

The JavaScript console should only be used in non-production presentations and it should be disabled before you publish in a production environment because it uses more memory, which can lead to frequent reboots, and it compromises security.

Enabling the Web Inspector

The Web Inspector can be enabled using BrightAuthor:connected, BrightAuthor, or BrightScript:

BrightAuthor:connected: Select Allow JavaScript console in the Chromium Debugging section of the DWS and Enable Javascript console in Presentation tab > State Properties > Options. To disable Chromium debugging, uncheck either of these boxes.
BrightAuthor: In your BrightAuthor presentation, navigate to File > Presentation Properties > HTML and check the Enable Javascript console box. Note that as of BOS 8.5.31 you will need to also set the enable_web_inspector registry key (in the "html" section) to enable the JavaScript console. See the "inspector_server" in roHtmlWidget for more information.
BrightScript: When creating the roHtmlWidget instance, include the inspector_server initialization parameter and specify a port number. Note that as of BOS 8.5.31, you must set the enable_web_inspector registry key to “1” to enable the web inspector for Chromium on the player (if it is set to “0” or nothing, the web inspector is disabled). For example:

reg = CreateObject("roRegistrySection","html")
reg.Write("enable_web_inspector", "1")
reg.Flush()

If you want to change the web inspector port, you must edit the configuration of roHtmlWidget. See the "inspector_server" in roHtmlWidget for more information.

Enabling the Web Inspector creates a security vulnerability on BrightSign players. See this page for more details.

Inspecting a Webpage

Once HTML content is running on a BrightSign player, follow these steps to inspect it:

Open Chrome on a desktop computer connected to the same local network.
Enter the following URL into the address bar: chrome://inspect/devices
In the Devices section, click Configure.
Enter the player IP address and Web Inspector port in the field (see the image below). The page(s) being run on the BrightSign player will be displayed at the bottom of the page.
1. If you don't know the player IP address, power on the player with the microSD card (and other storage devices) removed. After a few moments, the IP address will be displayed on screen.
2. If you enabled the Web Inspector in BrightAuthor, use port 2999 (e.g. http://192.168.1.62:2999/).
Click the Inspect button next to a page. A debugging session will be launched in a new window. Unlike local pages, the page contents are not displayed in the left pane, but the inspector window on the right can be used to debug the page.

Adding more than one device in your list can cause performance issues, especially if the devices are not online, because the Chrome client will continue to search for any offline devices.

Chromium Version Compatibility

Because BrightSign players use an older version of Chromium than recent desktop versions, newer desktop Chrome releases may not work with the Web Inspector. If you're having trouble using the Web Inspector with your version of Chrome, download and install one of these versions:

A larger collection of supported Chromium downloads can be found here.

Trace Events

The Chromium TraceEvent system allows you to debug JavaScript memory leaks, performance issues, and rendering problems. This feature is available in firmware versions 7.0.82 and later. Unlike PCs, where the trace/debugger is run in the same browser as the content, BrightSign players write JSON trace files to the local storage, which you can then import to Chrome on your PC.

When trace events are enabled on a BrightSign player, Chromium captures trace messages to a circular buffer. The player takes regular snapshots of this buffer and writes them to the root directory of the microSD card or SSD as JSON files.

Creating a TraceEvent Directory

Before enabling the TraceEvent system, create a directory named "brightsign-webinspector" in the root directory of the microSD card or SSD on the player. If this directory is missing, the player will not record trace events when they are enabled in the registry. Conversely, you can disable trace events by deleting the "brightsign-webinspector" directory from the storage device.

Enabling the TraceEvent System

The TraceEvent system is enabled and configured by writing to the BrightSign player registry (via BrightScript or JavaScript). To enable the TraceEvent system, write the following keys to the html section of the registry:

[string] tracecategories: A comma-separated list of trace event categories to enable. The category names are documented in the link below.
[int] tracemaxsnapshots: The maximum number of JSON-trace snapshot files in the "brightsign-webinspector" directory. When the limit is reached, the counter wraps around and begins writing over the oldest trace file.
[int] tracemonitorinterval: The frequency (in seconds) with which the player will take snapshots of the TraceEvent buffer. We recommend 60 seconds as a default value.

Example (JavaScript):

var registryClass = require("@brightsign/registry");
var registry = new registryClass();
registry.write("html", {
    "tracecategories": "toplevel,blink_gc,disabled-by-default-memory-infra,disabled-by-default-blink_gc,disabled-by-default.skia.gpu.cache",
    "tracemaxsnapshots": "25",
    "tracemonitorinterval": "60"
}).then(
    function() {
        console.log("Write Successful");
    });

Viewing Trace Events

Follow these steps to view the trace events:

Transfer the JSON trace files from the "brightsign-webinspector" directory to your PC.
Open chrome://tracing on your PC Chromium instance.
Import the JSON trace files.

You can merge multiple trace files; however, in a long trace capture, there will be too many trace events to view at once (you'll likely need to write a script to process them).

Additional Documentation

See the following links for further explanation of trace events:

Documentation