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 in setup() 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_MODE enabled in UniBase.h, the library prints start-up details (robot name, board version) to the Serial Monitor.