Build for Nzemaland

Every band so far handed you a brief. Build a signal tower. Build a lock. Build a game. You could always check your work by comparing it with the picture.

This time nobody gives you the brief. You go and find one, from a person with a problem, and the only way to know whether you succeeded is to give the finished thing back to them and watch.

That is a genuinely harder job, and it fails in ways that have nothing to do with code.

Two things you need first

• A way to organise a device that does several things. Every project worth building has modes: waiting, working, warning, quiet. Written the obvious way, four modes become a tangle nobody can follow, including you next week. Parts 1 to 5 teach the way out.
• A way to be honest about whether it works. Everything works on the desk of the person who built it. Parts 6 to 10 are about finding out whether it works anywhere else.

By the end you will be able to

• Break a device into states and write it so an impossible combination cannot happen
• Turn something a person said into criteria you can actually check
• Say what your device does when the power comes back
• Draw wiring somebody else can follow without asking you a question
• Watch a real person use your build without helping them
• Judge your own work against criteria you wrote before you started

What you need

• Everything from the previous bands. No new parts.
• Band 6's battery pack, if your build moves anything. Which means Band 6's rules come with it, and this is the band where nobody is checking your work. Battery red to the + rail, battery black to the − rail, or the rails are dead metal and nothing you build will move; the + rail is then about six volts and no Arduino pin may ever touch it; a knob's power leg goes straight to the Arduino's 5V pin, never to the + rail; and one more wire, separate from the battery's black one, joins the − rail to an Arduino GND pin, always, or the Arduino and the battery share no ground and your signals have no way home. Write those four lines onto your wiring drawing before you build anything, and check the finished board against them with the battery switched off.
• The same full-size breadboard Bands 5 and 7 needed. This band's worked example runs out to column 42.
• Card, tape, a box or a bottle, and whatever will make a housing that survives being carried
• Paper, for the criteria and the wiring drawing. This band uses more paper than solder.
• One real person with a real problem, and their patience for twenty minutes twice

No board for this part. Pick a thing near you that has more than one behaviour: an electric kettle, a phone, a fan with a timer, a washing machine, a torch with modes.

That last question is the one nobody thinks about and everybody meets. Your device will lose power. When it comes back, it will be doing something, and if you did not choose what, then it chose for you.

Keep this paper. Part 3 turns it into code almost line for line.

What you just wrote down has a name. Each of those behaviours is a state, and a device that is always in exactly one of them is a state machine.

That sounds grand and it is not. It is one variable and a few branches. But choosing to write it that way changes what your device can do wrong, and that is why it is worth a whole part.

Read that picture like a map. There is no arrow from WAITING straight to ALARM, so that jump cannot happen. Not “should not”. Cannot. There is no line to travel along.

Why not just use true-or-false names?

The obvious alternative is a name for each thing that might be true:

bool armed = false;
bool alarming = false;
bool snoozed = false;

That looks simpler and it is a trap. Three true-or-false names means eight combinations, and only four of them make any sense. The other four are nonsense that nothing prevents and nothing warns you about.

Here is the heart of b8_01_states_given.ino. Read it before running it.

const int WAITING = 0;
const int ARMED   = 1;
const int ALARM   = 2;
const int SNOOZED = 3;

int state = WAITING;

void enterState(int newState) {
  state = newState;
  stateSince = millis();

  if (state == WAITING) digitalWrite(ledPin, LOW);
  if (state == ARMED)   digitalWrite(ledPin, HIGH);
  if (state == SNOOZED) digitalWrite(ledPin, LOW);

  Serial.print("now in state ");
  Serial.println(state);
}

b8_02_buggy_flags.ino is the same device, wired the same way, written with three flags instead of one state.

It is not badly typed. Every line in it is reasonable on its own. Upload it and press the button slowly, watching both the light and the serial monitor.

if (armed && !alarming && !snoozed) { ... }
else if (armed && alarming) { ... }
else if (!armed && !alarming) { ... }

Every state machine you write from here on, and probably for the rest of your life, has the same five pieces. Learn the shape, not the sketch.

The rule about enterState

Look at what it does and notice something easy to miss: it sets the light for every state, including the ones where the light is off.

That is deliberate, and it is the same habit you learned in Band 1 when you wrote all three lights in every traffic state rather than only the ones that changed. Set every output every time. Leaving one out is how a buzzer gets stuck on, and it will be stuck on in exactly one rarely-used path that you will find at the worst moment.

In b8_03 you can see this taken seriously: enterState starts by turning the buzzer and both lights off, and then switches on only what the new state needs.

Fill this in by hand

For b8_01, complete the table. Two of the boxes have no answer, and working out which two is the exercise.

Now the other half of the band. Everything above was about how to write it. The rest is about knowing what to write, and whether it worked.

A brief is not an idea you had. It is a problem somebody else has, described in their words, before you have thought of any solution.

Go and ask somebody

Whether you take a brief from that list or bring your own, the next step is the same and it is not optional.

Now turn what they said into a list of things you can check. This is the single most valuable half hour in the band, and it is the one people skip.

The reason to write criteria first is not organisation. It is honesty. Criteria written afterwards are always met, because you write down whatever you happened to achieve. Written first, they can tell you something you did not want to hear.

What makes a criterion checkable

Put the list somewhere you will see it while you build. Tape it to the wall. Every time you are tempted to add a clever feature nobody asked for, the list is there to ask why.

Read b8_03_tank_alarm_worked.ino from its first comment to its last line before you build anything. It is a whole project done properly and it is shorter than you would expect.

The brief it came from

“Our poly tank overflows at night because nobody sees it filling. I want a warning while there is still time to close the valve, loud enough to hear from the next room, and I want to be able to shut it up without switching the whole thing off.”

Notice what is in there. A problem, a time constraint, a loudness constraint, and one specific complaint about a device they have used before: it could only be silenced by switching it off entirely. That last clause is where the SNOOZED state came from.

How it measures water with no water sensor

The ultrasonic sensor from Band 7, pointing straight down at the water from the top of the tank. A full tank means a short distance.

Nothing touches the water. Nothing corrodes. This is how real tank sensors work, and you already had the part.

This is what the map means by “no new components required, and the constraint is the point”. Almost every problem in this list can be solved with something you already have, pointed at it differently.

The two thresholds

int alarmLevel = 15;          // cm from the sensor. Measure yours.
int clearLevel = 20;          // must fall below this to count as safe

Two numbers, not one, and the reason is the same as the deadband in Band 6 and the light threshold in Band 4. With a single threshold of 15, a reading wobbling between 14 and 16 starts and stops the alarm several times a second.

With 15 to alarm and 20 to clear, the water has to genuinely fall by five centimetres before the alarm stops. The reading can wobble all it likes in between and nothing flaps.

Build it and test it

Your device will lose power. In Aiyinasi it will lose power more than once a week. Every project in this band has to answer for that, and it is the criterion that separates a demonstration from something that can be left alone.

The three questions

1. What state does it come back in? Whatever setup says. If setup says nothing, it is whatever the first value of your state variable happens to be, which is a decision you made by accident.
2. Does that need a person? A device that comes back needing somebody to arm it is disarmed most of the time, because nobody knows the power came back.
3. Does it forget anything that mattered? Counts, settings, the time. All of it is gone. Every number in your sketch goes back to what you typed.

Test it properly, three times

A photograph of your breadboard is not documentation. It shows where the wires are, not what they are for, and a jumble of six identical red wires tells a reader nothing.

What another learner needs is a drawing plus a table, and both fit on one sheet of paper.

The drawing

Draw the breadboard as a rectangle. Mark the two rails and the middle channel. Draw each part roughly where it sits, and label it. Draw each wire as a line, and write on it where it goes.

It does not have to be beautiful. It has to be unambiguous. If two people could read it differently, it is not finished.

The table

Exactly like the pin plans in every band from 3 onwards, because those were written for the same reason.

The last column is the one people leave out and the one a reader most needs. “Any pin, 6 was free” tells them they can move it. “Must be a ~ pin because it fades” tells them they cannot. Without that column, every pin looks equally sacred.

The test for your documentation

And the code

Your sketch is documentation too. Three things make the difference, and you have been doing all three since Band 5:

• A header comment saying what it does, the wiring hole by hole, and anything surprising.
• Names instead of numbers. Every number that could be tuned lives at the top with a name, once.
• Small functions. If loop is more than about ten lines, something in it wants a name.

b8_04_project_skeleton.ino is a blank version of all of this. Save a copy under your own name and start there.

Before you build something of your own, change somebody else's. Work on a copy of b8_03_tank_alarm_worked.ino.

Each of these forces you to touch a different one of the five pieces from Part 5, which is the point of doing them in order.

Bronze

Add a fifth state, TESTING, that you reach by holding the button down for two seconds from ARMED. In it, the red light and the buzzer come on for three seconds and then it goes back to ARMED, whatever the water is doing. Every alarm needs a way to prove it still works without waiting for a real emergency, and every alarm you have ever met has one.

Silver

Make alarmLevel settable from a potentiometer instead of being typed into the sketch, and show the level it is currently set to on the serial monitor. Then say in your log what this makes better and what it makes worse. There is a real cost and it is not obvious.

Gold

Make the snooze survive a power cut, using the EEPROM library, so that a device switched off and on again during a snooze comes back still snoozed with the right amount of time left. This is hard for an interesting reason, and finding the reason is most of the task.

How to spend the time

Notice that an hour and a half of it happens before you touch a single wire, and two and a half hours happen after the code works. Most people spend all their time in the middle stage, which is why most projects work only on the desk of the person who built them.

The test that matters most in the whole course

Take it to where it belongs. Hand it to the person whose problem it is. Say one sentence, no more. Then be quiet and watch.

Do not help. Do not explain. Do not say “you just have to”. Let them be confused, and write down every second of it.

• What did they look at first?
• What did they try that you did not expect?
• At what moment did they understand what it was telling them, and how long did that take?
• What did they ask you? Every question is a thing your device failed to say.

Then ask them one question: would you leave this switched on tonight? The answer to that is worth more than everything else you will collect.

The honest evaluation

One page, written against the criteria you wrote in Part 7, before you knew how it would turn out. For each of your five criteria, write which of these it is:

• Met. With the evidence: what you did to check, and what happened.
• Partly met. With what is missing and what it would take.
• Not met. With why, honestly. A criterion you missed and understood is worth more than one you quietly rewrote.

Five pieces. All of them producible on your own, all reviewable in ten minutes.

Show your work

Post all five pieces. Then look at one other person's capstone and do the hardest useful thing: build their project from their documentation alone and tell them exactly where you got stuck.

Code you have not seen. Answer from reading only. Do not upload it.

const int IDLE  = 0;
const int OPEN  = 1;
const int SHUT  = 2;

int state = IDLE;
int lampPin = 7;
int buzzerPin = 6;
int sensorPin = A0;

unsigned long stateSince = 0;

void enterState(int newState) {
  state = newState;
  stateSince = millis();

  if (state == IDLE) digitalWrite(lampPin, LOW);
  if (state == OPEN) {
    digitalWrite(lampPin, HIGH);
    tone(buzzerPin, 880);
  }
}

void setup() {
  pinMode(lampPin, OUTPUT);
  pinMode(buzzerPin, OUTPUT);
  Serial.begin(9600);
}

void loop() {
  int reading = analogRead(sensorPin);

  if (state == IDLE && reading > 600) enterState(OPEN);
  if (state == OPEN && reading < 600) enterState(SHUT);
  if (state == SHUT && millis() - stateSince > 2000) enterState(IDLE);
}

1. Three states are named. How many of them does enterState set the outputs for?
2. The device goes IDLE, then OPEN, then SHUT. Describe exactly what the lamp and the buzzer are doing once it reaches SHUT, and say why.
3. There is no enterState call in setup. Name one thing that is different because of that, in the first moment after the power comes on.
4. The sensor is sitting right on the boundary and its reading wobbles between 599 and 601. Follow what happens, round by round, and say what a person watching would see and hear.
5. Fix question 4 without adding a new state and without changing loop. Say which two numbers you would use and why they must be different.
6. Somebody says “this is fine, it only has three states, so nothing can go wrong”. Using questions 2 and 4, say in two sentences why having states is not by itself enough.

Part 12 was the real test. This is a warm-up for it, and a list to come back to. Say each of these out loud, to somebody or to yourself, without looking anything up.

• Draw your own project as boxes and arrows, and name every state and every transition
• Say why three true-or-false names are more dangerous than one name with four values
• Say why enterState sets every output, including the ones being switched off
• Turn a sentence somebody said into a criterion that can be checked
• Say what your device does when the power comes back, and why you chose that
• Hand your documentation to a stranger and have them build it
• Say one thing about your own build that is not good enough yet

That is Band 8, and the end of the ladder. Go and build something nobody asked you to.

And that is the ladder

Nine bands. You started by making one light blink and not knowing which way round an LED goes. You can now measure the world, decide what a measurement means, move something in response, tell a person about it, organise a program that does several things at once, and find out honestly whether what you built is any use.

None of that is beginner work any more. The parts in your box have not changed since Band 0, and everything you can now do with them came from you.

What comes next is not another band. It is a bigger problem, a part you have not used before, and the same six steps you have run nine times: think first, guess, run it, look closer, change it, make your own. That pattern is the thing you actually learned. The Arduino was only where you practised it.

Before you call the ladder finished, make sure you have

• All five pieces of evidence from the Evidence section, saved together in one folder
• Your brief in the user’s own words, and your five criteria, written before you built anything
• Your states drawn as boxes and arrows, and the transition table from Part 5
• Your Bronze, Silver or Gold change to the tank alarm from Part 11, with the note on what it cost
• Your ninety-second voice note explaining your own code
• Your build log, with at least one thing that broke and what fixed it
• Five or six correct answers in Part 12, including question 2