Before the workshop

Versão em português

DotBot Academy is a hands-on introduction to programming a swarm of small robots with Python. You work in pairs, first in a simulator and then on real robots.

What you need to know

  • Basic Python: variables, loops, calling functions.
  • No robotics or electronics background is needed.

Your computer

You can use the lab Macs, which are already set up, or bring your own computer. Both work. On a lab Mac, DotBot is already installed: jump to Already installed? Update it. On your own computer, follow steps 1-4 below before the workshop; it takes a few minutes and about 250 MB of disk space. The PyDotBot documentation covers the same steps in its Install section.

1. Create your workshop folder

Keep everything for the workshop in one folder named dotbot-academy in your home folder: the virtual environment, your scripts, and any files we give you. Create it and go into it:

macOS and Linux

mkdir -p ~/dotbot-academy && cd ~/dotbot-academy

Windows (PowerShell)

mkdir -Force ~\dotbot-academy; cd ~\dotbot-academy

2. Install Python

You need Python 3.11, 3.12 or 3.13; 3.13 is recommended. Python 3.14 does not work yet, on any system: pygame, which DotBot needs, fails to install on it. Check what you have with python3 --version (macOS, Linux) or py --list (Windows).

  • macOS and Windows: download “macOS installer” or “Windows installer (64-bit)” (also for ARM laptops) from the Python 3.13.16 page, not from python.org’s main download button, which gives 3.14. On Windows, tick “Add python.exe to PATH” in the first screen of the installer. On macOS, brew install python@3.13 also works if you use Homebrew.
  • Linux: use your distribution’s package (for example sudo apt install python3 python3-venv on Debian or Ubuntu), as long as it is 3.11, 3.12 or 3.13.

3. Create a virtual environment and install DotBot

A virtual environment keeps the workshop’s packages separate from the rest of your system. Run these commands in a terminal, inside dotbot-academy.

macOS and Linux

python3.13 -m venv .venv
source .venv/bin/activate
pip install pydotbot

No python3.13? If python3 --version shows 3.11, 3.12 or 3.13, use python3 -m venv .venv instead.

Windows (PowerShell)

py -3.13 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install pydotbot

The organizers have not yet tested the workshop on Windows. If anything fails there, a lab Mac is available on the day.

Each time you open a new terminal, go back to the folder and activate the environment before using dotbot: cd ~/dotbot-academy, then the second command above. Your prompt then starts with (.venv).

4. Check it works

  1. Print the version:

    dotbot --version

    It prints a line such as dotbot 0.32.0. A message saying that no config file was found is normal.

  2. Start the simulator with four robots:

    dotbot run simulator --robots 4

    A browser tab opens on the live map, showing four simulated robots.

  3. Press Ctrl+C in the terminal to stop the simulator.

If both steps work, you are ready.

To look further ahead, dotbot guide prints PyDotBot’s built-in getting-started walkthrough in the terminal: the simulator, moving a robot, the REST API, then real hardware. It is also good context for an AI assistant.

Already installed? Update it

On a lab Mac, or if you installed DotBot earlier, bring it up to date, as a new release may have come out since:

macOS and Linux

cd ~/dotbot-academy
source .venv/bin/activate
pip install --upgrade pydotbot
dotbot --version

Windows (PowerShell)

cd ~\dotbot-academy
.\.venv\Scripts\Activate.ps1
pip install --upgrade pydotbot
dotbot --version

On the day

  1. If you use your own laptop, bring it charged, with its charger.
  2. The Wi-Fi details are given in the room.
  3. If you could not finish the install, arrive 10 minutes early and we will help you, or use a lab Mac.
  4. Still installing when the session starts? Start it anyway, as soon as you sit down: it can run while the instructor presents the platform, and you need it for the simulator, the first hands-on step.

Troubleshooting

Asking an AI assistant (ChatGPT, Claude, Gemini, or a coding agent) is a good first step: paste the exact error message and say which operating system you use. The common cases are below, and the PyDotBot docs have a troubleshooting page.

pip install pydotbot fails with “Failed to build pygame”. You are on Python 3.14 (or 3.10 or older): install 3.13 (step 2), delete the .venv folder (rm -rf .venv; Windows: Remove-Item -Recurse -Force .venv) and create it again (step 3).

dotbot: command not found (or “not recognized” on Windows). The virtual environment is not active in this terminal. Run cd ~/dotbot-academy, then the activate command from step 3.

Windows refuses to run Activate.ps1. PowerShell blocks scripts by default. Run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once, then activate again.

The simulator stops by itself a second after it starts (“Controller stopped”). Most likely another program, or a simulator you did not stop, is already using port 8000. Close it, or start on another port with dotbot run simulator --robots 4 --controller-http-port 8001.

No browser tab opens. Open http://localhost:8000/console/ by hand while the simulator is running (use your port number if you changed it).

Your laptop does not let you install software (for example a company-managed laptop). Use a lab Mac on the day; nothing needs to be installed on it.