AntiprotonTechnologies

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 SingularityA real partTalks to the computer byROS 2 driver
LiDAR (/scan)RPLIDAR A1/A2, LD06/LD19, YDLIDAR X4USB serialrplidar_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 webcamCSI ribbon or USBcamera_ros, v4l2_camera, usb_cam
IR line sensors (/line_sensors)TCRT5000 modules, Pololu QTR arrayanalog or digital pinsread by an Arduino
IMU (/imu)MPU-6050, BNO055, BNO085I²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 interruptsyour motor controller node, or ros2_control
GPS (/gps)u-blox NEO-M8N outdoors (meters); RTK for centimeters; UWB beacons indoorsserialnmea_navsat_driver
Bumper (/bumper)Micro switch behind a bumper barone digital pinread by an Arduino
LED, headlightsWS2812 LED strip, white LEDs with a transistorone pin (data or PWM)your own small node
Motors (/cmd_vel)DC gear motors + a driver board (TB6612FNG, L298N, Cytron MDD10A)PWM and direction pinsyour motor node, or ros2_control diff_drive_controller

Two ways to build it

Way 1: Arduino robotWay 2: ROS 2 robot
BrainAn Arduino (Uno, Nano) or ESP32A Raspberry Pi 4/5 or NVIDIA Jetson, often with an Arduino/ESP32 helper for motors
LanguageArduino C++Python (the same rclpy code you wrote here) or C++
Good forLine followers, obstacle avoiders, first robotsLiDAR, cameras, SLAM, navigation: everything on hub pages 02–04
From Singularity, useThe simple robot.… lessons: the ideas move straight acrossThe 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.

SingularityOn 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)
obstacle_stop.ino · a starting pointstandard wiring, check your own pins
// 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

  1. 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.
  2. 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 /odom from 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.
  3. The sensors. Install the driver for each sensor (table above). Check each one alone with ros2 topic echo and ros2 topic hz, exactly as on hub page 02.
  4. Drive by hand. ros2 run teleop_twist_keyboard teleop_twist_keyboard is the real version of W A S D.
  5. Map. Run slam_toolbox and drive around. Look at the map in RViz (the real Map window). Save it with ros2 run nav2_map_server map_saver_cli -f my_map: on a real robot, saving is built in.
  6. 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_pose and /cmd_vel.

A safe plan, step by step

  1. Write and test the behaviour in Singularity first, with the noise turned up.
  2. Build the robot. Put it on a box, wheels in the air.
  3. Test each sensor alone and print its numbers. Compare with Singularity: same units? same direction (is 0° really forward)?
  4. Test the motors alone, slowly: does a positive speed go forward? does a positive turn go left?
  5. Put it on the floor. Drive it by hand.
  6. Run your program at half speed. Then full speed.

What is different in real life

ThingIn SingularityIn real life
Noisesmall and steadybigger, and sometimes wild readings. Filter them (median of the last few) and ignore impossible values
Timingperfectly regular, in lock-stepmessages arrive late or bunched. Use the time stamps; do not assume 10 Hz
Wheelsslip a littleslip more on smooth floors, and motors are never equal: one side is always faster
Batterynever runs outas it drains, the same command gives less speed. Use the encoders to control speed
Positionrobot.true_pose() is always therethere is no truth. You only have odometry, IMU, SLAM and your judgment
Stoppinginstant when the program endsmake 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).