Debugging NXT programs

[linusa]

Another recovered article:

Debugging NXT-Programs

Sooner or later all users writing programs to be executed on the NXT brick find themselves in the following situation: Your program compiles fine, is transferred to the NXT, it starts running — but it doesn’t do what you want it to! Sometimes the mistake you made is obvious, but often it’s hard to spot the flaw. Well, now it’s time for debugging: the art of finding what went wrong, and especially where. Usually during debugging, you begin to understand how your program really works, and that is what helps you fix the problem. In this post, I’d like to give some general ideas and examples for debugging NXT programs.

Independent from the language you use (NXT-G, NXC, LeJOS or whatever), you have these options to get information from a running program back to you, the debugger:

• The LCD display. This is obviously your first line of attack. Use the NXT’s display to show contents of variables, status messages, checkpoints, or anything you need. Often printing text is enough, but if you have more complex things or contents with greater volume, consider displaying graphics (pixels, graphs, symbols, etc.).
• The speaker. Don’t underestimate the NXT’s capability to play sounds or tones. I call this “acoustic debugging”. Make the NXT play signal tones or sound files when certain conditions are met, procedures are executed or a special sensor value is detected.
• Lights. Yes, that’s right. If you want to monitor a boolean value, maybe whether a certain task is running, you can use lights to show this information. There’s the red LED light of the classic NXT light sensor, the old LEGO lamps for motor ports (e.g. from the NXT Education Kit), or of course the LEDs of the new NXT 2.0 color sensor.
• Motors. If you have no space left on the display and a free motor port, why not use a motor to help you visualize a variable? You can set the motor’s power to the variable if it’s confined to a range of -100 to 100. Some of the TryMe programs utilize this method (not for debugging purpose though).
• Files. You can start generating log-files for later analysis. While this is a bit more effort initially to get yourself some helper-functions, you can re-use these routines later on in your other projects. This can be very powerful as you can include valuable information like timestamps or the calling procedure. You are however limited in available file size, and writing data to flash can sometimes take a fairly long time.
• A computer. Once you have your PC connected to the NXT via Bluetooth or USB, you can retrieve valuable information from the brick. There are many methods of different complexity. BricxCC has a nice “Watching the brick” feature, there is an NXT debug monitor which can receive string messages from your programs via mailbox queues, or you can play around with direct commands yourself.

The main reason you should think of other ways than the display during debugging: There is limited space on the LCD, and there can be problems with updating speed. It can either influence your programs performance (and certain time critical bugs might magically disappear — a Heisenbug) or your eyes aren’t fast enough to identify a flashy change. While it’s easy to overlook a certain value / text for a split of a second, you’ll usually notice a beep! Apart from that: If your program crashes, text on the LCD display is lost, while messages stored in logfiles or sent to a computer will still be readable.
Having said all this, two things are important: Most of the time, you don’t need all the different ways at once. And it’s about the right combination of methods, which depend on your actual problem.

If you’re interested in more specific details and some examples for NXC, read on.

In the remaing article I’ll focus on text-based languages and use NXC for the examples.

Handling debug statements. Most of the time you have to manually insert debug statements into your program code. Unfortunately, those statements don’t do anything “useful” apart from helping you to debug, so those commands are often considered annoying. It’s common practice to start with inserting simple TextOut commands where needed, and commenting them out later on once everything works. The more statements you’ve got, the more annoying it gets to enable them once a new bug occurs, and to disable them again eventually. I suggest wrapping your debug code in between compiler directives, i.e.

Code: Select all

#define DEBUG_LCD

#ifdef DEBUG_LCD
    TextOut(...);
#endif

This makes frequent debugging very easy: Simply comment out the statement where DEBUG_LCD is defined at the top of your progam, and debug mode is turned off. You can even have multiple define-”switches” for various debug options, like DEBUG_LCD, DEBUG_ACOUSTIC, DEBUG_LIGHTS and so on. It can make sense to wrap these statemens (including the compiler directives) into further macros, to save some lines of code for better readability.

Logging data to files or a computer. Many techniques from data-logging can be used here. In this case, we’re interested in debug messages, not sensor data. The debug messages might be too long or are generated to rapidly for being displayed on the LCD. This is why we can either send them to a PC or write them into a text-file on the NXT’s flash disk. The advantage of sending the data away to a computer: This can happen faster and easier than writing to a file (there are still limits on maximum message throughput though). You can either use the already mentioned NXT debug monitor, or write a similar custom thing on your own. An example of a very simple debug logging server can be found here (in this case written in MATLAB), the according counterpart for NXC is here (it puts a running number and a port number in front of the text message before sending). How to send strings from an NXT to a computer is described in my weather tutorial.
At this occasion I can’t refrain from mentioning the NXCProfiler (in a very early development stage), which could also be of some help.

Monitoring the NXT from a computer. Every program running on a PC interacts with the NXT via direct commands. These can be used to retrieve sensor & motor data, as well as raw data from the firmware’s memory. The cool thing: This also works while user-programs (written in NXT-G, NXC, …) are being executed at the same time, i.e. you can use all programs that run on a computer to help you debug your NXT-program (that runs on the brick). If you have tools that monitor motor position, display sensor values or anything else, feel free to use them if they help you. The possibilities are endless. I agree that this last point might not be of direct use to you, but to focus on three more specific cases:

• BricxCC’s “Watching the brick”: I won’t go into details now, but refer you to John Hansen’s book “LEGO Mindstorms NXT Power Programming: Robotics in C, second edition”. Here’s a post by John. As NXC programmer, you should definitely give the variable watching feature a try.
• Direct NXT memory access: This is very complex and advanced, never the less I should mention it. Nicolas Schodet proposed a way to read out the firmware’s memory and grab variable information from it. This is similar to what BricxCC does internally.
• The NBC debugger: My article can’t be complete without the NBC debugger being mentioned at least. Since I’m not an NBC user I’ve not yet used it, but it might work for NXC programs, too (since the NXC compiler generates intermediate NBC code first). An interesting feature I’d first try is the #pragma debuglog statement, it’s explained here.

As always, feel free to create a thread on the forums if you have questions, ideas or comments.

So long, Linus Atorf

[schodet]

Direct NXT memory access: This is very complex and advanced, never the less I should mention it. Nicolas Schodet proposed a way to read out the firmware’s memory and grab variable information from it. This is similar to what BricxCC does internally.

Dead link, here is it on my webpage: Access NXT program memory from computer

Thanks for the post!

[afanofosc]

In the most recent test release with the enhanced NBC/NXC firmware installed on your NXT you can Pause and step through a program running on your NXT in the BricxCC IDE and the current executing line is highlighted in the editor window as you step through your code. You can use this in conjunction with the configurable watch window to inspect variable values as your program runs.

This capability has not been extensively tested and I would love to have BricxCC users try it out and let me know what does or does not work for them. Setting breakpoints via the editor window is not yet supported but I am working on that. The enhanced firmware has a direct command and underlying code to support setting breakpoints but as of right now that bit of code has not been tested at all.

John Hansen