Welcome to MicroROS V2 Robot Car repository
3. QR Code Follow
QR Code Follow (No-PTZ)
1. Experiment Objective
The camera tracks a QR code, with body rotation tracking + distance following keeping the QR code centered in the frame and maintaining a constant distance.
2. Experiment Principle
1. Key Terms
| Term | Description |
|---|---|
| Visual Follow | Adds distance control (linear.x) on top of tracking, making the car rotate and move forward/backward simultaneously |
| Distance Follow | Estimates distance from the QR code pixel size, with PD control keeping the car at the desired distance |
| pyzbar Decoding | Decodes the QR code content based on the open-source library pyzbar, displayed in real time on the terminal |
| Stable-frame Gating | Only confirms following after the same target is detected for follow_stable_frames (3) consecutive frames |
| QoS | best_effort (image input + cmd_vel downlink), depth=1 |
2. Technical Architecture
Shares the node qr_tracker_node, with enable_distance_follow:=true:
/camera/image_raw (BEST_EFFORT)→ qr_tracker_node (enable_distance_follow:=true)├── pyzbar/OpenCV dual-backend QR detection → stable-frame gating└── PD angular velocity + QR code size distance following → /cmd_vel
3. Core Topics Quick Reference
Firmware Downlink
| Topic | Message Type | QoS | Field | Range | Direction |
|---|---|---|---|---|---|
/cmd_vel | geometry_msgs/Twist | best_effort + keep_last(1) | linear.x | -0.18~0.18 m/s | += forward, −= backward |
angular.z | -0.60~0.60 rad/s | += left turn, −= right turn |
3. Experiment Steps
1. Hardware Preparation
| Hardware | Requirement |
|---|---|
| PTZ Version | ❌ |
| No-PTZ Version | ✅ |
| Required Peripherals | ESP32 camera (mounted on bracket), a printed or phone-displayed QR code |
2. Start Agent + Camera + Joint Model (Terminal 1)
xxxxxxxxxxros2 launch microros_v2_bringup car_base.launch.py
3. Start QR Code Follow (Terminal 2)
xxxxxxxxxxros2 launch microros_v2_no_ptz_visual_control_pkg qr_follow.launch.py
5. Operation Instructions
| Key | Function |
|---|---|
| Space | Toggle follow/standby |
| q / ESC | Exit |
4. Experiment Result
- QR code approaches → the car moves backward to keep the distance
- QR code moves away → the car moves forward to follow
- The terminal outputs the decoded QR code content in real time
- Stable-frame gating prevents false triggering
- Auto-stops after target-loss timeout
5. Code Explanation
Source code paths:
- Launch:
~/microros_ws/src/microros_v2_no_ptz_visual_control_pkg/launch/qr_follow.launch.py- Node source:
~/microros_ws/src/microros_v2_no_ptz_visual_control_pkg/microros_v2_no_ptz_visual_control_pkg/qr_tracker_node.py
1. Core Node Explanation
qr_follow.launch.py launches qr_tracker_node, with enable_distance_follow defaulting to true. Distance following computes the PD linear velocity from the deviation between the QR code bounding rectangle size and the desired size target_qr_size_px (120 px). Stable-frame gating (detected for 3 consecutive frames) prevents occasional false detections from triggering following.
2. Key Parameters
Parameter definition files:
- Launch:
~/microros_ws/src/microros_v2_no_ptz_visual_control_pkg/launch/qr_follow.launch.py- Node:
~/microros_ws/src/microros_v2_no_ptz_visual_control_pkg/microros_v2_no_ptz_visual_control_pkg/qr_tracker_node.py
| Parameter | Type | Default | Description |
|---|---|---|---|
qr_detector_backend | str | pyzbar | QR decoding backend |
follow_stable_frames | int | 3 | Stable-frame gating frame count |
deadband_x_pixel | float | 50.0 px | Horizontal deadband |
angular_kp / angular_kd | float | 1.6 / 0.75 | Angle PD gains |
max_angular_z | float | 0.6 rad/s | Maximum turning speed |
enable_distance_follow | bool | true | Enable distance following |
target_qr_size_px | float | 120.0 px | Desired QR code pixel size |
distance_tolerance_qr_size_px | float | 20.0 px | Distance tolerance |
distance_kp | float | 0.05 | Distance PD proportional gain |
max_linear_x | float | 0.18 m/s | Maximum forward/backward speed |
3. Node Description
| Node | Package | Description |
|---|---|---|
qr_tracker_node | microros_v2_no_ptz_visual_control_pkg | QR code tracking + following, stable-frame gating + dual PD |
6. Common Issues
| Issue | Cause | Solution |
|---|---|---|
| Frequent target loss | QR code too small or moving too fast | Enlarge the QR code and slow down the movement |
| Inaccurate distance following | Unreasonable distance PD parameters | Adjust distance_kp / target_qr_size_px |
| Decoding failure | QR code blurry or reflective | Make sure the QR code is clear and flat |