06Singularity Hub
From Singularity to a real robot
Everything you practised in Singularity has a real twin: real sensors, real motors, real ROS 2. This page shows how the pieces line up, so the day you build a robot, nothing feels new. Take it slowly; real hardware rewards patience.
Every sensor has a real twin
| In Singularity | A real part | Talks to the computer by | ROS 2 driver |
|---|---|---|---|
| LiDAR (/scan) | RPLIDAR A1/A2, LD06/LD19, YDLIDAR X4 | USB serial | rplidar_ros, ldlidar driver, ydlidar_ros2_driver |
| Ultrasonic (/sonar/…) | HC-SR04, JSN-SR04T (waterproof) | two digital pins (trigger, echo) | usually read by an Arduino and sent on |
| Camera (/camera/image_raw) | Raspberry Pi Camera Module, USB webcam | CSI ribbon or USB | camera_ros, v4l2_camera, usb_cam |
| IR line sensors (/line_sensors) | TCRT5000 modules, Pololu QTR array | analog or digital pins | read by an Arduino |
| IMU (/imu) | MPU-6050, BNO055, BNO085 | I²C (two wires: SDA, SCL) | imu drivers for each chip |
| Wheel encoders (/wheel_ticks, /odom) | Gear motors with Hall encoders (N20, JGB37-520) | two pins per wheel, counted with interrupts | your motor controller node, or ros2_control |
| GPS (/gps) | u-blox NEO-M8N outdoors (meters); RTK for centimeters; UWB beacons indoors | serial | nmea_navsat_driver |
| Bumper (/bumper) | Micro switch behind a bumper bar | one digital pin | read by an Arduino |
| LED, headlights | WS2812 LED strip, white LEDs with a transistor | one pin (data or PWM) | your own small node |
| Motors (/cmd_vel) | DC gear motors + a driver board (TB6612FNG, L298N, Cytron MDD10A) | PWM and direction pins | your motor node, or ros2_control diff_drive_controller |
Two ways to build it
| Way 1: Arduino robot | Way 2: ROS 2 robot | |
|---|---|---|
| Brain | An Arduino (Uno, Nano) or ESP32 | A Raspberry Pi 4/5 or NVIDIA Jetson, often with an Arduino/ESP32 helper for motors |
| Language | Arduino C++ | Python (the same rclpy code you wrote here) or C++ |
| Good for | Line followers, obstacle avoiders, first robots | LiDAR, cameras, SLAM, navigation: everything on hub pages 02–04 |
| From Singularity, use | The simple robot.… lessons: the ideas move straight across | The ROS 2 lessons and programs: the code moves almost unchanged |
Way 1: an Arduino robot
On an Arduino there is no robot object; you write small functions that do the same jobs. The ideas, the if/else decisions and the numbers you tuned in Singularity stay the same.
| Singularity | On an Arduino |
|---|---|
robot.front_distance() | Send a 10 µs pulse on the HC-SR04 trigger pin, time the echo with pulseIn(), distance = time × 0.000343 ÷ 2 (meters) |
robot.forward(0.3) | Set both motor driver direction pins forward and analogWrite() a speed (0–255) to the PWM pins |
robot.line_sensors() | analogRead() on each IR sensor and scale to 0–1 |
robot.wait(0.5) | delay(500), or better, millis() timing so the robot keeps checking its sensors |
robot.bumped() | digitalRead() on the switch pin (with INPUT_PULLUP) |
// HC-SR04 on pins 9 (trigger) and 10 (echo).
// Motor driver with one PWM and one direction pin per motor (for example Cytron MDD10A).
// L298N and TB6612FNG use two direction pins per motor (and TB6612 needs STBY high): adapt drive().
const int TRIG = 9, ECHO = 10;
const int L_PWM = 5, L_DIR = 4, R_PWM = 6, R_DIR = 7;
float frontDistance() { // meters, like robot.front_distance()
digitalWrite(TRIG, LOW); delayMicroseconds(2);
digitalWrite(TRIG, HIGH); delayMicroseconds(10);
digitalWrite(TRIG, LOW);
long us = pulseIn(ECHO, HIGH, 30000); // wait up to 30 ms for the echo
if (us == 0) return 2.0; // nothing heard: say "far", like Singularity
return us * 0.000343 / 2.0; // speed of sound, there and back
}
void drive(int left, int right) { // -255 .. 255, like robot.set_wheels()
digitalWrite(L_DIR, left >= 0); analogWrite(L_PWM, abs(left));
digitalWrite(R_DIR, right >= 0); analogWrite(R_PWM, abs(right));
}
void setup() {
pinMode(TRIG, OUTPUT); pinMode(ECHO, INPUT);
pinMode(L_DIR, OUTPUT); pinMode(R_DIR, OUTPUT);
}
void loop() {
if (frontDistance() < 0.4) drive(-120, 120); // too close: turn on the spot
else drive(150, 150); // clear: forward
delay(50);
}Way 2: a ROS 2 robot
- The computer. A Raspberry Pi 4 or 5 (4 GB or more) with Ubuntu 24.04 and ROS 2 Jazzy, or Ubuntu 22.04 and ROS 2 Humble. Follow the official ROS 2 install guide for your version.
- The motors. A small node (or an Arduino/ESP32 with micro-ROS or a serial link) that listens to
/cmd_vel, turns it into left and right wheel speeds, and publishes/odomfrom the encoders. The maths is the same as Singularity’s: left = v − ω·L/2, right = v + ω·L/2, where L is the distance between the wheels. - The sensors. Install the driver for each sensor (table above). Check each one alone with
ros2 topic echoandros2 topic hz, exactly as on hub page 02. - Drive by hand.
ros2 run teleop_twist_keyboard teleop_twist_keyboardis the real version of W A S D. - Map. Run
slam_toolboxand drive around. Look at the map in RViz (the real Map window). Save it withros2 run nav2_map_server map_saver_cli -f my_map: on a real robot, saving is built in. - Navigate. Use Nav2 (the standard navigation stack: costmaps, planners like A*, path followers like pure pursuit, recovery behaviours) with your saved map, or run your own A* program from page 03 on
/map,/goal_poseand/cmd_vel.
A safe plan, step by step
- Write and test the behaviour in Singularity first, with the noise turned up.
- Build the robot. Put it on a box, wheels in the air.
- Test each sensor alone and print its numbers. Compare with Singularity: same units? same direction (is 0° really forward)?
- Test the motors alone, slowly: does a positive speed go forward? does a positive turn go left?
- Put it on the floor. Drive it by hand.
- Run your program at half speed. Then full speed.
What is different in real life
| Thing | In Singularity | In real life |
|---|---|---|
| Noise | small and steady | bigger, and sometimes wild readings. Filter them (median of the last few) and ignore impossible values |
| Timing | perfectly regular, in lock-step | messages arrive late or bunched. Use the time stamps; do not assume 10 Hz |
| Wheels | slip a little | slip more on smooth floors, and motors are never equal: one side is always faster |
| Battery | never runs out | as it drains, the same command gives less speed. Use the encoders to control speed |
| Position | robot.true_pose() is always there | there is no truth. You only have odometry, IMU, SLAM and your judgment |
| Stopping | instant when the program ends | make sure your code sends a stop (zero /cmd_vel) when it exits, and keep a power switch in reach |
Moving your code across
- ROS 2 programs (with
rclpy, topics and messages) move almost unchanged. If a driver uses a different topic name (for example/ultrasonic/front), change the string, or remap it when you start the node. - Things only a simulator has:
/ground_truth,robot.true_pose(), and the Map window’s buttons. Remove them, or replace them with what a real robot has. - Simple
robot.programs need a small class of your own on the real robot that does the same jobs with topics:forward()publishes a Twist,front_distance()returns the latest Range, and so on. Writing that class is a great exercise: it shows you exactly what Singularity does for you. - Units and directions are the ROS standard in both places (meters, seconds, radians; x forward, y left), so your numbers keep their meaning.
Safety first
- Start with the wheels off the ground, and at low speed.
- Keep a switch that cuts motor power where your hand can reach it.
- Lithium batteries (LiPo, Li-ion) need the right charger and must never be punctured or over-drained.
- LiDARs are eye-safe (Class 1) but do not stare into one; keep fingers away from spinning parts.
- Never leave a powered robot alone with children or pets.
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).