Designing and Testing Microcontroller Applications

1Scope and structure of the lecture6 min

Microcontroller projects almost always fail for reasons of method, not programming - rarely because someone misunderstood a prescaler, almost always because nobody wrote down clearly what the system had to do, because the split into modules happened on the fly, or because testing was left until the end. We will follow the entire path, from a vague requirement to a documented system, through a single reference example: an automatic watering system for a greenhouse, revisited identically in every section.

• Explain the three main causes for which microcontroller projects fail
• Turn a vague requirement into a verifiable requirement, with a numeric acceptance criterion
• Partition a system into subsystems with interfaces fixed before implementation
• Describe the logic of an application as a finite state machine, starting from a complete transition table
• Distinguish the testing levels (unit, module, system, boundary, robustness) and write a test plan linked to the specification
• Apply the three principles of systematic debugging: minimal reproducible case, measure instead of guessing, separate hardware from software

2Why a project fails: the three causes11 min

The first cause: an unclear requirement. The customer says "I want the system to react quickly" or "I want it to be safe". Nobody disagrees with such statements, because nobody knows what they mean. At acceptance, the customer notices the system reacts in 300 ms and claims it is not "fast", the designer answers that nothing else was asked for, and the discussion cannot end - there is no objective criterion either side can point to. A requirement that cannot be checked by a measurement is not a requirement, it is a wish.

The second cause: poor delimitation of subsystems. When code grows without a structure decided in advance, functions start communicating through global variables, each modifying the other's state. Such a program usually works, up until the first change - that is when it turns out that changing a threshold forces changes in the relay routine, which breaks the display, and fixing the display reintroduces the original bug. The system becomes impossible to maintain not because it is complex, but because it has no internal boundaries.

The third cause, the most costly one: testing postponed to the end. It is tempting to write the whole program and only then try it, because testing along the way seems like a waste of time. In reality, when you integrate ten untested modules and the result does not work, you have no information about where the bug is - any of the ten, or any interaction between them, could be guilty. If each module was verified separately and the system breaks when the tenth one is added, the search space has shrunk to a single module.

The two stages and the cycle between them

Development unfolds in two large stages: design, which begins with the description of the system and ends with the first code draft, and testing, which begins with simulation and ends with documentation. Showing the steps as a list is misleading, because it suggests a one-way flow - in reality there is a feedback loop: if, during testing, the system does not behave according to the specification, it is not only the code that gets corrected, but design is resumed at the level where the mistake occurred, sometimes even the specification itself. A healthy project goes through this cycle several times, with decreasing amplitude each time.

Worth remembering: the design stage produces documents, not code. Block diagrams, requirement tables, transition tables and the pin map outlive the project and determine its long-term value - a working system with no document behind it is a system whose lifetime equals the memory of its author.

3The reference example and the specification13 min

The whole chapter follows a single example: an automatic watering system for a small greenhouse. It measures soil moisture and, below a threshold, opens a solenoid valve through a relay for a limited interval; it has a manual-watering button, a stop button, two status LEDs, and it sends an event log over the serial interface. The first discussion with the customer always produces a second document, just as important as the description: the list of questions - what happens if the sensor fails and permanently indicates dry soil? If someone presses manual watering and stop at the same time? If power drops during watering? An experienced designer is recognized by the quality of this list, because every question asked now is a bug that will not be discovered later in the field.

What makes a requirement verifiable

A requirement is verifiable if, with the system in front of them and a measuring instrument, two independent people are bound to reach the same conclusion about whether it is met.

A well-written requirement has four elements: a subject, an observable action, a triggering condition, and a numeric value with a unit and a tolerance. Words that should give pause when they appear in a specification: "fast", "stable", "safe", "friendly", "approximately" - each hides a negotiation that never took place.

Functional requirements describe what the system does; they are relatively easy to state, because they follow directly from the customer's description. Non-functional requirements describe under what conditions it must do those things, and are the source of most late surprises: average consumption decides whether the system can be powered from a solar panel; the temperature range decides whether the oscillator can be the internal one or must be a crystal; unit cost decides between 8 and 32 KB of program memory. None of these requirements appear in the customer's description, but all of them change the project if discovered late.

4System partitioning and choosing the microcontroller13 min

Partitioning means dividing the system into subsystems, each with a single responsibility, and establishing how they communicate. The fundamental rule: a subsystem's interface is fixed before the subsystem is implemented. The reason is practical - as long as the interface is not fixed, no other subsystem can be written, because nobody knows what it will receive and what it will return. From the moment the interface is written, even just as function prototypes with comments, every module can be developed in parallel.

The second criterion of good partitioning: each subsystem has a single reason to change. If replacing the moisture sensor with another one forces a change in the code that lights the LEDs, the partitioning is wrong. The watering system is thus split into: moisture acquisition, operator interface (buttons + LEDs), valve control, time base, serial logging, and, in the middle, the application itself, which makes decisions without touching any register.

Choosing the microcontroller

The choice is not made by habit or by whatever part is in the drawer, but as a consequence of the specification and the partitioning: once it is known which signals go in and out, the pin count is determined; once the operating periods are known, the needed peripherals are determined. Only then does the catalog get opened.

An ATmega328P satisfies every line of the table with margin to spare. Important: the conclusion followed from the table, it did not precede it - if the application had required eight analog channels and consumption under 100 µA, the same method would have led to a different chip. The practical rule: keep a margin of at least 20% on pins, memory and execution time - a project that uses everything it has is a project with no future, for which the first additional requirement forces a change of microcontroller and a board redesign.

5Program architecture and the finite state machine13 min

With the subsystems defined, next comes describing what each one does inside, through activity and state diagrams (the UML language). The quality criterion for an activity diagram is simple and strict: the code must be writable directly from it, with no further design decisions.

Polling loop or event-driven architecture

In the polling loop, the program endlessly walks through the same sequence: read every input, compute, update every output - simple and predictable, but the reaction time is, in the worst case, equal to the duration of the entire loop. In the event-driven architecture, peripherals signal the moment of an event through interrupts, and the main loop consumes the raised flags - fast reaction, but new problems appear: sharing variables with the ISR, volatile, critical sections. In practice, almost every real application is a hybrid: interrupts capture fast events, while the main loop, paced by a timer tick, makes the decisions.

The finite state machine

The natural way to organize the logic of an embedded application. The idea: the system is, at any moment, in one of a small number of well-defined states, and behavior depends not only on inputs but also on the current state - the same button press means one thing when the system is watering and another when it is waiting.

The table must be complete - for every state, every possible event, including those that produce no transition; otherwise undefined corners of behavior remain, exactly where bugs appear. Translating it into code is mechanical:

typedef enum { ST_WAITING=0, ST_MEASURING, ST_WATERING, ST_PAUSE, ST_FAULT } state_t;
static state_t currentState = ST_WAITING;

void runStateMachine(event_t ev) {
    switch (currentState) {
    case ST_WAITING:
        if (ev == EV_TICK_1S) { adcStartConversion(); currentState = ST_MEASURING; }
        else if (ev == EV_MANUAL_BUTTON) { valveOpen(); currentState = ST_WATERING; }
        break;
    case ST_MEASURING:
        if (ev == EV_INVALID_VALUE) { currentState = ST_FAULT; }
        else if (ev == EV_BELOW_THRESHOLD) { valveOpen(); currentState = ST_WATERING; }
        else if (ev == EV_ABOVE_THRESHOLD) { currentState = ST_WAITING; }
        break;
    /* ... the other states, one case per state ... */
    }
}

6The main activity: initialization, loop, buttons11 min

The activity diagram of the main program describes what happens from power-up to shutdown. It invariably begins with initialization: variables, ports with their directions, the timer that provides the time base, the ADC, the serial interface, then globally enabling interrupts. The order is not indifferent.

volatile uint8_t tickFlag = 0;    /* raised by the ISR, read by the main loop */
ISR(TIMER1_COMPA_vect) { tickFlag = 1; }   /* very short ISR: only marks time */

int main(void) {
    valveClose();               /* safe state BEFORE configuring the output */
    portsInit();
    timerInit();                 /* interrupt every 10 ms */
    adcInit(); serialInit(9600);
    parametersLoadFromEeprom();
    sei();
    for (;;) {
        if (tickFlag) {
            cli(); tickFlag = 0; sei();   /* protected clear: the ISR can write at any time */
            event_t ev = collectEvent();
            runStateMachine(ev);
            timerTick();
            logSendOneCharacter();
        }
    }
}

Note that the loop contains no active waiting and no long operation - anything that takes a long time, such as sending the log, is either split into pieces or left to interrupts.

Reading buttons by transition, not by level

A button is not read as a level, but as a transition: the system must react to the moment of the press, not to the fact that it is being held down. The standard method: keep the previously read value of the port and compare it with the current one; if they differ, a change has occurred, and the changed bits show which button was actuated. The same method solves the case of several buttons pressed at once, because the value of the whole port is interpreted as a code, and disallowed codes can be handled explicitly - if the user presses stop and manual watering at the same time, the program can explicitly decide that stop takes priority, a decision that must appear in the specification, not left to the whim of instruction order.

7Writing and early testing of the code11 min

With the diagrams finished, writing the code becomes largely transcription. The essential rule of this stage: the whole program is not written at once. The code is developed in layers, from the bottom up - first the actual clock frequency of the microcontroller is verified (toggling a pin in a loop, measured with the oscilloscope), then an output with an LED, then an input with a button, then the ADC with a potentiometer, then the timer, and only at the end are they brought together.

Why testing does not happen directly on the real installation

Two reasons. First: a software bug can destroy expensive hardware - commanding both arms of an H-bridge at once short-circuits the supply, a valve left open floods the greenhouse. Second, less obvious: the real installation cannot be brought on demand into the situations that matter - you cannot make the soil dry in five seconds to check the threshold, you cannot repeat a power failure a hundred times.

The solution is a cheap simulation module, which imitates the electrical interface of the installation: digital inputs from buttons, analog inputs from potentiometers, outputs on LEDs - for the watering system, a potentiometer in place of the sensor, three buttons, three LEDs. The cost is a few dollars; the gain is the ability to produce, at any time, any combination of inputs, including ones that are physically impossible, which are exactly the most interesting ones for testing.

Code that is easy to test

It is possible to write code that lends itself to testing and code that does not - the difference lies in separating the decision from peripheral access. A function that reads the ADC itself and writes to the relay port itself cannot be verified except with hardware. The same logic, written as a pure function that receives the measured value and returns the decision, can be compiled and run on a computer, with thousands of combinations, in a few seconds.

/* hysteresis: width of the dead zone, in the same units as moisture and threshold */
uint8_t decideWatering(uint16_t moisture, uint16_t threshold,
                        uint16_t hysteresis, uint8_t wateringNow) {
    if (wateringNow) return (moisture < threshold + hysteresis) ? 1 : 0;
    return (moisture < threshold) ? 1 : 0;
}

8The test plan and its levels11 min

Once the trial module is ready, the test plan is written - not a list of things tried "whenever it comes to mind", but a document derived from the specification, in which every requirement has at least one associated test and every test has a numeric acceptance criterion. The link is made through requirement codes, so that at the end it can be shown that no requirement was left unverified.

The testing levels

Unit tests apply to purely logical functions, which touch no peripherals: converting the ADC to a percentage, averaging, the watering decision. They are compiled for the host computer and run automatically, so they can be repeated on every code change at zero effort. A good unit test includes the boundary values of the domain.

assert(decideWatering(300, 400, 50, 0) == 1);  /* below threshold, closed: turns on */
assert(decideWatering(500, 400, 50, 0) == 0);  /* above threshold: stays off */
assert(decideWatering(400, 400, 50, 0) == 0);  /* exactly at threshold: strict comparison */
assert(decideWatering(430, 400, 50, 1) == 1);  /* in the hysteresis zone: stays open */

Module tests verify an entire subsystem, with simulated hardware - a known voltage is applied and the displayed value is compared with the one measured on a voltmeter, checking not only the logic but also the peripheral configuration (reference, prescaling, alignment). System tests verify the whole through realistic usage scenarios, timed and compared against the limits in the specification. Boundary tests exercise extreme values - a 16-bit millisecond counter wraps around after about 65 s, and a carelessly written comparison gives a wrong result right there; the test must exist in the plan, otherwise the bug reaches the customer. Robustness tests check unwanted situations: sensor disconnection, unstable power, reset during watering, simultaneous button presses. The criterion is not that the system does something useful, but that it does not do something dangerous.

9Systematic debugging9 min

However well organized a project is, bugs will exist, and the way they are hunted makes the difference between an hour and a week. Debugging is not an activity of inspiration, but a procedure with three principles.

First: reduce to a minimal reproducible case. A bug that appears "sometimes, after about half an hour" cannot be studied. The shortest sequence of actions that triggers it every time must be found, then every part of the system not necessary for reproduction is removed, one by one - disconnect the display: does it still happen? Turn off the serial log: does it still happen? Most of the time the bug becomes clear on its own during this reduction, because the part removed at which the bug disappears points directly to the cause.

Second: measure, do not guess. Most plausible hypotheses are false, and checking them often costs less than arguing about them. If you suspect an interrupt is not firing, toggle a pin inside the ISR and look at it with the oscilloscope - in three minutes you have a certain answer.

#define TEST_PIN_HIGH (PORTD |= (1<