From Waveshare Wiki
Jump to: navigation, search

TTL Serial Bus Servo Control Interface





UGV01 boasts the mobile robot crawler chassis with superb off-road performance, shock absorbers, and open-source code that supports customization development. It supports external host computers (Raspberry Pi, Jetson Nano, Horizon Sunrise X3 Pi, etc.), and the host computer communicates with the ESP32 slave computer through the serial port. The motor with an encoder can obtain the speed feedback for speed closed-loop control.

The built-in UPS power supply module with 3S 18650 lithium battery (3x 18650 lithium batteries connected in series) provides uninterruptible power for the robot and supports charging and discharging at the same time. Also, with a built-in multi-functional robot driver board, it supports external serial bus servos, PWM servos, SD cards, and so on. The driver board is based on ESP32 with onboard WiFi and Bluetooth.

Boasting multi-suspension systems, it can enjoy smooth driving on tough terrains. Also, it comes with 2x 1020 European standard profile rails, which can easily meet the needs of heavy loads, shock absorption, and off-road performance, and provides more feasibility for customization development.


  • It adopts multi-independent suspension systems, which greatly reduces the impact of complex terrain.
  • It demonstrates super-strong performance in climbing. When climbing with a heavy load, the suspension shrinks, and the rear wheels will provide extra support.
  • The motor with an encoder can obtain speed feedback for speed closed-loop control.
  • Equipped with interactive device 0.96-inch OLED screen.
  • The UPS power supply module has 3x 18650 batteries in series with 7800mAh. Higher output current, stronger motor power.
  • The UPS power supply module also provides outputs of 5V and 3.3V for external other devices.
  • The onboard lithium battery protection circuit of the UPS power supply module has anti-overcharge, anti-over-discharge, anti-overcurrent, and short circuit protection functions.
  • The demo is developed on Arduino IDE, no need to manually configure the compilation environment, ESP32 automatically set a WIFI hotspot when it is turned on. You can use a mobile phone (Android/iOS) or a computer (Linux/Windows/Mac) to connect and log in to the control page by installing the Chromium browser, and no need to download an app.
  • ESP32 can be used to drive DC motors, serial bus servos, onboard OLED screen interfaces, TF card slots, nine-axis IMU modules, WiFi, and Bluetooth, and can be used alone without installing the host computer.
  • Support a variety of external host computers.
  • All codes are open source and provide rich development documents and tutorials.

UGV01 User Guide

Note: Customers need to purchase and install three 18650 lithium batteries on their own before using the product. When connecting the batteries for the first time, please pay attention to whether the LED light is on. If the LED light is on, it indicates that the positive and negative poles of the batteries are reversed. Please check and ensure that the batteries are not reversed. Charging is prohibited if the batteries are connected in reverse, as it may cause a risk of explosion.

UGV01 Basic Use

The driver board of UGV01 is developed based on the ESP32 module. After starting up, ESP32 will give priority to connecting to known WIFI hotspots (the following tutorial will introduce how to set up known WIFI). If WIFI is not connected within 20 seconds after starting up, ESP32 will create a hotspot automatically.
Hotspot name: UGV01_BASE
Hotspot password: 12345678

After connecting to this hotspot with your mobile phone, the mobile phone will prompt you that this hotspot has no network, and whether you are allowed to switch hotspots, please choose not to, keep the connection with the UGV01_BASE hotspot.

Open the mobile browser (Google Chrome is recommended), visit the URL, and you can open the UGV01_BASE control page. You can send commands in JSON format on this page to control and set the onboard serial bus servo device, get the serial bus servo feedback, obtain IMU information, control the angle of the PWM servo, set the content of the OLED display, etc., which is convenient for users to develop on the host computer.

UGV01 02.jpgUGV01 01.jpg
The web interface will display the robot's voltage, signal strength (STA mode), heading angle, IP and MAC address, and other information in real time.

The movement of the robot can be controlled by the direction buttons, and the SLOW, MIDDLE and FAST buttons below the direction buttons are used to select the moving speed of the robot.

Adopting closed-loop speed control, and the web page includes "heartbeat detection". After opening the web control interface, the web application will communicate with the robot continuously. If the connection is disconnected during the movement of the robot, the robot will automatically stop moving in a short time to avoid danger.

When using a tablet computer or PC to open the web control interface, you can use the WASD keys on the keyboard to control the robot. In order to avoid misuse, the first few shortcut keys after login are unresponsive, and you can start to control the robot by pressing the WASD keys once or several times in a cycle.

As the web application is completely open-source, you can change its interface and functions by changing WebPage.h. You can follow the customizable development tutorial we provide to learn.

UGV01's JSON Instruction Interaction Tutorial

What Is JSON?

JSON (JavaScript Object Notation) is an open standard file format and data interchange format that is easy for humans to read and write, and can exchange data between multiple languages. It is also easy for machines to parse and generate.

Why Interact With JSON Commands and UGV01?

As UGV01 boasts more onboard resources, rich demo functions, and is easy to connect external host computers, it is easily controlled by the host computer in more aspects. Hence, we can use JSON commands to interact with UGV01. Also, we can customize these functions based on the current framework to make them more suitable for your needs.

JSON Commands Interaction Method

We provide two interaction methods for UGV01 and the JSON commands:
1. Through the web application (or send a request through the program, which can be used for wireless JSON interaction with the host computer).
2. Through UART communication. The 40PIN expansion header on the driver board of UGV01 has a corresponding RX and TX header, using 3.3V logic level (applicable to host computers such as Raspberry Pi, Jetson nano, etc., not suitable for Arduino Uno with a serial port logic level of 5V.) Also, you can interact with the host computer through the Type-C connector and USB interface. There are two Type-C connectors on the UGV01 driver board, and the Type-C connector in the middle is used to communicate with the ESP32 and upload the demo, no matter which way you use to connect to the host computer, the communication baud rate is 1000000.

JSON Commands Using Way

Open the Web terminal control interface, you can see the "FEEDBACK INFOMATION" under the interface. There is an input field and a "SEND" button on the top of the board. You can fill in the JSON data here and click the SEND button. If the command has feedback, the feedback information will be displayed above the input field. Below the input field, there are examples of JSON commands. There is an INPUT button behind each example. Click it, and the instruction will be filled in the input field. You can edit the instruction in the input field, and then press the SEND button to interact with the robot.

Of course, you can also generate this JSON command through the host computer and send it to the robot through the serial port, the baud rate is 1000000, the logic level of the RX/TX pin of the serial port is 3.3V, and the USB cable of the Type-C connector can also be used for communication.

Each JSON command will be explained later. First, let's take the JSON command to control movement as an example. The JSON command to control movement is {"T":1, "L":0.5, "R":0.5} after SPEED_INPUT, click INPUT behind this command, this command will be filled in the upper input field. The first parameter of each JSON command is "T", which represents the type of this command.

For example, "T": 1 means that it is an instruction to control the movement of the robot. In addition to the T parameter, there are two parameters L and R in the movement command, which control the speed of the left track and the speed of the right track respectively. The unit is m/s. It can take a value between -1 and +1, but due to the low-speed characteristics of the DC geared motor, the absolute value of the speed value must be greater than or equal to 0.2. When the absolute value of the speed value is lower than 0.2 but not zero, the track will run at a speed of 0.2m/s, when the speed is positive, the track moves forward; when the speed is 0, the track stops; when the speed is negative, the track turns backward.

For example, if you want the robot to reverse at full speed, you can edit this command as {"T":1,"L":-1,"R":-1}, and after clicking the SEND button, the robot will go backward at full speed. After moving for a period of time, it stops. Due to heartbeat detection, when the robot does not receive new instructions for a period of time, it will automatically stop running to avoid danger.

The following content is for introducing the JSON commands.


Emergency stop command, if the command type T has no corresponding function, it will also trigger an emergency stop.

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

Movement control command, the parameters represent the speed of the left track and the right track respectively, the speed value can be positive or negative, stop when it is 0, and the absolute value of the action needs to be greater than 0.2 and less than 1.

PID_SET: {"T":2,"P":170,"I":90}

For the PID control of the motor closed-loop control, since the motor control of the product does not use the D parameter, only the P and I parameters need to be input here, and P:170 and I:90 are the default parameters of the product.

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

The OLED screen display content setting, the lineNum parameter is the line setting, which can be: 0, 1, 2, 3, and a total of 4 lines of content can be displayed. Each time a line of content is set, the new content will not affect the content displayed in other lines but will replace the original content of this line.
The Text parameter is the content setting, you can enter text here, and the text will be displayed on the corresponding line.
After using this command, the OLED screen will no longer display the information about the robot but will display the content that the command asked it to display.


When the command type is -3, the OLED screen will be reset to the initial state, and the information about the robot will be displayed.

PWM_SERVO_CTRL: {"T":40,"pos":90,"spd":30}

PWM servo angle control command, the PWM signal is generated by the IO4 pin of the driver board, the servo rotation range of most PWM signals is 0-180°, the pos parameter is the angle to be rotated, and 90° is the middle position of the servo, The spd parameter is a reserved speed interface. In order to avoid stuck thread in the demo, the spd parameter is not used.


The PWM servo turns to the middle position, which is the 90° position.

BUS_SERVO_CTRL: {"T":50,"id":1,"pos":2047,"spd":500,"acc":30}

In the serial bus servo control command, here you need to pay attention to whether the operating voltage of the connected serial bus servo is consistent with the power supply voltage of the driver board, you can directly use our ST3215 serial bus servo.
id: The ID of the serial bus servo, cannot be the same as the serial bus servo connected to the driver board.
pos: The target position is to be rotated by the servo. For the ST3215 servo, this value can be 0-4095 in the angle control mode, corresponding to the clockwise rotation range of 0-360°. In the continuous rotation mode, values can be ±32766.
spd: the rotation speed of the serial bus servo, the number of steps per unit time (per second), 50 steps/second=0.732RPM (turn/minute), the larger the value, the faster the speed (but the speed of the servo has a limit), when the parameter is 0, it runs at the maximum speed.
acc: The acceleration of the bus servo rotation. The smaller the value, the smoother the start and stop. The value can be 0-254. If it is set to 10, the speed will be changed according to the square acceleration of 1000 steps per second. When the parameter is 0, it runs with the maximum acceleration.

BUS_SERVO_MID: {"T":-5,"id":1}

Turn the bus servo of a certain ID to the middle position of the servo (provided that the operating mode of this servo is 0: position servo mode).
id: The ID of the target servo.

BUS_SERVO_SCAN: {"T":52,"num":20}

This command is used to scan which servo IDs are connected to the bus, no duplicate IDs are allowed. The results are fed back and displayed above the input field.
num: The maximum ID of the servo, the larger the value, the longer the scan time.

BUS_SERVO_INFO: {"T":53,"id":1}

To obtain the information feedback on a certain servo, the feedback content includes the position, speed, voltage, torque, and other information of the servo.

BUS_SERVO_ID_SET: {"T":54,"old":1,"new":2}

It is used to change the ID of a servo. The ID of each new servo is 1 by default. If you don’t know the ID of the servo at hand, you can use the above BUS_SERVO_SCAN command to get it, but the premise is that when viewing the ID of the servo, the driver board is only connected to this servo, otherwise, you don't know which ID corresponds to which servo.
old: the ID of the servo whose ID is to be changed.
new: the new ID to set.

BUS_SERVO_TORQUE_LOCK: {"T":55,"id":1,"status":1}

Servo torque lock switch.
id: The ID of the servo to control the torque lock.
status: Torque lock switch parameter, 1 is to turn on the torque lock, the servo will keep its position; 0 is to turn off the torque lock, and the servo will rotate under the action of external force.

BUS_SERVO_TORQUE_LIMIT: {"T":56,"id":1,"limit":500}

Servo torque limit command.
id: The ID of the target servo.
limit: Torque limit ratio, 500 is 50%*locked-rotor torque, 1000 is 100%*locked-rotor torque, after the torque is limited when the servo receives external force when the torque of the external force is greater than the limited torque, the servo will follow the external force Rotation, but still provide this torque, this feature can be used to make the gripper of the robotic arm.

BUS_SERVO_MODE: {"T":57,"id":1,"mode":0}

Servo operating mode.
id: Target servo ID.
mode: operation mode value. 0: position servo mode, used to control the absolute angle of the servo, you can use the BUS_SERVO_CTRL command to control the angle of the servo. 3: step servo mode, also use the BUS_SERVO_CTRL command to control it, the difference in the stepping servo mode is the pos parameter of BUS_SERVO_CTRL can be a negative number, and the range is ±32766, if you set 4096, it will rotate forward for one circle, if you set -4096, it will reverse for one circle.

WIFI_SCAN: {"T":60}

WIFI scanning command, which will disconnect the existing WIFI connection and scan the surrounding WIFI hotspots.

WIFI_TRY_STA: {"T":61}

WIFI connection command, STA mode, is used to connect to known WIFI.


WIFI hotspot open command, AP mode, the robot will set a WIFI hotspot by itself.
Hotspot name: UGV01_BASE
Hotspot password: 12345678

WIFI_INFO: {"T":65}

Used to obtain WIFI information.

WIFI_OFF: {"T":66}

Close Wifi.

INA219_INFO: {"T":70}

Obtain the information on INA219, including the voltage, current, and power of the power supply.

IMU_INFO: {"T":71}

Used to obtain IMU information, including heading angle, geomagnetic field, acceleration, altitude, temperature, and other information.


Used to obtain motor encoder information.


It is used to obtain device information, which needs to be customized by the user and is used to introduce the purpose of this device or other information.

IO_IR_CUT: {"T":80,"status":1}

It is used to control the high and low levels of the IO5 pin on the driver board, which can be used to control the night vision function switch of the infrared camera and can also be used to control the relay.

SET_SPD_RATE: {"T":901,"L":1.0,"R":1.0}

It is used to adjust the speed of each side track. When giving the same speed to the left and right tracks of the robot, if the movement of the robot is not a straight line, you can use this command to fine-tune the track speed. This value will be used as a coefficient to multiply the output power of the track to come to change the speed of the track.
L: Speed coefficient of the left track.
R: Speed coefficient of the right track.

GET_SPD_RATE: {"T":902}

Get the velocity coefficients of the left and right tracks.

SPD_RATE_SAVE: {"T":903}

The speed coefficient of the storage track will be saved in the nvs area of the ESP32, and will not be lost after power failure. After the power is turned on, the speed coefficient will be read and loaded by the nvs area.

GET_NVS_SPACE: {"T":904}

Get the remaining space of nvs area of ESP32.

NVS_CLEAR: {"T":905}

Clean up the nvs area, this command will delete all the contents of the nvs area, and the speed coefficient will return to the default value of 1.0.

Driver Board General Driver for Robots Module Usage Tutorial


Open-Source Demo

Dimensions & Drawing

Robot Model



Three 18650 batteries are used 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.
Batteries 18650 en.jpg




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 AM GMT+8 (Monday to Friday)