Review a debug log after a crash

This tutorial will help you find where and why your VEX V5 robot code crashed by using the debug logs created by PROS or vexide. You can check if you are using PROS by looking for a file named project.pros in your robot code.

This feature is not included in VEXcode, so this guide won't work if you're using the official "VEX Robotics" VS Code extension.

Background information

What are stack traces?

The VEX V5 frameworks PROS and vexide provide users with "stack traces" to aid in debugging during a crash. These help the savvy developer figure out exactly what caused a crash. For example, in the following Rust program, the program will crash because the function foo is given a number bigger than 5:

fn foo(num: i32) {
    if num > 5 {
        panic!("num was bigger than 5");
    }
}

fn main() {
    foo(10);
}

If this code ran in a desktop environment, the crash message would include the following stack trace, which contains information about where the code crashed:

thread 'main' panicked at src/main.rs:3:9:
num was bigger than 5
stack backtrace:
   0: rust_begin_unwind
   1: core::panicking::panic_fmt
   2: playground::foo
             at ./src/main.rs:3:9
   3: playground::main
             at ./src/main.rs:8:5

Code running on a VEX V5 robot doesn't give specific line numbers or file names in stack traces, instead logging machine-readable address codes. Read on to learn how to use these to solve robot code crashes.

Install the Visual Studio Code extension

Install Symbolizer for VEX V5 from the VS Code extension marketplace:

https://marketplace.visualstudio.com/items?itemName=vexide.symbolizer-for-vex-v5

This extension will allow you to find the buggy lines of code using your program's debug logs.

Open the debug log

Debug messages are sent over the robot's USB serial connection, so connect the V5 brain to your computer using a USB cable before running the buggy program.

Use one of the following methods to start the log message viewer. Then, the next time the buggy program crashes, its debugging information will appear in the VS Code terminal.

Option 1: View logs with the PROS extension

Install the "PROS" VS Code extension (it's likely you already have it).

Start the V5 brain terminal by selecting PROS icon > V5 Brain > Brain Terminal.

Option 2: View logs using vexide

Install the vexide tooling by following the instructions on this page:

https://vexide.dev/docs/prerequisites/

Start the V5 brain terminal by opening a new terminal and running cargo v5 terminal.

Reveal the buggy code

The next time your program crashes, you will be presented with a debug log containing a stack trace.

This is a list of alphanumeric "addresses" that encode the file names and line numbers of the buggy code in a machine-readable format.

Hold Ctrl (Windows, Linux) or Command (macOS) while clicking on each address to decode it and open the line of code that was running during the crash. More recent function calls will appear at the top of the stack trace.

If the code you open is part of an external framework like PROS, Symbolizer for VEX V5 will present a link that allows you to view the relevant code online.