Preparing the Test Environment
The test commands run in a root shell for GPIO and PWM access. Follow the commands in the tab that matches your installation type.- Direct installation
- Docker
If the robot service is installed, stop it first and switch to a root shell.Load the ROS environment and the libgpiod v2 Python path, and assign the hardware file path to the When the tests are finished, leave the root shell with
HW variable.exit and start the service again.Some steps require a second terminal. Run the environment commands above again in every new terminal.
1. Preparation
- PWM overlays are enabled in
/boot/uEnv.txtand conflicting overlays are disabled (PWM and UART settings) - Encoders and line sensor are powered with 3.3 V (the “3.3V” bridge on the sensor is soldered), and the ENA/ENB jumpers on the L298N are removed
- Pins resolve and there are no conflicts
GPIOxx should resolve to a gpiochipN:line and every PWM channel to a pwmchipN. If you get a
“not found” error, find the line name on the board with gpioinfo | grep -i gpio and write that name or
the gpiochipN:line form into hardware.yaml.
2. IMU
- The “gyro bias” line appears at startup (the robot must be stationary at this time)
- While the robot is still,
z≈ 0 (±0.01 rad/s) - When the robot is rotated counterclockwise viewed from above,
zbecomes positive
If
z is negative, the board is mounted upside down. In that case set imu.roll: 3.14159 in
ugv_description/config/robot.yaml
(this is how it is in the kit). Since the correction is applied in the TF, the raw /imu/data_raw still appears
negative. Verify on the complete robot: while the robot turns left in place, angular.z on both /wheel/odom and
/odometry/filtered must be positive. If it is reversed, the map comes out mirrored.3. Motor Directions
left wheel first, then the
right wheel.
- The left wheel turns first, then the right wheel. If they turn in the reverse order, swap the
leftandrightblocks (together with their direction settings) inhardware.yaml; otherwise the robot drives forward but left/right turns are reversed - Each wheel turns in the direction that moves the robot forward. If not, apply the
invertfix suggested by the command - If a wheel does not turn at all, check the IN pins, the PWM channel, the EN jumper and the motor supply
4. Encoders
- When the wheel is turned one full revolution forward by hand, the count is positive and about 2184 (x4: 546 × 4)
- If the displayed
ppr≈value is very different from 546, the motor has a different gearbox; correctencoder.ppr - The
hata(error) counter stays at 0. If it increases at high duty values duringhw_check sweep, events are being missed; verify that thehw_check pinsoutput showslibgpiod python API: v2(the v1 event buffer is too small for this motor) - If the count direction is reversed, set
enc_invert: true(hw_check motorsalso suggests this)
5. Speed Range
pid.min_duty← the duty value at which the wheel starts turningmax_wheel_speed← the speed of the slower of the two wheels at 100% duty
6. Closed-Loop Driving
http://<gemstone-ip>:8000 in the computer’s browser, switch to Manual mode and drive the robot.
Watch the wheel speeds in a second terminal.
[target_left, measured_left, duty_left, target_right, measured_right, duty_right].
- The measured speeds settle on the target without oscillation. If there is oscillation, lower
pid.kp; if the speed stays below the target, increasepid.ki - The robot does not drift when driving straight (both wheels at the same speed)
- The emergency stop (Space key) cuts the motors immediately
7. Odometry Calibration
- Straight 1 m: Drive straight from the interface and compare the x value on
/wheel/odomwith a tape measure →wheel_radiusinrobot.yaml× (actual / measured) - 5 turns in place: Compare the
/wheel/odomangle with the actual angle →wheel_separation× (measured / actual) - After 5 turns, the EKF (
/odometry/filtered) yaw is closer to reality than the wheel odometry
8. Lidar
- The lidar head is spinning and the panel shows about 5–8 Hz (or
ros2 topic hz /scan) - USB: If the panel says “no lidar port”, the
ls /dev/serial/by-id/output may be empty; the CP210x driver is missing from the minimal image (lsmod | grep cp210x). CP210x driver - GPIO: If you get an “operation timeout” error, check that the TX/RX lines are crossed (lidar TX → pin 26),
that the
dmesgoutput contains the2b300000.serial: ttyS0line, and that theugv-bt-off,uart-ttys0andecap2overlays are enabled. If the problem persists, lowergpio.duty_percentto 75 (motor noise can corrupt the UART) - The lidar angle is correct. Place a box taller than the lidar height directly in front of the robot (on the line
sensor side, centered, 30–40 cm away), with no other objects within 1 m. If the box’s angle in
/scanisa, setrobot.yaml→lidar.yaw = -a(radians). In the kit the lidar is mounted rotated by 180°: the box appears at about ±180° andyaw≈ 3.14. If the angle is wrong, the map slides while driving and smears during turns - Lidar brake (on by default,
control.yaml→safety.enabled): the robot stops about 0.10 m before a box in front of it and does not slow down because of a wall it passes alongside
9. Line Sensor and Line Following
- Deneyap Mini v2 (default)
- Direct GPIO
While the robot is running with
line:=true, watch the raw readings.- D1 … D8 values (mV) are streaming. If not, check the Deneyap TX → pin 10 and RX → pin 8 connections, the common GND and that the firmware is uploaded; look for the “no data from the Deneyap” warning in the log
- The sensor is at 3–6 mm height and there is a difference of several hundred mV between white and black on every channel (if the difference is around 100 mV, the sensor is too high)
- Calibration completes successfully
- The start → white → black sequence works in the web panel; the robot stays in Idle and driving is blocked. The saved mV table is filled and persists after a restart
- Measuring the same surface twice gives an error and the previous record does not change. The process closes when the connection drops or the mode changes
- In the
ros2 topic echo /line/state --field sensorsoutput, all channels arefalseon white andtrueon black - When a black strip is moved under the sensor from left to right, the
truevalue moves from left to right. If it moves in the opposite direction, the A0…A7 wires are connected in reverse
- While the robot is running, the
positionvalue on the/line/statetopic is positive when the line is on the left - Try Line follow mode from the interface on the track. Start with
speed: 0.10, then tune thekp,kdandspeedvalues incontrol.yaml
10. Mapping
- While driving slowly from the interface, the map is built and walls do not appear doubled
- Save map creates the
~/ugv_maps/<name>.{pgm,yaml,posegraph,data}files
11. Navigating to a Goal on a Saved Map
Place the robot at the point where you started mapping, facing the same direction.- With the Click → goal option enabled in the interface, clicking on the map makes the robot drive to that point (mode: NAV)
- Pressing a driving key along the way switches the robot to manual mode and stops it

