Project 001: C4 Bomb Prop — A FreeRTOS-Based Embedded System on PSoC 5LP

1. Introduction & Objectives

1.1 Introduction

This project builds a fully functional CS:GO-style C4 bomb prop around the Cypress/Infineon PSoC 5LP (CY8CKIT-059 kit, CY8C5888LTI-LP097). Behind the playful exterior, the prop is a serious, production-grade exercise in embedded system design: it combines a real-time operating system, three different serial buses, DMA-driven audio streaming from a FAT-formatted SD card, and a carefully choreographed user interface into one coherent firmware architecture.

A game prop turns out to be an ideal teaching vehicle. The requirements are strict enough to be realistic — audio must never stutter, the countdown must never drift, a key press must never be missed — yet the system is small enough that a designer can hold the entire architecture in their head. Every classic embedded-systems problem appears here in miniature: concurrency, shared-resource arbitration, real-time data pipelines, hardware/software co-design in PSoC Creator, and the kind of subtle timing bugs that only reveal themselves on real hardware.

The finished device behaves as follows. When the operator flips the power switch, the character LCD greets the user and a green LED "breathes" softly. Entering the correct 7-digit code arms the bomb: the display clears, a + marker sweeps back and forth across the screen, a red LED flashes in step with an accelerating three-stage beep pattern, and a 40-second countdown begins. A defender may press and hold a defuse key — 10 seconds bare-handed, or 5 seconds with the "defuse kit" key — while the countdown continues mercilessly underneath. Whichever timer expires first decides the outcome: a triumphant DEFUSED message, or a two-stage explosion sound effect streamed from the SD card through an I2S power amplifier.

1.2 Learning Objectives

The project is written for designers who already know C and have basic microcontroller experience, and who want to move from bare-metal super-loops to a professionally structured RTOS application. Working through the design, a designer will learn to:

1.3 Functional Specification Summary

1.4 Document Roadmap

This report is published as a three-part series. Part 1 (this article) proceeds from the outside in: the system overview, the bill of materials, the hardware design with schematics, and the complete PSoC Creator TopDesign configuration, including clocking and interrupt priorities. Part 2 presents the software architecture — the FreeRTOS task set, the SD-to-I2S audio pipeline, the operating principles behind the countdown and defuse logic, and selected implementation highlights. Part 3 collects the troubleshooting case studies encountered on real hardware, the test results, future work, and the source-code downloads.

2. System Overview

2.1 System Block Diagram

Figure 2-1 shows the system at a glance. The PSoC 5LP sits at the center; everything the user sees, hears, or touches connects to it over one of three serial buses or plain GPIO. The diagram is organized so that human inputs enter from the left, indications and sound leave to the right, and bulk storage hangs below — the same left-to-right direction in which data actually flows through the firmware.

Figure 2-1: System Block Diagram

2.2 Subsystem Summary

2.3 Data-Flow Overview

Two largely independent flows run through the system, meeting only at the event group that broadcasts the machine state.

Control flow (left to right). KeypadScanTask sweeps the matrix every 20 ms, debounces the entire keymap, and emits exactly one event per key press into a queue; it also publishes the currently held key for press-and-hold detection. KeypadTask consumes those events, renders the entry field on the LCD, and judges each complete 7-digit attempt. A correct code raises an event-group bit; CountdownTask wakes, takes ownership of the LCD, buzzer, and red LED, and runs the countdown/defuse state machine. PowerTask supervises everything: flipping PWR_SW off clears the state bits, and every task returns to a safe idle.

Audio flow (top to bottom, then out). Any task may request a sound by name. AudioReadTask opens the WAV file on the SD card via FatFs, validates the format, and fills 512-byte blocks from a shared pool; AudioPlayTask arms one DMA transfer per block into the I2S TX FIFO and recycles each block as it empties. Because only descriptors travel through the queues, the PCM data itself is never copied — a zero-copy pipeline that keeps SD-card read jitter from reaching the speaker. An abort mechanism lets the state machine cut a playing sound cleanly (for example, when a defuse attempt is released halfway).

2.4 Operating States at a Glance

The full state machine is developed in Part 2; for orientation, the system passes through five macroscopic states: Standby (power switch off; green LED breathing, LCD dark) → Entry (LCD shows the dash field, digits accepted) → Armed (40-second countdown, staged beeps, marker animation) → optionally Defusing (a hold-key overlay running on top of the still-live countdown) → a terminal Outcome (DEFUSED or EXPLODED, with its sound sequence), which persists until the power switch is cycled.

3. Component Requirements

3.1 Bill of Materials

Table 3-1 lists everything needed to build the prop. All parts are inexpensive, widely available modules; nothing requires custom PCB work — the whole system assembles on a breadboard or a piece of perfboard.

Table 3-1: Bill of materials

3.2 Component Selection Notes

Each part was chosen for a specific technical reason; understanding these choices is itself part of the lesson.

3.3 SD Card and Sound-Bank Preparation

The audio pipeline is deliberately minimal — it streams raw PCM straight from the file into the I2S FIFO with zero CPU processing — so the files must match the hardware configuration exactly:

Any audio editor or ffmpeg converts arbitrary source material in one step:

ffmpeg -i source.mp3 -ac 1 -ar 16000 -sample_fmt s16 C4INIT.WAV

3.4 Development Tools

4. Hardware Design & Schematics

4.1 Pin Assignment

Table 4-1 is the complete pin map of the design, taken directly from the project's .cydwr Pins editor. The drive mode column is not a formality — three of the subsystems in this design only work because of a deliberately chosen drive mode, as the following subsections explain.

Table 4-1: Pin assignment and drive modes

4.2 Keypad Matrix Circuit

The 4×3 keypad is a bare switch matrix: pressing a key connects one row wire to one column wire, nothing more. The electrical scheme chosen here — open-drain rows that drive high, columns with pull-downs — makes the scan both safe and simple.

Figure 4-1: Keypad matrix schematic

How the scan works. The firmware selects exactly one row at a time by writing a one-hot mask: the selected row is actively driven high, while every other row is written 0, which in this drive mode means high impedance — electrically absent. The three columns are then read: an idle column is held at 0 by its pull-down; a column reads 1 only if a key connects it to the currently driven row. Row/column intersection identifies the key.

Two electrical details deserve attention:

4.3 RGB LED Gating

One PWM serves all three LED colors. PWM_LED (1 MHz clock, period 1000 → a flicker-free 1 kHz PWM with 0.1 % duty resolution) generates a single brightness waveform; inside the UDB fabric, it fans out to three AND-style buffer gates, each enabled by one bit of the 3-bit control register CtrlReg (bit 0 = R, bit 1 = G, bit 2 = B). The gated outputs leave on P0[7:5] through per-channel series resistors to a common-cathode RGB LED.

Figure 4-2: PWM gating schematic

The division of labor is clear: software sets the PWM compare value to create effects (the breathing ramp, or parking the duty at 100% during the countdown so the red channel flashes at full brightness), while the color lit is a one-bit register write. Because two different tasks own those two halves at different times, the register is wrapped in a read-modify-write mutex — a story for Part 2.

4.4 Audio Output Path

The I2S connection to the MAX98357A is three wires plus power:

Figure 4-3: Audio path wiring

The amplifier is an I2S slave with no control bus: it locks onto whatever the PSoC transmits. The frame timing (64-bit word-select period) and the 2.048 MHz bit clock together set the sample rate to 16 kHz; the firmware transmits 16-bit mono on the left channel. All of that is configured in TopDesign — Section 5 shows the exact component settings, including one checkbox (Tx byte swap) that stands between you and pure noise.

4.5 SD Card SPI Wiring

Figure 4-4: SD card wiring

The one decision on this page that regularly bites designers is the chip select. It is tempting to let the SPI master's hardware SS pin handle CS "for free" — but SD-card commands are multi-byte transactions: a command frame, response bytes, wait states, and possibly a 512-byte data block with its token and CRC must all occur under one continuous CS assertion. Hardware SS on most SPI blocks releases the line between bytes or between FIFO batches, which the card interprets as end-of-transaction, and initialization fails in maddeningly intermittent ways. A GPIO under explicit firmware control (assert, run the whole transaction, deassert) removes the entire failure class.

5. PSoC Creator TopDesign Configuration

Everything in Section 4 was wiring; this section is the other half of PSoC hardware design — the components placed on TopDesign.cysch and their parameters. Several of these settings look innocent but are load-bearing: three of them, mis-set, produce failures ranging from pure noise to a completely frozen scheduler. Each is called out below.

5.1 TopDesign at a Glance

Figure 5-1: TopDesign.cysch overview

The design places seven components plus the pins from Table 4-1:

5.2 Component Parameters

Table 5-1: Component configuration summary

5.3 Clock Tree

Table 5-2: Clock plan

One clock, two speeds. The SD specification requires the entire initialization sequence to run at 100–400 kHz; only after the card reports ready may the host raise the clock. Rather than compromising on a single frequency, the SPIM uses an external clock (CLK_SPIM, set to 800 kHz in the schematic) and diskio.c retunes its divider at runtime: CLK_SPIM_SetDividerValue(60) before the init sequence (SCLK 400 kHz), CLK_SPIM_SetDividerValue(6) once the card is identified (SCLK 4 MHz). The switch matters quantitatively: at 400 kHz, the bus delivers barely 40 KB/s after protocol overhead, against the audio pipeline's 32 KB/s sustained appetite — a margin thin enough to starve playback. At 4 MHz, the margin is roughly 15×. Two details make the switching robust: the slow speed is forced at every disk_initialize() entry (so a retry after a card swap never inherits the fast clock), and the divider is only ever changed while CS is deasserted, so no transfer can straddle the glitch.

Why 48 MHz and not the maximum? This design originally ran BUS_CLK at 74 MHz — and the build's Static Timing Analysis reported a setup violation with −4.45 ns of slack: the UDB fabric containing the PWMs, the SPI master, the I2S shifter, and the control register could only close timing up to 55.65 MHz. A timing violation is not a warning to dismiss; it means register-to-register paths may mis-capture, producing intermittent, temperature-dependent corruption — the kind that works on the bench and fails in the field. Dropping the master clock to 48 MHz (comfortably below the fabric's ceiling and exactly dividing both 1 MHz and 2 MHz peripheral clocks) cleared every violation with zero functional cost: nothing in this system needs more CPU.

5.4 Interrupt Configuration

FreeRTOS on Cortex-M3 imposes one iron rule: any interrupt handler that calls a ...FromISR() API must run at a priority numerically greater than or equal to configMAX_SYSCALL_INTERRUPT_PRIORITY. This project sets that threshold at priority 2, and the kernel itself (SysTick/PendSV) at the lowest priority 7:

#define configPRIO_BITS                       3
#define configKERNEL_INTERRUPT_PRIORITY       ( 7 << 5 )   /* 0xE0 */
#define configMAX_SYSCALL_INTERRUPT_PRIORITY  ( 2 << 5 )   /* 0x40 */

Table 5-3: Interrupt priority plan (PSoC 5LP: 0 = highest, 7 = lowest)

Note that PSoC Creator's interrupt editor takes the raw 0–7 values from the table, while FreeRTOSConfig.h takes the same values shifted left by 5 (the priority field occupies the top 3 bits of an 8-bit register). Keeping the two representations consistent is the designer's job; get it wrong in the dangerous direction (an ISR more urgent than the syscall threshold calling a FromISR function) and the scheduler's internal state corrupts in ways that surface far from the cause.

5.5 Part 1 Summary

At this point, the hardware story is complete: every part on the bench (Section 3), every wire and drive mode (Section 4), and every component parameter, clock, and interrupt priority (this section) has a documented reason. The prop, however, is still silent and dark — all of its behavior lives in firmware. Part 2 picks up there: how eight FreeRTOS tasks divide the specification among themselves, how the SD-to-I2S audio pipeline moves sound without copying it, and how the countdown, defuse, and explosion logic is orchestrated in a single unified engine loop.

6. Software Architecture

Part 1 of this series covered the hardware: the bill of materials, the wiring, and every TopDesign parameter. Part 2 is the firmware. This section presents the architecture — how the specification decomposes into FreeRTOS tasks, how those tasks communicate, and how the audio pipeline streams sound from an SD card to an I2S amplifier without ever copying a sample.

6.1 The Task Set

The whole specification factors into eight tasks, each owning one concern and one set of hardware. The decomposition rule used throughout: a task owns a resource (a bus, a peripheral, a data stream), never a feature — features emerge from tasks cooperating through queues and events.

Table 6-1: FreeRTOS task set

Three priority decisions carry the architecture:

Figure 6-1: Task-and-communication diagram

6.2 Communication Objects

No task calls another; every interaction crosses one of these objects. That single discipline is what makes the system testable one piece at a time.

Table 6-2: Queues and semaphores

Table 6-3: Event-group bits (xSysEvents) — the system's broadcast state

6.3 The Audio Pipeline

The most instructive subsystem in the project. The requirement sounds simple — "play WAV files from the SD card" — but hides three hard sub-problems: SD reads have unpredictable latency; the I2S consumes samples at an inflexible 32 KB/s; and the state machine must be able to cut a sound off (a released defuse key) without corrupting whatever plays next.

The zero-copy buffer pool. Four 512-byte blocks live in static RAM. Two queues circulate descriptors (pointer + length) between the producer and consumer:

typedef struct
{
    uint8_t  *pData;       /* points into gAudioPool[]; NULL == end-of-stream */
    uint16_t  length;      /* valid bytes                                     */
} AudioBlock_t;

End-of-stream is in-band. When the file ends (or aborts), the reader posts a descriptor with pData == NULL. The player treats it as "stop after what is queued drains" — no side-channel flag, no polling, no race about who noticed the end first.

Aborting a stream — and the sticky-abort trap. Audio_Abort() sets EVT_AUDIO_ABORT and flushes any queued requests; the reader checks the bit between blocks and closes the file early. The subtle question is who clears the bit, and when. The answer that survived debugging: the reader clears it immediately after accepting a new request — not when the abort is serviced, and never the caller.

/* AudioReadTask main loop (shape) */
if (xQueueReceive(xAudioReqQ, &req, portMAX_DELAY) == pdTRUE)
{
    /* v2 fix: a stale abort must not kill THIS new request */
    xEventGroupClearBits(xSysEvents, EVT_AUDIO_ABORT);
    ...open, parse, stream blocks, checking the bit between blocks...
}

Blocking playback for sequences. Outcome sounds must play in order (explosion = two files back-to-back), so the audio module offers Audio_PlayBlocking(name, maxMs): wait for any current stream to end, request, wait for start, wait for finish — every wait is bounded, so a missing file can never hang the state machine.

[Figure 6-2: Audio pipeline diagram — drawing plan]

6.4 RTOS Bring-Up on PSoC 5LP

Part 1 ended on a cliffhanger: three FreeRTOS exception handlers must be installed by hand. On PSoC 5LP, cy_boot relocates the vector table into RAM and fills it with default handlers; the SVC, PendSV, and SysTick entries that FreeRTOS depends on are not wired to the kernel. Patch them before starting the scheduler:

extern void vPortSVCHandler( void );
extern void xPortPendSVHandler( void );
extern void xPortSysTickHandler( void );
extern cyisraddress CyRamVectors[];

void FreeRTOS_Init( void )
{
    CyRamVectors[ 11 ] = ( cyisraddress ) vPortSVCHandler;     /* SVC     */
    CyRamVectors[ 14 ] = ( cyisraddress ) xPortPendSVHandler;  /* PendSV  */
    CyRamVectors[ 15 ] = ( cyisraddress ) xPortSysTickHandler; /* SysTick */
}

Miss this and vTaskStartScheduler() issues its first SVC into a default infinite-loop handler: the system freezes with no fault, no assert, no clue. The remaining configuration essentials:

6.5 Source-File Map

Table 6-4: Firmware source files

Section 7 walks through the operating principles built on this skeleton — the state machine, the three-stage cadence math, and the defuse race — and Section 8 closes Part 2 with selected implementation highlights from these files.

7. Operating Principles

Section 6 built the skeleton; this section explains the behavior that runs on it — the state machine, the arithmetic behind the accelerating beeps, the defuse race, and two pieces of display craft that make the prop feel polished.

7.1 The System State Machine

Figure 7-1: System state machine

Two properties of this machine are deliberate and worth internalizing:

7.2 The Three-Stage Beep Cadence

The countdown's tension curve is pure arithmetic. The beep interval is a function of remaining time rem (in ms):

static uint32_t BeatInterval(uint32_t remMs)
{
    if (remMs > 15000u) return 1000u;                    /* stage 1: 1 Hz  */
    if (remMs >  5000u) return  500u;                    /* stage 2: 2 Hz  */
    return 50u + ((remMs * remMs) / 125000u);            /* stage 3: ramp  */
}

Stages 1 and 2 are constants; stage 3 is the interesting one. The design goal is a perceived exponential acceleration over the final five seconds — the classic movie-bomb effect — without floating point or a lookup table. A quadratic does the job:

Because the curve is steepest near zero, each second feels faster than the last — which is exactly how an exponential sounds, even though the formula is polynomial. Note also the deliberate discontinuity at the stage-2/3 boundary: the interval jumps from 500 ms to 250 ms in one beat. That audible "gear change" is the five-second warning.

The beep's ON time is min(interval/2, 60 ms): half-duty at slow rates for a relaxed "tick… tick…", but capped at 60 ms so that even at 20 Hz each blip stays a crisp click instead of merging into a continuous tone.

7.3 The Defuse Race

Defusing is a hold gesture measured against a running clock, with three thresholds in play: 1 s to enter, then 5 s (*, "with kit") or 10 s (#, "bare-handed") to finish — all while the 40-second countdown keeps running. The tracker is a tiny sub-state machine polled every 10 ms slice:

Who wins an exact tie? With 10 ms polling, both thresholds can cross in the same slice. The loop body evaluates the defuse tracker before incrementing elapsed and re-testing the countdown bound — so a same-slice tie goes to the defender. That is not an accident: the rule is encoded purely by statement order, costs zero code, and matches the game convention that a completed defuse counts even as the timer hits zero. When a race's resolution matters, write down which side wins and make the code's evaluation order say so.

Figure 7-2: Defuse-attempt timing diagram

7.4 The '+' Marker: Animation Under a Visibility Floor

During the countdown, a + bounces across the seven dash positions (odd columns 1–13) as a visual heartbeat. Its scheduler is one line: hop every max(interval/2, 200 ms) — twice the beep rate, clamped.

The clamp is the design decision. Unclamped, stage 3 would demand a hop every 25 ms: each hop costs two I2C transactions (erase old cell, draw new cell) on a 100 kbps bus shared with nothing else at that moment but budgeted for coexistence, and — more fundamentally — a character that teleports every 25 ms reads as flicker, not motion. 200 ms is roughly the floor at which the eye still tracks discrete character movement as movement. So the marker accelerates honestly through stages 1 and 2 (500 → 250 ms) and then saturates while the beeps keep accelerating underneath — the ear carries the final panic, the eye stays legible. Splitting one "faster!" requirement across two output channels with different perceptual limits is a small but transferable piece of UX engineering.

7.5 The 1×16 "Type B" LCD: One Row That Is Secretly Two

Many inexpensive 1×16 character modules are electrically a 2×8 display laid end to end: columns 0–7 live at DDRAM 0x00–0x07, but columns 8–15 live at 0x40–0x47 — the address range a 16×2 panel uses for its second row. (A "Type A" 1×16 is genuinely linear, 0x00–0x0F, and wants 1-line mode; Type B must be initialized in 2-line mode, N = 1, despite being physically one row.)

The driver hides the seam behind the normal API, and it takes two cooperating fixes because there are two ways to reach column 8:

if (sLcdType == LCD_TYPE_1X16_B && row == 0u) {
    if (col < 8u) sendCmd(HD_SET_DDRAM | col);
    else          sendCmd(HD_SET_DDRAM | (0x40u + (col - 8u)));
}

sendData((uint8_t)c);
sCursorCol++;
if (sLcdType == LCD_TYPE_1X16_B && sCursorCol == 8u) {
    sendCmd(HD_SET_DDRAM | 0x40u);      /* hop to the right half */
}

Either fix alone leaves a hole: without the Position translation, the bouncing marker (which jumps directly to columns 9, 11, 13) lands in the void; without the PutChar hop, the 16-character outcome messages truncate. Together they make the panel type a single enum passed to LCD_Init(LCD_TYPE_1X16_B) — the rest of the firmware never knows.

Section 8 closes Part 2 with implementation highlights from the remaining files: the WAV chunk parser, the keypad debouncer, and a trick for driving register-less I2C devices through a register-oriented API.

8. Implementation Highlights

Architecture (Section 6) and behavior (Section 7) leave a handful of implementation techniques that deserve their own spotlight — not because they are large, but because each one encodes a lesson that transfers directly to other projects. Three are selected here: a WAV parser that survives real-world files, a keypad scanner built around one debouncing insight, and a small I2C trick that turns an API limitation into a non-issue.

8.1 Walking the RIFF Chunks: a WAV Parser That Survives Real Files

A WAV file is a RIFF container: a 12-byte header followed by chunks, each tagged with a 4-character ID and a 32-bit length. The two chunks that matter are fmt  (the sample format) and data (the PCM payload). The temptation is to hard-code their classic offsets — format at byte 20, data at byte 44 — and countless hobby parsers do exactly that.

This parser walks the chunks instead:

for (;;)
{
    uint32_t csz;
    if ((f_read(fp, ch, 8u, &br) != FR_OK) || (br != 8u)) { return false; }
    csz = le32(ch + 4);

    if (memcmp(ch, "fmt ", 4) == 0)
    {
        /* read up to 16 bytes of format, skip any extension + pad */
        ...
        haveFmt = true;
    }
    else if (memcmp(ch, "data", 4) == 0)
    {
        *dataBytes = csz;
        return haveFmt;              /* file position is now at the PCM */
    }
    else
    {
        DWORD skip = csz + (csz & 1u);   /* chunks are word-aligned */
        f_lseek(fp, f_tell(fp) + skip);
    }
}

Three details carry the robustness:

After parsing, the reader validates before playing: anything that is not 16-bit mono PCM is rejected outright, because the I2S configuration is fixed in hardware — mismatched data would DMA through the pipeline, emerge as full-volume garbage. A file that refuses to play is a far better failure than a file that plays as noise.

8.2 The Keypad Scanner: Debounce the Map, Not the Key

The scanner wakes every 20 ms, drives the four rows one-hot (open-drain high, 20 µs settle time per row — Section 4.2), and assembles all 12 switch states into a single 12-bit key map. The debouncing insight is to treat that map as the unit of stability:

raw = ScanMatrix();                  /* all 12 keys, one bit each      */

if (raw == lastRaw)                  /* unchanged for a full period?   */
{
    stable = raw;                    /* accept the whole map at once   */
}
lastRaw = raw;

pressed  = stable & ~prevStable;     /* rising edges: new key-downs    */
prevStable = stable;

One comparison debounces every key simultaneously — no per-key timers, no counters, no state array. A map that repeats across two 20 ms scans cannot be mid-bounce (contact bounce is over in a few milliseconds), so equality is the debounce. The XOR-style edge extraction then converts the stable level picture into events.

That level/event distinction is the second lesson, because this system has two consumers that need different shapes of the same information:

One producer, two projections: a queue of edges for the consumer that must never miss or double-count, a live level for the consumer that must measure duration. Choosing the wrong shape — polling for events, or queuing levels — is one of the most common architectural mistakes in embedded UI code, and the fix is always this: publish both, cheaply, from the one place that knows the truth.

8.3 Driving a Register-Less I2C Device Through a Register-Oriented API

The project's I2C helpers follow the near-universal register convention:

bool I2C_WriteBytes(uint8_t addr, uint8_t reg, int len, uint8_t *data);
/* on the wire: START · addr+W · reg · data[0..len-1] · STOP */

Perfect for EEPROMs, sensors, RTCs — anything with a register map. But the PCF8574 backpack behind the LCD is portless: it has no registers at all. Any single byte written to it is latched straight onto its eight output pins. The API seems one byte too "smart" for the part… until you look at the wire format above and notice that the register byte is just the first byte after the address. So:

static void pcfWrite(uint8_t data)
{
    uint8_t port = (uint8_t)(data | (sBacklight ? PCF_BL : 0u));
    (void)I2C_WriteBytes(LCD_I2C_ADDR, port, 0, (uint8_t *)0);
    /* len = 0: exactly ONE byte follows the address - the port value
     * riding in the "register" slot. START · addr+W · port · STOP.   */
}

The port byte travels in the register slot with a zero-length payload, and the PCF8574 receives exactly the single byte it expects. No new API, no special case in the I2C layer, no second driver. Note the same line also ORs in the remembered backlight bit — on this backpack, the backlight is just another port pin, so every byte written must carry its current state, or the backlight flickers with each LCD access.

8.4 Part 2 Summary

Part 2 covered the firmware from skeleton to skin: eight tasks and their communication fabric (Section 6), the state machine, cadence arithmetic, the defuse race, and the Type-B display craft (Section 7), and three implementation techniques worth stealing (this section). On paper, the design is now complete and correct.

Real hardware had other opinions. Part 3 is the story of every way this "complete and correct" design failed on the bench — an LCD that ate characters because of a tick-rate constant, an SPI FIFO setting that starved the entire scheduler, a vector table that froze the kernel before its first context switch — each written up as a case study: symptom, diagnostic path, root cause, fix. If Parts 1 and 2 are how the system works, Part 3 is how a designer works.

9. Testing & Troubleshooting

Parts 1 and 2 described a design that, on paper, is complete and correct. This part is about the gap between paper and bench. Every case below actually happened during this project's development; each is written up in the same four movements — symptom, diagnostic path, root cause, fix — because the diagnostic path is the part textbooks skip and the part you will reuse forever.

9.0 Test Strategy: the Bring-Up Ladder

The system was never tested "all at once". Subsystems came up in an order chosen so that each working stage becomes the debug instrument for the next:

Two standing instruments ran through all of it: the FreeRTOS stack high-water marks (checked after every feature landed) and the malloc-failed / stack-overflow hooks, enabled from day one so that resource exhaustion fails loudly instead of corrupting silently. Both pay off in the cases below.

9.1 Case: the Scheduler That Never Started

Symptom. First RTOS build: initialization runs, vTaskStartScheduler() is called… and nothing. No task runs. No fault, no reset, no hard-fault LED — the board simply sits there.

Diagnostic path. When nothing moves, ask the debugger where the PC is. Halting the core showed execution parked in IntDefaultHandler — an infinite loop. The IPSR register said which exception got us there: 11, SVC. That number is the entire diagnosis: the scheduler's very first act is an SVC instruction to launch the first task.

Root cause. On PSoC 5LP, cy_boot relocates the vector table to RAM and fills it with default handlers. FreeRTOS's three exception handlers — SVC, PendSV, SysTick — are never installed unless the firmware does it. The kernel issued its first SVC into a do-nothing loop.

Fix. Patch CyRamVectors[11/14/15] before starting the scheduler (code in Section 6.4). Transferable rule: on any port, know how the first context switch physically happens — it is always the first thing to break, and it always breaks silently.

9.2 Case: the Fourth Task That Never Came

Symptom. Three tasks run happily. Adding the fourth causes the system to hang at boot — before the scheduler ever gets going.

Diagnostic path. Because the hooks were enabled from day one, this one solved itself: a breakpoint in vApplicationMallocFailedHook() was already waiting. The call stack pointed straight at the fourth xTaskCreate().

Root cause. Every task's TCB and stack are carved from the FreeRTOS heap (heap_4); the initial configTOTAL_HEAP_SIZE was sized by optimism rather than arithmetic.

Fix. Heap raised to 20 KB — roughly the sum of all stacks plus TCBs plus queues, with margin — then verified live with xPortGetFreeHeapSize() and per-task high-water marks. Transferable rule: the hooks cost two empty functions and catch an entire class of "works until we add one more thing" failures at the exact line that caused them.

9.3 Case: the LCD That Ate a Letter

Symptom. LCD_ClearDisplay() followed by LCD_PrintString("HELLO") displays "ELLO". Reliably. Only the first character after a clear ever disappears.

Diagnostic path. First suspicion: the string or the I2C. But a logic-analyzer capture showed the 'H' transmitted on the bus, correctly framed, ACKed. The LCD received the H — and discarded it. A controller that ACKs but ignores is a controller that is busy. What is it busy with? The Clear command — the one HD44780 instruction that takes not 37 µs but over 1.5 milliseconds. So the driver's post-clear delay was next: vTaskDelay(pdMS_TO_TICKS(2)). Printing the macro's value ended the hunt: zero.

Root cause. The tick rate was 100 Hz at the time. pdMS_TO_TICKS(2) = 2 × 100 / 1000 = 0 ticks by integer division. The "2 ms delay" was no delay at all, and the H arrived inside the clear's busy window.

Fix. Two-layered: the driver's fixed hardware waits use CyDelay() (tick-rate independent — a busy-wait is correct for a mandatory 2 ms hardware window), and the system tick moved to 1000 Hz so millisecond arithmetic is exact everywhere else.

9.4 Case: One Checkbox Starved the Whole System

The flagship case — the failure that reshaped the task priorities in Table 6-1.

Symptom. The SD card's first integration froze everything. Not just audio: the LCD stopped mid-string, the breathing LED froze mid-fade — and the power switch itself went dead. The ultimate reset lever of the user experience is ignored.

Diagnostic path. The dead power switch was the loudest clue. PowerTask polls a GPIO every 20 ms; for it to stop, it must never be scheduled — meaning something at a higher priority never blocks. That reframes the question from "what broke?" to "who is spinning?" Halting the core answered it: the PC sat inside the SD driver's byte-exchange routine, polling SPIM_STS_RX_FIFO_NOT_EMPTY, forever. Yet the identical routine had worked in a bare-metal spike weeks earlier. The diff between the two projects was a single component parameter, changed in the meantime "for performance": SPIM RX/TX Buffer Size, 4 → 64.

Root cause. On the PSoC SPIM, a buffer size above the 4-byte hardware FIFO silently instantiates an internal interrupt that whisks every received byte out of the FIFO into a software circular buffer the moment it lands. The polled status flag the driver was watching can then never be observed, asserted — the ISR always wins the race. The driver spun at a worker priority; every task below it, PowerTask included (it lived near the bottom then), starved. One GUI checkbox changed the component's API contract, and the datasheet says so — in a paragraph nobody reads until this happens.

Fix — defense in three depths. (1) Buffer size restored to 4, matching the polled-FIFO driver model. (2) The exchange loop got a guard counter — a bounded spin that gives up and returns 0xFF after ~100 000 iterations, converting any future variant of this bug from "system dead" into "SD read fails". (3) PowerTask moved above the workers, so the user's reset lever survives any worker misbehaving. All three shipped; any one would have contained the failure.

9.5 Case: "Stop" Is Not "Off"

Symptom. After an outcome silences the buzzer, the line does not always go quiet the way it should: probing the buzzer pin showed it sometimes parked at logic high after PWM_Stop() — holding DC through the transducer coil, and (in an earlier two-channel revision that mixed sources through an OR gate) jamming the gate so the other channel's beeps could no longer pass at all.

Diagnostic path. The state depended on when the stop was called: silence during a beep's OFF phase left the line low; during the ON phase, it was high. Phase-dependent behavior after a stop points at one thing — the stop halts the engine but not the output.

Root cause. PWM_Stop() gates the block's counter; it does not define the output level. The pin simply freezes at whatever the waveform was doing in that instant.

Fix. The driver's off-path writes WriteCompare(0) first — forcing a defined low output — and then stops the counter. Transferable rule: for any hardware block, "stop" and "output in a safe state" are separate obligations; sequence them explicitly (motors and power stages make this same mistake expensive instead of annoying).

9.6 Honorable Mentions

9.7 What the Bench Taught: a Summary

Table 9-1: Case-to-rule summary

Section 10 shows the finished prop in action, and Sections 11–12 close the series with future work and the complete source downloads.

10. Results & Demonstration

The previous nine sections argued the design; this one shows it running. (Editor's note: photo, video, and measured-value placeholders are marked [TODO: …] throughout.)

10.1 The Finished Prop

[TODO: Figure 10-1 — photo of the assembled prop, powered off. Suggested framing: top-down view showing the keypad, 1×16 LCD, RGB LED, speaker, and the CY8CKIT-059 visible on the breadboard/perfboard.]

[TODO: Figure 10-2 — close-up of the wiring around the PSoC: I2C pair, keypad harness, SPI cluster to the microSD breakout, I2S trio to the MAX98357A. A caption keyed to Table 4-1 turns this photo into a wiring reference.]

The complete build measures [TODO: dimensions] and runs from [TODO: power source — USB / battery pack]. Total component cost, at hobby-quantity prices, lands around [TODO: cost] — the most expensive single item is the CY8CKIT-059 itself.

10.2 Operational Walkthrough

One full session, as a spectator experiences it:

[TODO: embed demo video — suggested 60–90 s cut: power-on → arm → escalation → failed defuse (release mid-hold) → successful defuse; then a second take ending in the explosion. Host on YouTube and embed.]

10.3 Verification Matrix

Every behavior specified in Section 1.3 was exercised on hardware. The matrix below doubles as a regression checklist for anyone modifying the firmware:

Table 10-1: Acceptance tests

10.4 Resource Utilization

Measured on the final build (PSoC Creator 4.4, GCC, [TODO: optimization level]):

Table 10-2: Resource summary

How to obtain each number, for reproducibility: flash/SRAM from the build output's memory summary; heap and stack figures by temporarily printing xPortGetFreeHeapSize() and per-task uxTaskGetStackHighWaterMark() to the LCD or a debug UART after ten minutes of mixed use; UDB utilization from the placement report; CPU load from a free-running counter incremented in vApplicationIdleHook() and sampled once per second.

10.5 Observations from Live Use

[TODO: two or three paragraphs after field-testing with real users — suggested prompts: How do first-time users react at the 5-second ramp? Has anyone discovered the backdoor? How does the hold-to-defuse gesture survive sweaty-fingered panic? Any missed keys, audio glitches, or SD hiccups during an hour-long continuous demo? These observations are what future revisions (Section 11) should be built on.]

11. Conclusion & Future Work

11.1 What Was Built

Across three parts, a game prop became a complete embedded systems curriculum: eight FreeRTOS tasks coordinating through queues, mutexes, and an event group; three serial buses running concurrently under per-bus ownership; a zero-copy DMA audio pipeline with clean abort semantics; a state machine honest enough to model a race between two timers; and seven documented encounters with the gap between datasheet and bench. None of the individual techniques is exotic — that is the point. Professional embedded work is rarely about exotic techniques; it is about composing ordinary ones so that each failure, when it comes, is small, loud, and findable.

If one idea deserves to outlive the prop, it is the decomposition rule from Section 6: a task owns a resource, never a feature. Every pleasant property of this firmware — the testable bring-up ladder, the contained SPI disaster, the defuse overlay that costs no state restoration — traces back to that single discipline.

11.2 Future Work

The firmware ships with deliberate growth points. The sound-bank header already reserves three WAV slots that the current code never references:

Beyond the reserved slots: a battery supply and enclosure to make the prop portable; a wire-cut defuse input (a header of jumper wires, one correct) for full genre authenticity; per-session random codes displayed briefly at power-on; and software volume via sample scaling in the read task.

11.3 Exercises for the Reader

Graded roughly by how much of the architecture each one touches.

11.4 Closing

A blinking, beeping movie prop is an unserious object built with entirely serious engineering — and that combination is deliberate. The stakes are low enough to take risks and break things; the requirements are real enough that the breakage teaches. Build one, break it in a new way we did not document, and write that up. That is the whole game.

12. Downloads & References

12.1 Source Package

[TODO: attach the project archive and link it here.] The package contains the complete PSoC Creator 4.4 workspace. The firmware sources, keyed to the file map in Table 6-4:

Not included — add these yourself: the FreeRTOS kernel (ARM_CM3 GCC port) and the FatFs R0.16 core (ff.c, ff.h, diskio.h) from their official sources below. The package's ffconf.h documents every setting this build depends on; the load-bearing ones:

#define FF_FS_READONLY   1     /* playback only - halves the code       */
#define FF_USE_LFN       0     /* 8.3 names only - no LFN RAM buffers   */
#define FF_CODE_PAGE     437   /* single code page                      */
#define FF_MIN_SS        512   /* SD sector size                        */
#define FF_MAX_SS        512
#define FF_FS_NORTC      1     /* no RTC - fixed timestamps             */

12.2 The Sound Bank

All files: WAV, PCM, 16 kHz, 16-bit, mono, 8.3 upper-case names, FAT32 card ≤ 32 GB (Section 3.3). [TODO: link a downloadable sound-bank ZIP, or state that readers supply their own.]

Table 12-1: Sound-bank manifest

12.3 References

12.4 Series Index

Questions, corrections, or a write-up of your own build: [TODO: contact/comment channel]. If you found a new way to break it — especially then.