Lab 3: FreeRTOS debug derby

What will learn in this lab

• Some of the things that can easily go wrong with real-time, multiple-task embedded systems
• Debugging strategies

Overview

Lab #2 used FreeRTOS to blink LEDs and run a UART. Having a reliable way to output text can be very useful for debug. But what do you do when the text output itself is broken?

This lab will introduce you to a variety of ways that even simple-seeming systems like ours can break; and hopefully in doing so, make you more skilled at building them.

Prework

The prework is a short video describing how an ADC works. The part on algorithms isn’t really important for this lab, but is nice background information. The part about different ways to read a DAC is important; our library, in ADC_DAC.c, uses the spin-wait loop described in the video (its slide 16, starting about time=10:35).

Initial set up

You can build this lab in either of two ways. First, just like last week, start with the zipped, basic VScode/FreeRTOS environment and add a few new files to it from our website. Second, you could just make a copy of last week’s project, delete the extras that you added last week and use that as your clean base.

In either case, once you have a clean VScode/FreeRTOS set up, rename it to lab3_debug_derby and add the extras for this week: the files main_problem1.c for the first problem and main_problem2.c for the second.

Note that, by default, platformIO will compile every .c file in src. so if you have both main_problem1.c and main_problem2.c in src at the same time, then both will be compiled, and you will have numerous clashes between them, causing multiple linker errors. Perhaps the simplest way around this is to temporarily rename which ever one you aren’t using to have any extension other than .c. So, when you’re working on the first problem, you could rename main_problem2.c as main_problem2.c_unused. Then, when you’re ready for the second problem, reverse that trick and instead rename main_problem1.c.

Tricks of the trade

Debugging is difficult, even with a full desktop IDE, and it’s way harder with our bare-bones set up. Here are a few tricks that may help:

• Trial and error are your two best friends. When you’re debugging a hang, like in problem #1, try commenting out various lines of code to see if that causes the hang to vanish. If you can find one line of code that seems to be causing the problem, clearly you’ve found a good clue.
• Above and beyond commenting out single lines of code, you can try commenting out entire features. Can you get some minimal system to behave as expected? When you add entire features in one by one, which feature break things?
• Keep good records of all the things you’ve tried and their results. After you’ve conducted half a dozen experiments, it’s surprisingly easy to forget how they all turned out.
• In an industry that values time to market, we often borrow code. The bugs will involve pieces of code or concepts that you may well not understand. True, that’s not particularly fair; but when you have a real job, it is going to be part of your life. Tackling problems like that now will give you great things to talk about on job interviews :-).
• You can re-purpose one of the LEDs as a debug tool. For example, start with the LED off and turn it on at a certain point in the code to see if that point is ever reached.
• VSCode has a debugger built into it. Feel free to use it if you know how, or to ask with help, if you don’t. The debugger can help for simple things; it’s a bit underpowered to deal with our system that has interrupts every millisecond.
• Above all: this is just a class, and it’s not worth getting frustrated if your debugging is hard. Ask for help before you hit your frustration point!

Debugging problem #1

This example for you to debug is just a version of last week’s lab. However, it has multiple bugs. Your job, of course: to find them.

 Debugging problem #2

This example is a look ahead to our ECG labs. A main task uses an ADC to sample an analog voltage input every 2 ms. A second task merely blinks the red and green LEDs on and off. It serves as a “canary in a coal mine;” if the LEDs are blinking, then the task (and presumably the system) is alive.

However, the LEDs don’t blink. Your job: find out what’s stopping them from blinking. The “why” may be too hard, but take your best shot.

What to turn in

Turn in your final working code for each problem. In addition turned in a short summary of which bugs you fixed and why they needed to be fixed. Please do this as two .c files and a .pdf file (so three total files).