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
linetarget is detected, proportional line-following control is performed based on the deviation between the line center and the image center. - When a
zttraffic 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 startscomplete_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_WAITINGstate.
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:
After copying the origincar_competition package to the current directory, return to the workspace root directory to build:
If you want the workspace to be loaded automatically every time a terminal is opened, add the following command to ~/.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:
After starting, you can check whether the chassis velocity topic exists:
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:
You can also directly use the launch file provided by this package, which internally includes the camera display launch file described above:
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:
You can use the following command to check whether the topic exists:
Check the topic type:
Under normal conditions, the topic type should be:
Step 4: Start the Integrated Control Node
If you did not use start.launch.py in step 2, you can run the node separately:
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:
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:
View the velocity output:
View the line-following state output:
Simulate QR code input:
Simulate starting teleoperation takeover:
Simulate ending teleoperation takeover and resuming line following:
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:
- Starts line following after the guide line is detected.
- Enters obstacle avoidance after an approaching traffic cone is detected.
- Automatically finds the guide line and resumes line following after obstacle avoidance ends.
- Stops and waits for teleoperation or subsequent task commands after a QR code is detected.
- Resumes automatic line following through the
/sign4returnsignal after teleoperation ends.
