Library Limitations
This page documents the boundaries of the UNI library: things worth knowing in advance so the robot's behavior never comes as a surprise. Most of these are deliberate trade-offs rather than bugs, and each one comes with a recommended way to work with it.
Movement and Commands
Only one movement command runs at a time
There is no command queue: a new movement command silently cancels the current one. The code
moveDistAsync(50, 500); rotateAsync(50, 90); will only perform the rotation —
the distance move is aborted right after it starts.
How to work with it: wait for completion between async commands using
waitMove(), or use the blocking versions (moveDist,
rotate) which wait on their own.
Minimum speed
In movement commands power sets the speed, and the robot holds it with the encoders, so even
a small power drives slowly. The approach to the target never goes below a minimum speed — about 12 mm/s
on a straight and 8 mm/s per wheel in a turn — so that the wheels do not stall right before the target.
How to work with it: motors() sends the power straight to the motors: below
about 15 % they cannot overcome static friction and the wheels stand still. For slow, steady driving use
motorsSync() or motorsSpeed().
Speed is a percentage of the maximum
The power parameter is the speed as a percentage of the maximum wheel speed: power 100 is
about 0.3 m/s. The robot holds this speed with the encoders and allows for the battery charge, so a
command takes about the same time on a fresh and on a half-drained battery. On a nearly flat battery the
top speed may be out of reach — the robot then drives as fast as the motors allow and still stops at the
target.
How to work with it: for a speed in physical units use motorsSpeed() (mm/s)
or convert with speedToPower() and turnRateToPower(); getSpeed()
shows the measured speed.
A stuck command ends with false
If the wheels stop turning for about 0.8 s (the robot is pushed against a wall, the wheels are blocked),
the command ends early. If the robot has not reached its target within about three times the estimated
time, the safety timeout ends it. In both cases the robot brakes, and a blocking call returns
false.
How to work with it: check the result where getting stuck is likely:
if (!robot.moveDist(50, 500)) { ... }. For async commands use
waitMove(timeout): a false return means the robot did not arrive in time.
Arc limitations
moveArcRadius()requires a radius of at least half the track width (about 53 mm). For turning in place userotate().- In
moveArcDist()/moveArcTime()/motorsArc(), ananglewith |angle| > 90 makes the inner wheel spin backwards — the path is still an arc, but behavior is less predictable.
Accuracy and Odometry
Physical accuracy depends on the wheels and the floor
Odometry turns encoder ticks into millimetres and degrees with the geometry of the standard UniBase platform built into the library: wheel diameter 45 mm, track 107 mm. Turns are physically accurate as far as the real track matches it, distances as far as the real wheel diameter does.
Rule of thumb: if odometry reads exactly the target (getAngle() = 90
after rotate(50, 90)) but the robot physically turned more or less, the program did its part:
look at the wheels (dirt, wear, slipping) and at the floor.
Odometry accumulates drift
Position is computed from wheel encoders only: wheel slip, floor bumps and collisions are
invisible to odometry. There is no gyroscope or external correction.
moveTo() and setPosition() work well over routes of a few meters,
but the error grows with mileage and aggressive maneuvers.
How to work with it: on long routes, periodically "re-ground" the pose
against an external reference (wall, line) and call setPosition() with known
coordinates.
Finishing a move: one brake, no reverse correction
Before the target the robot brakes with a lead for its coasting distance and waits for a full stop. It does not back up or nudge the wheels afterwards, so the end of a move stays clean. By odometry the residual is usually a few tenths of a millimetre on a straight and 0.2–0.3° on a turn. The braking lead adapts after every stop, so the first 3–5 moves after power-on are a little less exact.
How to work with it: the residual is not lost: the next command measures its target from
the previous command's target, so residuals do not add up over a sequence of moves. The chain is broken by
motors(), motorsSync(), a stop() in mid-move,
setPosition() and by moving the robot more than 5°.
moveTo: steering to the point
moveTo() turns toward the target, then drives straight while steering onto the point by
odometry. 40 mm before the target the heading is frozen (right next to the point its bearing changes
abruptly), so the lateral residual is whatever was left uncorrected before that.
How to work with it: on legs shorter than about 10 cm the steering has little time to act — accuracy there is set by the initial turn.
Coordinate system and resets
- The X axis points forward from the robot's starting pose, Y points sideways, and a positive angle is a turn to the right.
resetDistance()andresetAngle()reset only the trip counters for distance and angle — they do not touch the X/Y pose.- To anchor odometry to the field (or reset everything at once), use
setPosition(x, y, angle).
Behavior and Blocking
Blocking calls
Some functions halt program execution:
stop(HARD)— until the robot stands still, usually 50–300 ms;waitButton()— waits forever for a press;ultraSonic()— up to ~70 ms when no echo returns (3 attempts);- all light ring effects (
pixelsRainbowetc.) — block for the entireduration.
How to work with it: in a loop that watches sensors while driving, avoid
long effects; for lighting during movement use the basic
pixel()/pixelsAll() calls.
Lazy initialization
Calling begin() is optional — the first command initializes the robot
automatically. The consequence: a sketch that never calls any robot method will
not bring up the display or odometry.
How to work with it: if the robot should "just stand there showing the
screen" — call robot.begin() explicitly in setup().
The API is designed for setup() and loop()
The library itself uses the second ESP32 core for odometry and control loops, and API calls are synchronized assuming a single user core. Calling robot methods from your own FreeRTOS tasks is unsupported and may cause race conditions.
Peripherals
Display
displayPrint()strings — 15 characters maximum, longer ones are truncated.- The screen refreshes ~10 times per second: values changing faster are partially skipped — this is normal.
Servos
- At most 12 servos at once (16 ESP32 PWM channels minus 4 for the motors).
- A PWM channel is bound to a port on first use and is not reused for another port
(though
servoDetach()does not consume channels). - Pulses are fixed: 0.5–2.5 ms at 50 Hz. Servos with non-standard calibration cannot be adjusted.
- Horn speed is not controlled — the servo moves to the angle at full speed. Smooth motion is achieved with a series of small angle steps and delays.
Ultrasonic sensor
The working range of ultraSonic() is 20–4000 mm. A return value of
0 means "no echo": the target is too close, too far, or does not reflect
sound.
Important: always check for zero separately, otherwise the condition
dist < threshold falsely triggers as "obstacle right here":
int dist = module.ultraSonic(P6, P7);
if (dist > 0 && dist < 150) {
robot.stop(HARD); // the obstacle really is close
}
No analog input on some ports
On board V1, ports P5, P6 and P8 (GPIO 17, 16 and 23) have no analog input; on board V2 every port has one. When an analog read is attempted on a port without it, the library prints a warning to Serial.
How to work with it: on board V1 use P1–P4 (ADC2) or
P7 (ADC1) for the line sensor and other analog sensors. Digital sensors
(digitalSensor()) work on any port.
Wi-Fi note: ADC2 is unavailable while Wi-Fi is active. The library itself does not use Wi-Fi; if you add Wi-Fi to your sketch, the analog inputs left are P7 on board V1 and P1–P2 on board V2 (ADC1).