Debugging

Debugging a misbehaving program or embedded controller can be very hard, in particular because the teensy development board does not expose any JTAG headers (which is a pity because the microcontroller has them).

Print-style debugging

The go-to way practised in the firmware is classical print statements. Logging flags (Flags related to debugging) are used to turn on/off these print statements in certain parts of the code.

Post mortems

The teensy code can put some debugging information after some trap condition (such as a nullpointer access) into RAM. This feature is passed by the firmware into the system logs so there is a minimum chance to undestand at least the final reason for a crash. However, the stack pointer address of such a crash is typically not useful.

Native debugging

In the native environment, debugging is trivial because any system native debugger can be easily used. Since a recent version of the code, the ArduinoFake shim library allows to exploit the full debugging capabilities of your IDE (or pio debug, respectively) as if you would not work with any firmware at all.

Debugging with VSCode (MacOS with lldb)

To properly use the native debug mode provided by VSCode, you need to modify the launch.json file, that configures the debug process. To access the file, first open the Run and Debug menu in VSCode. Then click on the small gear labeled Open 'launch.json' (probably on the top of the window). Then amend the configurations tag by this code:

{
    "name": "LUCIDAC Debug",
    "type": "cppdbg",
    "request": "launch",
    "program": "${workspaceFolder}/.pio/build/native/program",
    "args": [],
    "stopAtEntry": false,
    "cwd": "${fileDirname}",
    "environment": [],
    "externalConsole": false,
    "MIMode": "lldb",
    "preLaunchTask": {
        "type": "PlatformIO",
        "task": "Pre-Debug"
    }
}

Now you should see a new debugging target called LUCIDAC Debug in the respective dropdown menu (probably next to the small gear icon). After selecting this target, you can start the debugging process.

Other approaches

Gdb stubs are something we have not evaulated yet. Most likely it is not feasible in time critical situations, thought.