05Singularity Hub
The robot library
Every Singularity program starts with a ready-made object called robot. You do not need to import it. This page lists everything it can do: what you give it, what it gives back, and the units. Keep it open in a tab while you program.
Also ready without importing: PID (a controller, explained below), math and SensorOffError. Anything else you import as usual: import numpy as np, import random, and so on. If you prefer, from singularity import robot, PID also works.
Moving
A motion command keeps going until you give a new one. Commands that do a whole job (move, turn, wait) finish before the next line runs.
robot.forward(speed=0.3)- Drive forward. speed in m/s (top speed 0.6 by default).
robot.forward(0.2) robot.backward(speed=0.3)- Drive backward.
robot.turn_left(speed=1.0)- Spin left on the spot. speed in rad/s (1 rad/s ≈ 57°/s).
robot.turn_right(speed=1.0)- Spin right on the spot.
robot.drive(linear, angular)- Both at once: linear in m/s (+ forward), angular in rad/s (+ left). This is exactly a ROS Twist.
robot.drive(0.2, 0.5) # a curve to the left robot.set_wheels(left, right)- Each wheel’s speed in m/s. Equal = straight; different = curve; opposite = spin.
robot.set_wheels(0.2, 0.3) robot.stop()- Stop both wheels.
robot.wait(seconds)- Let time pass while the last command keeps going. time.sleep() does the same.
robot.forward(0.3); robot.wait(2) # about 0.6 m robot.move(distance, speed=0.25)- Drive an exact distance in meters (negative = backward), using the wheel encoders, then stop.
robot.move(0.5) robot.turn(degrees, speed=1.2)- Turn by an exact angle (+ = left), using the IMU, then stop. speed is the top turn rate in rad/s.
robot.turn(-90) # right turn
Distance sensors
robot.front_distance()→ meters- Front ultrasonic. Also back_distance(), left_distance(), right_distance(), front_left_distance(), front_right_distance(). 2.0 = nothing in range.
robot.distance(direction="front")→ meters- The same, by name: "front", "front_left", "front_right", "left", "right", "back".
robot.lidar()→ list of meters- 360 LiDAR distances. Index 0 = forward, counter-clockwise. inf = nothing in range (3.5 m).
robot.lidar_distance(angle=0)→ meters- LiDAR distance at an angle in degrees: 0 ahead, 90 left, −90 right, 180 behind.
robot.scan()→ LaserScan- The whole scan as a ROS sensor_msgs/LaserScan message.
Camera
robot.camera()→ NumPy array or None- The latest picture, shape (height, width, 3), RGB values 0–255, row 0 at the top. The first call switches the camera on and returns None: wait and ask again.
robot.find_color(color="red", image=None, min_pixels=12)→ dict or None- Find a color: "red", "orange", "yellow", "green", "cyan", "blue", "purple", "pink", "black", "white", or a hue range like (100, 140). Returns x (−1 left … +1 right), y (−1 top … +1 bottom), size, width, height (0–1) and pixels.
ball = robot.find_color("red") if ball: robot.drive(0.2, -ball["x"]) robot.pan_camera(degrees=0)- Turn the camera head: 0 ahead, + left, − right, up to ±150°. About 120°/s.
robot.tilt_camera(degrees_down=40)- Tilt the camera: 0 level, + down (up to 70°), − up (up to −25°).
robot.camera_pan(), robot.camera_tilt()→ degrees- Where the camera points right now.
robot.headlights(on=True)- Headlights: True/False or a brightness 0–1.
Line sensors
robot.line_sensors()→ list of 0–1- IR values from left to right. 0 = light floor, 1 = black tape.
robot.line_position()→ −1 … +1 or None- Where the line is under the robot: −1 far left, 0 middle, +1 far right. None = no sensor sees it.
IMU, encoders and position
robot.heading()→ degrees- Which way the robot faces, −180 to 180 (0 = +x, 90 = +y).
robot.yaw()→ radians- The same heading in radians, −π to π.
robot.gyro()→ degrees per second- How fast it is turning (+ = left).
robot.imu()→ Imu- The full ROS sensor_msgs/Imu message.
robot.encoders()→ (left, right) ticks- Wheel encoder counts since Run.
robot.ticks_per_rev()→ ticks- Ticks per wheel turn (360 by default).
robot.odometry()→ (x, y, theta)- Position from the wheels, in meters and radians. Drifts slowly.
robot.position()→ (x, y)- GPS position in meters, with a little noise.
robot.slam_pose()→ (x, y, theta) or None- Where SLAM thinks the robot is. None while SLAM is off.
robot.map_explored()→ 0.0 – 1.0 or None- How much of the floor the SLAM map has seen. None while SLAM is off.
robot.true_pose()→ (x, y, theta)- The exact pose. Simulator only: great for checking your work, not for driving.
robot.bumped()→ True / False- True while the robot touches something.
robot.time()→ seconds- World time since you pressed Run.
robot.is_on(sensor)→ True / False- Is a sensor switched on? "lidar", "camera", "imu", "encoders", "gps", "bumper", "line", "sonar", or a mount like "front".
LED, headlights, plots and sliders
robot.led(color="green")- LED color by name ("red", "orange", "yellow", "green", "cyan", "blue", "purple", "pink", "white", "off"), or robot.led(r, g, b) with 0–255 or 0–1. It keeps the color until you change it, press Run again, or Reset.
print(...)- Write to the Terminal.
robot.plot(name, value)- Add a point to the live Plot window. Call it every loop with the same name to draw a line.
robot.plot("front", robot.front_distance()) robot.slider(name, value=1.0, min=0.0, max=None, step=None)→ number- A live slider in the Tune tab. Returns its current value, so read it inside your loop.
kp = robot.slider("Kp", 1.0, 0, 5)
The PID helper
A PID controller turns an error (how far you are from what you want) into a correction. P pushes harder the bigger the error. I slowly adds up errors that stay. D brakes when the error changes fast, so you do not overshoot. You will meet it in the Heading PID and Wall Follower lessons.
PID(kp=1.0, ki=0.0, kd=0.0, setpoint=0.0, output_limits=(None, None), integral_limit=None)→ PID- Make a controller.
pid.compute(error)→ number- Give it the error, get the correction. It measures the time between calls for you.
pid.update(measurement)→ number- Or give it the measurement; it uses error = setpoint − measurement.
pid.reset(), pid.tune(kp=…, ki=…, kd=…)- Start fresh, or change the gains while running.
pid = PID(kp=0.04, kd=0.01, output_limits=(-1.5, 1.5))
while True:
error = 90 - robot.heading()
error = (error + 180) % 360 - 180 # take the short way round
robot.drive(0.2, pid.compute(error))
robot.wait(0.05)Angle helpers
from tf_transformations import euler_from_quaternion→ (roll, pitch, yaw)- Turn a ROS orientation (quaternion) into angles in radians. Pass the orientation itself.
yaw = euler_from_quaternion(msg.pose.pose.orientation)[2] from tf_transformations import quaternion_from_euler→ (x, y, z, w)- The other way round.
math.radians(deg), math.degrees(rad)→ number- Change degrees to radians and back.
Which Python, which libraries
- Python 3.12, built into Singularity. Nothing to install.
- Ready to import:
numpy,math,random,statistics,heapq,collections,itertools,functools,json,re,copy,string,time. - ROS-style imports:
rclpy,rospy, and the messages ingeometry_msgs,sensor_msgs,nav_msgs,std_msgs, plustf_transformations. - Not in version 1.0: OpenCV, SciPy and other large packages, files on your disk, and the internet. OpenCV and SciPy are planned.
Messages you might see
SensorOffError: The front ultrasonic sensor is off…- You read a sensor that is switched off in the Robot tab. Switch it on, or use the other sensor the message suggests.
A value was None…- A sensor had no data yet, most often the camera on its first call. Check for None and try again a moment later.
This loop ran for 5 seconds without letting the robot move…- A long loop inside __init__, a lambda or a generator. Move it into a normal function, a timer or a callback.
This code tried to wait … in a place that cannot wait- robot.wait, sleep or spin inside __init__ or a lambda. Same fix.
Your program did not answer Stop, so the simulator was restarted- Nothing is lost: your code is kept. It happens when a program is busy in a place that cannot be interrupted.
Unknown color 'redd'. Try: red, green, …- A spelling slip in robot.led(...). The message lists the names it knows.
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).