Skip to content

OriginCar Competition Integrated Control

Hint

The operating environment and software/hardware configuration are as follows:

  • OriginCar X3 robot
  • PC / robot: Ubuntu (≥20.04) + ROS2 (≥foxy)
  • Control package: origincar_competition
  • Perception input: object detection result topic origincar_competition
  • Control output: velocity control topic cmd_vel
  • Competition scenario: line following along a black guide line, traffic cone avoidance, and stopping to wait for teleoperation takeover after QR code recognition

Package/resources download link: (refer to Kit Resources/Resource Links for download)

Scenario Description

This example is used for integrated motion control in OriginCar competition tasks. The package receives ai_msgs/msg/PerceptionTargets object detection results published by the visual perception node, and controls the car to complete line following, obstacle avoidance, and stop-and-wait operations based on the detected guide line, traffic cone, and QR code signals.

The core node of this package is complete_control_node, and its main logic is as follows:

  • When a line target is detected, proportional line-following control is performed based on the deviation between the line center and the image center.
  • When a zt traffic cone target is detected and its height exceeds the threshold, the vehicle enters the traffic cone avoidance state.
  • After obstacle avoidance ends, if the line can be detected again, line following resumes; if the line is temporarily lost, the vehicle first searches forward and then performs a recovery turn search.
  • After receiving the QR code topic /sign, the direction command is determined by the parity of the QR code number, and the vehicle enters the stop-and-wait state.
  • After receiving the teleoperation end signal on /sign4return, line following resumes.
Attention

This package itself is not responsible for training models, nor does it directly perform image recognition. It relies on an external visual recognition node to publish object detection results of type ai_msgs/msg/PerceptionTargets.

The target types must match those in the program:

  • Guide line target type: line
  • Traffic cone target type: zt

If the target type names do not match, the vehicle cannot enter the corresponding line-following or obstacle-avoidance logic.

Package Structure

The main file structure in the archive is as follows:

origincar_competition/
├── CMakeLists.txt
├── package.xml
├── include/
│   └── origincar_competition/
│       └── origincar_competition.h
├── launch/
│   └── start.launch.py
└── src/
    └── origincar_competition.cpp

Where:

  • origincar_competition.cpp: source code of the integrated control node, including the logic for line following, obstacle avoidance, QR code stopping, and teleoperation takeover.
  • origincar_competition.h: definitions of the node class, state machine enumeration, QR code commands, and topic interfaces.
  • start.launch.py: launches the camera display-related launch files and starts complete_control_node.
  • CMakeLists.txt: compilation configuration for the C++ node.
  • package.xml: ROS2 package dependency description file.

Communication Topics

Subscribed Topics

Topic Name Message Type Description
origincar_competition ai_msgs/msg/PerceptionTargets Receives visual object detection results for identifying lines and traffic cones
/sign std_msgs/msg/String Receives the raw QR code recognition result
/sign4return std_msgs/msg/Int32 Receives the teleoperation takeover and teleoperation end signals

Published Topics

Topic Name Message Type Description
cmd_vel geometry_msgs/msg/Twist Publishes the chassis linear velocity and angular velocity
follower_line std_msgs/msg/Int32 Publishes whether the vehicle is currently in the line-following state; 1 means line following, 0 means not line following
stop std_msgs/msg/Int32 Publishes the stop signal
/sign_switch origincar_msg/msg/Sign Forwards the QR code direction command to the host computer or other nodes

State Machine Description

The program uses the RobotBehaviorState enumeration internally to manage the vehicle behavior states:

State Meaning
LINE_FOLLOWING Normal line-following state
CONE_AVOIDANCE_ACTIVE Traffic cone avoidance in progress
POST_AVOIDANCE_SEARCH_FORWARD Searches forward for the guide line for a short time after obstacle avoidance
POST_AVOIDANCE_RECOVERY_TURN After the forward search fails, turns back according to the previous avoidance direction to look for the line
QR_CODE_WAITING Stops and waits after receiving a QR code command

QR Code and Teleoperation Logic

QR code data is received through the /sign topic, and the message type is std_msgs/msg/String. The program attempts to convert the string to an integer:

  • A value is considered valid only if it is in the range 1 ~ 9999.
  • Odd QR code: publishes QR_CLOCKWISE = 3, indicating the clockwise direction.
  • Even QR code: publishes QR_ANTICLOCKWISE = 4, indicating the counterclockwise direction.
  • After receiving a valid QR code, the vehicle stops immediately and enters the QR_CODE_WAITING state.

The teleoperation takeover signal is received through the /sign4return topic, and the message type is std_msgs/msg/Int32:

Value Macro Definition Description
5 SIG_START_TELEOPERATION Starts teleoperation takeover; automatic line following pauses
6 SIG_ENDING_TELEOPERATION Ends teleoperation takeover; automatic line following resumes

Parameter Description

start.launch.py already provides the commonly used parameters, which can be overridden from the command line at startup.

Parameter Name Default Value Description
line_following_speed 0.65 Forward speed during line following, in m/s
line_kp 0.003225 Proportional control coefficient for line following; the larger the value, the more sensitive the steering
cone_avoidance_speed 0.4 Base forward speed during traffic cone avoidance, in m/s
cone_detection_y_threshold 130.0 Traffic cone height trigger threshold, in px
cone_critical_y_threshold 250.0 Traffic cone critical height threshold, in px
cone_avoidance_steering_gain 0.5 Angular velocity gain for traffic cone avoidance and recovery turns
cone_lateral_offset_threshold 30.0 Lateral offset threshold for determining whether a traffic cone is directly ahead, in px
post_avoidance_forward_search_duration 0.5 Duration of the forward search for the guide line after obstacle avoidance, in s
post_avoidance_recovery_turn_duration 0.0 Maximum duration of the recovery turn search; 0.0 means no limit
recovery_turn_linear_speed_ratio 0.3 Linear velocity ratio during the recovery search
search_swing_frequency 0.3 Swing search frequency when there is no clear recovery direction
Attention

Excessively large parameter values can easily cause the vehicle to steer too sharply or run off the track. It is recommended to lower the speed first, for example by setting line_following_speed to 0.25 ~ 0.35, and then gradually increase the speed after confirming that recognition is stable.

Build Steps

Place the package in the src directory of the ROS2 workspace, for example:

cd ~/dev_ws/src

After copying the origincar_competition package to the current directory, return to the workspace root directory to build:

cd ~/dev_ws
colcon build --packages-select origincar_competition
source install/setup.bash

If you want the workspace to be loaded automatically every time a terminal is opened, add the following command to ~/.bashrc:

echo "source ~/dev_ws/install/setup.bash" >> ~/.bashrc
source ~/.bashrc

Launch Steps

Running this example completely usually requires three terminals, which are used to start the chassis, start visual perception, and start the integrated control node respectively.

Step 1: Start the Chassis Driver

Connect to OriginCar over SSH, and enter the following command in the first terminal to start the robot's low-level driver:

ros2 launch origincar_base origincar_bringup.launch.py

After starting, you can check whether the chassis velocity topic exists:

ros2 topic list | grep cmd_vel

Step 2: Start the Camera and Image Display

Enter the following command in the second terminal to start the USB camera and the image display-related nodes:

ros2 launch origincar_bringup usb_websocket_display.launch.py

You can also directly use the launch file provided by this package, which internally includes the camera display launch file described above:

ros2 launch origincar_competition start.launch.py
Attention

start.launch.py contains only usb_websocket_display.launch.py and the integrated control node. If your object detection node is not started by another launch file, you need to start a visual recognition node that can publish the origincar_competition topic separately.

Step 3: Start the Visual Recognition Node

Start the object detection node in the third terminal so that it publishes recognition results of type ai_msgs/msg/PerceptionTargets.

The recognition result topic name must be consistent with the control program:

origincar_competition

You can use the following command to check whether the topic exists:

ros2 topic list | grep origincar_competition

Check the topic type:

ros2 topic info /origincar_competition

Under normal conditions, the topic type should be:

ai_msgs/msg/PerceptionTargets

Step 4: Start the Integrated Control Node

If you did not use start.launch.py in step 2, you can run the node separately:

ros2 run origincar_competition origincar_competition

It is recommended to start it with launch and adjust the parameters according to the on-site conditions:

ros2 launch origincar_competition start.launch.py \
  line_following_speed:=0.35 \
  line_kp:=0.003225 \
  cone_detection_y_threshold:=130.0 \
  cone_critical_y_threshold:=250.0

After a successful start, the terminal prints messages similar to the following:

CompleteControl Node started.
Centered cone avoid bias: 1.0 (1=Left, -1=Right)
Post-Avoidance Forward Search: 0.50s

Step 5: Host Computer Visualization

To make it easier to observe the recognition results and debug the on-site effect, you can start rqt_image_view on the PC under the same network:

ros2 run rqt_image_view rqt_image_view

After selecting the camera image topic, you can observe the camera feed. If the object detection node provides debug images with bounding boxes, it is also recommended to subscribe to the corresponding debug image topic for observation.

Common Debugging Commands

View the current topics:

ros2 topic list

View the velocity output:

ros2 topic echo /cmd_vel

View the line-following state output:

ros2 topic echo /follower_line

Simulate QR code input:

ros2 topic pub --once /sign std_msgs/msg/String "{data: '3'}"

Simulate starting teleoperation takeover:

ros2 topic pub --once /sign4return std_msgs/msg/Int32 "{data: 5}"

Simulate ending teleoperation takeover and resuming line following:

ros2 topic pub --once /sign4return std_msgs/msg/Int32 "{data: 6}"

Running Effect

After starting the chassis, camera, visual recognition node, and integrated control node, the vehicle automatically executes the following process according to the visual detection results:

  1. Starts line following after the guide line is detected.
  2. Enters obstacle avoidance after an approaching traffic cone is detected.
  3. Automatically finds the guide line and resumes line following after obstacle avoidance ends.
  4. Stops and waits for teleoperation or subsequent task commands after a QR code is detected.
  5. Resumes automatic line following through the /sign4return signal after teleoperation ends.

Image 1