Testing Roku Channels involves using a debug console and access to a variety of ports. The debug console provides a window into the runtime environment and provides features such as crash logs, stack-traces and much more.
Sections:
- Accessing the debug console
- Debug ports
- BrightScript debug console commands
- SceneGraph debug server commands
- SceneGraph debug ports1
1 This section only applies for firmware v7.2 and below. As of firmware version 7.5, port 8089 - 8093 have been deprecated and thread info has been integrated into port 8085.
The Roku Plugin for Eclipse contains a built-in console with access to all the available debug ports.
The debug console can also be accessed using telnet through a shell application such as PuTTY for Windows or terminal on Mac and Linux: telnet roku-ip-adress 8085
The console shows the output of your channel during run time. If the channel crashes, the debugger will display the line number of the error, as well as the contents of variables at the time of the crash. If there is a syntax error in the code, it will also be described here. The developer console should be open whenever a channel is side-loaded to catch any possible startup errors.
In addition to displaying console output, the shell can also be used as an interactive debugger. When your application is running, simply press ctrl + c to break the application and enter debug mode. You will see the BrightScript Debugger prompt where you can type in commands.
ℹ️ You can also force your channel to break at a specific point by adding the
stopcommand anywhere in your code.
| Port | Thread | Description |
|---|---|---|
| 8080 | debug server | debug server containing a host of utilities |
| 8085 | Main() | BrightScript runtime environment |
| 8087 | Screensavers | The starting point for screensavers |
| Command | Description |
|---|---|
bsc |
Print current BrightScript Component instances |
bscs |
Print a summary of BrightScript component instance counts by component type. |
brkd |
Toggle whether BrightScript should break into the debugger after non-fatal diagnostic messages. |
bt |
Print backtrace of call function context frames |
classes |
Print Brightscript Component classes |
cont or c |
Continue Script Execution |
down or d |
Move down the function context chain one |
exit |
Exit shell |
gc |
Run garbage collector |
help |
Print the list of debugger commands |
last |
Print the last line that executed |
list |
List current function |
next |
Print the next line to execute |
over |
Step over function (Available since firmware version 7.2) |
out |
Step out of a function (Available since firmware version 7.2) |
print, p, or ? |
Print a variable or expression |
step, s, or t |
Step one program statement |
threads1 |
List all current executed suspended threads |
thread <ID>1 |
Select a suspended thread to debug - all following debug commands will execute within that thread |
up or u |
Move up the function context chain one |
var |
Print local variables and their types/values |
1 This command is only available on firmware version 7.5 and greater.
ℹ️ BrightScript statements can also be compiled and executed in the console. This can be used to change variables during execution or call a function that prints useful information about the state of your program.
With firmware version 7.5+, the main debug port (8085) now provides context for all threads. This eliminates the need to have multiple telnet sessions open for each running thread and ports 8089 - 8093 will no longer be used.
As seen below, any break or stop in the channel will suspend all threads. All threads will be listed with the following information:
- ID: thread ID
- Location: file the thread originated from and line number
- Source Code: current line of code
The current selected thread will be marked with an *.
ℹ️ This information can be recalled anytime during debugging using the
threadscommand.
| Command | Description |
|---|---|
loaded_textures |
Displays the current set of images loaded into texture memory |
r2d2_bitmaps |
Prints a list of assets loaded into texture memory and the amount of free, used, and maximum available memory on your device, respectively. |
sgnodes all |
Prints every existing node created by the currently running channel |
sgnodes roots |
Prints every existing node without a parent created by the currently running channel. The existence of these unparented nodes means they are being kept alive by direct BrightScript references. These could be in variables local to a function, arrays, or associative arrays, including a component global m or an associative array field of a node. |
sgnodes node_ID |
Prints nodes with an id field set to node_ID, except it bypasses all the hierarchy and rules, and just runs straight down the whole list in the order of node creation. It will list multiple nodes if there are several that match. |
sgversion force or default 1.0 or 1.1 |
This command can be used to change the observer callback model and can also override the default rsg_version specified in the manifest. For example, sgversion force 1.0 will set rsg_version=1.0 regardless of what is specified in the manifest. With default, it will set the default rsg_version when it is not specified in the manifest. Changing the rsg_version will require restarting the channel but these changes will not survive a device reboot. |
ℹ️ These commands are similar to the getAll() , getRoots() , getRootsMeta(), and getAllMeta() ifSGNodeChildren methods, which can be called on any SceneGraph node.
The following section only applies for firmware version 7.2 and below:
SceneGraph applications can be debugged using the same tools as previous Roku applications. However, there are some additional ports that can be used to debug specific threads of SceneGraph applications, and port 8085 has limited value in debugging SceneGraph applications.
Because SceneGraph applications run on their own thread, and can also launch additional asynchronous threads using a Task node, five additional ports are available for debugging, as follows.
| Port | Thread | Description | | ---- | ------ | ----------- | | 8085 | Main() | For SceneGraph applications, the Main() function only starts the SceneGraph application thread, so provides no debugging information about the SceneGraph application itself. | 8089 | SceneGraph| The main SceneGraph application thread. This contains all of the debugging information for SceneGraph applications, except for information returned from asynchronous threads launched by a Task node. | 8090 | First Task node thread | The first asynchronous thread launched by a Task node. If only one asynchronous thread is running after the Task node thread is launched, this port will show the debugging information for that thread. | 8091 | Second Task node thread | The second asynchronous thread launched by a Task node. If there are two asynchronous threads running after a Task node is launched, this port will show the debugging information for the second thread launched. | 8092 | Third Task node thread | The third asynchronous thread launched by a Task node. If there are three asynchronous threads running after a Task node is launched, this port will show the debugging information for the third thread launched. | 8093 | More than three task node threads | This port is used if there are more than three asynchronous threads that have been launched by a Task node. If there are more than three asynchronous threads running after a Task node is launched, this port will show all the debugging information for all the threads launched after the third asynchronous thread.