How it all works¶

Everything BugBot does sits in three places: the lessons, where you read and run code; the tasks at the end of each lesson, which the simulator marks; and the competitions, where programs race each other. This page is the tour. Ten minutes here saves a lot of hunting later.

If you have never programmed, start at lesson 0.1 in Robot club, or lesson F1.1 if you are working towards a GCSE, and read this page alongside the first one.

The three pieces¶

	What it is	Where
Lessons	Short pages that mix explanation with code you can run on the spot. 404 of them, in GCSE, Robot club, A level and University.	the lessons site
Tasks	A challenge at the end of a lesson. The simulator runs your program and says whether it did the job. 425 of them.	inside each lesson
Competitions	19 games where programs race, on one screen or in a room with other people.	the competitions site

Nothing needs installing, nothing needs an account, and your progress is kept in your own browser. A class code from a teacher adds their view of your work, and nothing else changes.

Choosing a course¶

The lessons site opens on a list of modules with a row of chips at the top: Everything, and one for each course.

GCSE is the full computer science course, matched to the exam boards.
Robot club is the fun one: no specification, no marking, games after most modules. It starts with an hour of Python for people who have never programmed.
A level is the full A level course.
University is robotics as a degree teaches it: kinematics, odometry, filtering, control, state estimation, localisation, mapping, planning, vision and learning, written as programs that run on a robot which does not know where it is.

Pick a chip and the list narrows to that course. Your choice is remembered.

Inside a lesson¶

A lesson is a page you scroll. Text explains an idea, then a cell lets you try it.

A cell¶

Each cell is a small editor with the robot beside it.

Here is a real one, running in this page. Press Run and watch the robot; change a number and run it again.

Run starts the program. While it runs the button says Stop, and pressing it halts the robot.
The robot appears on the mat on the right, and drives as the program says.
Anything you print() appears underneath, in the console.
Debug runs the program one line at a time, so you can watch what changes. Step moves to the next line.
Replay plays the last run again, with a slider to scrub through it.
Camera and Depth show what the robot's camera and depth sensor saw, which is how you find out why a program that looked right behaved oddly.
The ⋮ menu holds the rest: full screen, copy the code, download it, a link to this exact program, and saved versions.

Edit any cell and run it again. Nothing you type can break the page: reload it and the original comes back.

The reference¶

The Reference button opens the list of every robot command, with an example for each and a search box. Pressing the example inserts it into your program. It is the fastest way to remember whether it is turn_right(30, angle=90) or something else.

Files¶

A cell starts with one file, main.py. The + file tab adds another, which is how a longer program gets split up, and how Module F4 teaches importing your own code.

Reading comfortably¶

The Aa button at the top of the page sets text size and a dark theme. Robot sound has its own switch, and a lesson with a lot of code can be read full screen from the cell menu.

Tasks¶

The last cell of most lessons is a task: the same editor, with a job to do and a checker watching.

Read what the task asks. The mat is set up for it, with zones, walls or balls where they need to be.
Write your program in the cell.
Press Run. The simulator runs it and then marks it.
You get Passed, with the time it took, or Not yet and the reason: "did not finish in the green zone", "touched the wall", "print one line like nearest: 27.4".

The reason is the useful part. It is written from what your robot actually did, not from what the program looks like.

Stuck? gives a nudge: what to work out, never the code. Use it. Every task also has a best time, kept in your browser, so a second go at a task you have passed is a race against yourself.

A task is passed by doing the job, not by matching an expected answer. There are usually several ways.

The university course¶

The university course works differently from the others in one important way: the robot does not know where it is.

position() and heading() still exist, and they are exact. In this course they are treated as the lab's overhead camera: something the building measures, not the robot, there so you can mark your own work. What the robot actually has is its own sensors, and they are wrong in the ways real sensors are wrong.

The robot's own sensors	What they give you
`flow()`	how fast the mat is sliding past underneath, in the robot's own frame
`imu()`	a heading, a turn rate and an acceleration, all measured and all noisy
`odometry()`	those added up into a position, which drifts the further you go
`scan()`	the depth sensor read as a fan of eight directions
`set_noise(level)`	how rough all of that is: 0 perfect, 1 as built, 3 a bad day

Most of the course is about closing the gap between what the robot believes and what is true: filters, a Kalman filter, a particle filter, maps, planners and the camera.

The chart¶

plot(name, value) draws a line on a chart under the console, and it follows the replay like everything else. A control loop or a filter is far easier to judge as a shape than as a column of numbers.

This cell steps the drive to full power and plots three lines: the measured speed rising to its limit, and where the robot believes it is against where it really is. Press Run.

How its tasks are marked¶

A university task is often marked on a number your program works out, not only on where the robot ends up. The task asks you to print something, bias: 0.31 or my x: 42.5, and the simulator compares it with the truth it kept to itself, within a tolerance. Some tasks ban position() from your program entirely, because using the answer as the input teaches nothing.

Others check that a controller settled: that from some time onwards the robot stayed inside a band, rather than just happening to be in the right place when the clock stopped.

The course has lesson plans written as a lecture and a lab, a quiz on every lesson, and a capstone at the end that uses nearly all of it.

Competitions¶

A competition is a program that runs with other robots on the same mat. There are 19 of them, sorted into easy, medium and hard, and into single robot, free-for-all and team games.

Practice¶

Open a game and press Race. Your program runs against the game's built-in bots on your own screen, as often as you like. Each game page explains its rules, lists what info() tells your program, and describes each bot so you know what you are up against.

That is where a program gets good. Print as you go, race, then read your log to see when your robot changed its mind.

This is a real game page, in this page. Press Race to run the starter program against the built-in bots.

A room¶

To play other people:

One screen presses Open on the projector and gets a six-letter room code.
Everyone else opens the same game, presses Join, types the code and a name, and presses Submit to send their program in.
The host presses Start the race. Every screen runs the same race, with everybody's programs.
The results board shows who finished where, and why anyone who went out did.

A class can keep a points table across several games in a session, which is what makes a lesson's last ten minutes worth watching.

Working with a class¶

If your teacher gives you a six-letter class code, press Join a class at the top of the lessons site and type it with a nickname, or your school number or account if the class uses those.

After that:

Your task results appear on your teacher's board as they happen.
Hand in appears on task cells: it sends the program and how its run went, so your teacher can look properly and reply.
A teacher can send a hint or a message, which appears at the top of your page.
Your teacher may lock modules ahead of the class, or set an assignment with a due date, or run a test with a time window.

Without a class code, none of that exists and nothing leaves your browser.

For teachers¶

The teacher side is BugBot Teach: make a class, read out the code, and watch the room work.

Right now shows who is on what, who is stuck, and their last error.
The board shows every task, passed, tried or not started, and quiz scores.
Materials has a lesson plan, a printable worksheet with answers, and projector slides for every one of the 404 lessons.
Tasks lets you build your own task or competition: put robots, balls and zones on a mat and write the rules as IF and THEN steps.

When things go wrong¶

The robot does nothing. Check the program has connect() after the import, and that a driving command is followed by wait() or a distance=.
The robot stops half a second after the program ends. That is deliberate: it stops itself if it hears nothing from your program.
The page is slow the first time. Python itself is being loaded into the browser. It is quick after that.
A task will not pass. Read the reason under the run, then use Stuck?. Check the task's own words: "stop inside the zone" means stopped, not driving through.
Nothing runs at all. Use Chrome, Edge, Firefox or Safari, reasonably up to date, and allow the page to use your browser's storage.

Where next¶

Getting Started: the same thing with a real robot on the end of a USB cable.
The lessons: every module and lesson, with what each one teaches.
Compete: every game, what it needs and who it is for.
The API reference: every command the robot understands.