Planning on Paper

Learning Goals 5 min

By the end of this lesson you will be able to:

1. Produce the five planning artefacts for any small Arduino project — problem statement, component list, wiring sketch, state diagram, and pseudocode — before opening the IDE.
2. Recognise the three signals that "you started coding too soon" — buying the wrong parts, finding missing states halfway through, and writing code that doesn't fit on the breadboard you wired.
3. Reach for paper by reflex when you're stuck on a build, and use the gap between your plan and your code as the first place to look for the bug.

Warm-Up 10 min

You've done 46 lessons. You can now wire and code something useful in an hour. Today we slow down on purpose — because the difference between a beginner who finishes a project and one who gets stuck halfway isn't usually skill. It's how much they planned before the first void setup().

Quick-fire puzzle

Imagine your friend says: "I want to build an Arduino weather station for my room." That's the entire spec they've given you.

1. What's the very first question you'd ask them?
2. How many different physical components might they need — list everything that could possibly be involved.
3. If they started typing code right now without answering anything, where do you predict they'd get stuck first?

New Concept — the five planning artefacts 20 min

The big idea — make all your mistakes on paper

A wrong line of code costs a few seconds to retype. A wrong part costs days waiting for delivery. A wrong wiring plan costs a frustrated hour of debugging. A wrong plan, caught in five minutes on paper, costs nothing. So spend the five minutes.

The professional workflow has five distinct artefacts. None requires the IDE or the breadboard. Each takes 2–10 minutes. They're done in order; each builds on the previous one.

Artefact 1 — the problem statement (one sentence)

Write one sentence describing what the device does. Concrete enough that a friend can repeat it back. Vague enough to leave wiggle room.

• ❌ "A traffic light." → too vague.
• ❌ "Three LEDs that go red for 5 seconds, then amber, then green, and a button that does something." → too detailed (already a design, not a spec).
• ✅ "A pedestrian crossing controller with car and pedestrian lights and a request button, where pressing the button shortens the wait for crossing." → goal + actors + behaviour, no implementation.

If you can't write this sentence, you don't know what you're building. Don't proceed.

Artefact 2 — the component list (a table)

List every physical item the device needs. Make a table with what, how many, and what pin it'll talk to (your best current guess — you can adjust later).

Tally the pins — make sure you have enough on the Uno. Tally the parts — check your kit. Now you know what to grab before you sit down at the breadboard. This is the artefact that catches the "wait, I don't have one of those" mistake before it costs you a delivery wait.

Artefact 3 — the wiring sketch (a block diagram)

Not a full schematic — just a quick picture showing where parts go and what's connected to what. The point is to think about physical layout: which columns, where the GND bus is, how long the wires need to be. Drawn freehand, takes 5 minutes:

• Draw the breadboard rectangle. Mark the + and − rails.
• Place each component as a box where you'll plug it in. Label.
• Draw signal wires to the Arduino's pin names (no need to draw the Arduino itself — just label the pin numbers on the wires).
• Mark the GND return wire.

You'll spot two problems with this artefact alone: parts colliding (you've put two big components in the same columns) and signal wires crossing (which is fine but messy — better to plan the order now).

Artefact 4 — the state diagram (if it's an FSM)

Many projects aren't pure FSMs — a sensor logger reads + prints in a loop, no states needed. But anything that responds to events is an FSM. If yours is one, draw the L01-46-style diagram now:

• Each state as a labelled circle.
• Each transition as a labelled arrow.
• External inputs (buttons, sensor thresholds) as the labels on arrows.
• Each state's expected duration written under its name.

Drawing this often reveals a missing state or a missing transition. That's the point. Fixing those gaps on paper takes seconds; finding them in 200 lines of code takes hours.

Artefact 5 — the pseudocode / data sketch

Finally, write what the data and the loop will look like — in English mixed with code-ish shorthand. Just enough to know "the sketch will have a 5-element array of these, a state variable that's one of these, and a loop that goes through these steps". It's not a full implementation; it's a rough sketch.

// Data:
//   int state            — one of: CAR_GREEN, CAR_AMBER, PED_WALK, PED_FLASH
//   unsigned long stateEntryTime — millis() when state was last entered
//   bool requestPending  — true if button has been pressed since last ped phase
//   int lastButton       — for state-change detection
//
// loop():
//   - latch button press into requestPending
//   - compute elapsed = millis() - stateEntryTime
//   - switch on state — transition if conditions met
//   - in PED_FLASH, blink ped LED at 2 Hz using elapsed

Eight lines of pseudocode capture the whole worked example from L01-46. Notice that this looks suspiciously like the comments at the top of the real sketch — that's not a coincidence. Pseudocode is what a comment was, before you wrote the code under it. Many engineers literally paste pseudocode into the IDE as comments, then replace each line with real code as they go.

Three signals you should've planned more

• You're at the kit drawer and don't remember if you have part X. The component list (artefact 2) would have caught this before you stood up.
• You've wired half the project and realised the wires won't reach. The wiring sketch (artefact 3) would have caught this in pencil.
• You're 30 minutes into the code and you've just realised there's a state you missed. The state diagram (artefact 4) would have caught this in 60 seconds.

When any of these happens, the lesson is the same: go back to paper, fix the plan, then continue. Don't paper over the planning gap with extra code — the gap won't shrink.

Why it matters

Professional engineering of any size — phone apps, kitchen appliances, satellites, video games — runs on planning artefacts. The names differ ("PRD", "ERD", "wireframe", "schematic", "state chart"), but the workflow is the same: think, sketch, debate, then build. The five artefacts you'll practise today are the smallest set you'd want for an Arduino project; bigger systems just have more of each. This lesson saves you weeks of frustration across the rest of the syllabus.

Worked Example — plan a coin-toss device 25 min

You're not going to build anything today. Instead, we'll walk through planning a brand-new project from scratch — producing all five artefacts on (imaginary) paper — then briefly look at the code that would follow naturally from the plan.

The project we'll plan

Your friend asks: "Can you build me a little coin-toss device? Press a button, it shows heads or tails — but with a bit of suspense, not just an instant answer."

Artefact 1 — problem statement

Take 30 seconds. Write one sentence that's specific enough to act on:

A handheld device with one button and two LEDs (one labelled "heads", one labelled "tails") that, when the button is pressed, briefly cycles between the two LEDs for ~1 second of "suspense" before settling on a random choice.

Notice what made the cut: the inputs (one button), the outputs (two LEDs), the behaviour (random pick with a built-up suspense), and what the user perceives. Notice what didn't: pin numbers, durations, code structure. Those come later.

Artefact 2 — component list

Lay out everything you'll plug in:

Check your kit. Yes, you have all of this — these are all parts you've used since Cluster B. The pin count is fine (using only 3 of 14 digital pins). Move on.

Artefact 3 — wiring sketch

Quick block diagram:

• Breadboard left to right: button at columns 1–4 (straddling the trough, INPUT_PULLUP), LED-red + 220 Ω at cols 8–11, LED-green + 220 Ω at cols 15–18.
• − rail jumpered to Arduino GND.
• Yellow signal wires: D7 to button, D9 to red LED, D10 to green LED.
• Button GND lead jumpered to − rail; both LED cathodes to − rail.

If you sketched this on paper, you'd see immediately that it fits comfortably on a half breadboard with room to spare. No wire-crossing issues. Done. The wiring is locked in before you've touched a single jumper.

Artefact 4 — state diagram

Is this an FSM? Yes — it responds to events (button press) and changes its behaviour over time (suspense phase, then settle). Three states:

• IDLE — both LEDs off; waiting for the button.
• SUSPENSE — alternating LEDs every 100 ms for 1 second.
• RESULT — one LED on (the random pick), other off; stays for 3 seconds, then returns to IDLE.

Transitions:

• IDLE → SUSPENSE: button press
• SUSPENSE → RESULT: timer (1 s) — pick result at this moment
• RESULT → IDLE: timer (3 s)

Three states, three transitions, two inputs (button + millis timer). Draw it as three circles with arrows. Done in two minutes.

Artefact 5 — pseudocode / data sketch

// Data:
//   int state            — IDLE | SUSPENSE | RESULT
//   unsigned long stateEntryTime — for state durations
//   int lastButton       — state-change detection
//   int result           — 0=tails, 1=heads (set when SUSPENSE → RESULT)
//   int suspenseSlot     — for alternating during SUSPENSE
//
// setup(): pinModes, Serial.begin, randomSeed(analogRead(A0)), state = IDLE
//
// loop():
//   if state == IDLE: both LEDs off; on button press → enter SUSPENSE
//   if state == SUSPENSE: alternate LEDs every 100 ms; after 1 s → pick result, enter RESULT
//   if state == RESULT: result LED on, other off; after 3 s → enter IDLE

Eleven comment lines. That's the entire design. Notice the resemblance to L01-46's structure — that's because it is L01-46's structure, applied to a different project. Patterns repeat.

The five artefacts side by side

Total planning time: about 10 minutes. Total output:

Now imagine opening the IDE and turning the pseudocode comments into real code one at a time. Each line of pseudocode becomes 5–10 lines of real code. The sketch writes itself — there's no "what next?" moment, no "should I…?" pause. You spent 10 minutes deciding; you spend the next 30 minutes typing what you decided.

(You're welcome to try actually building the coin-toss device after this lesson — but the planning artefacts themselves are the whole point of today. Building is a treat for after.)

Basic 5 min

Today's tasks check plans against reality. A mistake in the plan becomes a mistake on the breadboard, so catch it on paper.

Challenge 1 5 min

// Pins: LDR divider on A0, red LED on D9, buzzer on D8
//
// loop():
//   - read the LDR on A0 (0..1023)
//   - LED brightness = reading / 4  (brighter room, brighter LED)
//   - if reading > 600: buzzer on at 1000 Hz
//   - else: buzzer off

const int LDR_PIN = A0;
const int LED_PIN = 7;
const int BUZZER_PIN = 8;
const int THRESHOLD = 600;

void setup() {
  pinMode(LED_PIN, OUTPUT);
  pinMode(BUZZER_PIN, OUTPUT);
}

void loop() {
  int light = digitalRead(LDR_PIN);
  analogWrite(LED_PIN, light / 4);
  if (light < THRESHOLD) {
    tone(BUZZER_PIN, 1000);
  }
}

Challenge 2 5 min

// Data:
//   int state             — STOPPED | RUNNING
//   unsigned long startMs — millis() when timing started
//   int lastButton        — for state-change detection
//
// loop():
//   - on a button press:
//       if STOPPED: startMs = millis(), state = RUNNING
//       if RUNNING: print the time as mm:ss, state = STOPPED
//   - if RUNNING: LED on for the first 500 ms of each second, off for the rest
//   - if STOPPED: LED off

Challenge 3 — build the coin-toss device 10 min

"The plan is done — now follow it"

Build the coin-toss device from the worked example's five artefacts. Wire it exactly as the wiring sketch says. Then turn each line of the pseudocode into code, in order.

Your task:

1. Wire the button on D7, the red "tails" LED on D9 and the green "heads" LED on D10, each LED with a 220 Ω resistor.
2. Make one constant for each state, and one for each time in the plan: 100 ms, 1 second and 3 seconds.
3. Write loop() with one branch per state, following the state diagram.
4. Pick the result once, at the moment SUSPENSE ends. Print HEADS or TAILS to the Serial Monitor.

It works if:

• A press makes the two LEDs swap every 100 ms for about one second.
• Then one LED stays on for 3 seconds, and both go off.
• Twenty presses give a mix of heads and tails.
• Holding the button down does not start a second toss.

Recap 5 min

Make mistakes on paper, not in code. The five planning artefacts — problem statement, component list, wiring sketch, state diagram, pseudocode — take 10 minutes total and save hours of debugging. Drawing the wiring catches missing parts; drawing the state diagram catches missing logic; writing pseudocode catches missing data structures. The plan becomes the comments at the top of the real sketch. When you're stuck mid-build, the first place to look is the gap between your plan and your current code — that's where the bug almost always is. This lesson teaches no new wiring and no new code; it teaches the workflow that turns "I had an idea" into "I have a working sketch" with minimum friction.

Problem statement

A one-sentence description of what a project does — concrete enough to act on, vague enough to leave implementation choices open. The first artefact, written before any other.

Component list

A table of every physical part the project needs, with quantity, pin assignment, and purpose. Catches "I don't have one of those" before you start wiring.

Wiring sketch

A freehand block-diagram of the breadboard layout — boxes for components, lines for wires, labels for pins. Not a full schematic. Catches layout collisions before you spend an hour wiring.

State diagram

A drawing of the project's FSM — circles for states, arrows for transitions, labels for triggers. Catches missing states before they cause hours of code rewriting. Skip for projects that aren't FSMs.

Pseudocode

An English-mixed-with-code-shorthand sketch of the data structures and the loop() body. The plan often becomes the comments at the top of the real sketch. The fifth and last artefact.

Proportional planning

The rule that planning effort should match project size. One-LED blink needs only a problem statement; a multi-LED FSM with sensors needs all five artefacts. Over-planning small projects is just as wasteful as under-planning big ones.

The plan / code gap

The difference between what your plan says and what your code is doing. When stuck, look here first — most bugs hide in this gap rather than in the code itself.

Extra Mission 5 min

Part 1 — Plan your own project

Think of a small project you want to build, or invent one now. It must use only parts from your kit: LEDs, buttons, pots, the LDR, the buzzer, the RGB LED or the tilt switch. It must fit on one breadboard.

Ideas: a plant-pot sunrise alarm, a "don't open this drawer" trap, a practice metronome, or an RGB mood ring.

Your design must include:

• All five planning artefacts: problem statement, component list, wiring sketch, state diagram and pseudocode.
• A check that every line of pseudocode uses a skill you already have.
• A guess at how long the build will take.

Part 2 — Make it

Build the project from your plan. Wire it from your wiring sketch, and code it from your pseudocode. Note every change you had to make to the plan.

Bring back next class:

• The saved .ino file.
• Photos of your five artefacts.
• A short video of the finished device.
• Your list of plan changes.

Heads up for next class: L01-48 "Level 1 Recap" is the very last lesson of Level 1. We'll walk back through every cluster, name the highest-leverage idea from each, and you'll write your own one-page "what I can do now" summary as a permanent record of the journey. Level 2 starts the lesson after with real sensors, motors, and external libraries — but Level 1 deserves a proper closing ceremony.