start from the template

Start from the template

Import this repo into MakeCode as a ready-to-run robot project, then add your own program to its on-robot menu.

Use this path when you want something that already works. The template has the DiffDrive extension installed, a menu you drive with the micro:bit's buttons, and example programs (a square, a circle, and two calibration routines) that you can copy from.

1. Import the project into MakeCode

1. Go to https://makecode.microbit.org/.

2. Click Import, then Import URL….

3. Paste the repo URL and click Go ahead!:

   https://github.com/League-Microbit/nezha-robot-template
   

MakeCode opens the project in the JavaScript editor. The DiffDrive extension comes with it, because pxt.json lists it as a dependency. You'll see a DiffDrive category in the toolbox.

Want to keep your changes on GitHub? Fork the repo first, then import your fork's URL. MakeCode can commit back to it.

2. Try it on the robot

1. Plug the micro:bit V2 into the computer with USB.
2. Click Download, then drag the .hex file onto the MICROBIT drive, or pair the board in MakeCode and let it flash directly.
3. Put the micro:bit in the Nezha and switch it on. Give the robot room to move: about a metre of clear floor.

The programs run from an on-robot menu:

Button	What it does
A	Step to the next program. The screen shows its picture.
B	Run the program whose picture is showing.
A, B, or A+B while a program runs	Stop it.

The menu order is circle, square, cal-wheels, cal-turn. Try square first: the robot drives a 50 cm square and ends up back where it started.

3. Add your own program

Each program is a function in its own file under test/. Here is square.ts, cut down:

function driveSquare() {
    for (let i = 0; i < 4; i++) {
        if (!legMove(50, 0)) { programStopped("square"); return }   // 50 cm straight
        if (!legMove(0, 90)) { programStopped("square"); return }   // turn 90° left
    }
}

legMove(distance, turn) is a helper from test/runhelp.ts. It calls diffDrive.move(), and returns false if a button press cancelled the program, so your program can stop cleanly.

To add a program called zigzag:

1. Create test/zigzag.ts with a driveZigzag() function, written like driveSquare() above.
2. Add "test/zigzag.ts" to the files list in pxt.json, above "test/boot.ts". boot.ts must stay last, because it wires up the menu after every program has loaded.
3. In test/boot.ts, add your function to PROGRAM_RUNS, add its name to PROGRAM_NAMES, and add a picture for it to PROGRAM_PICTURES. Put each one at the same position in its list.
4. Download and flash again. Your program is now on the menu.

For every move, turn and pose function you can call, see Add the DiffDrive extension. It's the same API.

Build from the command line (optional)

If you'd rather work in VS Code and flash from a terminal, clone the repo and use the scripts in it:

git clone https://github.com/League-Microbit/nezha-robot-template
cd nezha-robot-template
npm run setup      # once: installs PXT, the micro:bit target and the extension
make build         # compile locally (needs Docker), or: make build-cloud
make deploy        # build, then flash to the plugged-in micro:bit
make code          # a local MakeCode editor at http://localhost:3232

The repo also has a .devcontainer/ for VS Code Dev Containers and GitHub Codespaces, with Node, Docker and PXT already installed.

Just want the calibration image?

Every release includes a ready-built nezha-robot-template-<version>.hex. Drag it onto the MICROBIT drive. There's nothing to compile.