FAQ & Troubleshooting
Short answers to what most often goes wrong. If your case is not here, look at Limitations: it describes how the library behaves at the edges of what it can do.
Installing and uploading
Compilation error: "UNI.h: No such file or directory"
Possible Cause: The library is not installed or sits in the wrong folder. The same goes
for an error about UniBase.h.
Solution: Install UNI through the Library Manager. After a manual install make sure the
UNI folder is inside your Arduino/libraries directory, then restart the
Arduino IDE.
Compilation error: "Adafruit_SSD1306.h: No such file or directory"
Possible Cause: The dependencies are missing. This happens after installing from a ZIP archive.
Solution: Install three libraries through the Library Manager: Adafruit GFX Library, Adafruit SSD1306 and Adafruit NeoPixel.
Movement
Robot doesn't move but screen is on
Possible Cause: The battery switch is off, or the battery is low.
Solution: Check the physical switch on the UniBase. Make sure the battery icon on the screen shows a charge.
The robot drives or turns inaccurately
Possible Cause: The wheels slip on the floor, are dirty or worn, or the robot was pushed or bumped. Odometry counts wheel turns and cannot see slipping.
Solution: Check on the surface the robot will work on, with a charged battery: the wheels must be clean and must not slip. The wheel diameter (45 mm) and the track (107 mm) of the standard UniBase platform are built into the library, so there is nothing to set in the sketch.
If the screen shows exactly 300 mm or 90° but the floor says otherwise, the robot did what the program
asked: the difference comes from slipping or from wheels that differ from the standard platform.
For an exact heading after several manoeuvres use rotateTo(), for an exact position
moveTo().
Only the last of two commands runs
Possible Cause: There is no command queue: a new movement command cancels the current one.
Solution: Call waitMove() between async commands or use the blocking
versions — moveDist(), rotate(). See
Movement and Commands for details.
The robot will not drive below a certain speed
Possible Cause: motors() sends the power straight to the motors: below
about 15 % they cannot overcome friction and the wheels stand still.
Solution: For slow driving use motorsSync() or
motorsSpeed() — they hold the speed with the encoders. Movement commands such as
moveDist() work the same way: power is the speed as a percentage of the maximum,
so even a small power drives slowly.
Sensors, screen and link
The distance sensor returns 0
Possible Cause: No echo came back: the target is closer than 20 mm, further than 4 m, or does not reflect sound. Zero also appears when trig and echo are swapped.
Solution: Check the wiring with the DistanceSensors example. Always filter zero out in
conditions: dist > 0 && dist < 150.
The line sensor shows random numbers
Possible Cause: The sensor is on a port without an analog input — P5, P6 or P8. The library prints a warning to the Serial Monitor when that happens.
Solution: Move the sensor to P1–P4 or P7.
Text on the screen is cut off
Possible Cause: displayPrint() shows at most 15 characters.
Solution: Shorten the label. Long messages are easier to print to the Serial Monitor.
The screen stays dark
Possible Cause: The screen was not found at start-up — then the Serial Monitor
(115200 baud) shows SSD1306 allocation failed and the robot keeps working without a
screen. Or the sketch never calls a robot command, so initialisation never ran.
Solution: Check that the robot is switched on. Add robot.begin() to
setup().
UART commands are ignored
Possible Cause: Wiring issue or incorrect baud rate.
Solution:
- Ensure RX connects to TX, and TX connects to RX.
- Check that
robot.UniBaseControl()is called insetup()of the ESP32 sketch. - Verify GND is shared between boards.
- Do not connect modules to ports P5 and P6: they are the same pins that carry UART.
Debug Tips
- Use
robot.displayPrint("Debug Info")to show status on the screen when the Serial Monitor is unavailable. robot.printOdometry()prints the encoder ticks, the coordinates and the heading to the Serial Monitor. The port speed is 115200 baud.- With
DEBUG_MODEenabled inUniBase.h, the library prints start-up details (robot name, board version) to the Serial Monitor.