Welcome to MicroROS V2 Robot Car repository
1. Quickly Start
Quick Start
1. Course Content
Complete the initial configuration of the MicroROS-V2 development environment and be able to control the robot's movement with a gamepad or keyboard. This chapter covers:
- Starting the MicroROS_V2_VM virtual machine
- Configuring the robot Wi-Fi and micro-ROS Agent parameters
- Gamepad control (USB Host direct control / ROS2 topic control)
- Keyboard control
2. Preparation
2.1 Flashing the Firmware
Note: The firmware is already flashed at the factory, so this step can be skipped.
Use the flash_download_tool utility to flash the factory firmware (MicroROS-V2-v1.1.0-complete.bin) to the MicroROS-V2 control board (ESP32-S3).
Connect the control board to the computer with a USB data cable, open the flash_download_tool software, and flash the factory firmware.
After configuring as shown in the image, click START to begin flashing. Set the firmware path according to your local actual path, and the port likewise.
During flashing, wait for the progress bar to finish. When FINISH is displayed, the flashing is successful. At this point you can reset the main control board and the firmware will take effect.
2.2 Opening the Virtual Machine
The VMware platform can be installed by yourself.
Download address (the address may change; please refer to the official VMware website):
Start the MicroROS-V2 virtual machine environment
2.3 Control Board Parameter Configuration
1. Modifying the Configuration Parameters
Modify the parameters in the custom mode in ~/workspaces/tools/config_robot.py according to your actual network.
Users should first confirm the Wi-Fi, Agent IP, Agent port, and ROS_DOMAIN_ID. Other parameters can remain at their default values and only need to be modified when calibrating the gimbal, adjusting the control effect, or configuring the camera.
| Parameter | Default Value | Description | Modification Suggestion |
|---|---|---|---|
| main_wifi_ssid | SSID | Wi-Fi name that the robot's main controller connects to | Change to an available 2.4G Wi-Fi; the ESP32-S3 does not support 5G Wi-Fi |
| main_wifi_passwd | PASSWORD | Wi-Fi password that the robot's main controller connects to | Must match the Wi-Fi name above |
| agent_ip_addr | [192, 168, 33, 146] | IP of the computer/virtual machine running the micro-ROS Agent | Change to the real IP of the virtual machine or host on the same LAN; keep the format of 4 numbers |
| agent_ip_port | 8090 | micro-ROS Agent UDP port | No need to change by default; if you specify a different port when starting the Agent, keep it consistent here |
| ros_domain_id | 77 | ROS_DOMAIN_ID | Must be consistent with the ROS_DOMAIN_ID in the virtual machine terminal |
| ros_namespace | "" | ROS namespace | Keep an empty string for a single robot; fill it in when multiple robots need to distinguish topics, e.g. "robot1" |
| servo_1_offset | 0 | S1 horizontal gimbal offset, in degrees | Fine-tune when the camera is not facing straight ahead; positive value turns right, negative value turns left |
| servo_2_offset | 0 | S2 tilt gimbal offset, in degrees | Fine-tune when the camera tilt angle deviates; positive value tilts up, negative value tilts down |
| motor_pid | (1.8, 0.12, 0.0) | Chassis motor speed-loop PID | Do not modify for ordinary users; only change when the motion control effect is abnormal and tuning is clearly needed |
| imu_yaw_pid | (2.4, 0.0, 0.16) | Straight-line heading-hold PID | Do not modify for ordinary users; only change when the straight-line holding effect needs optimization |
2. Servo Offset Adjustment Instructions
- servo_1_offset adjusts the horizontal gimbal S1. When the camera is facing too far to the left, appropriately increase the value; when the camera is facing too far to the right, appropriately decrease the value.
- servo_2_offset adjusts the tilt gimbal S2. When the camera is facing too low, appropriately increase the value; when the camera is facing too high, appropriately decrease the value.
- It is recommended to make small adjustments of 1° ~ 3° each time, and then re-run
python3 ~/workspaces/tools/config_robot.py customto observe the effect. - If the actual assembly direction is opposite to the above, take the actual motion direction as the standard and adjust the offset value in the opposite direction.
3. Parameter Configuration
- Turn on the robot's power, connect the robot control board to the virtual machine with a Type-C data cable, and then run the configuration command:
python3 ~/workspaces/tools/config_robot.py custom
After the configuration is successful, the robot will start with the new Wi-Fi and Agent parameters. If the ROS indicator light stays on, it means the micro-ROS Agent has been connected.
- If you need to restore the factory default parameters, run:
xxxxxxxxxxpython3 ~/workspaces/tools/config_robot.py default
3.1 Handle Button Operations
3.2 Running the Program for Gamepad Control
Quick start:
xxxxxxxxxxbash ~/workspaces/scripts/start_remote_control.sh joy
The script will automatically start the state estimation layer, the gamepad driver layer, and the remote control operation layer.
3.3 Motion Control
An independent per-axis arbitration between the joysticks and the D-pad is used — the joystick takes priority, and the D-pad only acts as a backup when the corresponding joystick axis is idle:
| Input | Function | Curve | Description |
|---|---|---|---|
| Left joystick up/down (LY) | Forward / Backward | Square curve (power=2.0) | Analog control, with a 0.15 dead zone |
| Right joystick left/right (RX) | Turn left / Turn right | Cubic curve (power=3.0) | Analog control, with a 0.15 dead zone |
| Left joystick left/right (LX) | No function | — | Not used |
| Right joystick up/down (RY) | No function | — | Not used |
| D-pad up/down | Forward / Backward | — | Effective only when LY is idle (digital backup) |
| D-pad left/right | Turn left / Turn right | — | Effective only when RX is idle (digital backup) |
3.4 Speed Gears
There are 5 fixed speed gears in total (G1–G5), with G2 as the default:
| Gear | Linear Speed | Angular Speed |
|---|---|---|
| G1 | 0.20 m/s | 0.50 rad/s |
| G2 ★ | 0.30 m/s | 1.50 rad/s |
| G3 | 0.50 m/s | 2.50 rad/s |
| G4 | 0.75 m/s | 3.75 rad/s |
| G5 | 1.00 m/s | 5.00 rad/s |
| Button | Function |
|---|---|
| L1 | Increase linear speed by one gear |
| L2 | Decrease linear speed by one gear |
| R1 | Increase angular speed by one gear |
| R2 | Decrease angular speed by one gear |
Raising the gear to G5 or lowering it to G1 triggers a double beep notification.
3.5 Handle Control
| Button | Function | Description |
|---|---|---|
| X | Servo S1 forward | Effective when X is pressed alone |
| B | Servo S1 reverse | Effective when B is pressed alone |
| Y | Servo S2 reverse | Effective when Y is pressed alone |
| A | Servo S2 forward | Effective when A is pressed alone |
S1 travel range: -90° ~ +90°; S2 travel range: -90° ~ +20°.
3.6 Buzzer and Enable Switch
| Button | Function |
|---|---|
| START (OPTIONS) | Hold to keep beeping, release to stop |
| SELECT (SHARE) | Toggle the gamepad enable state (/JoyState: True ↔ False) |