UniBase Reference
Core class for controlling the robot chassis, motors, and display.
Constants
Public constants available for control functions.
| Name | Value | Description |
|---|---|---|
SOFT |
0 | Used in stop() for a smooth slow-down along the speed profile; the call returns at once. |
HARD |
1 | Used in stop() for braking; the call returns once the robot stands still. |
Initialization
Creates the robot object. It is usually a global variable at the top of the sketch.
Parameters
robotName(optional): Name on the screen, up to 15 characters. It can also be set later, inbegin().board(optional): Board version,UNI_BOARD_V1orUNI_BOARD_V2. By default it is detected automatically, so the same sketch runs on both boards. A constructor with the board alone also exists:UniBase robot(UNI_BOARD_V2);
Example
#include <UNI.h>
UniBase robot("UNI");
Initializes all robot components (Motors, Encoders, OLED, Sensors). This function starts the
background tasks for odometry and motor control. It should be called once in
setup().
Parameters
robotName(optional): Name to display on the OLED splash screen. Typeconst char*. Passnullptrto use the library default.
Example
#include <UNI.h>
UniBase robot;
UniDev module;
void setup() {
robot.begin("MY_BOT");
}
void loop() {
}
Motor Control
Sets the power for both motors directly. Positive values match forward direction, negative match backward.
Parameters
powerLeft: Power for left motor (-100 to 100).powerRight: Power for right motor (-100 to 100).
Example
// Full speed forward
robot.motors(100, 100);
// Turn left in place
robot.motors(-50, 50);
Sets power for the left motor only.
Parameters
power: Motor power (-100 to 100).
Example
// Turn the left motor backward at half speed
robot.motorLeft(-50);
Sets power for the right motor only.
Parameters
power: Motor power (-100 to 100).
Example
// Turn the right motor forward at full speed
robot.motorRight(100);
Moves the robot along an arc with a specific turn intensity. This is a non-blocking control function.
Parameters
power: Base motor power (-100 to 100).angle: Turn sharpness (-90 to 90). Positive = Turn Right, Negative = Turn Left.
Example
// Drive forward while curving right
robot.motorsArc(80, 45);
Like motors() but with encoder-based synchronisation — maintains the set speed ratio between left and right wheels. Non-blocking; runs until stop() is called.
Parameters
powerLeft: Left wheel power (-100..100).powerRight: Right wheel power (-100..100).
Example
// Smooth arc with maintained speed ratio
robot.motorsSync(70, 40);
Same as motorsSync(), but the wheel speeds are given in millimetres per second. The robot holds them with the encoders. Non-blocking; runs until stop() is called.
Parameters
leftMMperSec,rightMMperSec: Wheel speeds in mm/s, negative backwards. The limit is the wheel speed at power 100 (about 300 mm/s).
Example
// Both wheels at 100 mm/s
robot.motorsSpeed(100, 100);
delay(2000);
robot.stop(SOFT);
Actively holds the current wheel position using PID. The robot resists being pushed. Cancelled by stop() or any movement command.
Example
robot.holdPosition();
Stops both motors. HARD brakes and waits until the robot stands still (usually 50–300 ms); SOFT slows down smoothly in the background and returns at once.
Parameters
stopType:SOFT(0) orHARD(1).
Example
robot.stop(HARD); // Instant stop
Stops the left motor only.
Parameters
stopType:SOFT(0) orHARD(1).
Example
robot.stopLeft(SOFT); // Coast left motor to stop
Stops the right motor only.
Parameters
stopType:SOFT(0) orHARD(1).
Example
robot.stopRight(HARD); // Brake right motor immediately
Movement (Blocking)
These functions block execution until the movement is complete. They use encoder feedback for
precision. Each returns true when the target is reached and false if the robot
got stuck, ran out of time or the command was interrupted.
Moves the robot specific distance using PID control on encoders.
Parameters
power: Motor power (-100 to 100).millimeters: Target distance.
Example
// Move forward 50cm at 80% power
robot.moveDist(80, 500);
Drives for a set time. The robot speeds up and slows down smoothly so that it stops when the time is up.
Parameters
power: Motor power (-100 to 100).milliseconds: Duration in ms.
Example
// Move forward for 2 seconds
robot.moveTime(100, 2000);
Moves along a curved path for a specific distance.
Parameters
power: Motor power (-100 to 100).angle: Steering angle (-90 to 90). Positive = right, negative = left.millimeters: Distance traveled along the arc.
Example
// Drive 1 meter in a wide right curve
robot.moveArcDist(60, 20, 1000);
Moves along a curved path for a specific duration.
Parameters
power: Motor power (-100 to 100).angle: Steering angle (-90 to 90). Positive = right, negative = left.milliseconds: Duration in ms.
Example
// Turn sharply right for 1.5 seconds
robot.moveArcTime(80, 60, 1500);
Rotates the robot in place by a specific angle.
Parameters
power: Speed (0-100)angle: Degrees. Positive = Right (clockwise), Negative = Left.
Example
// Turn 90 degrees right
robot.rotate(60, 90);
Rotates to an absolute odometry heading via the shortest path. Unlike rotate(), this corrects accumulated drift from previous manoeuvres.
Parameters
power: Speed (0-100).angleDeg: Target heading in degrees (odometry frame).
Example
robot.rotateTo(50, 90); // Face heading 90°
robot.rotateTo(50, 0); // Return to original heading
Drives to a target odometry coordinate: turns to face the target then moves in a straight line.
Parameters
power: Speed (0-100).x, y: Target position in mm (odometry frame).
Example
robot.setPosition(0, 0, 0);
robot.moveTo(50, 400, 0); // Forward 400 mm
robot.moveTo(50, 400, 400); // Then 400 mm to the right
Arc with precise geometry: specify the turning radius and arc angle.
Parameters
power: Speed (0-100).radiusMM: Arc radius at robot centre (mm).angleDeg: Arc angle; positive = right, negative = left.
Example
// 300 mm radius arc, 90° to the right
robot.moveArcRadius(60, 300, 90);
Async Movement
Commands with the Async suffix start movement and return immediately — the next line of code runs while the robot moves. Use isMoving() or waitMove() to synchronise.
Async version of moveDist().
Parameters
power: Speed (0-100).millimeters: Distance in mm.
Example
robot.moveDistAsync(80, 500);
module.pixelsAll(0, 255, 0); // Light green while moving
robot.waitMove();
Async version of moveTime().
Parameters
power: Speed (0-100).milliseconds: Duration in ms.
Example
robot.moveTimeAsync(100, 2000);
robot.waitMove();
Async version of moveArcDist().
Parameters
power: Speed (0-100).angle: Steering angle (-90..90). Positive = right, negative = left.millimeters: Arc distance in mm.
Example
robot.moveArcDistAsync(60, 30, 800);
Async version of moveArcTime().
Parameters
power: Speed (0-100).angle: Steering angle (-90..90). Positive = right, negative = left.milliseconds: Duration in ms.
Example
robot.moveArcTimeAsync(80, 60, 1500);
Async version of moveArcRadius().
Parameters
power: Speed (0-100).radiusMM: Arc radius in mm.angleDeg: Arc angle.
Example
robot.moveArcRadiusAsync(60, 300, -90);
Async version of rotate().
Parameters
power: Speed (0-100).angle: Degrees. Positive = Right (clockwise), Negative = Left.
Example
robot.rotateAsync(60, 90);
Async version of rotateTo().
Parameters
power: Speed (0-100).angleDeg: Target absolute heading in degrees.
Example
robot.rotateToAsync(50, 90);
Async version of moveTo().
Parameters
power: Speed (0-100).x, y: Target position in mm.
Example
robot.moveToAsync(50, 400, 400);
Returns true while an async movement task is active.
Example
robot.moveDistAsync(80, 500);
while (robot.isMoving()) {
module.pixelsAll(255, 100, 0); // Orange while moving
}
module.pixelsAll(0, 255, 0); // Green when done
Blocks until the current async movement command finishes. Returns true on clean completion, false if the timeout expired.
Parameters
timeoutMs(optional): Maximum wait time in ms.0= wait forever.
Example
robot.moveDistAsync(80, 500);
bool ok = robot.waitMove(3000); // Wait up to 3 s
if (!ok) robot.stop(HARD); // Force stop on timeout
Odometry
Functions for tracking the robot's position relative to its starting point.
Returns the current estimated position and orientation struct.
Returns
Struct OdometryData containing float x, float y, and
float angle.
Example
OdometryData odom = robot.getOdometry();
Serial.print("X: "); Serial.println(odom.x);
Serial.print("Y: "); Serial.println(odom.y);
Serial.print("Angle: "); Serial.println(odom.angle);
Returns the absolute X coordinate in millimeters.
Example
float currentX = robot.getAbsX();
Serial.println(currentX);
Returns the absolute Y coordinate in millimeters.
Example
float currentY = robot.getAbsY();
Serial.println(currentY);
Returns the absolute heading angle in degrees.
Example
float currentAngle = robot.getAbsAngle();
Serial.println(currentAngle);
Resets the accumulated distance counter to 0. Used for relative measurements.
Example
robot.resetDistance();
// Now getDistance() will start from 0
Returns the distance traveled since the last reset in millimeters.
Example
robot.resetDistance();
robot.motorsArc(50, 0);
while(robot.getDistance() < 1000) {
delay(10);
}
robot.stop(HARD);
Resets the accumulated angle counter to 0.
Example
robot.resetAngle();
Returns the angle turned since the last reset in degrees.
Example
float currentAngle = robot.getAngle();
Serial.println(currentAngle);
Sets the odometry pose. Use this to anchor the robot to field coordinates or reset position at a checkpoint.
Parameters
x, y: Starting coordinates in mm.angleDeg: Starting heading in degrees.
Example
// Robot is at the origin, facing along the X axis
robot.setPosition(0, 0, 0);
Returns the raw encoder tick count for the respective motor.
Example
long l = robot.getLeftTicks();
long r = robot.getRightTicks();
Serial.printf("L: %ld, R: %ld\n", l, r);
Prints the current X, Y, and Theta values to the Serial Monitor. Useful for debugging.
Example
void loop() {
robot.printOdometry(); // encL: 488 encR: 488 X: 100.00 Y: 0.00 Theta: 0.00
delay(500);
}
Speed
Power in movement commands is a percentage of the maximum wheel speed: power 100 is about 0.3 m/s. These functions convert between power and physical speed and report the measured speed.
Converts a speed in millimetres per second into a power value for movement commands.
Parameters
mmPerSec: Desired speed in mm/s.
Example
// Drive 500 mm at 150 mm/s
robot.moveDist(robot.speedToPower(150), 500);
Converts a turn rate in degrees per second into a power value for rotate() and rotateTo().
Parameters
degPerSec: Desired turn rate in degrees per second.
Example
// Turn 90 degrees at 120 degrees per second
robot.rotate(robot.turnRateToPower(120), 90);
Returns the measured speed of the robot centre in millimetres per second; negative when driving backwards.
Example
robot.moveDistAsync(80, 500);
delay(500);
robot.displayPrint("mm/s", robot.getSpeed());
Returns the measured turn rate in degrees per second.
Example
robot.rotateAsync(60, 360);
delay(500);
robot.displayPrint("deg/s", robot.getTurnRate());
Display
Clears the OLED screen and prints the provided value in the center. Supports multiple types.
Supported Types
Text (const char*), int, long, float,
double and bool. At most 15 characters fit on the screen.
Example
// Print text
robot.displayPrint("Hello!");
// Print a number
robot.displayPrint(123);
Prints a name label at the top of the screen and a large value in the center. Supports all simple types as the value.
Example
robot.displayPrint("Battery", 85);
robot.displayPrint("Mode", "Auto");
Shows multi-line text in a small font: up to 8 lines of 21 characters, lines separated by \n. Handy for debugging without the Serial Monitor. displayClear() brings back the status screen.
Parameters
text: The text; lines are separated by\n.
Example
robot.displayText("Line 1\nLine 2\nLine 3");
Removes your text and brings back the status screen.
Example
robot.displayClear();
Utility
Returns current battery level percentage (0-100). Returns -1 if offline or error.
Example
int power = robot.getBatteryPower();
if (power < 10) {
robot.displayPrint("LOW BATT");
}
Returns the battery voltage in volts, smoothed. Returns 0 if it could not be measured.
Example
robot.displayPrint("Volts", robot.getBatteryVoltage());
Sets the background task to blink the onboard LED.
interval: Time in ms. Set to 0 to stop blinking.
Example
// Blink twice per second
robot.blinkLED(500);
// Stop blinking
robot.blinkLED(0);
Starts listening for UART commands from an external controller (Arduino Nano). Call it
once in setup(): commands are then received and executed in the background,
and loop() stays free for your own code.
Example
void setup() {
robot.begin("UNI");
robot.UniBaseControl(); // start listening for commands
}
void loop() {
// free for your own logic
}