Commands from the computer

The computer can send lines of text too. The micro:bit reads each whole line and its program decides what the word means, so both sides must agree on every word.

A 3D printer, a laser cutter and a robot arm in a factory all take orders from a computer as short lines of text: move here, heat up, stop. The machine's own program decides what each line means.

Last lesson the micro:bit sent lines to the computer. Now the computer sends lines to the micro:bit: the board has buttons that each send a word.

You need: a micro:bit, a USB cable, and Chrome or Edge. The MakeCode simulator cannot receive lines from the computer, so this lesson runs on a real micro:bit. Without one, do the Predict, Investigate, Modify and Make steps in the editor and check them with a partner.

Predict: Read the code and say what it will do before you run anything. A wrong guess is fine: it shows you what to look for.
Run: Run it and compare the result with your prediction.
Investigate: Trace how each line of code connects to what you see.
Modify: Change the code on purpose and check the result.
Make: Build something new using what you have learned. Expect a few tries; that is normal.

WidthMore contexts, same idea.

Explain it to me

The computer sends a line of text. on serial data received runs when the whole line has arrived; read line gives the text.

Your program decides what each word means, so the words must match exactly.
Reply with serial write line so the computer knows what happened, and use else for words you don't know.

Show as code

serial.onDataReceived(serial.delimiters(Delimiters.NewLine), function () {
    command = serial.readLine()
    if (command == "happy") {
        basic.showIcon(IconNames.Happy)
    } else if (command == "sad") {
        basic.showIcon(IconNames.Sad)
    }
})
let command = ""

The example, as blocks

What it makes

PredictRead the code and say what it will do before you run anything. A wrong guess is fine: it shows you what to look for.

Predict

Show as code

commands.ts

serial.onDataReceived(serial.delimiters(Delimiters.NewLine), function () {
    command = serial.readLine()
    if (command == "happy") {
        basic.showIcon(IconNames.Happy)
    } else if (command == "sad") {
        basic.showIcon(IconNames.Sad)
    }
})
let command = ""

The computer sends the line Happy (with a capital H) to a micro:bit running this program. What does it show?A happy faceThe word HappyA sad faceNothing

RunRun it and compare the result with your prediction.

Run it on a micro:bit

Click Download and copy the program to your micro:bit. Leave it plugged in. If the editor is connected to the micro:bit, disconnect it there first.

Show as code

commands.ts

serial.onDataReceived(serial.delimiters(Delimiters.NewLine), function () {
    command = serial.readLine()
    if (command == "happy") {
        basic.showIcon(IconNames.Happy)
    } else if (command == "sad") {
        basic.showIcon(IconNames.Sad)
    }
})
let command = ""

Try it yourselfYour edits are saved in this browser.

It takes a few seconds to load. Your work in this step is kept.

I downloaded the program to my micro:bit and left it plugged in.

Run TypicalRun it and compare the result with your prediction.

Send commands

Click Connect a micro:bit, then the Happy and Sad buttons. Then type Happy in the box and send it. What happens?

Try it yourselfYour edits are saved in this browser.

Send happy and sad with the buttons, then type Happy yourself.

Use the board. This ticks when you get there.

InvestigateTrace how each line of code connects to what you see.

Investigate

Show as code

commands.ts

serial.onDataReceived(serial.delimiters(Delimiters.NewLine), function () {
    command = serial.readLine()
    if (command == "happy") {
        basic.showIcon(IconNames.Happy)
    } else if (command == "sad") {
        basic.showIcon(IconNames.Sad)
    }
})
let command = ""

Show as code

serial.onDataReceived(serial.delimiters(Delimiters.Comma), function () {
    command = serial.readLine()
    if (command == "happy") {
        basic.showIcon(IconNames.Happy)
    }
})
let command = ""

When does on serial data received run?Each time a whole line arrives (it ends with a new line)When a button on the micro:bit is pressedEvery half secondOnly when the micro:bit starts

Ben's micro:bit never reacts, whatever the board sends. His program starts with on serial data received with delimiters comma. Why?He needs a forever blockThe cable is too slowIt waits for a comma, but the board ends each line with a new line, so it never runsCommas are not allowed in serial

Why is it useful for the micro:bit to send a reply, such as ok?Replies are needed for the LEDs to workReplies make the cable fasterThe micro:bit forgets the command otherwiseThe computer then knows the command arrived and was understood

ModifyChange the code on purpose and check the result.

Modify

Add a heart command. On the board, type heart in the box to test it.

Need a hint?

Add an else if: command = heart, then show icon heart.

Make the micro:bit reply: ok when it knows the word, ? when it doesn't. The board shows the replies.

Need a hint?

serial write line is in Serial.

Another hint

Add an else at the end for any other word: serial write line ?

Try it yourselfYour edits are saved in this browser.

It takes a few seconds to load. Your work in this step is kept.

Add a heart command that shows a heart.

This ticks by itself when your blocks do what is asked.

Reply ok to happy and sad, and ? to any other word.

This ticks by itself when your blocks do what is asked.

MakeBuild something new using what you have learned. Expect a few tries; that is normal.

Make

Make a desk lamp the computer controls. on lights every LED, off clears the screen, count shows (and sends back) how many commands it has had. Reply ok to on and off and ? to anything else.

Try it yourselfYour edits are saved in this browser.

It takes a few seconds to load. Your work in this step is kept.

Need a hint?

Three branches: on, off and count; an else for anything else.

Another hint

on: show leds with every LED lit; off: clear screen; count: show number and send it back with serial write value.

A desk lamp the computer controls: on, off, count (how many commands so far), a reply to each, and ? for other words.

This ticks by itself when your blocks do what is asked.

Info Typical

Test the lamp

Download your lamp to a micro:bit, connect it, and use the buttons. Type a word it doesn't know, too.

Try it yourselfYour edits are saved in this browser.

Send on, off and count to your lamp, and get a count back.

Use the board. This ticks when you get there.

For teachers

Students program a micro:bit to act on words the computer sends over USB, reply to each one, and handle words it doesn't know. About 45 minutes.

Open the teacher guide: answers, solutions, slides and a worksheet.

Students will be able to

I can make a micro:bit act on a line of text sent from the computer.
I can explain why the words must match exactly.
I can reply to each command, including words my program doesn't know.

Before class

The idea: the computer sends a line of text; on serial data received runs once the whole line has arrived (it ends with a new line), and read line gives its text. The micro:bit's own program decides what each word means, so both sides must agree on every word, capital letters included. A reply (ok, or ? for an unknown word) tells the computer what happened.

Hardware: the simulator cannot receive lines from the computer, so the board steps need a micro:bit, a data USB cable and Chrome or Edge. They are marked typical: without micro:bits, students do Predict, Investigate, Modify and Make in the editor (code checks still tick) and talk through what would happen.

Only one page can use the cable at a time: if MakeCode is connected to the micro:bit, disconnect it there first.

Running the lesson

Predict: many say a happy face. Ask: is Happy the same text as happy?
Send commands: let students find that typed Happy does nothing before you explain.
Investigate: Ben's comma is the delimiter idea; the board always ends lines with a new line.
Modify: the ? reply is the important one: it makes unknown words visible.

The hard part (on purpose)

The micro:bit acts only on the exact words it checks for. When a word does nothing, ask them to compare it letter by letter with the program.

When students get stuck

Nothing happens when a button is pressed. Ask: Is the board connected (the button says micro:bit connected)? Is MakeCode connected to the micro:bit in another tab? Fix: Disconnect MakeCode, then Connect a micro:bit on the board.
Some words work and others don't. Ask: Does the word you sent match the word in the if exactly? Fix: Match spelling and capitals, or add a branch.
The micro:bit never reacts to anything. Ask: Which delimiter does on serial data received wait for? Fix: Use new line.

Stretch and support

Stretch: Add a command that takes a number, such as bright 50: check the line starts with bright, and use the rest as the brightness.

Support: Give the reply branch for happy; students copy the pattern for sad and add the else.

Where it leads

Next: a radio bridge, so commands reach a micro:bit across the room. Real world: 3D printers and CNC machines take G-code, one command per line.

What each step is for

Send commands: Seeing which words work and which don't makes exact matching concrete: the micro:bit acts only on the words its program checks for.
Investigate: on serial data received runs once per whole line; read line gives the line's text, and the program's if chooses what each word does.
Modify: A new command needs a new branch; a reply for every line, including words the program doesn't know, tells the computer what happened.

Now you can

Make a micro:bit act on a line of text sent from the computer.
Explain why the words must match exactly.
Reply to each command, including words my program doesn't know.

Next lesson3. A radio bridgeA micro:bit on the cable relays messages by radio, so the micro:bit doing the work can be anywhere in the room. The bridge passes radio to serial one way and serial to radio the other.

Source: content/code/microbit-computer/commands/lesson.md