快速上手
Windows 下推荐用原生 Webots 显示场景,用 Docker 提供 Linux 编译和运行环境。Docker 容器手动启动,编译、运行 controller 等命令都在容器终端里执行。
Windows
安装开发工具
先安装:
- Git
- Docker Desktop,使用 Linux containers
- Webots
- VS Code
Windows 本机的 VS Code 只要求先安装:
Dev Containers ms-vscode-remote.remote-containers
XRobot、CMake Tools、clangd 等开发扩展安装在后面连接的 Linux 容器中。
拉取工程
PowerShell:
git clone --config core.autocrlf=false https://github.com/QDU-Robomaster/bsp-webots-autoaim.git
cd bsp-webots-autoaim
git submodule update --init --recursive
libxr/ 是 Git submodule;Modules/ 后面由 XRobot 下载。
准备开发容器
在仓库根目录构建开发镜像:
docker build -t bsp-webots-autoaim-webots:local .\docker
创建开发容器:
docker run -d `
--name qdu-autoaim-dev `
-p 8080:8080 `
-v "${PWD}:/workspace" `
-w /workspace `
bsp-webots-autoaim-webots:local `
sleep infinity
容器创建一次即可。以后从已有容器继续开发:
docker start qdu-autoaim-dev
进入容器:
docker exec -it qdu-autoaim-dev bash
后面的 Linux 命令默认都在这个容器终端中执行。
初始化 XRobot 模块
进入工程后执行:
xrobot_setup
完成后应能看到 Modules/ArmorDetector/、Modules/ArmorTracker/、Modules/Aimer/ 等目录。xrobot_setup 会同时生成当前入口文件;后续 CMake 也会在 YAML 变化时自动重新生成。
User/xrobot_main.hpp 和 User/xrobot_constexpr.hpp 由 XRobot 生成,修改配置时改 YAML 即可。
配置与编译
先 configure:
cmake -S . -B build/debug -G Ninja \
-DCMAKE_BUILD_TYPE=Debug \
-DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
-DAUTO_AIM_PREVIEW_IMAGE=ON
再并行编译:
cmake --build build/debug \
--target rm_auto_aim \
--parallel "$(nproc)"
生成:
build/debug/rm_auto_aim
build/debug/compile_commands.json
--parallel "$(nproc)" 会按容器可用 CPU 核数并行编译。首次完整 Debug 构建仍会比较重。
VS Code
连接开发容器
Windows 上打开 VS Code,按 Ctrl+Shift+P:
Dev Containers: Attach to Running Container...
选择:
qdu-autoaim-dev
然后在这个 VS Code 窗口中打开:
/workspace
连接后在容器侧安装开发扩展。打开 Extensions 面板(Ctrl+Shift+X),搜索:
@recommended
选择 Install Workspace Recommended Extensions。仓库已经在 .vscode/extensions.json 中声明推荐项,至少确认下面三个显示为 Installed in Container: qdu-autoaim-dev:
XRobot xrobot.xrobot
CMake Tools ms-vscode.cmake-tools
clangd llvm-vs-code-extensions.vscode-clangd
Python、Docker 和调试扩展也在推荐列表中。C/C++ 代码索引由 clangd 提供,Microsoft C/C++ IntelliSense 保持关闭。
这些扩展保存在 qdu-autoaim-dev 容器中。复用同一个容器时无需重复安装;删除并重建容器后再安装一次即可。
这里使用 Attach to Running Container 连接已经启动的 qdu-autoaim-dev。Reopen in Container 会按 .devcontainer 配置另起一套 Compose 环境,两种方式不要混用。
代码索引与跳转
这个工程使用 clangd 做 C/C++ 补全和跳转。它读取:
build/debug/compile_commands.json
完成一次 Debug configure + build 后,compile_commands.json 才包含完整的编译参数。
Windows bind mount 下,首次 background index 往往需要一段时间。状态栏仍显示 indexing 时,跳转和补全尚未完全就绪。
索引完成后可以检查:
User/main.cpp中的XRobotMain能否F12跳转;Modules/ArmorDetector/ArmorDetector.hpp中的类型能否正常跳转;- include 是否不再整页报红。
build/debug/compile_commands.json 已存在而索引仍长期停滞时,可以重启 language server:
Ctrl+Shift+P
→ clangd: Restart language server
这份数据库记录的是 /workspace/... 编译路径,因此应由容器中的 clangd 使用。
在 VS Code 中编译
首次完成 xrobot_setup 后,仓库的 CMake Tools 配置会在打开工程时自动 configure:
source /workspace
build /workspace/build/debug
generator Ninja
build type Debug
VS Code 底部状态栏或 CMake Tools 面板里的 Build 可以直接构建 build/debug,底层使用 Ninja 并行编译。
CMake 还会跟踪:
User/xrobot.yaml
Modules/modules.yaml
这两个配置变化后,CMake 会先更新 XRobot 生成文件,再编译 rm_auto_aim。
仓库 task 也提供同一套完整流程:
Ctrl+Shift+B
→ Build: Webots debug
它会显式执行:
生成 XRobot 入口
→ configure build/debug
→ 并行编译 rm_auto_aim
两种入口共用 build/debug。刚打开工程时 CMake Tools 会先 configure,状态栏完成后即可 Build。
打开 Webots 场景
- 从开始菜单打开 Webots;
- 选择 File → Open World...;
- 打开:
webots/worlds/auto_aim_test_field_target_vehicle_camera_preview.wbt
- 点击工具栏的运行按钮。
场景中的机器人 self 使用 <extern> controller。Webots Console 会显示 external controller 地址,例如:
ipc://1234/self
tcp://<ip_address>:1234/self
后面连接 controller 时使用 Console 中显示的端口。
Webots 保持打开,controller 停止后它会继续等待下一次连接。
运行 controller
回到容器终端,先设置 controller 需要的环境变量。
假设 Webots Console 显示端口 1234:
export WEBOTS_CONTROLLER_URL=tcp://host.docker.internal:1234/self
export WEBOTS_SIM_FLOW_RATE=0.1
export XR_ARMOR_OPENVINO_DEVICE=CPU
export QT_QPA_PLATFORM=offscreen
再启动 controller:
./build/debug/rm_auto_aim
其中:
| 变量 | 作用 |
|---|---|
WEBOTS_CONTROLLER_URL | Docker 中的 controller 连接 Windows Webots |
WEBOTS_SIM_FLOW_RATE | 仿真运行倍率 |
XR_ARMOR_OPENVINO_DEVICE | OpenVINO 推理设备 |
QT_QPA_PLATFORM | 容器中不弹本地图形窗口 |
Windows Docker 环境使用 CPU:
export XR_ARMOR_OPENVINO_DEVICE=CPU
OpenVINO 还支持:
GPU
NPU
AUTO_DETECT
AUTO_DETECT 的顺序是:
NPU → GPU → CPU
显式指定设备时,OpenVINO 会直接使用该设备;设备不可用则启动失败。