Getting started

Everything you need before the other tutorials: install the tools, get the API repository from Git, run the simulators on your own PC, drive a robot from Python, and choose between training on the CPU or on a GPU. About half an hour.

1Three ways to use it

The rest of this page sets up the second and third ways on your own PC.

2Install the tools

Windows

winget install Git.Git OpenJS.NodeJS.LTS Google.Chrome Python.Python.3.12

macOS (Homebrew)

brew install git node python@3.12
brew install --cask google-chrome

Ubuntu / Debian

sudo apt install git python3 python3-venv python3-pip
# Node.js 22: the apt version is often too old, use NodeSource
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install nodejs
# Chrome: download the .deb from google.com/chrome, or: sudo apt install chromium

Open a new terminal afterwards and check:

git --version
node --version       # v22.x or higher
python --version     # 3.10 or higher (Linux/macOS: python3)

3Get the code

Everything you need on your own PC (API server, Python client, tutorial scripts and trained models) is in the robotSimulatorAPI repository. The simulators themselves stay on this website: the API server fetches them from here. Clone the repository in a folder of your choice:

git clone https://github.com/mdequanter/robotSimulatorAPI.git
cd robotSimulatorAPI

What is in it:

Get the latest version later with:

git pull

4Run the simulators locally

Start the API server. It also serves the simulator pages, so you need no web server:

node server.mjs
Botopia simulator API on http://localhost:8780/api/  (simulators: http://localhost:8780/)
Simulator pages from https://robotics.dinno.be/

The server fetches each simulator page from robotics.dinno.be once and keeps it in memory, so you need an internet connection when it starts a robot for the first time. The simulation itself runs on your PC. Open http://localhost:8780/ to see the simulators through your local server. Leave the terminal open; Ctrl+C stops it.

5Python environment

Make a virtual environment inside robotSimulatorAPI, so the packages stay out of your system Python:

# Windows (PowerShell)
python -m venv .venv
.venv\Scripts\Activate.ps1

# Linux / macOS
python3 -m venv .venv
source .venv/bin/activate

What to install depends on what you want to do:

stable-baselines3 and ultralytics bring PyTorch along. With a plain pip install that is the CPU version on Windows and macOS. For a GPU, read step 7 before you install them.

6Your first API program

With the server from step 4 running, save this as hello.py in the robotSimulatorAPI folder:

import sys
sys.path.append("python")
from botopia import BotopiaEnv

env = BotopiaEnv(robot="skid", lane="corridor", dt=0.05, max_steps=200)
obs, info = env.reset(seed=1)
print("actions:", env.action_names)        # ['fwd', 'turn']

for t in range(200):
    obs, reward, terminated, truncated, info = env.step([0.5, 0.0])   # half speed, straight on
    if terminated or truncated:
        break
print("steps:", t + 1, "last reward:", reward)
env.close()

python hello.py

Start the server with --show to see the robot drive. Simulated time only moves when you call step, so the run is reproducible and as fast as your PC allows.

Without Python

The API is plain HTTP + JSON, so any language works. With curl:

curl localhost:8780/api/robots
curl -X POST localhost:8780/api/envs -d "{\"robot\":\"skid\",\"lane\":\"corridor\",\"seed\":1}"

The other calls (step, reset, camera images, several robots at once, direct motor control) are in the repository's README.md. Every robot and its commands are listed on the API page. For a quick demo with four robots, run python python/botopia.py.

7With or without a GPU

You do not need a graphics card. The simulators run in Chrome on the CPU, and for small networks the CPU is even faster. A GPU only speeds up the neural network, which pays off when the robot learns from camera images.

Without a GPU (CPU only)

Install as in step 5; that is all. On Linux, plain pip install torch downloads the large CUDA build; to save a few GB, install the CPU build first:

pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install stable-baselines3 gymnasium pillow

Use more CPU cores instead: more parallel environments (--envs in the tutorial scripts) and --browsers on the server.

With an NVIDIA GPU

1. Install a recent NVIDIA driver. nvidia-smi shows the highest CUDA version it supports.
2. Install the CUDA build of PyTorch first, then the rest (otherwise pip may pick the CPU build). Pick the command for your system on pytorch.org; RTX 50-series cards need CUDA 12.8 or newer:

pip install torch --index-url https://download.pytorch.org/whl/cu128
pip install stable-baselines3 gymnasium pillow
python -c "import torch; print(torch.cuda.is_available())"     # True = the GPU is usable

Then train with --device cuda (or auto, which picks the GPU when PyTorch sees one):

python python/track_vision_rl.py train --device cuda

8Remote control (PHP API)

To control a simulator that is open in a normal browser tab, in real time (for example to test a trained model or to mirror a real robot), use the PHP API. It runs on this website, so you install nothing for it:

1. Open https://robotics.dinno.be/indexSkid.php?remote=1. The page shows a session code in its bottom-right corner.
2. Control it from Python with that code:

import sys, time
sys.path.append("python")
from botopia import RemoteSession

s = RemoteSession("https://robotics.dinno.be/api/index.php", "CODE")
s.command(action={"drive": {"fwd": 0.5, "turn": 0.0}})
time.sleep(2)
print(s.state())                       # latest observation + incidents
s.command(action={"drive": {"fwd": 0, "turn": 0}})

The PHP API runs in real time (about 5 updates per second), so use the Node API for training.

9Where to go next

• Tutorial 1: your first reinforcement learning (PPO), the fastest lap through the corridor. Start here.
• Tutorial 2: learning from the robot's camera (GPU recommended).
• Tutorial 3: YOLO segmentation + RL.
• Tutorial 4, 5, 6: skills, robot arms, Hindsight Experience Replay.
• Tutorial 7 and 8: ROS 2, entirely in the browser, nothing to install.

10Troubleshooting