BrightScript debug protocol

The Roku socket-based BrightScript debug protocol enables Roku app development to be tightly integrated into Visual Studio Code, Eclipse, and other Integrated Development Environments (IDEs). A tight integration helps expedite Roku app development as an IDE could be used to do the following:

• Write code using BrightScript syntax-directed editing and highlighting.
• Upload and run the app directly to the Roku media player.
• Communicate app stops and failures.
• Stop a running app.
• Inspect variables and stack traces of a stopped app.
• Step through a thread.
• Insert dynamic breakpoints.
• Resume a stopped app (if a fatal error has not occurred in the script).

This protocol may be used in an interactive debugging session. Do not use it for storing data in a static file.

Network Format

The network format of the protocol adheres to the following rules:

• Numeric values are sent in little-endian order.
• Data types are sent as a network byte stream in little-endian order.
• String values are encoded as UTF-8.

The notation used in this specification is similar to C++; however, the protocol describes the network data stream format—it does not define in-memory data structures.

Debugging target startup sequence

After an app is launched with a request to enable remote debugging, the firmware waits for a connection from the remote debugger client. Immediately after a connection is established, an initial handshake is then performed. The handshake consists of the following data being sent by each end of the connection:

struct HandshakeToDVP {    // DVP = Digital Video Player (Roku device)
    uint64 magic_number;   // 0x0067756265647362LU
};

struct HandshakeFromDVP {    
    uint64 magic_number  
    uint32 protocol_major_version;
    uint32 protocol_minor_version;
    uint32 protocol_patch_version;
    uint32 remaining_packet_length;
    int64  platform_revision_timestamp;
};

The behavior after the handshake has been executed, depends on the version of the BrightScript debug protocol being used:

• 2.0.0 (and later): The debug target will immediately stop on the first BrightScript statement in the script and send an ALL_THREADS_STOPPED message. The debugger client (for example, an IDE) may then set dynamic breakpoints in the target before its execution. In all cases, the debugger client must send a CONTINUE command to begin executing BrightScript code.
• 1.0.1: The debug target runs immediately after the handshake.

Debugger Request Format

Remote debugging clients can send a debugger request to the debugging target (for example, the script group) using the following packet structure for the network byte stream:

struct DebuggerRequest {
    uint32 packet_length;
    uint32 request_id;        
    uint32 command_code;      
    uint8 command_arguments;
};

Debugger Response Format

The debugger sends responses to DebuggerRequest messages in the following format:

struct DebuggerResponse {
    uint32 packet_length;  
    uint32 request_id;  
    uint32 error_code;
    uint32 error_flags;
    uint8[] error_data;
    uint8 data;
};

enum ErrorFlags {
    INVALID_VALUE_IN_PATH = 0x0001,
    MISSING_KEY_IN_PATH = 0x0002
};

Debugger Update Format

The debugger sends an update message when a state change occurs in the application being debugged, which may or may not have been requested by the debugging client or user. DebuggerUpdate messages have a similar format as DebuggerResponse messages, except that the request_id is always 0, and it includes an update_type field, which specifies the type of update being sent.

struct DebuggerUpdate {
        uint32 packet_length;
        uint32 request_id;
        uint32 error_code;
        uint32 update_type;
        uint8 data;
};

AllThreadsStopped

If the update_type in a DebuggerUpdate message is set to ALL_THREADS_STOPPED, the data field contains a structure named AllThreadsStoppedUpdateData that provides the reason for the stop. The AllThreadsStoppedUpdateData structure has the following syntax:

struct AllThreadsStoppedUpdateData{
        int32 primary_thread_index;
        uint8 stop_reason;
        utf8z stop_reason_detail;
};

ThreadAttached

If the update_type in a DebuggerUpdate message is set to THREAD_ATTACHED, the data field contains a structure named ThreadAttachedUpdateData that provides the reason for the stop. The ThreadAttachedUpdateData structure has the following syntax (see AllThreadsStopped for the details of each field):

struct ThreadAttachedUpdateData{
     int32 thread_index;
     uint8 stop_reason;   
     utf8z stop_reason_detail;
}

BreakpointError

A BREAKPOINT_ERROR is sent if a compilation or runtime error occurs while evaluating the cond_expr of a conditional breakpoint. In this case, the update_type field in a DebuggerUpdate message is set to BREAKPOINT_ERROR, and the data field contains a structure named BreakpointErrorUpdateData that provides the reason for the error. The BreakpointErrorUpdateData structure has the following syntax:

struct BreakpointErrorUpdateData {
    uint32                    flags;            
    uint32                    breakpoint_id;
    uint32                    num_compile_errors;
    utf8z[num_compile_errors] compile_errors;
    uint32                    num_runtime_errors;
    utf8z[num_runtime_errors] runtime_errors;
    uint32                    num_other_errors;
    utf8z[num_other_errors]   other_errors;
}

CompileError

A COMPILE_ERROR is sent if a compilation error occurs. In this case, the update_type field in a DebuggerUpdate message is set to COMPILE_ERROR, and the data field contains a structure named CompileErrorUpdateData that provides the reason for the error. The CompileErrorUpdateData structure has the following syntax:

struct CompileErrorUpdateData {
    uint32 flags;
    utf8z  error_string;
    utf8z  file_spec;
    uint32 line_number;
    utf8z  library_name;
}

BreakpointVerified

Available since Roku OS 12.0

A BREAKPOINT_VERIFIED message is sent when a breakpoint has successfully been applied to an executable line of code. Breakpoints may be added at any time; however, the changes may not be applied immediately if the debug target is running. In this case, the update_type field in a DebuggerUpdate message is set to BREAKPOINT_VERIFIED, and the data field contains a structure named BreakpointVerifiedUpdateData that provides the ID assigned to the verified breakpoint. The BreakpointVerifiedUpdateData structure has the following syntax:

struct BreakpointVerifiedUpdateData {
    uint32 flags // Reserved for future use
    uint32 num_breakpoints
    VerifiedBreakpointInfo[num_breakpoints]
}

struct VerifiedBreakpointInfo {
    uint32 breakpoint_id
}

ProtocolError

Available since Roku OS 12.0

A PROTOCOL_ERROR message is sent when an unrecoverable error has occurred on the protocol stream. As a result, the debug target is terminated. In this case, the update_type field in a DebuggerUpdate message is set to PROTOCOL_ERROR, and the data field contains a structure named ProtocolErrorUpdateData that provides the reason for the protocol error. The ProtocolErrorUpdateData structure has the following syntax:

struct ProtocolErrorUpdateData {
    uint32 flags // Reserved for future use
    uint32 protocol_error_code
}

enum ProtocolErrorCode {
    UNDEFINED = 0,
    IO_CONSOLE_FAIL = 1
}

ExceptionBreakpointError

An EXCEPTION_BREAKPOINT_ERROR is sent if a compilation or runtime error occurs while evaluating the cond_expr of an exception breakpoint. In this case, the update_type field in a DebuggerUpdate message is set to EXCEPTION_BREAKPOINT_ERROR, and the data field contains a structure named ExceptionBreakpointErrorUpdateData that provides the reason for the error. The ExceptionBreakpointErrorUpdateData structure has the following syntax:

struct ExceptionBreakpointErrorUpdateData {
    uint32                    flags;
    uint32                    filter_id;
    uint32                    num_compile_errors;
    utf8z[num_compile_errors] compile_errors;
    uint32                    num_runtime_errors;
    utf8z[num_runtime_errors] runtime_errors;
    uint32                    num_other_errors;
    utf8z[num_other_errors]   other_errors;
    uint32                    line_number;
    utf8z                     file_path;
}

Debugging Commands

The BrightScript debugger supports the following debug commands:

ThreadsResponse

The ThreadsResponse struct has the following syntax:

struct ThreadsResponse{
    uint32 threads_count;
    ThreadInfo[] threads;
};

struct ThreadInfo{
    uint8 flags;        
    uint8 stop_reason;  
    utf8z stop_reason_detail;
    uint32 line_number;
    utf8z function_name;
    utf8z file_path;
    utf8z code_snippet;
};

StackTraceResponse

The StackTraceReponse struct has the following syntax:

struct StackTraceResponse{
    uint32 stack_size;
    StackEntry[] entries;
};

struct StackEntry{
    uint32 line_number;
    utf8z function_name;
    utf8z file_name;
};

Variables arguments

VariablesResponse

The VariablesResponse struct has the following syntax:

struct VariablesResponse{
    uint32 num_variables;
    VariableInfo[] variables;
};

struct VariableInfo{
    uint8 flags;           
    uint8 variable_type;   
    utf8z name;           
    uint32 ref_count;
    uint8 key_type;
    uint32 element_count;
    void* value;
};

Step arguments

Execute arguments

ExecuteResponseData

• Success: ErrorCode::OK. The code snippet was legal BrightScript and no compile-time errors occurred. However, the code itself may still generate a runtime error. For example, the code snippet "x = 5 / 0" will compile but generate a "divide by zero" runtime error. This error would be sent as text to the output stream of the debugging connection.

  If the error_code is ErrorCode::OK, the following fields are also included:

  Field	Type	Summary
  execute_success	bool	Indicates whether the code ran and completed without errors (true).
  runtime_stop_code	uint8	A StopReason enum.
  num_compile_errors	uint32	The number of compile-time errors.
  compile_errors	utf8z[num_compile_errors]	The list of compile-time errors.
  num_runtime_errors	uint32	The number of runtime errors.
  runtime_errors	utf8z[num_runtime_errors]	The list of runtime errors.
  num_other_errors	uint32	The number of other errors (for example, permission errors).
  other_errors	utf8z[num_other_errors]	The list of other errors.

• Failure: other ErrorCode. No additional fields are included.

Dynamic Breakpoints

Dynamic breakpoints enable developers to navigate through the app, inspect its state, and view its execution flow when a specific runtime conditions occurs. The debug protocol includes commands for adding, listing, and removing breakpoints.

AddBreakpointsRequestArgs

The AddBreakpointsRequestArgs struct has the following syntax:

struct AddBreakpointsRequestArgs {
    uint32 num_breakpoints;
    BreakpointSpec[] breakpoints;
};

struct BreakpointSpec {
    utf8z file_spec;
    uint32 line_number;
    uint32 ignore_count;
};

AddBreakpointsResponseData

The AddBreakpointsResponseData struct has the following syntax:

struct AddBreakpointsResponseData {
    uint32 num_breakpoints;
    BreakpointInfo[] breakpoint_responses;
};

struct BreakpointInfo {
    uint32 breakpoint_id;
    uint32 error_code;
    uint32 ignore_count;
};

ListBreakpointsResponseData

The ListBreakpointsResponseData struct has the following syntax:

struct ListBreakpointsResponseData {
    uint32 num_breakpoints;
    BreakpointInfo[] breakpoints;
};

struct BreakpointInfo {
    uint32 breakpoint_id;
    uint32 error_code;
    uint32 ignore_count;
};

RemoveBreakpointsRequestArgs

The RemoveBreakpointsRequestArgs struct has the following syntax:

struct RemoveBreakpointsRequestArgs {
    uint32 num_breakpoints;
    uint32[] breakpoint_ids;
};

RemoveBreakpointsResponseData

The RemoveBreakpointsResponseData struct has the following syntax:

struct RemoveBreakpointsResponseData {
    uint32 num_breakpoints;
    BreakpointInfo[] breakpoint_infos;
};

struct BreakpointInfo {
    uint32 breakpoint_id;
    uint32 error_code;
    uint32 ignore_count;
};

Conditional Breakpoints

Conditional breakpoints enable developers to break inside a code block when a defined expression evaluates to true. Clients must use the ADD_CONDITIONAL_BREAKPOINTS debug command to add breakpoints that have conditional expressions (the ADD_BREAKPOINTS command must be used to add breakpoints without conditional expressions).

Use the LIST_BREAKPOINTS debugging command to get the existing conditional breakpoints and their status.

AddConditonalBreakpointsRequestArgs

The AddConditonalBreakpointsRequestArgs struct has the following syntax:

struct AddBreakpointsRequestArgs {
    uint32 flags;
    uint32 num_breakpoints;
    ConditionalBreakpointSpec[] breakpoints;
};

struct CondtionalBreakpointSpec {
    utf8z file_spec;
    uint32 line_number;
    uint32 ignore_count;
    utf8z cond_expr;  //available since Debug Protocol v3.1
};

AddConditonalBreakpointsResponseData

The AddConditonalBreakpointsResponseData struct has the following syntax:

struct AddConditonalBreakpointsResponseData {
    uint32 num_breakpoints;
    ConditionalBreakpointInfo[] breakpoint_responses;
};

struct ConditionalBreakpointInfo {
    uint32 breakpoint_id;
    uint32 error_code;
    uint32 ignore_count;
};

Exception Breakpoints

Available since Roku OS 14.1

Exception breakpoints enable developers to pause the debugger whenever a runtime error is encountered or an exception is thrown. Unlike other breakpoints, exception breakpoints do not have an associated source file and line number, and they can not be listed or removed using LIST_BREAKPOINTS or REMOVE_BREAKPOINTS. Clients must use SET_EXCEPTION_BREAKPOINTS to set or clear the active exception breakpoints.

SetExceptionBreakpointsRequestArgs

The SetExceptionBreakpointsRequestArgs struct has the following syntax:

struct SetExceptionBreakpointsRequestArgs {
    uint32 num_breakpoints;
    ExceptionBreakpointSpec[] breakpoints;
};

struct ExceptionBreakpointSpec {
    uint32 filter_id;
    utf8z cond_expr;
};

SetExceptionBreakpointsResponseData

The SetExceptionBreakpointsResponseData struct has the following syntax:

struct SetExceptionBreakpointsResponseData {
    uint32 num_breakpoints;
    ExceptionBreakpointInfo[] breakpoint_responses;
};

struct ExceptionBreakpointInfo {
    uint32 filter_id;
    uint32 error_code;
};

Virtual Variables

Available since Roku OS 14.1

Virtual variables are values that can be retrieved with a VARIABLES request but do not correspond to actual variables (for example, the length of a container). By convention, variables start with a $ character. The following virtual variables are supported:

Virtual variables are only returned if both GET_VIRTUAL_KEYS and GET_CHILD_KEYS are set in the VARIABLES request. Variable paths may include multiple virtual keys. For example, to get the first grandchild node's thread info, the client can send a request with the following path: node.$children.0.$children.0.$threadinfo.

Sample remote debugger

You can download the Roku Remote Debugger, which is a Python-based sample command-line remote debugger for testing and debugging Roku apps under development. The Roku Remote Debugger (rokudebug.py) provides the same functionality as the BrightScript debug console; however, it demonstrates how the BrightScript network debug protocol could be used to integrate a debug tool into an IDE.

To run the Roku Remote Debugger, follow these steps:

1. Verify that you have Python 3.5.3 (or greater) installed on your machine.

2. Create a ZIP file containing the development app to be tested. You can also download sample apps to test with the debugger.

3. Sideload an app by entering the following command in a terminal or command prompt:

   python rokudebug.py --targetip <Roku device IP address> --targetpass <Roku device webserver password> <development app zip file>

   The following example demonstrates a command for running the debugger

   python3 rokudebug.py --targetip 192.168.1.10 --targetpass abcd VideoListExample/Archive.zip

4. Enter help to view a list of the available debug commands, which are as follows:

   Command	Abbreviation	Description
   addbreak	break, ab	Adds a breakpoint
   backtrace	bt	Print stack backtrace of selected thread.
   continue	c	Continue all threads.
   down	d	Move one frame down the function call stack.
   help	h	Print the available commands.
   list	l	List the currently running function.
   listbreak	Lb	List all breakpoints
   out	o	Step out of the current function
   over	v	Step over one program statement
   print var		Print the value of a specific variable.
   rmbreak breakpointid	rb	Clears the specified breakpoint
   quit	q	Quit the Roku Remote Debugger and exit the app.
   status		Show the status of the Roku Remote Debugger.
   step	S, t	Step one program statement
   stop		Stop all threads.
   thread	th	Inspect a thread.
   threads	ths	Show all threads.
   up	u	Move one frame up the function call stack.
   vars	v	Show the variables in the current scope.

[BETA] Visual Studio Code extension

You can download the beta version of the Visual Studio Code extension for the Roku BrightScript debug protocol. After extracting and installing the extension, you can use it for debugging Roku apps in Visual Studio.

Demo video

The following video demonstrates the Roku Remote Debugger, and it shows how the BrightScript network debug protocol could be used in an integration with an IDE such as Visual Studio Code.

Change log

• 12-28-2024: Roku Remote debugger 3.3.0 release.

  • DebuggerRequest messages now support a SET_EXCEPTION_BREAKPOINTS debugging command (code 12).
  • DebuggerUpdate messages include the EXCEPTION_BREAKPOINT_ERROR (updat_type code 8) command.
  • The Variables debug command now supports requesting "virtual" variables using the GET_VIRTUAL_KEYS flag and VIRTUAL_PATH_INCLUDED keys.

• 03-06-2023: Roku Remote debugger 3.2.0 release.

  • Support added for sending ADD_CONDITIONAL_BREAKPOINTS requests while the script is running.
  • DebuggerUpdate messages now include BREAKPOINT_VERIFIED (update_type code 6) and PROTOCOL_ERROR (update_type code 7) commands.

• 09-12-2022: Roku Remote debugger 3.1.0 release.

  • DebuggerRequest messages now support an ADD_CONDITIONAL_BREAKPOINTS debugging command (code 11). The LIST_BREAKPOINTS debugging command (code 7) now supports both conditional and non-conditional breakpoints.

  • DebuggerResponse messages now include error_flags and error_data fields if the value returned to the error_code field is not "OK" (error code 0).

  • DebuggerUpdate messages include the following new update_type codes:

    • BREAKPOINT_ERROR (update_type code 4). A compilation or runtime error occurred when evaluating the cond_expr of a conditional breakpoint
    • COMPILE_ERROR (update_type code 5). A compilation error occurred.

  • The Variables debug command now supports a new path_force_case_insensitive flag that forces a case-insensitive lookup of the corresponding path entry when enabled. Enabling this flag also requires the VariablesRequestFlag argument to be set to the new "CASE_SENSITIVITY_OPTIONS" value. This is useful for debugging scripts using "." notation for associative arrays, which is always case insensitive for all object types.

• 03-22-2022: Roku Remote debugger 3.0.0 release.

  • The HandshakeFromDVP object, which is sent by a Roku device to a debugger client as part of the initial handshake, includes a new platform_revision_timestamp field that is primarily used to identify the Roku OS version of the device being used for debugging.

  • DebuggerResponse messages include a new packet_length field that enables a debugger client to read past non-essential data that it does not understand.

  • DebuggerUpdate messages include the following new THREAD_DETACHED (error code 6) and EXECUTION_TIMEOUT (error code 7) error_code status and codes:

• 08-14-2020: Beta release of Visual Studio Code extension. Updated debug command table.

• 03-29-2020: Roku Remote debugger 2.0.0 release. Added breakpoint and step commands.

• 11-09-2019: Roku Remote debugger 1.0.1 release.