UGV02

I2C, UART
TTL Serial Bus Servo Control Interface

Introduction

UGV02 is a six-wheel, four-wheel-drive mobile robot chassis with exceptional off-road capability and shock resistance. All code is open-source, facilitating secondary development. It supports expansion with various host computers (Raspberry Pi, Jetson Nano, Horizon Sunrise X3, etc.), which communicate with the ESP32 slave via UART.

Built-in 3S 18650 lithium battery UPS power module (three 18650 lithium batteries in series) provides a continuous power source for the robot while also allowing battery charging. The integrated multifunctional robot driver board supports expansion for bus servos, PWM servos, TF card, etc. The driver board is based on ESP32 and features onboard Wi-Fi and Bluetooth.

It uses soft rubber tires that greatly reduce impact from rough terrain, and is equipped with two 1020 European standard profile extension rails, easily meeting requirements for heavy loads, shock absorption, and off-road use, offering more possibilities for secondary development.

Features

Equipped with 203mm-spacing 1020 aluminum profile extension rails (including boat nuts and screws) for flexible expansion of various peripherals;

Uses soft rubber tires to significantly reduce impact from complex terrain;

Six-wheel, four-wheel-drive design provides excellent climbing ability;

Equipped with a 0.96inch OLED display for interaction;

Includes a charging interface and automatic download circuit, allowing use while charging;

UPS power module features an onboard INA219 acquisition chip for real-time monitoring of battery voltage and charging current;

The UPS power module uses three 18650 batteries in series with a large 7800mAh capacity, providing higher output current and stronger motor power;

The UPS power module also provides 5V and 3.3V outputs for expanding other devices;

The UPS power module has a built-in lithium battery protection circuit with overcharge, over-discharge, overcurrent, and short-circuit protection;

The demo is developed using Arduino IDE, no manual compilation environment configuration needed; the ESP32 automatically creates a Wi-Fi hotspot on startup, allowing control via a mobile phone (Android/iOS) or computer (Linux/Windows/Mac) by connecting and logging into the control page. Only a Chromium-based browser is required, no app installation needed;

The slave ESP32 can drive DC motors and bus servos, with onboard OLED interface, TF card slot, 9-axis IMU module, Wi-Fi, and Bluetooth, so it can be used independently even without a host computer;

Supports expansion with various host computers, using UART to transmit JSON-formatted data for control;

All code is open-source and comes with extensive development documentation and tutorials;

Open-source expansion flat drawings and chassis structure drawings, including 3D models, for easy secondary development;

JSON commands can be issued via serial port, USB, HTTP, ESP-NOW, etc.;

Most configuration settings can be achieved via JSON commands, e.g., configuring Wi-Fi connection without a USB cable.

Product Firmware Update

If the OLED screen displays "UGV Rover Version:0.96" when the robot is powered on, the driver program is already up-to-date and no update is needed;

If the OLED screen does not display "UGV Rover Version:0.96", the driver program is still the old version and should be updated using this section; this section can also be used to restore factory settings.

We provide an ESP32 download tool for the UGV02. With this tool, users can quickly update the firmware or restore the factory program.

1. First, connect the robot to your computer using a USB cable. (This step requires opening the robot to access the USB interface in the middle of the driver board).

2. Download the ESP32 download tool for UGV02: UGV02 ESP32 download tool. Unzip it and double-click to run "flash_download_tool_3.9.5.exe". After opening, two windows will pop up, we need to operate the UI interface of the download tool, and the other window will act as a terminal to show the working status of the download tool.

3. In the "DOWNLOAD TOOL MODE" interface, select ChipType as ESP32 and WorkMode as Factory. When using Factory, the binary file will be called using a relative path, so the user does not need to manually input the binary file path. After selecting, click OK.

4. In this software interface, keep the "LockSettings" checkbox selected, with the right side indicating that programs can be uploaded to 8 UGV02 units simultaneously. Click "COM", and select the new COM (the new COM here is COM3); BAUD is used to set the download speed, the higher the value, the faster the speed, and it can be up to 921600 for ESP32.

5. After selection, click "START" to start uploading the program. Once the upload is complete, "IDLE WAIT" will change to "FINISH COMPLETE". After completion, you can disconnect the USB connection between the driver board and the computer, turn on the switch of the robot product, and control the robot after powering on.

Product Basic Usage

Precautions Before Use (MUST READ!!)

Please read the following before use:

The product does not come with lithium batteries installed; customers must install three 18650 lithium batteries themselves for normal operation. International customers need to purchase three 18650 lithium batteries separately. It is recommended to use 18650 lithium batteries with a capacity of 2200mAh or higher and a discharge rate of 4C.
When connecting the battery for the first time, check if the LED on the battery module lights up. If it lights, the battery polarity is reversed; if not reversed, the LED will not light. Check and ensure the battery is not reversed. Charging is forbidden if the battery is reversed, as it may cause an explosion.
This product must not be subjected to violent impacts, and is not waterproof or sandproof.

Battery Installation

1. First, remove the four black metal cup head hex socket screws M3*6 from the chassis as shown in the red circles below.

2. Then insert the three 18650 lithium batteries into the battery module (Note: the battery module has positive and negative markings; if the LED on the module lights up, the polarity is reversed; it should not light if connected correctly).

3. After insertion, secure the chassis cover using the four black metal cup head hex socket screws M3*6 previously removed.

4. After installing the batteries, for first-time use, you need to insert the included 12.6V 2A charger into the robot's charging port to activate the UPS power module; only then will the robot have power output.

First Time Use

For first-time use, first insert the supplied 12.6V 2A charger into the robot's power port. After turning on the power switch, the robot will initialize and the OLED screen will display a series of initialization information.

After power-on, the content shown on the OLED screen means:
- The first line indicates that the Wi-Fi is in AP mode; the robot creates a hotspot named UGV.
- The second line indicates STA mode is off. When Wi- Fi is in STA mode, the router assigns an IP address to the robot, which is displayed here.
- The third line indicates the model name for the six-wheel four-wheel-drive series is UGV Rover.
- The fourth line: U represents the robot's power supply voltage; s 20, where s indicates a robot type setting; the first digit 2 indicates the robot's main type is UGV Rover (1 represents RaspRover, 3 represents UGV Beast); the second digit 0 indicates no expansion module (1 indicates the expansion module is the RoArm-M2 series robotic arm, 2 indicates the expansion module is Camera PT).
After booting up, use your phone or computer to connect to the robot's Wi-Fi: UGV, the password is 12345678. After connecting to Wi-Fi, open Google Chrome and enter 192.168.4.1 in the URL bar to open the web interface. You can now use the Web buttons to control the robot or send JSON commands via the Web interface.

Lower Computer Web Usage

The web interface displays real-time information such as the robot's voltage (VOLTAGE), Wi-Fi signal strength (RSSI) in STA mode, IP address, and MAC address.

Direction buttons control the robot's movement; the SLOW, MIDDLE, and FAST buttons below set the movement speed.

Other buttons function when external expansion modules are attached. For example, when a camera pan-tilt is attached, UP, LEFT, RIGHT, and DOWN control the pan-tilt rotation; IO4, IO5, and OFF control LED switches.

In the FEEDBACK INFORMATION window, you can send JSON commands to the robot. Below the input box are specific JSON commands; detailed explanations of JSON commands are available in the JSON Command Set.

The Web interface includes a "heartbeat detection" feature. After opening the interface, the Web app maintains continuous communication with the robot. If the connection is interrupted during movement, the robot will automatically stop within a short time for safety.

This web application is completely open-source. You can modify its interface and functionality by editing the WebPage.h file in the open-source example.

JSON Usage Tutorial

What is JSON?

JSON (JavaScript Object Notation) is a lightweight data interchange format commonly used for transmitting and storing data between different systems. JSON originated from JavaScript but has become a language-independent data format, so it can be used and parsed in various programming languages.

Below is an example of a JSON-formatted command for controlling the left and right wheel speeds of the robot:

{"T":1,"L":0.5,"R":0.5}

Explanation of this command:

"T" represents the command type, defined in the lower-level program's header file `json_cmd.h`. 1 corresponds to CMD_SPEED_CTRL (used to control left and right wheel speeds).

We will detail the usage and precautions of each command in the following JSON Command Set. Once you have a basic understanding of each function, you can refer to the JSON command set to improve secondary development efficiency.

Why Use JSON Commands to Interact with the Robot?

Given the abundant onboard resources of the robot's driver board, rich example functionalities, and the need to conveniently support upper computers for more extensive and flexible control, we use JSON command communication for interaction. Similarly, you can perform secondary development based on this existing framework to tailor the robot's functions to your specific needs.

Communication Methods Supporting JSON Commands

The robot supports multiple methods for JSON command interaction. Wired methods include serial communication via the RX/TX pins or USB serial communication via the Type-C interface. Wireless methods include communication via HTTP requests or ESP-NOW. You can use the examples below to send corresponding JSON commands using different methods to control various robot functions.

The robot has a built-in heartbeat function: if no new movement control command is received within 3 seconds, the robot will automatically stop. Therefore, when controlling the robot via an upper computer, you need to periodically repeat movement commands to keep it moving continuously.

1. Serial/USB Communication

Features: Wired connection, default baud rate @115200, bidirectional communication, stable, low latency;

Use: Convenient for controlling the robot with host computers such as PC, Raspberry Pi, Jetson Orin Nano, etc.;

Connection Methods:

Connect the robot's 40PIN UART interface to a Raspberry Pi, Jetson Nano, Jetson Orin Nano.
Connect the lower driver board's USB interface to the upper computer using a USB cable (requires disassembling the robot).

Python demo: Serial_simple_ctrl.zip. The specific example content is as follows:

import serial
import argparse
import threading

def read_serial():
    while True:
        data = ser.readline().decode('utf-8')
        if data:
            print(f"Received: {data}", end='')

def main():
    global ser
    parser = argparse.ArgumentParser(description='Serial JSON Communication')
    parser.add_argument('port', type=str, help='Serial port name (e.g., COM1 or /dev/ttyUSB0)')

    args = parser.parse_args()

    ser = serial.Serial(args.port, baudrate=115200, dsrdtr=None)
    ser.setRTS(False)
    ser.setDTR(False)

    serial_recv_thread = threading.Thread(target=read_serial)
    serial_recv_thread.daemon = True
    serial_recv_thread.start()

    try:
        while True:
            command = input("")
            ser.write(command.encode() + b'\n')
    except KeyboardInterrupt:
        pass
    finally:
        ser.close()


if __name__ == "__main__":
    main()

Use the following command to run the serial communication program, and be sure to add the port number to which the robot is connected. Replace `COM20` with the new serial port device name assigned to the robot on your PC. If using a Raspberry Pi, Jetson Orin Nano, etc., change to the corresponding port name.

python serial_simple_ctrl.py COM20

After running, you can send JSON format commands and receive robot feedback in this interface to communicate with the robot.

2. HTTP Request Communication

HTTP (Hypertext Transfer Protocol) is a protocol used for data communication on the Web.

Features: Wireless communication based on the Wi-Fi module, using a request-response model, is flexible and simple.

Python demo: Download the HTTP request communication demo http_simple_ctrl.py. The specific content is as follows:

import requests
import argparse


def main():
    parser = argparse.ArgumentParser(description='Http JSON Communication')
    parser.add_argument('ip', type=str, help='IP address: 192.168.10.104')

    args = parser.parse_args()

    ip_addr = args.ip

    try:
        while True:
            command = input("input your json cmd: ")
            url = "http://" + ip_addr + "/js?json=" + command
            response = requests.get(url)
            content = response.text
            print(content)
    except KeyboardInterrupt:
        pass


if __name__ == "__main__":
    main()

Before running, you need to confirm the robot's IP address, which depends on its Wi-Fi mode.

If the robot's Wi-Fi is only in AP mode, the IP address is `192.168.4.1`.
If the robot's Wi-Fi is in STA mode, you can obtain its IP address from the `ST` line on the OLED screen.

Use the following command to run the HTTP request communication program. Replace the IP address in the command with your robot's IP address.

python http_simple_ctrl.py 192.168.4.1

Note: Regardless of the mode, the robot and the device running this script must be on the same local network.

3. ESP-NOW Communication

You can control the robot's driver board to send commands to other driver boards via ESP-NOW, which features connectionless, low latency, and supports unicast, multicast, and broadcast.
For testing, the product's default ESP-NOW mode on startup is set to receive ESP-NOW commands. If you do not want the product to be controlled by other devices via this method, you can use the command {"T":301,"mode":0} to disable ESP-NOW reception, and later use {"T":301,"mode":3} to restore it.
If you need the product to automatically disable ESP-NOW command reception on every boot, you can write the command to the boot.mission file. For example, add {"T":301,"mode":0} to boot.mission using: {"T":222,"name":"boot","step":"{\"T\":301,\"mode\":0}"}. To cancel this setting later, you can delete the boot.mission file (it will be recreated on next boot) with: {"T":203,"name":"boot.mission"}.

ESP-NOW Preparation

In the following ESP-NOW tutorials, the receiving end's ability to receive JSON commands assumes that ESP-NOW command reception is enabled (which is the default for new products).
The hardware involved in the following functions are ESP32 devices running our slave program, such as the General Driver for Robots or ROS Driver for Robots.

Unicast Control

Unicast is a point-to-point control method, allowing one device to control another.

You need the MAC address of the device to be controlled, usually displayed on the OLED screen.
Send a JSON command to the controlling device to add the target MAC address as a peer, for example: {"T":303,"mac":"CC:DB:A7:5C:1C:40"}, replacing the mac value with the slave's MAC address.
To remove a MAC address from the peer list, use {"T":304,"mac":"CC:DB:A7:5C:1C:40"}.
To send a JSON command to the slave: {"T":306,"mac":"CC:DB:A7:5C:1C:40","dev":0,"b":0,"s":0,"e":0,"h":0,"cmd":1,"megs":"{"T":114,"led":255}"}
Replace the JSON command inside megs with other commands, and replace mac with the slave's MAC address; do not modify the other values, as they are used for other functions.

Broadcast Control

Broadcast is a one-to-many control method, allowing one device to control multiple devices simultaneously.

You do not need the MAC addresses of the slaves. This mode sends commands to all devices within range. The method is the same as unicast, except replace the mac value with the broadcast address: "FF:FF:FF:FF:FF:FF"
Send a JSON command to the controlling device to add the broadcast address as a peer: {"T":303,"mac":"FF:FF:FF:FF:FF:FF"}
To remove the mac address from the peer list, use {"T":304,"mac":"FF:FF:FF:FF:FF:FF"}.
Broadcast a JSON command: {"T":306,"mac":"FF:FF:FF:FF:FF:FF","dev":0,"b":0,"s":0,"e":0,"h":0,"cmd":1,"megs":"{"T":114,"led":255}"}
Replace the JSON command inside megs with other commands; do not modify the other values.

Multicast Control

Multicast is also one-to-many, but it allows selecting specific devices to control, as opposed to broadcast which sends to all.

You need the MAC address of the device to be controlled, usually displayed on the OLED screen.
Using the method described in this tutorial, users send JSON commands to the controller to add the MAC address of the controlled device to the peer. For example: {"T":303,"mac":"CC:DB:A7:5C:1C:40"}, {"T":304,"mac":"CC:DB:A7:5C:E5:FC"}. You need to replace the value of "mac" with your controlled device's MAC address. You can add multiple MAC addresses for controlled devices, but it is recommended not to exceed 20.
Do not add the broadcast address "FF:FF:FF:FF:FF:FF".
To remove the mac address from the peer list, use {"T":304,"mac":"FF:FF:FF:FF:FF:FF"}.
Send a multicast JSON command: {"T":305,"dev":0,"b":0,"s":0,"e":1.57,"h":1.57,"cmd":1,"megs":"{"T":114,"led":255}"}
Replace the JSON command inside megs with other commands; do not modify the other values.

4. Issuing JSON Commands via Web Application

After power-on, connect your phone or computer to the robot's Wi-Fi: UGV, password 12345678. Open Google Chrome and enter 192.168.4.1 in the address bar to access the web interface.
In the FEEDBACK INFORMATION window, you can send JSON commands to the robot. Below the input box are specific JSON commands; for detailed explanations, refer to the JSON Command Set below.

JSON Command Set

Chassis Movement

Left/Right Wheel Speed Control - CMD_SPEED_CTRL

{"T":1,"L":0.5,"R":0.5}

L is left wheel speed, R is right wheel speed. Speed range: -0.5 to +0.5, positive for forward, negative for backward.
This product model is UGV02, equipped with encoders; the speed unit is m/s (closed-loop speed control).
It is recommended to use this command for controlling the product.

Left/Right Motor PWM Control - CMD_PWM_INPUT

{"T":11,"L":164,"R":164}

L is left motor PWM value, R is right motor PWM value. PWM range: -255 to +255, positive for forward, negative for backward.
Because DC geared motors have poor low-speed characteristics, the motor may not rotate when the absolute PWM value is too small.
This command is for debugging only; use CMD_SPEED_CTRL for controlling the product's movement.

ROS Control - CMD_ROS_CTRL

{"T":13,"X":0.1,"Z":0.3}

X is linear velocity in m/s, Z is angular velocity in rad/s.
Note: This command is only applicable to UGV01 and UGV02 (with encoders).

Set Motor PID

{"T":2,"P":200,"I":2500,"D":0,"L":255}

P, I, D are proportional, integral, derivative coefficients respectively. L is the Windup Limits reserved parameter. The default PID controller used in UGV01 does not use this parameter; we reserved it for users who want to replace with other PID controllers.
Note: This command is not applicable to the encoder-less WAVE ROVER.

OLED Screen Settings

OLED Screen Control

{"T":3,"lineNum":0,"Text":"putYourTextHere"}

Sets the content displayed on the OLED screen. The lineNum parameter specifies the line, and can be 0, 1, 2, or 3, for up to 4 lines. Each command sets one line; new content does not affect other lines but replaces the existing content of that line.
The Text parameter is used to set the content; you can enter text here, and it will be displayed on the corresponding line.
When this command is used, the OLED screen will no longer display robot information, but will instead show the content directed by the command.

Restore OLED Screen

{"T":-3}

When the command type is -3, the OLED screen resets to its initial state, displaying the robot's information.

Get Product Information

Get IMU Data

{"T":126}

Retrieves IMU information including heading angle, magnetic field, acceleration, attitude, temperature, etc.

Get Chassis Information Feedback - CMD_BASE_FEEDBACK

{"T":130}

Continuous Serial Feedback

// Disable (default)
{"T":131,"cmd":0}
// Enable
{"T":131,"cmd":1}

When disabled, chassis information is obtained via a question-and-answer method using commands like CMD_BASE_FEEDBACK.
When enabled, the chassis continuously sends feedback information without needing host commands. Suitable for ROS systems.

Serial Echo Switch

// Disable (default)
{"T":143,"cmd":0}
// Enable
{"T":143,"cmd":1}

When enabled, all commands sent to the slave will appear in the serial feedback.

Serial Echo Switch

// Disable (default)
{"T":143,"cmd":0}
// Enable
{"T":143,"cmd":1}

When enabled, all commands sent to the slave will appear in the serial feedback.

IO4 IO5 Control

{"T":132,"IO4":255,"IO5":255}

Sets the PWM for IO4 and IO5.

External Module Expansion

Set External Module Type

{"T":4,"cmd":0}

0. Null - 1: RoArm-M2 Robotic Arm - 3: Gimbal pan-tilt

Basic Gimbal Control

{"T":133,"X":45,"Y":45,"SPD":0,"ACC":0}

If a gimbal is installed, this command controls it. X is horizontal angle (positive left, negative right); Y is vertical angle (positive up, negative down).

Robotic Arm JSON Command Control

If a robotic arm is installed, refer to RoArm-M2-S_JSON Command Meaning to control it.

Product Hardware Introduction

Slave Driver Board Onboard Interfaces

Motor Parameters

Model: JGB37-520 DC Geared Motor
No-load current: ≤120mA
Rated voltage: 12V
Rated current: ≤1A
Stall current: 2.3A
Rated torque: 3.5kg.cm
Stall torque: 5.0kg.cm
No-load speed: 333RPM
Rated speed: 250RPM
Reduction ratio: 1:30
Motor dimensions: 33*55mm
Output shaft dimensions:6*15.5mm

Host Computer Usage Tutorial

Raspberry Pi Host

This section uses Raspberry Pi 5 and Raspberry Pi 4B for testing.

Connect a USB camera to the Raspberry Pi's USB port; we recommend the IMX335 5MP USB Camera (B).
Mount the Raspberry Pi onto the chassis.
Create an image and download the host program into the Raspberry Pi.
- ugv_rpi Download Link
cd ugv_rpi/
Add execute permission to the installation script: sudo chmod +x setup.sh
Add execute permission to the the autorun script: sudo chmod +x autorun.sh
International users: sudo ./setup.sh
Domestic users in China: sudo ./setup.sh -i
After installation completes, configure autorun: ./autorun.sh (do not use sudo for this command)
Configure Wi-Fi related features (auto-switch to hotspot when no network): cd ugv_rpi/AccessPopup/
Install AccessPopup, add execute permission to the installation script: sudo chmod +x installconfig.sh
Run the installation script: sudo ./installconfig.sh
Enter 1 to install AccessPopup, then press any key to exit; enter 9 and press Enter to exit the installation script.
After restarting the device, the Raspberry Pi will automatically run the product's host program.

Resources

Open Source Demo

UGV02 Slave Open Source Demo (ESP32)

UGV02 GitHub repository for UGV02 Slave Demo

Robot Dimension Drawings and Expansion Platform Drawings

Robot Model

UGV02 3D model

FAQ

Question: 1. What batteries does UGV02 use?

Answer:

Support three 18650 batteries (not included) and the voltage of every battery is 3.7V. Generally, the voltage per battery is 4.2V when fully charged. Please use batteries without a protective plate.
BTW, the Power of UGV02 is down when the voltage of the whole system is similar to 9V (it is not accurate), we recommend you charge batteries if the voltage displayed is lower than 10V.
We recommend you use high-quality batteries like Sanyo or Panasonic.

{{{5}}}

Question: 2. When disassembling the chassis, I noticed that only the front two motors light up, while the rear two motors do not. Is this normal?

Answer:

A: Yes, it is normal. The rear motor LEDs do not light because the encoder data for those motors is not read. The slave driver board's motor interfaces drive the wheels on both sides, but only reads encoder data from the front wheels.

Question: 3. After re-uploading the program, I cannot connect to Wi-Fi due to password errors or other connection issues. How can I resolve this?

Answer:

A: After re-flashing the program, send the command {"T":604} via serial to clear the NVS area, then turn off the power and turn it back on. Forget the Wi-Fi and reconnect.

Question: 4. When using the download tool or Arduino IDE to upload a program to the robot's general driver board, no new COM port appears. Why?

Answer:

A: First, refer to the Slave Driver Board Onboard Interfaces section to confirm that you are plugging into USB interface ⑥. Then check if a new COM port appears in the computer's Device Manager. If not, look under "Other devices" for an unrecognized device with "CP2102" in its name (as shown). If found, the driver is not installed; install the CP2102 serial driver. If there is no unrecognized device with CP2102 in the name in other devices part, please contact the store's customer service to return it to the factory for repair.

Question: 5. Does the 40Pin expansion interface on the robot's slave driver board provide any other usable GPIO pins?

Answer:

A: No, only UART and I2C interfaces are exposed on the 40Pin header.

Support

Technical Support

If you need technical support or have any feedback/review, please click the Submit Now button to submit a ticket, Our support team will check and reply to you within 1 to 2 working days. Please be patient as we make every effort to help you to resolve the issue.
Working Time: 9 AM - 6 PM GMT+8 (Monday to Friday)

Submit Now