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.ROS_DOMAIN_ID. Give each robot on the same network a different value.
Ctrl+C.
1.1. Launch arguments
The default launch runs the complete robot in mapping mode. To enable or disable components, add arguments in the formargument:=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.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.- Web interface
- Terminal
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.
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.~/.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.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 withCtrl+C and leave the root shell with exit.
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
$$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
/etc/default/ugv file. The commands used to manage the service are:
/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.7. Multiple Robots
Apply the same installation steps on each board; only theROS_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.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.
Trying the interface without hardware
Trying the interface without hardware
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.
