AntiprotonTechnologies

01Singularity Hub

First steps

Before the sensors and the maps, it helps to know the ground you are standing on: where things are on the screen, which way is which, how big each world is, and how far the robot goes when a wheel turns once. None of this is hard. We will go slowly.

The screen, piece by piece

  • Top bar. The ☰ menu (files, help, guide), the World picker, Run and Reset, the speed buttons (II pause, ½×, 1×, 2×, 4×), the clock, the windows (Lessons, Code, Sensors, Map, Camera, Plot, Drive), Focus, and the Python status light.
  • Left panel. Five tabs: Lessons, Files (your own programs), Robot (pick Scout or Ranger, switch sensors on and off, change their settings), World (pick or build a world, lights, graphics, Run mode) and Docs (the guide and a quick reference you can click to insert code).
  • Middle. The 3D world. Buttons in its corner change the camera: Orbit (drag to look around), Chase (behind the robot), Top (straight down, like a map) and Follow. Select, Move and Rotate let you pick up and place objects. Beams shows the sensor beams; HUD shows the position box.
  • Right. The code editor, and under it the Terminal (what your program prints, and a place to type ros2 commands), Tune (live sliders) and Graph (which nodes talk to which topics).
  • The position box (HUD). Top-left of the 3D view: x and y in meters, θ (the heading) in degrees, v speed in m/s, w turn rate in rad/s (shown as r/s), and t, the simulated time in seconds.

Run, Stop, Reset and the clock

ButtonWhat it does
Run (Ctrl + Enter, or F5 in the desktop app)Starts your program. By default the robot and objects first go back to their start spots, so every test is fair.
Stop (Esc, or Shift + F5)Stops the program and the motors. If a program is stuck, Stop restarts the simulator for you after a moment. Your code is kept.
ResetPuts everything back where you placed it, without running anything.
IIPauses time. Press 1× to carry on from the same moment.
½× 1× 2× 4×How fast simulated time runs compared with real time. The number under the clock shows the real speed your computer manages.

Units: meters, seconds, degrees

Singularity uses the same units as real robots that run ROS. Once they feel normal here, they will feel normal everywhere.

WhatUnitExample
Distancemeters (m)0.25 m = 25 cm, about the length of the Scout robot
Speedmeters per second (m/s)robot.forward(0.3) drives 30 cm every second
Turning speedradians per second (rad/s)1 rad/s ≈ 57 degrees per second
Angles in the simple commandsdegreesrobot.turn(90), robot.heading(), robot.pan_camera(45)
Angles in ROS messagesradiansa quarter turn is π/2 ≈ 1.571 rad
Timesecondsrobot.wait(1.5) lets 1.5 s pass

Which way is x, y and the heading

  • The middle of every world is (0, 0). The small red and green lines on the floor at the center show the axes.
  • Red is +x, green is +y. Switch to the Top view and you are looking down at the floor like a map.
  • Heading (θ) is the direction the robot faces: 0° points along +x, 90° along +y, 180° (or −180°) along −x, −90° along −y. Turning left makes the number go up.
  • For the robot itself (its own point of view): x is forward, y is to its left, and positive turning is to the left. LiDAR beam 0 points forward and the numbers go round to the left.

This is the standard ROS convention (called REP 103), so the directions you learn here are the same on a real robot.

The worlds and their sizes

Each world is a walled area with (0, 0) in the middle. “6 × 6 m” means 6 meters from wall to wall along x, and 6 meters along y.

WorldSize (x × y)Robot starts atFloor tilesWhat is inside
Open Lab6 × 6 mx −1, y −1, facing 0°0.5 m tiles, darker line every 1 mA taped 1 m square starting at the start spot, and a few cones
Studio6 × 6 mx −2, y −1.9, facing 45°0.5 m tiles, a small cross at every whole meterBig blocks on a dark glossy floor
Playground5 × 5 mx −1.8, y −1.8, facing 45°0.5 m tiles, crosses every meterCrates, barrels, boxes and cones; light things slide when pushed
Maze5 × 5 mx −2, y −2, facing 90°0.5 m tiles, crosses every meterA 5 × 5 maze with 1 m wide corridors and a few loops
Line Track5 × 5 mx 1.85, y 0, facing 90°0.5 m tilesA closed loop of black tape with S-bends
Camera Lab5 × 5 mx −1.5, y −1.5, facing 45°0.5 m tilesRed, orange, yellow, green, blue and purple balls, posts and boxes
Office8 × 6 mx −0.2, y −2.3, facing 90°0.6 m tilesDesks, chairs, a meeting table, sofa, shelves, plants
Warehouse8 × 6 mx −3.3, y −2.3, facing 0°2 m slabsLong racks, pillars, loose boxes, crates, a barrel, cones

Walls are 30 cm high in most worlds (40 cm in Camera Lab and Warehouse, 90 cm in the Office). You can build your own world in the World tab: + Build a new world, then add walls and objects and drag the robot to where it should start.

The two robots

ScoutRanger
KindTwo driven wheels and casters (differential drive), like a TurtleBotFour wheels, skid steering, off-road tires
Size (length × width)30 × 24 cm46 × 30 cm
Weight2.2 kg9 kg
Wheel radius4 cm (8 cm across)7.5 cm (15 cm across)
Distance between left and right wheels25 cm39 cm
LiDAR height17.5 cm above the floor21.5 cm above the floor
Camera21 cm high, starts tilted 40° down25 cm high, starts tilted 38° down
Encoder ticks per wheel turn360 (change it in the Robot tab)360
Top speed0.6 m/s by default (Robot tab → Motors, up to 1.0)same setting

Every lesson works with both. Pick one in the Robot tab; the sensors move to the right places on its body by themselves.

One wheel turn: how far does it go?

When a wheel turns once, the robot rolls forward by the wheel’s circumference: the distance around the edge of the wheel. The formula is circumference = 2 × π × radius.

Scout (radius 4 cm)Ranger (radius 7.5 cm)
One wheel turn2 × 3.1416 × 0.04 = 0.251 m (25.1 cm)2 × 3.1416 × 0.075 = 0.471 m (47.1 cm)
One encoder tick (360 per turn)0.251 ÷ 360 = 0.70 mm0.471 ÷ 360 = 1.31 mm
Turns to drive 1 m1 ÷ 0.251 = 3.98 turns1 ÷ 0.471 = 2.12 turns
Ticks to drive 1 m3.98 × 360 = 1432 ticks2.12 × 360 = 764 ticks
Across a 5 m world (Maze, Playground)19.9 wheel turns10.6 wheel turns
Across a 6 m world (Open Lab, Studio)23.9 wheel turns12.7 wheel turns
Along an 8 m world (Office, Warehouse)31.8 wheel turns17.0 wheel turns

And how long does crossing take? Time = distance ÷ speed. At robot.forward(0.3), crossing a 5 m world takes 5 ÷ 0.3 ≈ 17 seconds (a little more, because the robot needs a moment to speed up).

Turning on the spot. To spin, the wheels turn in opposite directions. For the Scout, a full turn on the spot moves each wheel around a circle 25 cm across: 3.1416 × 0.25 = 0.785 m, which is about 3.1 wheel turns. The Ranger’s tires slide sideways when it turns (that is what skid steering means), so it behaves as if its wheels were a little further apart than they are, and its odometry drifts more when it spins.

You can check all of this yourself. This program drives exactly half a meter and works the distance out from the ticks:

encoders_simple.pytested: 0.497 m from ticks
# Wheel encoder test · world: Open Lab
# encoders() = (left, right) ticks. One wheel turn = ticks_per_rev() ticks.
import math
WHEEL_RADIUS = 0.04                        # Scout: 4 cm (Ranger: 7.5 cm)
l0, r0 = robot.encoders()
robot.move(0.5)                            # drive exactly 0.5 m, then stop
l1, r1 = robot.encoders()
ticks = ((l1 - l0) + (r1 - r0)) / 2
dist = ticks / robot.ticks_per_rev() * 2 * math.pi * WHEEL_RADIUS
print(f"ticks: left {l1 - l0}, right {r1 - r0}")
print(f"distance from ticks: {dist:.3f} m")
print("odometry pose (x, y, theta):", [round(v, 3) for v in robot.odometry()])
print("true pose (simulator only):  ", [round(v, 3) for v in robot.true_pose()])

Floor tiles and the map grid

There are two kinds of grid, and they are different things:

  • The floor tiles you see are only there to help your eyes judge distance (0.5 m tiles in most worlds, with a stronger line or a cross every 1 m). The robot cannot see them.
  • The map grid is what SLAM builds: a grid of square cells, each 5 cm × 5 cm (0.05 m). It covers the whole world plus 75 cm extra on every side, so a 5 × 5 m world gives a map of 130 × 130 cells, and an 8 × 6 m world gives 190 × 150 cells. Page 03 explains how to read it.
World sizeMap size in cellsMap corner (origin)
5 × 5 m (Playground, Maze, Line Track, Camera Lab)130 × 130(−3.25, −3.25)
6 × 6 m (Open Lab, Studio)150 × 150(−3.75, −3.75)
8 × 6 m (Office, Warehouse)190 × 150(−4.75, −3.75)

How time works in your program

The simulator and your program take turns, like two people sharing one pencil. The world moves forward in tiny steps of 1/120 of a second. This keeps things fair and repeatable: a slow computer runs the world more slowly, but your robot still sees exactly the same thing.

  • robot.wait(1) lets one second of world time pass. time.sleep(1) does the same.
  • A while loop that uses the robot gives the world one step every time it goes round, so while True: is safe and does not freeze anything.
  • A motor command keeps going until you give a new one. robot.forward(0.3) on its own starts the robot; the next line runs at once. Add robot.wait(...) to let it drive for a while.
  • When your program ends, the robot stops.
  • robot.time() tells you the world time since you pressed Run.

Keyboard shortcuts

KeysWhat they do
W A S D or arrowsDrive by hand (click the 3D view first). Works even while a program runs: your keys win while you hold them.
Ctrl + EnterRun
EscStop the program, or go back to the Select tool
HHeadlights on and off
T / RMove tool / Rotate tool for objects
Q ETurn the object you hold by 15°
DelDelete the selected object
F5 / Shift + F5Run / Stop (desktop app)
F1, F11Open the guide, full screen (desktop app)
Ctrl + N, Ctrl + ONew program, open a .py file (desktop app)
Ctrl + Shift + SSave a copy of the program as a .py file (desktop app)

Where your programs are saved

Programs in the Files tab, your worlds and your settings are saved automatically, on your own computer only. To keep a copy somewhere else (or to share it), use ☰ → Save a copy (.py), which writes a normal .py file. ☰ → Open program (.py) loads one back in. ☰ → New program starts an empty one.

Stuck on something this page did not answer? Write to us at antiprotontechnologies@gmail.com. Paste what you tried and what happened (the Copy details for support button in Singularity’s Help & Support window helps us a lot).