Welcome to MicroROS V2 Robot Car repository
1. Color Follow
Color Follow (PTZ)
1. Experiment Objective
PTZ pan-tilt + car body collaborative color following — the pan-tilt locks onto the target with PD tracking, the car body automatically turns to home based on the pan-tilt horizontal angle, and distance following is driven by the target's enclosing-circle radius.
Note: the ESP camera's data transmission is affected by the network. A low frame rate degrades the tracking/following effect. If you notice a low frame count, switch the network or use a phone hotspot.
2. Experiment Principle
1. Key Terms
| Term | Description |
|---|---|
| Visual Following | Visual tracking + coordinated body movement; the pan-tilt locks onto the target center while the car actively turns and moves forward/back to follow |
| Error sharing (body_share) | The body only takes on the pan-tilt horizontal angle × body_share ratio of the homing task; the remaining error is naturally absorbed by the PTZ, preventing the body and pan-tilt from fighting over control |
| Angular-rate feedforward (body_ff_gain) | When the body rotates, the pan-tilt compensates in the opposite direction synchronously (canceling body_az × body_ff_gain / ptz_rate radians per PTZ tick), preventing the target from being dragged away by the body rotation |
| Distance Follow | PD control based on the target's enclosing-circle radius: radius < target_radius → move back, radius > target_radius → move forward |
| Lost-frame tolerance (lost_frame_threshold) | Only after N consecutive lost frames is the target judged lost and the body frozen, filtering transient frame loss such as lighting flicker |
| HSV Color Space | A three-dimensional color description of hue/saturation/value; a specified color object is segmented by threshold filtering |
| PD Control | Proportional-derivative control; the tracking error (P) and its rate of change (D) drive the output, with no integral term to avoid overshoot |
2. Technical Architecture
Node chain: state estimation (ekf_filter_node + camera_node) → color_follow_ptz_node → /cmd_ptz_angle (pan-tilt) + /cmd_vel (body)
Three-layer coordination: PTZ PD (30 Hz) + body angular-velocity PD (10 Hz) + distance-follow PD (10 Hz)
3. Core Topics Quick Reference
Firmware Uplink
| Topic Name | Message Type | QoS | Source |
|---|---|---|---|
| /camera/image_raw | Image | best_effort | ESP32 camera |
| /odom | Odometry | best_effort | Odometry (needed by the body control) |
Firmware Downlink
| Topic Name | Message Type | QoS | Description |
|---|---|---|---|
| /cmd_ptz_angle | Vector3 | best_effort + keep_last(1) | x: [-90,90]° horizontal, y: [-90,20]° tilt |
| /cmd_vel | Twist | best_effort + keep_last(1) | angular.z: turning, linear.x: forward/back |
ROS2 Internal
| Topic Name | Message Type | QoS | Source | Description |
|---|---|---|---|---|
| /joint_states | JointState | reliable | State estimation layer | Current pan-tilt angle feedback |
3. Experiment Steps
1. Hardware Preparation
| Hardware | Requirement |
|---|---|
| PTZ version | ✅ |
| No-PTZ version | ❌ |
| Required peripherals | ESP32 camera (pan-tilt) + PTZ servo |
2. Start Agent + Camera + Joint Model (Terminal 1)
ros2 launch microros_v2_bringup car_base.launch.py
3. Start Color Follow (Terminal 2)
xxxxxxxxxxros2 launch microros_v2_ptz_visual_control_pkg color_follow_ptz.launch.py
4. Operation Instructions
Workflow:
After startup, the node processes frames at the image frame rate with two independent control timers running in parallel (PTZ 30 Hz + body 10 Hz):
- Image decoding and HSV detection: the image callback converts the raw Image frame → flips/rotates → scales it to 640×480. BGR is converted directly to HSV, binarized with
cv.inRangeusing the sixHmin~Vmaxparameters, morphological open+close operations remove noise, the largest contour is extracted, and the minimum enclosing circle (cx, cy, r) is computed. An area ≥min_target_area(60 px²) and radius ≥min_target_radius(5 px) marks the target as valid. - N-frame lost-frame tolerance: when the target is lost consecutively, the
lost_framescounter increments; only when it reacheslost_frame_threshold(5 frames) is the target truly judged lost and the body frozen. - PTZ PD control (30 Hz): normalized pixel error → PD step → angular-rate feedforward compensation → step limiting (±1.2°) → step smoothing (α=0.35) → direction reversal → angle smoothing (α=0.85) → publish
/cmd_ptz_angle. - Body angular-velocity PD control (10 Hz): takes the PTZ horizontal angle s1, zeros it within the angle tolerance (
angular_tolerance_deg=3°). Multiplied bybody_share(0.4) to get the effective homing errors1_eff, PD computes the angular velocityangular.z, published to/cmd_vel. - Distance-follow PD control (10 Hz): enabled with
enable_distance_follow=true. Computes the deviation between the target radius and