Simon Says

Everything you have built so far does one thing at a time, in order, and never has to pay attention to anything while it is busy. That has been fine. It stops being fine here.

A game has to watch for a button while a light is doing something else. As soon as you want two things happening at once, the way you have been writing code falls apart. Not slowly. Completely.

So this band does three things:

• You write your own instructions. Until now you have used instructions somebody else wrote: digitalWrite, analogRead, map. Now you make your own and give them names. This is called writing a function, and it is the single most useful idea in programming.
• You break delay on purpose. You will build something that fails, understand exactly why, and then fix it properly.
• You build a real game. Not a demonstration. A thing people will actually pick up and play, and lose at, and ask for another go.

What you need

• Your board, USB cable and breadboard
• Four LEDs, ideally four different colours
• Four 220 ohm resistors
• Four push buttons
• A passive buzzer. This is the one where you can see a small green circuit board underneath, rather than a solid black cover.
• About twenty jumper wires

By the end you will be able to

• Write your own instruction, give it a name, and hand it values
• Get an answer back out of an instruction you wrote
• Make a sound at any pitch you choose
• Explain, with a real example, why delay makes a program deaf
• Use millis to make something happen on time without stopping everything else
• Build a program long enough that it has to be organised, and organise it

If you have someone with you

Give them two jobs at once.

1. Job one: count out loud from 1 to 60, one number per second, slowly.
2. Job two: if I clap, put your hand up straight away.
3. The rule: you must finish counting to 60 before you are allowed to check whether I clapped.

Start them counting. Clap once when they reach about 12. Then wait and watch.

If you are on your own

You can run the same thing alone. You need a clock you can see, so use the clock on your phone, a wall clock with a second hand, or a watch.

That is this whole band in one activity. Keep the paper.

The person was never deaf. They were busy, and the rule said they could not look up until they had finished. Change the rule so they look up constantly, and the response becomes instant while the counting carries on exactly as before.

Your board is that person. delay is that rule.

Sound is something being pushed back and forth very fast. Fast pushing makes air wobble, the wobble reaches your ear, and you hear a note.

How fast it wobbles is the pitch. Fast wobbling is a high note. Slow wobbling is a low note. We measure it in wobbles per second, and the unit is called hertz, written Hz.

Two kinds of buzzer, and why it matters here

This band needs the passive one, because the game plays four different notes.

The instruction

tone(buzzerPin, 262);   // start a note and keep it going
noTone(buzzerPin);      // stop it

The second number is the pitch in hertz. Bigger number, higher note.

tone starts the note and then carries straight on to the next line. It does not wait. If you want a note to last, follow it with a delay, and then noTone to stop it.

Here are four notes that sound good together. You do not have to use these.

Notice 523 is almost exactly double 262. Doubling the number always gives you the same note, higher. That is not a coincidence, it is what an octave is.

int buzzerPin = 12;

void setup() {
  pinMode(buzzerPin, OUTPUT);
}

void loop() {
  tone(buzzerPin, 262);
  delay(400);

  tone(buzzerPin, 330);
  delay(400);

  tone(buzzerPin, 392);
  delay(400);

  noTone(buzzerPin);
  delay(1200);
}

Build in stages and test each stage. There are thirteen parts in the finished thing. If you wire all of it and it fails, you have thirteen suspects.

The pin plan

Each light’s pin wire goes in row b, not row a, because the resistor leg is already in the row a hole and a hole takes one leg only. The five holes in a column are joined underneath, so b1 reaches the resistor in a1 perfectly well.

Everything shares the one − rail along the bottom edge. Buttons straddle the middle channel, so their pin wire comes from the top side and their ground wire from the bottom side. That is the diagonal rule from Band 3.

How each button sits on the board

You have done this once, in Band 3, and now you are doing it four times. It is worth a minute to get it right, because a button that is turned the wrong way is the single most common reason a build like this half works.

A push button has four legs, not two. They come out of the four corners of its square body, and they need four holes. The body sits over the middle channel of the breadboard, the groove running down the centre, so that two legs land in the top half and two land in the bottom half.

Take button 1 as the example. Its four legs go into e19, e21, f19 and f21. To seat it, line the four legs up over those four holes, then press straight down on the body with your thumb, not on a leg, until the body is almost touching the board. It will feel stiff and it may take real pressure. If it goes in crooked, pull it straight back out by the body, straighten any bent leg with your fingers, and try again.

Then the two wires. The pin wire goes into the top half in one column, and the ground wire into the bottom half in the other column. For button 1 that is j19 to pin 8, and a21 to the minus rail. Different column, different half. That is the diagonal.

pinMode(13, OUTPUT);
digitalWrite(13, HIGH);
digitalWrite(13, LOW);

Look at what that sketch would need without any new ideas. To play light 1 with its note, then light 2, then 3, then 4, you would write this five-line block four times over:

digitalWrite(ledPins[0], HIGH);
tone(buzzerPin, notes[0]);
delay(400);
digitalWrite(ledPins[0], LOW);
noTone(buzzerPin);

Twenty lines, nearly identical, differing by one number. And if you later decide the note should last 300 instead of 400, you have to find and change it in four places, and getting one wrong gives you a bug that is very hard to see.

Here is the alternative. Open b5_02_functions_worked.ino and find this:

void playStep(int which) {
  digitalWrite(ledPins[which], HIGH);
  tone(buzzerPin, notes[which]);
  delay(400);

  digitalWrite(ledPins[which], LOW);
  noTone(buzzerPin);
  delay(120);
}

And then, down in loop:

playStep(0);
playStep(1);
playStep(2);
playStep(3);

Twenty lines became four. And the 400 exists in exactly one place.

How to read a function, piece by piece

void playStep(int which) {

Getting an answer back

Some instructions do hand something back. digitalRead does: you get a HIGH or a LOW. To write one of your own, you replace void with the type of thing you are handing back, and use the word return.

int waitForPress() {
  ...
  return i;
}

Read it as: this instruction hands back a whole number. When it reaches return i, it stops immediately and gives back whatever is in i.

Then you can use it like any other instruction that produces a value:

int pressed = waitForPress();

return also ends the instruction there and then. Any lines below it do not run.

void flashAll() {
  for (int i = 0; i < 4; i = i + 1) {
    digitalWrite(ledPins[i], HIGH);
  }
  delay(300);
  for (int i = 0; i < 4; i = i + 1) {
    digitalWrite(ledPins[i], LOW);
  }
}

Here is a small thing that ought to be easy. A lamp fades slowly up and down, and a second light comes on whenever you hold a button. Two simple jobs you can already do.

Move four wires

You do not need to rebuild anything. Keep everything exactly where it is and move four wires. Unplug the USB first.

Work the table from the top down, in order. The order is not decoration. Only one wire fits in an Arduino pin, and pins 9 and 8 are both occupied right now, so the two wires that are in the way have to come out before the two new ones can go in.

Pin 9 matters. It is the fading lamp, and only a pin with a ~ can fade. Pin 2, where that light was, cannot. Lights 3 and 4 and buttons 3 and 4 are simply not used in this part, so leave them exactly where they are. Button 2 is not used either, but its wire had to come out of pin 9 to make room.

Upload b5_03_blocking_problem.ino. Then press the button.

This is worth sitting with, because it is not a small technical detail. It is the reason your projects have all been simple so far.

Every delay you have ever written has stopped the entire board. Not the light. Not the line it is on. Everything. For that whole time the board cannot read a button, cannot check a sensor, cannot do anything at all.

Up to now that never mattered, because your projects only ever did one thing. From here it matters in everything you build.

Here is the change in thinking, and it is a real change, so go slowly.

Instead of stopping until it is time, keep running and keep asking whether it is time yet.

That is exactly the rule change in the last step of Part 1, the one where you were allowed to write the time down the moment you said your signal number instead of waiting until sixty. The person keeps counting and checks the door after every number.

The instruction

millis()

It hands back how many thousandths of a second the board has been running since it was switched on. That is all it does. It does not wait, it does not pause, it just tells you the time.

It is a clock that started when the board did. Not the time of day. The board has no idea what day it is.

unsigned long now = millis();

The pattern

Every non-blocking timer you will ever write looks like this. Learn the shape, not the details. The sketch calls these two names lastFadeTime and fadeGap; here they are shortened to lastTime and gap so the shape is easier to see.

unsigned long lastTime = 0;
unsigned long gap = 20;

void loop() {
  unsigned long now = millis();

  if (now - lastTime >= gap) {
    lastTime = now;

    // it is time. Do the thing.
  }

  // everything else, every single round
}

Read it as three ideas:

1. lastTime remembers when you last did the thing.
2. now - lastTime is how long it has been since. If that is at least gap, it is time.
3. The moment you do the thing, write down the new time, so the count starts again.

And crucially: everything below the if runs on every single round, thousands of times a second, whether it was time or not.

A memory game is no fun if it plays the same sequence every time. You need a number the player cannot predict.

int which = random(0, 4);

That gives you 0, 1, 2 or 3, chosen at random.

The problem with random on a small chip

The board has no real source of randomness. It runs a calculation that produces numbers that look random. And it starts that calculation from the same place every time it is switched on.

So without help, your game plays the identical "random" sequence every single time you power it up. Try it if you like: it is a strange thing to watch.

The fix is to start the calculation from somewhere different each time:

randomSeed(analogRead(A0));

You do not have to type this in anywhere. The finished game sketch you will upload in Part 9, b5_05_simon_worked.ino, already has that line in its setup, just below the loop that sets the pin modes. Your only job here is to understand why it is there, and to make sure nothing is wired to A0. It reads an analog pin with nothing connected to it, which, as you found out in Band 4, gives a meaningless drifting number. Meaningless is exactly what is wanted here. For once, a floating pin is useful.

Everything is wired from Part 4. Put your wiring back the way the pin table describes it if you moved anything for Part 6. All four lights, all four buttons and the buzzer need to be working.

Which button belongs to which light

The game pairs them up by position in the sketch's two lists. Button 1 answers light 1, button 2 answers light 2, and so on:

If you built the board left to right in the order the table in Part 4 gives, then light 1 is the leftmost light and button 1 is the leftmost button, and the pairing is simply straight down the board. If your parts ended up in a different order, that is fine, but write the pairing on a slip of paper and put it next to the board before you play, or every guess will be a guess.

Upload b5_05_simon_worked.ino and open the serial monitor.

Read it as a set of small jobs

This is the longest sketch in the course so far, at about ninety lines. It is not harder than what you have read before. It is organised, which is the whole point of this band.

Open it and find each of these. Notice that you can understand any one of them without reading the others.

Now look at loop on its own. Strip away the details and it says: add a new random step, play the whole sequence, then check the player's answer one press at a time. If any press is wrong, game over.

Nine lines of real work. Everything else has a name and lives somewhere else. That is what functions bought you.

a. Follow the timing by hand

Fill this in for b5_04, assuming fadeGap is 20 and the board has been running a while. Do not run it.

b. Break it on purpose

In b5_04, delete the line lastFadeTime = now; from inside the if. Predict what will happen, then upload.

c. Put the lines back in order

These lines from a function have been shuffled:

  return total;
int addUp(int a, int b) {
  int total = a + b;
}

Put them in order. Then answer two questions: why is the first word int and not void? And what would happen if return total; came before int total = a + b;?

d. Explain one line

In b5_05, inside waitForPress, there is this:

while (digitalRead(buttonPins[i]) == LOW) {
  delay(5);
}

It does nothing at all. It has no body worth speaking of. Why is it there, and what exactly breaks without it?

Work on a copy of b5_05_simon_worked.ino.

Bronze

Make the game speed up as it gets longer. The sequence should play faster with every round. You will need to hand playStep a second value: how long the step should last.

Silver

Write a function called playSequence() that plays the whole sequence, and use it in loop instead of the for loop that calls playStep(sequence[i]). Leave the second for loop, the one that reads the player's answer, alone. Then say in one sentence what loop reads like afterwards.

Gold

Add a time limit. If the player does not press within three seconds, they lose. This one is hard, and it is hard for an interesting reason: waitForPress blocks, so it can never notice time passing. You will have to rewrite it using millis, so that it watches the buttons and the clock at the same time.

The test that matters most in this band

Hand it to somebody and say one sentence, no more. Then be quiet and watch. Do not help. Do not explain. Let them be confused.

Write down every moment they did not know what to do, and every moment they thought it was their turn when it was not.

Then ask one question at the end: would you play it again? Write down the answer exactly, including the pause before it.

Show your work

Post a video of somebody else playing it, if you had somebody. If you tested it alone, post the video of yourself playing it cold the next day, and say so. Include your build log, your list of confusions, and a list of your functions with the one sentence each.

Then read one other person's sketch and tell them one place where a job could be pulled out into a function of its own.

Code you have not seen. Answer from reading only.

int lampPin = 5;
int buttonPin = 7;
int count = 0;

unsigned long lastBlink = 0;
int gap = 500;

void blinkOnce(int pin, int howLong) {
  digitalWrite(pin, HIGH);
  delay(howLong);
  digitalWrite(pin, LOW);
}

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

void loop() {
  unsigned long now = millis();

  if (now - lastBlink >= gap) {
    lastBlink = now;
    blinkOnce(lampPin, 300);
    count = count + 1;
    Serial.println(count);
  }

  if (digitalRead(buttonPin) == LOW) {
    Serial.println("pressed");
  }
}

1. How many values does blinkOnce need when you call it, and what are they for?
2. Why does blinkOnce start with void rather than int?
3. How often does the lamp blink?
4. Out of every 500 thousandths of a second, roughly how much of it is the board unable to see the button? Explain how you worked it out.
5. What will the serial monitor show if you hold the button down for two seconds?
6. gap is an int but lastBlink is an unsigned long. Is that a problem here? What would happen if lastBlink were an int too?

This was the hinge of the course, and you are through it.

Before this band you could only write programs that were one long list. Now you can break a job into pieces, give each piece a name, and put the pieces together. That is the difference between programs that fit on a page and programs that do something real.

And you know why delay was never quite enough, because you built something that failed on account of it and then fixed it yourself.

Before you move on, make sure you have

• Your game, with a video of somebody else playing it, or of you playing it cold a day later
• Your list of the moments they were confused, and their answer to "would you play again"
• The list of your own functions with one sentence each
• Your completed timing table from Part 10a
• Your answers from the counting activity in Part 1
• Your build log for this band
• Five or six correct answers in Part 13, including question 4

Next is Band 6: Things That Move. Everything you have built so far makes light or sound. Next it moves, and you find out why a motor cannot simply be plugged into a pin.