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

UniBase (constructor) UniBase(const char* robotName = "UNI Robot", UniBoardVersion board = UNI_BOARD_AUTO)
▼

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, in begin().
  • board (optional): Board version, UNI_BOARD_V1 or UNI_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");
begin void begin(const char* robotName = nullptr)
▼

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. Type const char*. Pass nullptr to use the library default.

Example

#include <UNI.h>

UniBase robot;
UniDev module;

void setup() {
  robot.begin("MY_BOT");
}

void loop() {
  
}

Motor Control

motors void motors(int powerLeft, int powerRight)
▼

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);
motorLeft void motorLeft(int power)
▼

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);
motorRight void motorRight(int power)
▼

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);
motorsArc void motorsArc(int power, float angle)
▼

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);
motorsSync void motorsSync(int powerLeft, int powerRight)
▼

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);
motorsSpeed void motorsSpeed(float leftMMperSec, float rightMMperSec)
▼

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);
holdPosition void holdPosition()
▼

Actively holds the current wheel position using PID. The robot resists being pushed. Cancelled by stop() or any movement command.

Example

robot.holdPosition();
stop void stop(int stopType = HARD)
▼

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) or HARD (1).

Example

robot.stop(HARD); // Instant stop
stopLeft void stopLeft(int stopType = HARD)
▼

Stops the left motor only.

Parameters

  • stopType: SOFT (0) or HARD (1).

Example

robot.stopLeft(SOFT); // Coast left motor to stop
stopRight void stopRight(int stopType = HARD)
▼

Stops the right motor only.

Parameters

  • stopType: SOFT (0) or HARD (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.

moveDist bool moveDist(int power, int millimeters)
▼

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);
moveTime bool moveTime(int power, int milliseconds)
▼

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);
moveArcDist bool moveArcDist(int power, int angle, int millimeters)
▼

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);
moveArcTime bool moveArcTime(int power, int angle, int milliseconds)
▼

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);
rotate bool rotate(int power, int angle)
▼

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);
rotateTo bool rotateTo(int power, float angleDeg)
▼

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
moveTo bool moveTo(int power, float x, float y)
▼

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
moveArcRadius bool moveArcRadius(int power, float radiusMM, float angleDeg)
▼

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.

moveDistAsync void moveDistAsync(int power, int millimeters)
▼

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();
moveTimeAsync void moveTimeAsync(int power, int milliseconds)
▼

Async version of moveTime().

Parameters

  • power: Speed (0-100).
  • milliseconds: Duration in ms.

Example

robot.moveTimeAsync(100, 2000);
robot.waitMove();
moveArcDistAsync void moveArcDistAsync(int power, int angle, int millimeters)
▼

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);
moveArcTimeAsync void moveArcTimeAsync(int power, int angle, int milliseconds)
▼

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);
moveArcRadiusAsync void moveArcRadiusAsync(int power, float radiusMM, float angleDeg)
▼

Async version of moveArcRadius().

Parameters

  • power: Speed (0-100).
  • radiusMM: Arc radius in mm.
  • angleDeg: Arc angle.

Example

robot.moveArcRadiusAsync(60, 300, -90);
rotateAsync void rotateAsync(int power, int angle)
▼

Async version of rotate().

Parameters

  • power: Speed (0-100).
  • angle: Degrees. Positive = Right (clockwise), Negative = Left.

Example

robot.rotateAsync(60, 90);
rotateToAsync void rotateToAsync(int power, float angleDeg)
▼

Async version of rotateTo().

Parameters

  • power: Speed (0-100).
  • angleDeg: Target absolute heading in degrees.

Example

robot.rotateToAsync(50, 90);
moveToAsync void moveToAsync(int power, float x, float y)
▼

Async version of moveTo().

Parameters

  • power: Speed (0-100).
  • x, y: Target position in mm.

Example

robot.moveToAsync(50, 400, 400);
isMoving bool isMoving()
▼

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
waitMove bool waitMove(unsigned long timeoutMs = 0)
▼

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.

getOdometry OdometryData getOdometry()
▼

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);
getAbsX float getAbsX()
▼

Returns the absolute X coordinate in millimeters.

Example

float currentX = robot.getAbsX();
Serial.println(currentX);
getAbsY float getAbsY()
▼

Returns the absolute Y coordinate in millimeters.

Example

float currentY = robot.getAbsY();
Serial.println(currentY);
getAbsAngle float getAbsAngle()
▼

Returns the absolute heading angle in degrees.

Example

float currentAngle = robot.getAbsAngle();
Serial.println(currentAngle);
resetDistance void resetDistance()
▼

Resets the accumulated distance counter to 0. Used for relative measurements.

Example

robot.resetDistance();
// Now getDistance() will start from 0
getDistance float getDistance()
▼

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);
resetAngle void resetAngle()
▼

Resets the accumulated angle counter to 0.

Example

robot.resetAngle();
getAngle float getAngle()
▼

Returns the angle turned since the last reset in degrees.

Example

float currentAngle = robot.getAngle();
Serial.println(currentAngle);
setPosition void setPosition(float x, float y, float angleDeg)
▼

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);
getLeftTicks / getRightTicks long getLeftTicks() / long getRightTicks()
▼

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);
printOdometry void printOdometry()
▼

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.

speedToPower int speedToPower(float mmPerSec)
▼

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);
turnRateToPower int turnRateToPower(float degPerSec)
▼

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);
getSpeed float getSpeed()
▼

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());
getTurnRate float getTurnRate()
▼

Returns the measured turn rate in degrees per second.

Example

robot.rotateAsync(60, 360);
delay(500);
robot.displayPrint("deg/s", robot.getTurnRate());

Display

displayPrint (Simple) void displayPrint(ValueType value)
▼

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);
displayPrint (Named) void displayPrint(const char* name, ValueType value)
▼

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");
displayText void displayText(const char* text)
▼

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");
displayClear void displayClear()
▼

Removes your text and brings back the status screen.

Example

robot.displayClear();

Utility

getBatteryPower int getBatteryPower()
▼

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");
}
getBatteryVoltage float getBatteryVoltage()
▼

Returns the battery voltage in volts, smoothed. Returns 0 if it could not be measured.

Example

robot.displayPrint("Volts", robot.getBatteryVoltage());
blinkLED void blinkLED(int interval)
▼

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);
UniBaseControl void UniBaseControl()
▼

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
}