Worked Project: Temperature Controller

Lesson 1

1. Define the product and the engineering claim

The fictional product is a benchtop temperature controller for a small test chamber. A microcontroller reads a digital temperature sensor, accepts Start, Stop and Reset commands, and drives a low-voltage heater through a switching stage. Its fixed nominal target is 35.00 °C. A separate thermal cutoff is a proposed hardware protection. There is no network connection or remote update in this example.

The user needs deliberate operation, controlled heating, fault response and an understandable fault indication. Name these UN-01 to UN-04 so that a reviewer can ask why each software requirement exists. “Keep the chamber safe” is not an adequate software requirement: it does not identify a fault, trigger, response, timing origin or physical outcome.

All temperatures and deadlines here are illustrative teaching inputs. They have not been justified by a thermal risk assessment or experiments on a real chamber. The downloadable implementation is a host-tested control core, not a complete embedded image. The project follows the work through a release decision, including the decision that missing hardware evidence prevents a physical product release.

Identify the failure chain before writing the controller: acquisition stops, an old low temperature remains available, heating continues, and the chamber may overheat. The software control will detect old data and request heat off. A detached but electrically plausible sensor, a failed clock, stalled execution or a stuck-on output can defeat parts of that argument; separate system controls and verification are needed. Follow this distinction in TFA-104 and TFA-307.

Lesson 2

2. Give requirements identities, limits and timing origins

The eight requirements below form this teaching baseline. A value in centi-degrees Celsius is an integer: 3450 represents 34.50 °C. A sample is fresh only when its age is strictly less than 120 ms. “Acquisition time” means when the measurement was obtained, not when another task read a cached copy. Input plausibility limits are deliberately wider than the permitted heating range.

REQ-001 and the timing parts of REQ-004–006 allocate work to hardware and integration as well as the pure C core. Keep those obligations visible when recording a host pass. For a real project, configuration variants, measurement accuracy, command arbitration, sensor conversion delay and operating conditions would need additional controlled requirements. This small baseline is selected for the learning objective, not presented as a complete product specification.

Use TFA-303 to challenge each trigger, boundary and verification method. If 150 ms is not justified by the product need and risk analysis, improving its wording does not make it the right number.

Lesson 3

3. Allocate architecture and agree the interface contracts

The architecture isolates decisions that can run on a development computer from mechanisms that depend on the board. This makes the core easy to exercise while keeping the hardware obligations explicit. The key interface is a coherent sensor snapshot: presence, validity, signed temperature and acquisition timestamp must describe the same acquisition.

controller_tick receives the sample by value and has a single state owner. That does not by itself make an interrupt-shared cache safe: the board adapter must construct the snapshot coherently before calling it. Choose a justified handoff mechanism, such as a bounded critical section or message transfer, and analyse its timing. Merely declaring a structure volatile does not establish that every field belongs to one acquisition.

The architecture decision is therefore two-sided: host execution helps verify deterministic decisions; adapter and hardware tests must verify the meaning of the inputs and the effect of outputs. Continue with TFA-101, TFA-202 and TFA-304.

Lesson 4

4. Define states, fault priority and the timing budget

The controller has IDLE, RUNNING and FAULT states. Heating is possible only in RUNNING. A fault takes priority over ordinary control and remains latched. A valid Reset leaves the device in IDLE; it does not resume heating. The first reason is retained until accepted reset or device reinitialisation, allowing the initial failure to remain visible while later symptoms appear.

For stale data, allocate 120 ms until expiry, at most 10 ms to the next control invocation and 5 ms for physical de-energisation: 120 + 10 + 5 = 135 ms. Against the 150 ms requirement this leaves 15 ms of design margin. It is a budget under stated assumptions, not a measured result. The worst-case task interval must include interrupt interference and blocking.

The separate invalid-data and overtemperature deadline starts at sample publication: 10 + 5 = 15 ms. It does not include the sensor's conversion delay or the time from a physical temperature change to a valid reading. Those belong in a system response requirement. The code uses unsigned elapsed-time subtraction across clock rollover, with the API assumption that relevant gaps stay below 2³¹ ms and reset or suspend reinitialises the controller. Study TFA-102 and TFA-103 alongside this budget.

Lesson 5

5. Read the implementation as a set of decisions

This is the complete control implementation included in the download. It has no device drivers, allocation, interrupt handler or operating-system dependency. Constants remain fixed so that the exercise can concentrate on behaviour and evidence. The caller must supply a valid state pointer, a coherent snapshot and a common monotonic clock, then apply the returned heater command on every invocation.

#include "controller.h"

static void trip(struct controller *c, enum fault reason)
{
    c->mode = FAULT;
    c->fault = reason;
    c->heater_on = false;
}

void controller_init(struct controller *c)
{
    c->mode = IDLE;
    c->fault = NO_FAULT;
    c->heater_on = false;
}

void controller_tick(struct controller *c, struct sample s,
                     enum command cmd, uint32_t now_ms)
{
    /* REQ-002 / REQ-005: plausibility and acquisition freshness. */
    const bool valid = s.seen && s.valid &&
                       s.centi_c >= -2000 && s.centi_c <= 12500;
    /* Intentional unsigned elapsed-time arithmetic: see API clock contract. */
    const bool fresh = valid &&
                       (uint32_t)(now_ms - s.captured_ms) < UINT32_C(120);

    /* REQ-007 / REQ-008: retain the first reason; reset never restarts heat. */
    if (c->mode == FAULT) {
        c->heater_on = false;
        if (cmd == RESET_FAULT && fresh && s.centi_c < 4000) {
            controller_init(c);
        }
        return;
    }
    if (s.seen && !valid) {
        trip(c, SENSOR_INVALID);
        return;
    }
    if (c->mode == RUNNING && !fresh) {
        trip(c, SAMPLE_STALE);
        return;
    }
    /* REQ-004: only a fresh, plausible sample supports this diagnosis. */
    if (fresh && s.centi_c >= 4500) {
        trip(c, OVER_TEMPERATURE);
        return;
    }
    if (cmd == STOP) { /* REQ-006 */
        c->mode = IDLE;
        c->heater_on = false;
        return;
    }
    if (c->mode == IDLE && cmd == START && fresh) {
        c->mode = RUNNING;
    }
    if (c->mode != RUNNING) {
        c->heater_on = false;
        return;
    }
    /* REQ-003: inclusive hysteresis limits, fixed target 35 degrees C. */
    if (s.centi_c <= 3450) {
        c->heater_on = true;
    } else if (s.centi_c >= 3550) {
        c->heater_on = false;
    }
}

Read the order as part of the design. The latched FAULT branch returns before normal commands. Invalid input and stale input while running are handled before the temperature rule; a stale hot value therefore records stale data, not an assertion about current temperature. The normal STOP branch precedes START and hysteresis. Boundary comparisons are explicit: age 120 ms is stale, 45.00 °C trips and 40.00 °C cannot authorise reset.

Integer representation avoids floating-point dependence in this small example, but does not establish measurement accuracy. No coding-standard conformity or exhaustive verification is claimed. A review should examine input contracts, numeric range, state ownership, intentional time wrap and output application. TFA-305 explains how a selected coding rule set and justified deviations would enter a real project.

Lesson 6

6. Run tests and state exactly what passed

The download includes test_controller.c and run_tests.py. On a computer with Python 3 and a C99 compiler, run python3 run_tests.py from the extracted project directory. The runner compiles with warnings treated as errors, executes explicit checks, and writes the compiler, flags, source hashes, time and result to host-results.json.

Recorded execution: 13 host test cases passed on 2026-10-03, using cc (Ubuntu 13.3.0-6ubuntu2~24.04) 13.3.0 on Linux / x86_64. The code shown above and the tests in the download are the sources identified by that record.

The suite deliberately tests decisions that can be missed by a successful nominal run: equality at a threshold, retaining state inside the hysteresis band, the first fault cause, restart inhibition and time rollover. It does not show physical current, deadline compliance, target compiler behaviour or complete structural coverage. For example, TC-013 supplies a correctly retained timestamp to the core; it cannot prove that the unimplemented sensor adapter preserves that timestamp.

A test result needs an interpretation, not just a green mark. When a real result disagrees with a requirement, retain the original run, investigate the cause and record the correction and rerun against an identifiable baseline. Use TFA-109 and TFA-306 to choose the appropriate verification level.

Lesson 7

7. Close the trace without hiding missing evidence

The table below connects every requirement to its implementation allocation and named tests. Host case links lead to the recorded checks. HIL references identify defined protocols in the download; none of the HIL protocols has been executed. Keeping that distinction in each trace prevents a host result from being used as an accidental claim about the whole product.

This is bidirectional evidence: a reviewer can move from a requirement to its test, or ask which requirement a test supports. The downloadable CSV preserves the same IDs and relationships for further work. It also exposes gaps. TC-001 checks the C initialisation values, but cannot prove that a boot-time output pulse never occurs. TC-007 checks the normal STOP transition and TC-008 checks that STOP cannot clear FAULT; neither measures the physical response time or the real button interface.

Trace links establish relationships, not sufficiency. A test may exercise one decision but miss a platform dependency, adverse sequence or relevant configuration. Review adequacy separately from link completeness. See TFA-111 for the broader evidence argument.

Lesson 8

8. Plan integration and physical fault injection

Bring up the real adapter before relying on a chamber test. Feed a completed acquisition, then repeatedly request its cached value; check that the value, validity and original timestamp stay together. Exercise the actual interrupt / task handoff under load. If the timestamp advances without a new acquisition, the core receives a false claim of freshness and cannot detect the defect from the supplied fields.

The target protocols are concrete next actions. HIL-001 observes heater current from power-up through reset and brownout. HIL-002 checks physical hysteresis behaviour. HIL-003 injects invalid and overtemperature samples. HIL-004 freezes acquisition under worst supported load and sweeps the phase relative to the control task. HIL-005 measures Stop response. HIL-006 exercises fault indication, guarded reset and separate restart.

For HIL-004, mark the last valid acquisition, the control decision and physical current on a shared timebase. The acceptance limit is 150 ms from acquisition to de-energisation. A software flag becoming false is insufficient. Specify the current threshold that means “off”, probe loading, capture resolution and uncertainty. A measurement close to the limit needs an uncertainty-aware acceptance decision, not rounding down.

These are defined protocols with no claimed results. A real review also needs sensor bias and detachment analysis, independent cutoff tests, scheduler / watchdog failure tests, target build verification and a thermal assessment. The 35 °C regulation objective needs system validation on the intended chamber and load. Passing a state-machine test cannot demonstrate thermal stability. TFA-204 shows how those responsibilities connect.

Lesson 9

9. Assemble the release evidence and make the decision

A release dossier should tell a reviewer what is being released, why its behaviour is acceptable and which limitations remain. For teaching baseline 1.0.0, the source, eight requirements, architecture contracts, 13 host tests and actual host record are available. The record hashes the implementation, header, tests and runner. There is no target binary or claimed product approval.

This is an engineering outcome, not a failed example: the evidence supports a limited release and prevents an unsupported one. A real release record would add the board and firmware identities, build configuration, image digest, review dispositions, measured verification results, residual anomalies and authorised approval. Do not fill those fields with invented names or sample passes.

Use the standards modules to organise the work. TFA-302 connects lifecycle activities and decision ownership; TFA-303 supports requirements work; TFA-304 supports architecture descriptions; TFA-305 supports a chosen coding policy; and TFA-306 supports verification planning. These are learning connections, not a claim that the example conforms to any standard. TFA-301 remains the starting point for deciding which publications actually apply.

Lesson 10

10. Assess a change across the complete chain

A developer proposes increasing the freshness limit from 120 ms to 200 ms because occasional acquisition delays trigger the fault. The change looks like one constant, but its allocated worst-case response becomes 200 + 10 + 5 = 215 ms, beyond the current 150 ms requirement. Updating the test to expect 200 ms would conceal the conflict.

First investigate the delayed acquisitions and confirm whether the requirement and risk assumptions remain valid. Possible engineering responses include repairing blocking, improving scheduling or changing the acquisition design. A change to the requirement needs its own product justification. Then revise affected architecture contracts, code, boundary tests, HIL timing tests, trace links and release decision together.

A later configurable setpoint or network interface would introduce different obligations: input range and authority, retained configuration, malformed requests and an update / support policy. Evaluate those changes with TFA-106, TFA-309 and TFA-310. Do not quietly imply those capabilities exist in this baseline.

The project is complete as a learning thread when you can explain how a changed need reaches a changed release decision. The source diff is only one link in that chain.

Decision guide

What does the current evidence justify?

Engineering evidence

What should the work produce?

Practical check

Questions for your next design review

• Can you follow REQ-005 from its user need to code, tests and release disposition?
• Does the sensor timestamp retain its acquisition meaning across every handoff?
• Can a fault clear only under the specified guard, with a separate restart?
• Are physical timing and system safety claims limited to evidence actually obtained?
• Would changing one constant trigger review of the affected requirements and tests?