AntiprotonTechnologies

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.
hold a heading of 90° while driving
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 in geometry_msgs, sensor_msgs, nav_msgs, std_msgs, plus tf_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).