Skip to end of metadata
Go to start of metadata

This page has been deprecated. Please see Testing and Debugging Roku Channels for the latest changes.

Accessing the Debug Console

Using a standard shell program and a Telnet client application, you can connect to the console for your application. The console provides you a window into the runtime environment for your application. By default, all console output from your application goes to the shell. You can learn a lot about your application just from the debug output. To access the console for your application:

  1. Open up a terminal shell application, for example, one of the following:
    • or other terminal on Windows (All Programs -> Accessories -> Command Prompt)
    • Gnome or other terminal on Linux
    • Terminal on Mac
  2. Type the command:

telnet rokuPlayer-ip-address 8085

For example:

telnet 8085


You should see the contents of the current application output buffer. Make sure your application is running, because you must run a development app to see output in this console. The console will not allow access to the output of other applications on the system. It will only allow debug access to your development application.

Connecting to the Application Debug Console

Script Output

The console shows you the output of your script during run time. If your application crashes, the debugger will display the line number of the error, as well as the contents of various variables at the time of the crash. If there is a syntax error in your code it will also be described here. You should have the developer console open whenever you install a new application to catch any startup errors.

The BrightScript Debugger

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 application to break at a specific location by placing the "stop" command anywhere in your script.

You can resume you application again by typing "c" or "cont". For a full list of options, type "help" in the debugger. You'll see options for inspecting variables, stepping through your code and looking at the backtrace of the current call stack.

A Sample Debug Session

Debug Console Commands

The BrightScript Debug Console is one of the most important tools you will use when writing and debugging your application. Be sure to familiarize yourself with the use of the Debug Console.

The Debug Console is entered if a runtime error occurs or if the "stop" statement is explicitly executed during script execution. The Debug Console can be accessed by using a telnet client to connect to port 8085 on your device for normal scripts, or port 8087 for screensavers. You can determine the IP address of your device by looking in Settings->About on the Roku home screen.

The Debug Console prompt looks like this:

Any print statements executed by your script will also appear in the Debug Console telnet window.

Type "help" to get a list of commands you can use in the Debug Console.

Since the Debug Console is entered when a stop statement is executed, you can insert "stop" statements in your code to set a breakpoint. You can then use "c", "s", "t" to continue or step execution. 

One of the most powerful things you can do is to type in any BrightScript statement at the console. It will be compiled and execute in the current context. You could use this to change variables during execution, to call a function that prints useful information about the state of your program, or just to experiment and see how different Brightscript statements and components operate.

The following debugger commands are available: 

bscPrint current BrightScript Component instances
bscsPrint a summary of BrightScript component instance counts by component type.
brkdToggle whether BrightScript should break into the debugger after non-fatal diagnostic messages.
btPrint backtrace of call function context frames
classesPrint Brightscript Component classes
cont or c Continue Script Execution
down or dMove down the function context chain one
exitExit shell
gcRun garbage collector
helpPrint the list of debugger commands
lastPrint the last line that executed
listList current function
nextPrint the next line to execute
print, p, or ?Print a variable or expression
step, s, or tStep one program statement
overStep over function
Available since firmware version 7.2
outStep out of a function
Available since firmware version 7.2
up or uMove up the function context chain one
varPrint local variables and their types/values
Any Brightscript statementExecute an arbitrary Brightscript statement


Getting Packet Traces

It is sometimes useful to get packet traces from the Roku device in the process of debugging your application.  On the Roku platform, this can be done by sharing the internet connection of your development PC (the host computer) with the Roku device.  Traffic can then be captured using a network capture tool such as Wireshark:

To set up internet connection sharing on Windows, press the Start menu and then select the Help and Support menu option.  Enter Using ICS in the search box and press enter.  Then select the search result called Using ICS (Internet Connection Sharing) and you will be taken to the help documentation as shown in Figure 1 below.

Figure 1 - Setting up Internet Connection Sharing on Windows


  • No labels