> ## Documentation Index
> Fetch the complete documentation index at: https://docs.t3gemstone.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> A differential-drive ground robot based on T3 Gemstone O1, running ROS 2 Jazzy

![Battery and cables of the UGV robot](https://mintcdn.com/t3gemstone-754bcb96/ob7PTI-_45ZCj-OZ/images/ugv-ros/ugv-rear.png?fit=max\&auto=format\&n=ob7PTI-_45ZCj-OZ\&q=85\&s=ea47231da8a4971d495cdbc6388e186a)

Battery and cable layout

![Line sensor and motor driver of the UGV robot](https://mintcdn.com/t3gemstone-754bcb96/ob7PTI-_45ZCj-OZ/images/ugv-ros/ugv-front.png?fit=max\&auto=format\&n=ob7PTI-_45ZCj-OZ\&q=85\&s=f3d981c06056ce94b91f1b35cd5d8e3a)

Line sensor and motor driver

> [!TIP]
>
> By the end of this section, you will understand the following topics.
>
> * Setting up a ground robot on T3 Gemstone O1 with **Ubuntu 24.04** and **ROS 2 Jazzy**
> * Wiring the motors, encoders, IMU, line sensor and lidar
> * Driving the robot from the web interface, following a line and mapping the environment with a lidar
> * Navigating autonomously to a goal on a saved map with Nav2

## 1. Introduction

UGV ROS is a differential-drive ground robot based on T3 Gemstone O1. The robot runs **Ubuntu 24.04 and ROS 2 Jazzy**.
It can follow a line, map its surroundings with a lidar and, when Nav2 is enabled, drive to a selected goal on a saved
map.

* **Manual driving** uses the keyboard, the on-screen arrow buttons or a gamepad. Wheel speed is measured with
  encoders, and odometry is fused with the IMU on the board.
* **Line following** uses an eight-channel analog sensor read through a Deneyap Mini v2. White and black surface
  measurements are recorded from the web interface.
* **Mapping and navigation** use an RPLIDAR A1. Maps can be saved, and when Nav2 is enabled a goal can be selected on
  the map.

The source code of the project is available in the [t3gemstone/ugv-ros](https://github.com/t3gemstone/ugv-ros)
repository.

## 2. Components

| Component | Role |
| - | - |
| **T3 Gemstone O1** | Main computer. ROS 2 nodes, web interface, onboard ICM-20948 IMU |
| **L298N** motor driver | Drives the direction and speed (PWM) of the two motors |
| 2 × **Waveshare DCGM-3865** | 12 V, 1:42 gear ratio, 240 rpm DC motors with hall encoders |
| **Deneyap Mini v2** | Reads the eight analog channels of the line sensor and sends them to T3 Gemstone O1 over UART |
| Pololu QTR-8A line sensor | 8-channel analog, black/white surface detection |
| **RPLIDAR A1** | 360° lidar; mapping, localization and obstacle detection |
| 3S Li-Po (11.1 V, 4200 mAh) | Power supply for the motors and the board |

All pin connections are listed on the [Hardware and Wiring](https://docs.t3gemstone.org/en/projects/ugv-ros/hardware.md) page.

## 3. Web Interface

The **UGV Control** interface running on the robot is opened from a browser on a computer connected to
the same network. ROS does not need to be installed on the computer.

![Map, robot pose, driving, sensor calibration and lidar panels on the UGV Control screen](https://mintcdn.com/t3gemstone-754bcb96/ob7PTI-_45ZCj-OZ/images/ugv-ros/ugv-web-ui.png?fit=max\&auto=format\&n=ob7PTI-_45ZCj-OZ\&q=85\&s=0bbba1ceaa90d073b9a7ac762edcab9d)

The UGV Control screen with a map imported from a recorded lidar scan and sample sensor values.

| Panel | Function |
| - | - |
| **Mode** and **Drive** | Select **Idle**, **Manual** or **Line follow** mode. In manual driving use the on-screen buttons, WASD or the arrow keys, or a gamepad. Adjust the linear and turning speed. |
| **Map** | Watch the map built by SLAM and the robot's pose. Save the map with the **Save map** panel. When Nav2 is enabled, set a goal on the map with the **Click → goal** option. |
| **Status** and **Line sensor calibration** | Monitor the speed, obstacle distance and line sensor readings. Calibrate the Deneyap serial sensor on white and black surfaces. |
| **Lidar** | Select **USB** or **GPIO (UART)** according to your wiring and check the scan rate. |

To stop driving, use the **EMERGENCY STOP** button or the **Space** key.

## 4. Getting Started

**1. Install the operating system and the UGV software**

Write the Ubuntu 24.04 image to T3 Gemstone O1, install ROS 2 Jazzy and the dependencies, and build the workspace.
Then upload the line sensor firmware to the Deneyap Mini v2 and enable the PWM/UART overlays.
[Installation](https://docs.t3gemstone.org/en/projects/ugv-ros/installation.md)

**2. Connect the hardware**

With the power off, complete the motor, encoder, line sensor and lidar connections.
[Hardware and Wiring](https://docs.t3gemstone.org/en/projects/ugv-ros/hardware.md)

**3. Read the safety rules**

Read the battery and operating safety rules before the first drive.
[Battery and Operating Safety](https://docs.t3gemstone.org/en/projects/ugv-ros/safety.md)

**4. Run the field test**

With the wheels off the ground, verify the motor directions, encoders, IMU and lidar step by step.
[Field Test](https://docs.t3gemstone.org/en/projects/ugv-ros/field-test.md)

**5. Start and use the robot**

Start the robot, open the web interface, calibrate the line sensor and build a map.
[Usage](https://docs.t3gemstone.org/en/projects/ugv-ros/usage.md)

## 5. Technical References

> [card] [Architecture](https://docs.t3gemstone.org/en/projects/ugv-ros/architecture.md)
>
> ROS 2 packages, topics, services and driving modes

> [card] [Simulation](https://docs.t3gemstone.org/en/projects/ugv-ros/simulation.md)
>
> Mapping, navigation and line following in Gazebo, without the robot

> [card] [Network Connection](https://docs.t3gemstone.org/en/projects/ugv-ros/network.md)
>
> Connecting the robot to a new Wi-Fi network and finding its IP address

> [card] [PWM](https://docs.t3gemstone.org/en/boards/o1/peripherals/pwm.md)
>
> T3 Gemstone O1 PWM channels and overlay configuration

> [card] [IMU](https://docs.t3gemstone.org/en/boards/o1/peripherals/imu.md)
>
> The onboard ICM-20948 sensor


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.