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:
- Open up a terminal shell application, for example, one of the following:
- Command.com or other terminal on Windows (All Programs -> Accessories -> Command Prompt)
- Gnome or other terminal on Linux
- Terminal on Mac
- Type the command:
telnet rokuPlayer-ip-address 8085
% telnet 192.168.1.100 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
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:
|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|
|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|
|print, p, or ?||Print a variable or expression|
|step, s, or t||Step one program statement|
|over||Step over function|
Available since firmware version 7.2
|out||Step out of a function|
Available since firmware version 7.2
|up or u||Move up the function context chain one|
|var||Print local variables and their types/values|
|Any Brightscript statement||Execute 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