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
ros2commands), Tune (live sliders) and Graph (which nodes talk to which topics). - The position box (HUD). Top-left of the 3D view:
xandyin meters,θ(the heading) in degrees,vspeed in m/s,wturn rate in rad/s (shown as r/s), andt, the simulated time in seconds.
Run, Stop, Reset and the clock
| Button | What 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. |
| Reset | Puts everything back where you placed it, without running anything. |
| II | Pauses 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.
| What | Unit | Example |
|---|---|---|
| Distance | meters (m) | 0.25 m = 25 cm, about the length of the Scout robot |
| Speed | meters per second (m/s) | robot.forward(0.3) drives 30 cm every second |
| Turning speed | radians per second (rad/s) | 1 rad/s ≈ 57 degrees per second |
| Angles in the simple commands | degrees | robot.turn(90), robot.heading(), robot.pan_camera(45) |
| Angles in ROS messages | radians | a quarter turn is π/2 ≈ 1.571 rad |
| Time | seconds | robot.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.
| World | Size (x × y) | Robot starts at | Floor tiles | What is inside |
|---|---|---|---|---|
| Open Lab | 6 × 6 m | x −1, y −1, facing 0° | 0.5 m tiles, darker line every 1 m | A taped 1 m square starting at the start spot, and a few cones |
| Studio | 6 × 6 m | x −2, y −1.9, facing 45° | 0.5 m tiles, a small cross at every whole meter | Big blocks on a dark glossy floor |
| Playground | 5 × 5 m | x −1.8, y −1.8, facing 45° | 0.5 m tiles, crosses every meter | Crates, barrels, boxes and cones; light things slide when pushed |
| Maze | 5 × 5 m | x −2, y −2, facing 90° | 0.5 m tiles, crosses every meter | A 5 × 5 maze with 1 m wide corridors and a few loops |
| Line Track | 5 × 5 m | x 1.85, y 0, facing 90° | 0.5 m tiles | A closed loop of black tape with S-bends |
| Camera Lab | 5 × 5 m | x −1.5, y −1.5, facing 45° | 0.5 m tiles | Red, orange, yellow, green, blue and purple balls, posts and boxes |
| Office | 8 × 6 m | x −0.2, y −2.3, facing 90° | 0.6 m tiles | Desks, chairs, a meeting table, sofa, shelves, plants |
| Warehouse | 8 × 6 m | x −3.3, y −2.3, facing 0° | 2 m slabs | Long 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
| Scout | Ranger | |
|---|---|---|
| Kind | Two driven wheels and casters (differential drive), like a TurtleBot | Four wheels, skid steering, off-road tires |
| Size (length × width) | 30 × 24 cm | 46 × 30 cm |
| Weight | 2.2 kg | 9 kg |
| Wheel radius | 4 cm (8 cm across) | 7.5 cm (15 cm across) |
| Distance between left and right wheels | 25 cm | 39 cm |
| LiDAR height | 17.5 cm above the floor | 21.5 cm above the floor |
| Camera | 21 cm high, starts tilted 40° down | 25 cm high, starts tilted 38° down |
| Encoder ticks per wheel turn | 360 (change it in the Robot tab) | 360 |
| Top speed | 0.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 turn | 2 × 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 mm | 0.471 ÷ 360 = 1.31 mm |
| Turns to drive 1 m | 1 ÷ 0.251 = 3.98 turns | 1 ÷ 0.471 = 2.12 turns |
| Ticks to drive 1 m | 3.98 × 360 = 1432 ticks | 2.12 × 360 = 764 ticks |
| Across a 5 m world (Maze, Playground) | 19.9 wheel turns | 10.6 wheel turns |
| Across a 6 m world (Open Lab, Studio) | 23.9 wheel turns | 12.7 wheel turns |
| Along an 8 m world (Office, Warehouse) | 31.8 wheel turns | 17.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:
# 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 size | Map size in cells | Map 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
whileloop that uses the robot gives the world one step every time it goes round, sowhile 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. Addrobot.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
| Keys | What they do |
|---|---|
| W A S D or arrows | Drive by hand (click the 3D view first). Works even while a program runs: your keys win while you hold them. |
| Ctrl + Enter | Run |
| Esc | Stop the program, or go back to the Select tool |
| H | Headlights on and off |
| T / R | Move tool / Rotate tool for objects |
| Q E | Turn the object you hold by 15° |
| Del | Delete the selected object |
| F5 / Shift + F5 | Run / Stop (desktop app) |
| F1, F11 | Open the guide, full screen (desktop app) |
| Ctrl + N, Ctrl + O | New program, open a .py file (desktop app) |
| Ctrl + Shift + S | Save 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).