Skip to main content
The commands on this page assume that gemstone was chosen as the user name in Gem Imager. If you chose a different user name, replace /home/gemstone with your own home directory.

1. Starting the Robot

The robot software runs with root privileges for GPIO and PWM access. Switch to a root shell on T3 Gemstone O1.
Load the ROS environment and the libgpiod v2 Python path.
Set the robot’s ROS_DOMAIN_ID. Give each robot on the same network a different value.
Start the robot. To stop it, press Ctrl+C.
If the automatic startup service is installed, stop it with sudo systemctl stop ugv before starting the robot manually. Do not start a second ros2 launch while the service is running.

1.1. Launch arguments

The default launch runs the complete robot in mapping mode. To enable or disable components, add arguments in the form argument:=value to the end of the command. For example, to start without the line sensor:

2. Connecting to the Web Interface

1

Find the robot's IP address

Find the robot’s IP address on the local network in the T3 Gemstone O1 terminal.
2

Open the interface

Open a browser on a computer connected to the same network and go to http://<robot-ip>:8000. For example, if the robot’s IP address is 192.168.1.42, the address is http://192.168.1.42:8000.
3

Check the connection

When the connection indicator at the top right turns green, the interface is ready. If the indicator stays red, enter T3 Gemstone O1’s IP address in the robot address field and click Connect. The page uses port 8000 and the ROS connection uses port 9090.
If the connection problem persists, follow the checks on the Network Connection page. For a description of the panels in the interface, refer to the Overview page.
To stop driving, use the EMERGENCY STOP button or the Space key.

3. Line Sensor Calibration

For line following, each channel’s threshold is set to the midpoint between the white and black readings. Without calibration, no channel detects the line. Calibration is done while the robot is running and in Idle mode.
1

Start the calibration

In the Line sensor calibration panel, click Start calibration. The robot is switched to Idle mode; keyboard, gamepad, on-screen driving and map goals are blocked in this tab until the process is complete.
2

Measure the white surface

Hold the sensor steady at its working height, place a white surface under all eight sensors and click White ready — measure. Keep it steady for about 1.2 seconds after clicking.
3

Measure the black surface and save

Without changing the height, place a matte black surface and click Black ready — measure and save. Keep it steady for about 1.2 seconds after clicking.
The panel shows the last saved white/black values, thresholds and per-channel margin in mV; narrow margins below 200 mV are highlighted. If a new measurement fails or the process is closed, the previous record is kept. The saved settings are loaded automatically at every startup; repeat the calibration when the sensor height, surface or lighting changes.
This panel is only available with the Deneyap Mini v2 connection (type: serial). With the qtr_rc or digital types, or when the sensor is disabled, the panel is inactive.
The calibration result is written to the ~/.ugv/line_calibration.json file on the robot. Since the robot runs as root, the file is in the /root/.ugv/ directory. The file is replaced atomically only after a successful black measurement. After calibration is complete, try Line follow mode from the interface.

4. Mapping and Navigation

4.1. Creating a map

Mapping is enabled by default. Start the robot with the default arguments, drive it slowly in Manual mode from the interface, and when the map is complete, save it with a name from the Save map panel. The map is written to the ~/ugv_maps/<name>.{pgm,yaml,posegraph,data} files; since the robot runs as root, the directory is /root/ugv_maps.

4.2. Navigating to a goal on a saved map

Place the robot at the point where you started mapping, facing the same direction. Then start the robot in localization mode with the map path without extension and Nav2 enabled.
Enable the Click → goal option in the interface and click on the map; the robot switches to NAV mode and drives to the goal. Pressing any driving key along the way switches the robot to manual mode and stops it.

5. Starting Automatically at Boot

A systemd service is defined so that the robot starts automatically at every boot. If a manually started session is running, first stop it with Ctrl+C and leave the root shell with exit.
sudo bash ~/ugv-ros/scripts/install-service.sh 1 performs the three steps below in one command; the argument is the robot’s ROS_DOMAIN_ID. The service it installs starts the robot through scripts/start-native.sh, which reads the same /etc/default/ugv file.
1

Create the robot settings file

The robot settings are kept in the /etc/default/ugv file. Set ROS_DOMAIN_ID according to the robot’s number.
2

Create the service file

systemd passes the $$UGV_ARGS expression to bash as $UGV_ARGS; this way the arguments in the /etc/default/ugv file are appended to the launch command.
3

Enable the service

Give each robot on the same network a different ROS_DOMAIN_ID. The ROS nodes of two robots with the same number see each other, and a driving command sent from one robot’s interface also drives the other robot. Since the interface is opened from each robot’s own IP address, this number does not affect the interface.
Restart the service after changing the /etc/default/ugv file. The commands used to manage the service are:
Since the service runs as root, saved maps are under /root/ugv_maps, the lidar selection under /root/.ugv/lidar_source, and ROS logs under /var/log/ugv.

6. Updating

Pull the latest changes from the repository and rebuild the workspace.
If the update adds a new dependency, install the dependencies before building.

7. Multiple Robots

Apply the same installation steps on each board; only the ROS_DOMAIN_ID value in the /etc/default/ugv file must be different (e.g. 1 and 2). Also change the hostnames so that the boards can be told apart on the network.

8. Running with Docker

The robot can also run inside a container on a Linux system with Docker and Docker Compose installed. In the repository directory, build the image, start the robot and follow the logs with the commands below.
The container runs in privileged mode on the host network so that it can access GPIO, SPI, PWM and serial ports. Saved maps are stored in ~/ugv_maps and the settings selected in the interface in the ~/.ugv directory.
To try the interface without the robot hardware, build the image and run the command below. backend:=mock simulates the motors and encoders. Then open http://localhost:8000 in a browser.