AprilTag Control Car Action Group

1. Experiment Objective

A fixed camera recognizes tag36h11 family AprilTag machine codes, mapping IDs 1~4 to chassis velocity commands to drive the No-PTZ car forward, backward, and in turns.

This program does not publish preset action-group names; instead, it continuously publishes geometry_msgs/Twist to /cmd_vel based on the currently recognized machine code.

2. Experiment Principle

1. Control Flow

ESP32 camera
    -> /camera/image_raw
    -> image conversion and scaling to 320x240
    -> dt_apriltags AprilTag recognition
    -> filter IDs 1, 2, 3, 4 and select the smallest ID
    -> machine code mapped to Twist
    -> /cmd_vel
    -> car chassis

The node uses two timers: the image processing timer recognizes the machine code at 15 Hz by default, and the control publishing timer publishes the velocity at 20 Hz by default. When no valid machine code is detected, it publishes an all-zero Twist, stopping the car.

2. Topics and QoS

3. Machine Code to Action Mapping

The default linear speed is 0.2 m/s and the default angular speed is 0.8 rad/s.

When multiple valid IDs appear in the frame at the same time, the program selects the smallest ID. For example, when IDs 2 and 4 are recognized together, the action for ID 2 is executed. IDs outside the 1~4 range do not participate in control.

3. Experiment Steps

1. Hardware and Software Preparation

2. Start Agent + Camera + Joint Model (Terminal 1)

xxxxxxxxxx
ros2 launch microros_v2_bringup car_base.launch.py

3. Start AprilTag Machine Code Control (Terminal 2)

xxxxxxxxxx
ros2 run microros_v2_ptz_visual_control_pkg apriltag_action_group_control_ptz_node

4. Stop the Program

Press lowercase q or Esc in the OpenCV window to exit. The node publishes an all-zero Twist before destruction; pressing Ctrl+C to exit also runs the stop-and-cleanup logic.

4. Experiment Observations

• The debug window displays the currently recognized machine code, e.g., Machine code: 1.
• The car moves forward when ID 1 is recognized, and backward when ID 2 is recognized.
• The car moves forward and turns right when ID 3 is recognized, and moves forward and turns left when ID 4 is recognized.
• When the tag is removed, another ID is recognized, or no image has been received yet, the control output is zero velocity and the car stops.

5. Program Analysis

Source code: microros_v2_ptz_visual_control_pkg/microros_v2_ptz_visual_control_pkg/apriltag_action_group_control_ptz_node

Launch file: microros_v2_ptz_visual_control_pkg/launch/machine_code_action_group_control.launch.py

Note: The current launch file and setup.py still reference machine_code_action_group_control_node, but the corresponding machine_code_action_group_control_node.py does not exist in the source directory and has not been synced with the apriltag_action_group_control_ptz_node used by this tutorial. Therefore, this section launches the node with the Python module command above and does not use that launch file.

1. Node Initialization

The node is named apriltag_action_group_control_ptz_node, with the following main initialization:

​x
super().__init__("machine_code_action_group_control_node")
​
self.declare_parameter("image_topic", "/camera/image_raw")
self.declare_parameter("cmd_vel_topic", "/cmd_vel")
self.declare_parameter("tag_family", "tag36h11")
self.declare_parameter("quad_decimate", 2.0)
self.declare_parameter("processing_width", 320)
self.declare_parameter("processing_height", 240)
self.declare_parameter("image_processing_rate_hz", 15.0)
self.declare_parameter("control_rate_hz", 20.0)
self.declare_parameter("linear_speed", 0.2)
self.declare_parameter("angular_speed", 0.8)
self.declare_parameter("show_debug_window", True)
self.declare_parameter("window_name", "machine_code_action_group")

The program creates the detector with dt_apriltags.Detector, and configures both the image subscription and the /cmd_vel publisher as BEST_EFFORT, KEEP_LAST, depth=1, to match the camera and chassis communication links.

2. AprilTag Recognition

On every image processing tick, the program first scales the latest image to processing_width × processing_height, then converts it to grayscale and calls the detector:

xxxxxxxxxx
gray = cv.cvtColor(frame, cv.COLOR_BGR2GRAY)
tags = self._detector.detect(gray, estimate_tag_pose=False)
valid_ids = [
    int(tag.tag_id) for tag in tags
    if int(tag.tag_id) in (1, 2, 3, 4)
]
code = min(valid_ids) if valid_ids else None

Here, estimate_tag_pose=False means the node only needs the tag ID and corners, without computing distance, position, or pose. Recognized valid tags are drawn with a green border in the debug window, which also displays the current machine code.

3. Machine Code to Twist Mapping

The control timer reads the latest recognition result and publishes a Twist on every callback:

xxxxxxxxxx
cmd = Twist()
if code == 1:
    cmd.linear.x = self._linear_speed
elif code == 2:
    cmd.linear.x = -self._linear_speed
elif code == 3:
    cmd.linear.x = self._linear_speed
    cmd.angular.z = -self._angular_speed
elif code == 4:
    cmd.linear.x = self._linear_speed
    cmd.angular.z = self._angular_speed
self._cmd_pub.publish(cmd)

The Twist() default is zero, so a stop command is published when code is None or any other value. This program performs continuous velocity control, not a discrete action group that is published once and then executed by the chassis.

4. Key Parameters