From 1cffe576271ce481824c6b93fef1c791948440d6 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Tue, 15 Sep 2026 04:38:08 +0100 Subject: [PATCH 01/11] feat: adopt static module construction --- CMD.hpp | 168 ++++++++++++++++++++++++++++++-------------------------- 1 file changed, 91 insertions(+), 77 deletions(-) diff --git a/CMD.hpp b/CMD.hpp index 383e886..53e8727 100644 --- a/CMD.hpp +++ b/CMD.hpp @@ -3,11 +3,7 @@ /* clang-format off */ /* === MODULE MANIFEST V2 === module_description: 控制命令模块 -constructor_args: - - mode: CMD::Mode::CMD_OP_CTRL - - chassis_cmd_topic_name: "chassis_cmd" - - gimbal_cmd_topic_name: "gimbal_cmd" - - launcher_cmd_topic_name: "launcher_cmd" +depends: [] === END MANIFEST === */ /* clang-format on */ @@ -20,7 +16,6 @@ module_description: 控制命令模块 #include #include -#include "app_framework.hpp" #include "event.hpp" #include "libxr_def.hpp" #include "message.hpp" @@ -30,12 +25,14 @@ module_description: 控制命令模块 * @brief 控制命令处理类 * @details 接收来自不同控制源的命令,处理并转发到底盘和云台等执行单元 */ -class CMD : public LibXR::Application { +class CMD +{ public: /** * @brief 控制源枚举 */ - enum class ControlSource : uint8_t { + enum class ControlSource : uint8_t + { CTRL_SOURCE_RC, /* 遥控器控制源 */ CTRL_SOURCE_AI, /* AI控制源 */ CTRL_SOURCE_NUM /* 控制源数量 */ @@ -44,7 +41,8 @@ class CMD : public LibXR::Application { /** * @brief 遥控链路输入源枚举 */ - enum class RCInputSource : uint8_t { + enum class RCInputSource : uint8_t + { RC_INPUT_DR16, RC_INPUT_VT13, RC_INPUT_NUM @@ -53,7 +51,8 @@ class CMD : public LibXR::Application { /** * @brief 控制模式枚举 */ - enum class Mode : uint8_t { + enum class Mode : uint8_t + { CMD_OP_CTRL, /* 操作员控制模式 */ CMD_AUTO_CTRL, /* 自动控制模式 */ }; @@ -61,7 +60,8 @@ class CMD : public LibXR::Application { /** * @brief 底盘小模式枚举 */ - enum class ChasStat : int8_t { + enum class ChasStat : int8_t + { NONE = 0, /*无模式*/ BOOST = 1, /*加速*/ STRETCH = 2, /*伸腿*/ @@ -70,7 +70,8 @@ class CMD : public LibXR::Application { /** * @brief 底盘控制命令结构体 */ - typedef struct { + typedef struct + { float x; /* X轴方向控制量 */ float y; /* Y轴方向控制量 */ float z; /* Z轴方向控制量(旋转) */ @@ -80,7 +81,8 @@ class CMD : public LibXR::Application { /** * @brief 云台控制命令结构体 */ - typedef struct { + typedef struct + { float yaw; /* 偏航角(Yaw angle) */ float pit; /* 俯仰角(Pitch angle) */ float rol; /* 翻滚角(Roll angle) */ @@ -95,14 +97,16 @@ class CMD : public LibXR::Application { /** * @brief 发射控制命令结构体 */ - typedef struct { + typedef struct + { bool isfire; } LauncherCMD; /** * @brief 完整控制命令数据结构体 */ - typedef struct { + typedef struct + { GimbalCMD gimbal; /* 云台控制命令 */ ChassisCMD chassis; /* 底盘控制命令 */ LauncherCMD launcher; /* 发射控制命令 */ @@ -114,7 +118,8 @@ class CMD : public LibXR::Application { /** * @brief 控制事件ID */ - enum { + enum + { CMD_EVENT_START_CTRL = 0x13212508, /* 开始控制事件ID */ CMD_EVENT_LOST_CTRL = 0x13212509 /* 丢失控制事件ID */ }; @@ -125,9 +130,9 @@ class CMD : public LibXR::Application { */ Mode GetCtrlMode() { return this->mode_; } - bool GetAIGimbalStatus() { - return this->data_[static_cast(ControlSource::CTRL_SOURCE_AI)] - .gimbal_online; + bool GetAIGimbalStatus() + { + return this->data_[static_cast(ControlSource::CTRL_SOURCE_AI)].gimbal_online; } /** @@ -147,23 +152,27 @@ class CMD : public LibXR::Application { * @brief 直接写入遥控器控制数据 * @details 兼容接口,默认按DR16输入源写入 */ - void FeedRC(const Data& rc_data) { + void FeedRC(const Data& rc_data) + { this->FeedRC(RCInputSource::RC_INPUT_DR16, rc_data); } /** * @brief 按遥控输入源写入控制数据 */ - void FeedRC(RCInputSource source, const Data& rc_data) { + void FeedRC(RCInputSource source, const Data& rc_data) + { const auto source_index = static_cast(source); - if (source_index >= static_cast(RCInputSource::RC_INPUT_NUM)) { + if (source_index >= static_cast(RCInputSource::RC_INPUT_NUM)) + { return; } this->rc_input_data_[source_index] = rc_data; this->rc_input_seq_[source_index] = ++this->rc_update_seq_; - if (rc_data.chassis_online && this->IsRCInputActive(rc_data)) { + if (rc_data.chassis_online && this->IsRCInputActive(rc_data)) + { this->active_rc_input_ = source; } @@ -173,43 +182,39 @@ class CMD : public LibXR::Application { /** * @brief 直接写入 AI 控制数据 */ - void FeedAI(const Data& ai_data) { + void FeedAI(const Data& ai_data) + { this->data_[static_cast(ControlSource::CTRL_SOURCE_AI)] = ai_data; this->ProcessAndPublish(); } /** * @brief CMD构造函数 - * @param hw 硬件容器引用 - * @param app 应用管理器引用 * @param mode 控制模式,默认为操作员控制模式 * @param chassis_cmd_topic_name 底盘命令主题名称 * @param gimbal_cmd_topic_name 云台命令主题名称 */ - CMD(LibXR::HardwareContainer& hw, LibXR::ApplicationManager& app, Mode mode, - const char* chassis_cmd_topic_name, const char* gimbal_cmd_topic_name, + CMD(Mode mode, const char* chassis_cmd_topic_name, const char* gimbal_cmd_topic_name, const char* launcher_cmd_topic_name) : mode_(mode), - chassis_data_tp_(chassis_cmd_topic_name, sizeof(ChassisCMD), nullptr, - true), - gimbal_data_tp_(gimbal_cmd_topic_name, sizeof(GimbalCMD), nullptr, - true), - fire_data_tp_(launcher_cmd_topic_name, sizeof(LauncherCMD), nullptr, - true) { - UNUSED(hw); - UNUSED(app); + chassis_data_tp_( + LibXR::Topic::CreateTopic(chassis_cmd_topic_name, nullptr, true)), + gimbal_data_tp_( + LibXR::Topic::CreateTopic(gimbal_cmd_topic_name, nullptr, true)), + fire_data_tp_(LibXR::Topic::CreateTopic(launcher_cmd_topic_name, + nullptr, true)) + { /* 创建事件回调函数 */ auto callback = LibXR::Callback::Create( - [](bool in_isr, CMD* cmd, uint32_t event_id) { + [](bool in_isr, CMD* cmd, uint32_t event_id) + { UNUSED(in_isr); cmd->EventHandler(event_id); }, this); /* 注册控制模式事件处理回调 */ - this->cmd_event_.Register(static_cast(Mode::CMD_OP_CTRL), - callback); - this->cmd_event_.Register(static_cast(Mode::CMD_AUTO_CTRL), - callback); + this->cmd_event_.Register(static_cast(Mode::CMD_OP_CTRL), callback); + this->cmd_event_.Register(static_cast(Mode::CMD_AUTO_CTRL), callback); } /** @@ -224,9 +229,7 @@ class CMD : public LibXR::Application { * @param event_id 事件ID * @details 处理来自事件系统的控制模式切换请求 */ - void EventHandler(uint32_t event_id) { - this->SetCtrlMode(static_cast(event_id)); - } + void EventHandler(uint32_t event_id) { this->SetCtrlMode(static_cast(event_id)); } /** * @brief 注册控制器 @@ -235,14 +238,15 @@ class CMD : public LibXR::Application { * @details 将外部控制源的数据接入CMD系统,并进行预处理和分发 */ template - void RegisterController(LibXR::Topic& source) { + void RegisterController(LibXR::Topic& source) + { UNUSED(source); } /** * @brief 监控函数重写 */ - void OnMonitor() override {} + void OnMonitor() {} private: bool online_ = false; /* 在线状态 */ @@ -258,16 +262,14 @@ class CMD : public LibXR::Application { LibXR::Topic gimbal_data_tp_; /* 云台命令主题 */ LibXR::Topic fire_data_tp_; /* 开火命令主题 */ LibXR::Topic host_euler_data_tp_; /* 上位机欧拉角主题 */ - RCInputSource active_rc_input_ = - RCInputSource::RC_INPUT_DR16; /* 当前活动遥控输入源 */ - uint32_t rc_update_seq_ = 0; /* 遥控输入数据更新序号 */ + RCInputSource active_rc_input_ = RCInputSource::RC_INPUT_DR16; /* 当前活动遥控输入源 */ + uint32_t rc_update_seq_ = 0; /* 遥控输入数据更新序号 */ /*--------------------------工具函数-------------------------------------------------*/ - static bool IsRCInputOnline(const Data& rc_data) { - return rc_data.chassis_online; - } + static bool IsRCInputOnline(const Data& rc_data) { return rc_data.chassis_online; } - static bool IsRCInputActive(const Data& rc_data) { + static bool IsRCInputActive(const Data& rc_data) + { constexpr float RC_ACTIVITY_EPS = 0.05f; return std::fabs(rc_data.chassis.x) > RC_ACTIVITY_EPS || @@ -276,11 +278,11 @@ class CMD : public LibXR::Application { std::fabs(rc_data.gimbal.yaw) > RC_ACTIVITY_EPS || std::fabs(rc_data.gimbal.pit) > RC_ACTIVITY_EPS || std::fabs(rc_data.gimbal.rol) > RC_ACTIVITY_EPS || - (rc_data.chassis.self_define != ChasStat::NONE) || - rc_data.launcher.isfire; + (rc_data.chassis.self_define != ChasStat::NONE) || rc_data.launcher.isfire; } - static Data MakeOfflineRCData() { + static Data MakeOfflineRCData() + { Data rc_data{}; rc_data.chassis_online = false; rc_data.gimbal_online = false; @@ -288,33 +290,42 @@ class CMD : public LibXR::Application { return rc_data; } - Data SelectRCData() { + Data SelectRCData() + { const auto dr16_index = static_cast(RCInputSource::RC_INPUT_DR16); const auto vt13_index = static_cast(RCInputSource::RC_INPUT_VT13); const auto active_index = static_cast(this->active_rc_input_); /* 当前活动源在线则持续使用 */ if (active_index < static_cast(RCInputSource::RC_INPUT_NUM) && - this->IsRCInputOnline(this->rc_input_data_[active_index])) { + this->IsRCInputOnline(this->rc_input_data_[active_index])) + { return this->rc_input_data_[active_index]; } /* 活动源离线后切换 */ - if (this->active_rc_input_ == RCInputSource::RC_INPUT_DR16) { - if (this->IsRCInputOnline(this->rc_input_data_[vt13_index])) { + if (this->active_rc_input_ == RCInputSource::RC_INPUT_DR16) + { + if (this->IsRCInputOnline(this->rc_input_data_[vt13_index])) + { this->active_rc_input_ = RCInputSource::RC_INPUT_VT13; return this->rc_input_data_[vt13_index]; } - if (this->IsRCInputOnline(this->rc_input_data_[dr16_index])) { + if (this->IsRCInputOnline(this->rc_input_data_[dr16_index])) + { this->active_rc_input_ = RCInputSource::RC_INPUT_DR16; return this->rc_input_data_[dr16_index]; } - } else { - if (this->IsRCInputOnline(this->rc_input_data_[dr16_index])) { + } + else + { + if (this->IsRCInputOnline(this->rc_input_data_[dr16_index])) + { this->active_rc_input_ = RCInputSource::RC_INPUT_DR16; return this->rc_input_data_[dr16_index]; } - if (this->IsRCInputOnline(this->rc_input_data_[vt13_index])) { + if (this->IsRCInputOnline(this->rc_input_data_[vt13_index])) + { this->active_rc_input_ = RCInputSource::RC_INPUT_VT13; return this->rc_input_data_[vt13_index]; } @@ -323,35 +334,38 @@ class CMD : public LibXR::Application { return MakeOfflineRCData(); } - void ProcessAndPublish() { + void ProcessAndPublish() + { const Data rc_data = this->SelectRCData(); - const Data& ai_data = - this->data_[static_cast(ControlSource::CTRL_SOURCE_AI)]; + const Data& ai_data = this->data_[static_cast(ControlSource::CTRL_SOURCE_AI)]; this->data_[static_cast(ControlSource::CTRL_SOURCE_RC)] = rc_data; - if (!rc_data.chassis_online && this->online_) { + if (!rc_data.chassis_online && this->online_) + { this->cmd_event_.Active(CMD_EVENT_LOST_CTRL); this->online_ = false; - } else if (rc_data.chassis_online && !this->online_) { + } + else if (rc_data.chassis_online && !this->online_) + { this->cmd_event_.Active(CMD_EVENT_START_CTRL); this->online_ = true; } - if (this->mode_ == Mode::CMD_OP_CTRL) { + if (this->mode_ == Mode::CMD_OP_CTRL) + { Data out = rc_data; this->gimbal_data_tp_.Publish(out.gimbal); this->chassis_data_tp_.Publish(out.chassis); this->fire_data_tp_.Publish(out.launcher); - } else { + } + else + { /* CMD_AUTO_CTRL */ - ChassisCMD out_chassis = - ai_data.chassis_online ? ai_data.chassis : rc_data.chassis; - GimbalCMD out_gimbal = - ai_data.gimbal_online ? ai_data.gimbal : rc_data.gimbal; + ChassisCMD out_chassis = ai_data.chassis_online ? ai_data.chassis : rc_data.chassis; + GimbalCMD out_gimbal = ai_data.gimbal_online ? ai_data.gimbal : rc_data.gimbal; LauncherCMD out_launcher; - out_launcher.isfire = - (ai_data.launcher.isfire && rc_data.launcher.isfire); + out_launcher.isfire = (ai_data.launcher.isfire && rc_data.launcher.isfire); ChassisCMD chassis = out_chassis; GimbalCMD gimbal = out_gimbal; From 57de95b1dee06953b38eef19b507bdece4d3dd95 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Fri, 18 Sep 2026 01:50:34 +0100 Subject: [PATCH 02/11] Migrate to static assembly --- .github/workflows/build.yml | 239 ++++++++++++++++++------------------ CMD.hpp | 7 +- 2 files changed, 126 insertions(+), 120 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index ace43a9..3e201c8 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -1,129 +1,132 @@ name: XRobot Module Build Test - -on: - push: - pull_request: +'on': + push: null + pull_request: null schedule: - - cron: '0 3 1 * *' # 每月1日凌晨3点(UTC)自动触发 - + - cron: 0 3 1 * * +permissions: + contents: read jobs: build: runs-on: ubuntu-latest container: image: ghcr.io/xrobot-org/docker-image-linux:main options: --user 0 - env: + XR_MODULE_ID: ${{ github.repository }} XR_MODULE_NAME: ${{ github.event.repository.name }} - + XR_REF_NAME: ${{ github.head_ref || github.ref_name }} + XR_REF_KIND: ${{ github.ref_type }} + XR_TEMPLATE_ARGS: '[]' + XROBOT_REF: ${{ vars.XROBOT_REF || '' }} + LIBXR_REF: ${{ vars.LIBXR_REF || '' }} + PYTHONPATH: ${{ github.workspace }}/XRobot/src steps: - - name: Checkout current module repo to ./Modules/${{ env.XR_MODULE_NAME }} - uses: actions/checkout@v4 - with: - path: Modules/${{ env.XR_MODULE_NAME }} - - - name: Create main.cpp - run: | - cat > main.cpp <<'EOF' - #include - #include "xrobot_main.hpp" - #include "libxr.hpp" - - int main() { - LibXR::PlatformInit(); - LibXR::STDIO::Printf<"This is XRobot Module Template Test\n">(); - LibXR::HardwareContainer hw; - XRobotMain(hw); - return 0; - } - EOF - - - name: Create minimal CMakeLists.txt - run: | - cat > CMakeLists.txt <<'EOF' - project(xrobot_mod_test CXX) - set(CMAKE_CXX_STANDARD 20) - add_executable(xr_test main.cpp) - set(XROBOT_MODULES_DIR ${CMAKE_CURRENT_SOURCE_DIR}/Modules/) - add_subdirectory(libxr) - target_include_directories(xr_test PUBLIC $ ${CMAKE_SOURCE_DIR}/User) - target_link_libraries(xr_test PUBLIC xr) - EOF - - - name: Pull libxr to ./libxr - run: git clone --depth=1 https://github.com/Jiu-xiao/libxr ./libxr - - - name: Checkout DR16 module - uses: actions/checkout@v4 - with: - repository: QDU-Robomaster/DR16 - path: Modules/DR16 - - - name: Setup Python & Install deps - run: | - python3 -m pip install --upgrade pip - pip3 install pyyaml requests - - - name: Add XRobot tools to PATH - run: | - echo "$HOME/.local/bin" >> $GITHUB_PATH - - - name: Install xrobot toolchain (assumes pyproject/tar.gz/pip install .) - run: | - pip3 install xrobot libxr - - - name: Run xrobot_setup - run: | - xrobot_setup || true - - - name: Run xrobot_init_mod - run: | - xrobot_init_mod - - - name: Add modules - run: | - xrobot_add_mod BlinkLED --instance-id BlinkLED_0 - - - name: Add this repo module - run: | - xrobot_add_mod ${{ env.XR_MODULE_NAME }} --instance-id cmd - xrobot_add_mod DR16 --instance-id dr16 && cat User/xrobot.yaml - - - name: Generate main again - run: | - xrobot_setup - - - name: Build - run: | - mkdir -p build - cd build - cmake .. - make - - - name: Create Tag via GitHub API - if: ${{ success() && github.event_name != 'pull_request' }} - uses: actions/github-script@v7 - with: - github-token: ${{ secrets.GITHUB_TOKEN }} - script: | - const moduleTag = process.env.XR_MODULE_NAME; - const date = new Date(); - const yyyy = date.getUTCFullYear(); - const mm = String(date.getUTCMonth() + 1).padStart(2, '0'); - const dd = String(date.getUTCDate()).padStart(2, '0'); - const HH = String(date.getUTCHours()).padStart(2, '0'); - const MM = String(date.getUTCMinutes()).padStart(2, '0'); - const SS = String(date.getUTCSeconds()).padStart(2, '0'); - const tagName = `${moduleTag}-${yyyy}${mm}${dd}-${HH}${MM}${SS}`; - - // 获取当前 commit sha - const sha = process.env.GITHUB_SHA; - - // 创建 tag reference - await github.rest.git.createRef({ - owner: context.repo.owner, - repo: context.repo.repo, - ref: `refs/tags/${tagName}`, - sha: sha - }); - console.log(`Created tag: ${tagName} on sha: ${sha}`); + - name: Checkout the exact Module revision + uses: actions/checkout@v4 + with: + path: Modules/${{ github.repository }} + ref: ${{ github.event.pull_request.head.sha || github.sha }} + submodules: recursive + - name: Checkout matching core tools + shell: bash + run: | + set -euo pipefail + checkout_tool() { + local repo="$1" directory="$2" selected="$3" available + if [[ -n "$selected" ]]; then + if [[ "$selected" != refs/heads/* && "$selected" != refs/tags/* && + ! "$selected" =~ ^[0-9a-fA-F]{40}$ ]]; then + echo "Use a full refs/heads/, refs/tags/ or commit SHA for $directory" >&2 + return 1 + fi + elif [[ "$XR_REF_KIND" == tag ]]; then + selected="refs/tags/$XR_REF_NAME" + else + available=$(git ls-remote --heads "$repo" "refs/heads/$XR_REF_NAME") + if [[ -n "$available" ]]; then + selected="refs/heads/$XR_REF_NAME" + else + selected=refs/heads/dev + fi + fi + git init "$directory" + git -C "$directory" remote add origin "$repo" + git -C "$directory" fetch --depth=1 origin "$selected" + git -C "$directory" checkout --detach FETCH_HEAD + git -C "$directory" submodule update --init --recursive --depth=1 + } + checkout_tool https://github.com/xrobot-org/XRobot.git XRobot "$XROBOT_REF" + checkout_tool https://github.com/xrobot-org/libxr.git libxr "$LIBXR_REF" + - name: Install build dependencies + run: | + apt-get update + apt-get install -y --no-install-recommends libgpiod-dev + python3 -m pip install ./XRobot + - name: Resolve sources and generate the compile-only constructor + run: | + python3 - <<'PYCODE' + import json + import os + from pathlib import Path + import subprocess + import yaml + from xrobot.InitModule import sync_modules_by_config + from xrobot.GenerateMain import generate_compile_check + from xrobot.ModuleParser import load_single_module + from xrobot.SourceManager import validate_id + + identity = validate_id(os.environ['XR_MODULE_ID']) + folder = Path('Modules') / identity + + def git(*args): + return subprocess.check_output(['git', '-C', str(folder), *args], text=True).strip() + + def write_yaml(path, data): + Path(path).write_text(yaml.safe_dump(data, sort_keys=False), encoding='utf-8') + + # Pin the checked-out PR/branch commit. Only its logical dependency context moves. + context = ('refs/tags/' if os.environ['XR_REF_KIND'] == 'tag' else 'refs/heads/') + context += os.environ['XR_REF_NAME'] + write_yaml('ci-index.yaml', {'modules': [{'id': identity, 'repo': git('remote', 'get-url', 'origin')}]}) + write_yaml('Modules/sources.yaml', {'sources': [ + {'url': 'https://xrobot.work/xrobot-modules/index.yaml', 'priority': 0}, + {'url': 'https://qdu-robomaster.github.io/qdu-future-modules/index.yaml', 'priority': 0}, + {'url': '../ci-index.yaml', 'priority': -100}, + ]}) + write_yaml('Modules/modules.yaml', {'modules': [{ + 'id': identity, 'ref': git('rev-parse', 'HEAD'), 'context_ref': context, + }]}) + sync_modules_by_config('Modules/modules.yaml', 'Modules/sources.yaml', 'Modules') + manifest = load_single_module(folder) + if manifest.standalone: + generate_compile_check(identity, 'Modules', 'module_check.cpp', + json.loads(os.environ['XR_TEMPLATE_ARGS'])) + else: + # A library has no Module constructor. Its actual .cpp files still build in xr. + Path('module_check.cpp').write_text('#include "' + folder.name + '.hpp"\n', encoding='utf-8') + PYCODE + - name: Create native CMake project + run: | + cat > CMakeLists.txt <<'CMAKE' + cmake_minimum_required(VERSION 3.16) + project(xrobot_module_compile LANGUAGES C CXX ASM) + set(CMAKE_CXX_STANDARD 20) + set(CMAKE_CXX_STANDARD_REQUIRED ON) + set(LIBXR_SYSTEM linux CACHE STRING "LibXR execution backend") + set(LIBXR_DRIVER linux CACHE STRING "LibXR driver backend") + set(LIBXR_PRINT_INTEGER_ENABLE_64BIT ON CACHE BOOL "") + set(LIBXR_PRINT_FLOAT_ENABLE_DOUBLE ON CACHE BOOL "") + set(LIBXR_PRINT_ENABLE_POINTER ON CACHE BOOL "") + set(XROBOT_MODULES_DIR "${CMAKE_CURRENT_SOURCE_DIR}/Modules") + include(CTest) + add_subdirectory(libxr) + set_property(TARGET xr PROPERTY CXX_STANDARD 20) + set_property(TARGET xr PROPERTY CXX_STANDARD_REQUIRED ON) + add_library(module_check OBJECT module_check.cpp) + target_link_libraries(module_check PRIVATE xr) + CMAKE + - name: Compile Module sources and constructor + run: | + cmake -S . -B build -DBUILD_TESTING=OFF + cmake --build build --parallel 2 diff --git a/CMD.hpp b/CMD.hpp index 53e8727..556edd2 100644 --- a/CMD.hpp +++ b/CMD.hpp @@ -194,8 +194,11 @@ class CMD * @param chassis_cmd_topic_name 底盘命令主题名称 * @param gimbal_cmd_topic_name 云台命令主题名称 */ - CMD(Mode mode, const char* chassis_cmd_topic_name, const char* gimbal_cmd_topic_name, - const char* launcher_cmd_topic_name) + CMD( + Mode mode = CMD::Mode::CMD_OP_CTRL, + const char* chassis_cmd_topic_name = "chassis_cmd", + const char* gimbal_cmd_topic_name = "gimbal_cmd", + const char* launcher_cmd_topic_name = "launcher_cmd") : mode_(mode), chassis_data_tp_( LibXR::Topic::CreateTopic(chassis_cmd_topic_name, nullptr, true)), From e623c714e96c7deff40ef1d8aae2572c04fc9204 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Mon, 28 Sep 2026 20:55:13 +0100 Subject: [PATCH 03/11] Remove the empty OnMonitor hook The static-assembly entry calls OnMonitor() only for modules that declare it; the empty body was left over from the removed application framework. --- CMD.hpp | 5 ----- 1 file changed, 5 deletions(-) diff --git a/CMD.hpp b/CMD.hpp index 556edd2..0bec939 100644 --- a/CMD.hpp +++ b/CMD.hpp @@ -246,11 +246,6 @@ class CMD UNUSED(source); } - /** - * @brief 监控函数重写 - */ - void OnMonitor() {} - private: bool online_ = false; /* 在线状态 */ Mode mode_; /* 当前控制模式 */ From 59e0852b1654ec30777f6388a30e5f4d1165d24a Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Mon, 28 Sep 2026 21:51:25 +0100 Subject: [PATCH 04/11] Add the Apache-2.0 license The XRobot ecosystem Modules are published under the Apache License 2.0; the text is identical to xrobot-org/XRobot/LICENSE. --- LICENSE | 202 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 202 insertions(+) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..d645695 --- /dev/null +++ b/LICENSE @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. From 350c9d840ebfbc2b7b4073253a0bad48d5498a91 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Mon, 28 Sep 2026 21:53:34 +0100 Subject: [PATCH 05/11] Use the shared XRobot Module CI workflow Replace the generated inline workflow with a caller of xrobot-org/XRobot/.github/workflows/module-ci.yml, which resolves the dependencies, compiles the Module sources and a generated constructor probe against LibXR. During the coordinated 1.0 change the tools, LibXR and same-or-dev dependencies come from dev. --- .github/workflows/build.yml | 141 +++--------------------------------- 1 file changed, 11 insertions(+), 130 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 3e201c8..591717e 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -1,132 +1,13 @@ -name: XRobot Module Build Test -'on': - push: null - pull_request: null - schedule: - - cron: 0 3 1 * * -permissions: - contents: read +name: Module CI +on: + push: + pull_request: + workflow_dispatch: jobs: build: - runs-on: ubuntu-latest - container: - image: ghcr.io/xrobot-org/docker-image-linux:main - options: --user 0 - env: - XR_MODULE_ID: ${{ github.repository }} - XR_MODULE_NAME: ${{ github.event.repository.name }} - XR_REF_NAME: ${{ github.head_ref || github.ref_name }} - XR_REF_KIND: ${{ github.ref_type }} - XR_TEMPLATE_ARGS: '[]' - XROBOT_REF: ${{ vars.XROBOT_REF || '' }} - LIBXR_REF: ${{ vars.LIBXR_REF || '' }} - PYTHONPATH: ${{ github.workspace }}/XRobot/src - steps: - - name: Checkout the exact Module revision - uses: actions/checkout@v4 - with: - path: Modules/${{ github.repository }} - ref: ${{ github.event.pull_request.head.sha || github.sha }} - submodules: recursive - - name: Checkout matching core tools - shell: bash - run: | - set -euo pipefail - checkout_tool() { - local repo="$1" directory="$2" selected="$3" available - if [[ -n "$selected" ]]; then - if [[ "$selected" != refs/heads/* && "$selected" != refs/tags/* && - ! "$selected" =~ ^[0-9a-fA-F]{40}$ ]]; then - echo "Use a full refs/heads/, refs/tags/ or commit SHA for $directory" >&2 - return 1 - fi - elif [[ "$XR_REF_KIND" == tag ]]; then - selected="refs/tags/$XR_REF_NAME" - else - available=$(git ls-remote --heads "$repo" "refs/heads/$XR_REF_NAME") - if [[ -n "$available" ]]; then - selected="refs/heads/$XR_REF_NAME" - else - selected=refs/heads/dev - fi - fi - git init "$directory" - git -C "$directory" remote add origin "$repo" - git -C "$directory" fetch --depth=1 origin "$selected" - git -C "$directory" checkout --detach FETCH_HEAD - git -C "$directory" submodule update --init --recursive --depth=1 - } - checkout_tool https://github.com/xrobot-org/XRobot.git XRobot "$XROBOT_REF" - checkout_tool https://github.com/xrobot-org/libxr.git libxr "$LIBXR_REF" - - name: Install build dependencies - run: | - apt-get update - apt-get install -y --no-install-recommends libgpiod-dev - python3 -m pip install ./XRobot - - name: Resolve sources and generate the compile-only constructor - run: | - python3 - <<'PYCODE' - import json - import os - from pathlib import Path - import subprocess - import yaml - from xrobot.InitModule import sync_modules_by_config - from xrobot.GenerateMain import generate_compile_check - from xrobot.ModuleParser import load_single_module - from xrobot.SourceManager import validate_id - - identity = validate_id(os.environ['XR_MODULE_ID']) - folder = Path('Modules') / identity - - def git(*args): - return subprocess.check_output(['git', '-C', str(folder), *args], text=True).strip() - - def write_yaml(path, data): - Path(path).write_text(yaml.safe_dump(data, sort_keys=False), encoding='utf-8') - - # Pin the checked-out PR/branch commit. Only its logical dependency context moves. - context = ('refs/tags/' if os.environ['XR_REF_KIND'] == 'tag' else 'refs/heads/') - context += os.environ['XR_REF_NAME'] - write_yaml('ci-index.yaml', {'modules': [{'id': identity, 'repo': git('remote', 'get-url', 'origin')}]}) - write_yaml('Modules/sources.yaml', {'sources': [ - {'url': 'https://xrobot.work/xrobot-modules/index.yaml', 'priority': 0}, - {'url': 'https://qdu-robomaster.github.io/qdu-future-modules/index.yaml', 'priority': 0}, - {'url': '../ci-index.yaml', 'priority': -100}, - ]}) - write_yaml('Modules/modules.yaml', {'modules': [{ - 'id': identity, 'ref': git('rev-parse', 'HEAD'), 'context_ref': context, - }]}) - sync_modules_by_config('Modules/modules.yaml', 'Modules/sources.yaml', 'Modules') - manifest = load_single_module(folder) - if manifest.standalone: - generate_compile_check(identity, 'Modules', 'module_check.cpp', - json.loads(os.environ['XR_TEMPLATE_ARGS'])) - else: - # A library has no Module constructor. Its actual .cpp files still build in xr. - Path('module_check.cpp').write_text('#include "' + folder.name + '.hpp"\n', encoding='utf-8') - PYCODE - - name: Create native CMake project - run: | - cat > CMakeLists.txt <<'CMAKE' - cmake_minimum_required(VERSION 3.16) - project(xrobot_module_compile LANGUAGES C CXX ASM) - set(CMAKE_CXX_STANDARD 20) - set(CMAKE_CXX_STANDARD_REQUIRED ON) - set(LIBXR_SYSTEM linux CACHE STRING "LibXR execution backend") - set(LIBXR_DRIVER linux CACHE STRING "LibXR driver backend") - set(LIBXR_PRINT_INTEGER_ENABLE_64BIT ON CACHE BOOL "") - set(LIBXR_PRINT_FLOAT_ENABLE_DOUBLE ON CACHE BOOL "") - set(LIBXR_PRINT_ENABLE_POINTER ON CACHE BOOL "") - set(XROBOT_MODULES_DIR "${CMAKE_CURRENT_SOURCE_DIR}/Modules") - include(CTest) - add_subdirectory(libxr) - set_property(TARGET xr PROPERTY CXX_STANDARD 20) - set_property(TARGET xr PROPERTY CXX_STANDARD_REQUIRED ON) - add_library(module_check OBJECT module_check.cpp) - target_link_libraries(module_check PRIVATE xr) - CMAKE - - name: Compile Module sources and constructor - run: | - cmake -S . -B build -DBUILD_TESTING=OFF - cmake --build build --parallel 2 + uses: xrobot-org/XRobot/.github/workflows/module-ci.yml@dev + with: + xrobot-ref: dev + libxr-ref: dev + dependency-ref: refs/heads/dev + template-args: '[]' From de75d238def422100da5ff588c3d13c261efe0a6 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Mon, 28 Sep 2026 22:05:15 +0100 Subject: [PATCH 06/11] Rewrite the README for XRobot 1.0 Describe the Module, its dependencies, its constructor (dependencies first, then the value configuration) and its use with xrobot module add / setup / instance add, with a configuration example seeded by the tool. Drop the dynamic-framework text and the dead MIGRATION.md link. --- README.md | 138 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 78 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 7569c8e..a35b58b 100644 --- a/README.md +++ b/README.md @@ -2,76 +2,94 @@ 用于统一汇总控制输入并发布控制命令的中枢模块。 -CMD 把不同来源(例如遥控、上位机)统一整理为三路命令: - -1. 底盘命令 -2. 云台命令 -3. 发射命令 - -## 解决什么问题 - -CMD 主要解决三件事: - -1. 统一控制源输入接口(`FeedRC` / `FeedAI`)。 -2. 统一控制模式切换(操作手/自动等)。 -3. 统一命令发布出口(下游模块只订阅 Topic,不关心输入来源)。 - -## 核心流程 - -CMD 的典型流程是: - -1. 输入模块调用 `FeedRC(...)` 或 `FeedAI(...)`。 -2. CMD 内部执行 `ProcessAndPublish()`。 -3. 发布 `chassis_cmd`、`gimbal_cmd`、`launcher_cmd`。 -4. 底盘/云台/发射模块各自订阅并执行。 +CMD 把不同来源(遥控器 DR16 / VT13、上位机等)的输入统一整理为三路命令 Topic: +底盘命令、云台命令、发射命令。下游模块只订阅 Topic,不关心输入来源。 + +## 行为 + +- 输入模块调用 `FeedRC(...)` 或 `FeedAI(...)` 喂入 `CMD::Data`;每次喂入都会立即执行 + `ProcessAndPublish()` 并发布三路命令。CMD 自身不创建线程,没有输入时不发布。 +- 遥控输入分 DR16 与 VT13 两路(`FeedRC(RCInputSource, const Data&)`; + `FeedRC(const Data&)` 按 DR16 处理)。某一路在线(`chassis_online`)且有操作 + (摇杆绝对值 > 0.05、自定义底盘模式或开火)时成为活动源;活动源离线后切换到另一路在线源; + 两路都离线时使用离线(全零)数据。 +- 控制模式: + - `CMD_OP_CTRL`(操作手):直接发布遥控数据。 + - `CMD_AUTO_CTRL`(自动):底盘 / 云台命令在 AI 数据的 `chassis_online` / + `gimbal_online` 为真时取 AI 数据,否则取遥控数据;开火需要 AI 和遥控同时开火。 +- 遥控在线状态变化时在 CMD 的事件上触发 `CMD_EVENT_START_CTRL`(`0x13212508`)或 + `CMD_EVENT_LOST_CTRL`(`0x13212509`)。 + +## Topic + +| Topic(默认名) | 类型 | 内容 | +| --- | --- | --- | +| `chassis_cmd` | `CMD::ChassisCMD` | `x`、`y`、`z`(旋转)控制量与 `self_define`(`NONE` / `BOOST` / `STRETCH`) | +| `gimbal_cmd` | `CMD::GimbalCMD` | `yaw`、`pit`、`rol` 及其一阶、二阶导数 | +| `launcher_cmd` | `CMD::LauncherCMD` | `isfire` | + +三个 Topic 都以多发布者模式创建。 + +## 接口 + +- `FeedRC(const Data&)` / `FeedRC(RCInputSource, const Data&)`:喂入遥控数据。 +- `FeedAI(const Data&)`:喂入上位机 / 自动控制数据。 +- `SetCtrlMode(Mode)` / `GetCtrlMode()`:切换 / 读取控制模式。 +- `GetEvent()`:返回 CMD 的 `LibXR::Event`。在其上激活事件 ID + `static_cast(CMD::Mode::CMD_OP_CTRL)` 或 `CMD_AUTO_CTRL` 会切换模式 + (`EventHandler()`);EventBinder 等模块通过它绑定事件。 +- `Online()`:遥控是否在线;`GetAIGimbalStatus()`:AI 数据的 `gimbal_online`。 + +## 依赖 + +无其他模块依赖,仅使用 LibXR。DR16、VT13 以及底盘、云台、发射等模块依赖本模块。 + +## 构造接口 + +```cpp +CMD(Mode mode = CMD::Mode::CMD_OP_CTRL, + const char* chassis_cmd_topic_name = "chassis_cmd", + const char* gimbal_cmd_topic_name = "gimbal_cmd", + const char* launcher_cmd_topic_name = "launcher_cmd"); +``` -关键函数: +无依赖参数。 -1. `FeedRC(const Data&)`:喂入遥控控制数据。 -2. `FeedAI(const Data&)`:喂入上位机/自动控制数据。 -3. `SetCtrlMode(Mode)`:切换控制模式。 -4. `EventHandler(uint32_t)`:响应外部事件切换模式。 -5. `ProcessAndPublish()`:统一整理并发布命令。 -6. `GetEvent()`:提供事件绑定入口给 EventBinder 等模块使用。 +配置: -## 最小接入示例 +- `mode`:初始控制模式,`CMD::Mode::CMD_OP_CTRL` 或 `CMD::Mode::CMD_AUTO_CTRL`, + 默认 `CMD_OP_CTRL`。 +- `chassis_cmd_topic_name`:底盘命令 Topic 名,默认 `"chassis_cmd"`。 +- `gimbal_cmd_topic_name`:云台命令 Topic 名,默认 `"gimbal_cmd"`。 +- `launcher_cmd_topic_name`:发射命令 Topic 名,默认 `"launcher_cmd"`。 -1. 添加模块: +## 使用 -```bash -xrobot_add_mod CMD --instance-id cmd -xrobot_gen_main +```sh +xrobot module add QDU-Robomaster/CMD +xrobot setup +xrobot instance add QDU-Robomaster/CMD ``` -2. 典型配置(来自模块 manifest): +`xrobot instance add` 在 `User/xrobot.yaml` 中写入一个实例,默认值按源码写出(CMD 没有 +依赖参数): ```yaml -module: CMD -entry_header: Modules/CMD/CMD.hpp -constructor_args: - - mode: CMD::Mode::CMD_OP_CTRL - - chassis_cmd_topic_name: "chassis_cmd" - - gimbal_cmd_topic_name: "gimbal_cmd" - - launcher_cmd_topic_name: "launcher_cmd" -template_args: [] +modules: + - module: QDU-Robomaster/CMD + id: cmd_0 + args: + - mode: CMD::Mode::CMD_OP_CTRL + - chassis_cmd_topic_name: '"chassis_cmd"' + - gimbal_cmd_topic_name: '"gimbal_cmd"' + - launcher_cmd_topic_name: '"launcher_cmd"' ``` -3. 下游模块只需订阅对应命令 Topic。 - -## 使用约定 - -1. 推荐先初始化 CMD,再初始化依赖它的控制模块。 -2. 控制源切换尽量都走 CMD 的 `SetCtrlMode` / 事件入口。 -3. 不同来源数据结构最终都转换成 `CMD::Data` 再进入 CMD。 +CMD 不需要 BSP 对象,因此不需要 `XR_REGISTER`。其他模块(如 DR16、VT13)以 +`CMD&` 参数引用它时填写 CMD 的实例 id(上例为 `cmd_0`),并且 CMD 必须在 `modules:` +中排在它们前面。 -## 模块信息 +填好后再次运行 `xrobot setup`,生成 `User/xrobot_main.hpp`。 -1. 代码入口:`Modules/CMD/CMD.hpp` -2. Required Hardware:None -3. Constructor Arguments: - - `mode` - - `chassis_cmd_topic_name` - - `gimbal_cmd_topic_name` - - `launcher_cmd_topic_name` -4. Template Arguments:None -5. Depends:None +`xrobot module show .`(在本仓库中)或 `xrobot module show Modules/QDU-Robomaster/CMD` +(在 BSP 中)打印 manifest 和当前的构造函数。 From 74f1c156fd234aafb50d8088c59b2d44726c8b9c Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Sat, 3 Oct 2026 18:07:25 +0100 Subject: [PATCH 07/11] Rewrite the README to the Module README structure --- README.md | 150 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 91 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index a35b58b..6c074f7 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,56 @@ # CMD -用于统一汇总控制输入并发布控制命令的中枢模块。 +控制命令中枢:汇总遥控器与上位机输入,发布底盘、云台、发射命令 / Control command hub that merges remote-controller and host inputs and publishes chassis, gimbal and launcher commands -CMD 把不同来源(遥控器 DR16 / VT13、上位机等)的输入统一整理为三路命令 Topic: -底盘命令、云台命令、发射命令。下游模块只订阅 Topic,不关心输入来源。 +## 1. 模块作用 / Purpose -## 行为 +CMD 把遥控器(DR16、VT13)与上位机等来源的输入整理为三路命令 Topic:底盘命令、云台命令、发射命令。下游 Module 订阅这三个 Topic,输入来源由 CMD 内部选择。 -- 输入模块调用 `FeedRC(...)` 或 `FeedAI(...)` 喂入 `CMD::Data`;每次喂入都会立即执行 - `ProcessAndPublish()` 并发布三路命令。CMD 自身不创建线程,没有输入时不发布。 -- 遥控输入分 DR16 与 VT13 两路(`FeedRC(RCInputSource, const Data&)`; - `FeedRC(const Data&)` 按 DR16 处理)。某一路在线(`chassis_online`)且有操作 - (摇杆绝对值 > 0.05、自定义底盘模式或开火)时成为活动源;活动源离线后切换到另一路在线源; - 两路都离线时使用离线(全零)数据。 -- 控制模式: - - `CMD_OP_CTRL`(操作手):直接发布遥控数据。 - - `CMD_AUTO_CTRL`(自动):底盘 / 云台命令在 AI 数据的 `chassis_online` / - `gimbal_online` 为真时取 AI 数据,否则取遥控数据;开火需要 AI 和遥控同时开火。 -- 遥控在线状态变化时在 CMD 的事件上触发 `CMD_EVENT_START_CTRL`(`0x13212508`)或 - `CMD_EVENT_LOST_CTRL`(`0x13212509`)。 +输入由其他 Module 调用 `FeedRC(...)` 或 `FeedAI(...)` 写入 `CMD::Data`,每次写入立即执行一轮处理并发布三路命令。CMD 自身不创建线程,由输入 Module 的调用驱动发布。 -## Topic +遥控器在线状态变化时,CMD 在自己的事件上激活 `CMD_EVENT_START_CTRL`(`0x13212508`,遥控器上线)或 `CMD_EVENT_LOST_CTRL`(`0x13212509`,遥控器离线)。 -| Topic(默认名) | 类型 | 内容 | -| --- | --- | --- | -| `chassis_cmd` | `CMD::ChassisCMD` | `x`、`y`、`z`(旋转)控制量与 `self_define`(`NONE` / `BOOST` / `STRETCH`) | -| `gimbal_cmd` | `CMD::GimbalCMD` | `yaw`、`pit`、`rol` 及其一阶、二阶导数 | -| `launcher_cmd` | `CMD::LauncherCMD` | `isfire` | +CMD merges the input of the remote controllers (DR16, VT13) and of the host into three command Topics: the chassis command, the gimbal command and the launcher command. Downstream Modules subscribe to these Topics, and CMD selects the input source internally. -三个 Topic 都以多发布者模式创建。 +Other Modules write a `CMD::Data` through `FeedRC(...)` or `FeedAI(...)`; every write runs one processing pass and publishes the three commands immediately. CMD creates no thread of its own, and the publishing is driven by the calls of the input Modules. -## 接口 +When the remote-controller online state changes, CMD activates `CMD_EVENT_START_CTRL` (`0x13212508`, remote controller online) or `CMD_EVENT_LOST_CTRL` (`0x13212509`, remote controller offline) on its own event. -- `FeedRC(const Data&)` / `FeedRC(RCInputSource, const Data&)`:喂入遥控数据。 -- `FeedAI(const Data&)`:喂入上位机 / 自动控制数据。 -- `SetCtrlMode(Mode)` / `GetCtrlMode()`:切换 / 读取控制模式。 -- `GetEvent()`:返回 CMD 的 `LibXR::Event`。在其上激活事件 ID - `static_cast(CMD::Mode::CMD_OP_CTRL)` 或 `CMD_AUTO_CTRL` 会切换模式 - (`EventHandler()`);EventBinder 等模块通过它绑定事件。 -- `Online()`:遥控是否在线;`GetAIGimbalStatus()`:AI 数据的 `gimbal_online`。 +## 2. 输入源与控制模式 / Input Sources and Control Modes -## 依赖 +遥控输入分 DR16 与 VT13 两路:`FeedRC(RCInputSource, const Data&)` 指定输入源,`FeedRC(const Data&)` 使用 DR16。某一路写入的数据 `chassis_online` 为真,且存在操作时,该路成为活动源。存在操作指:底盘 `x`、`y`、`z` 或云台 `yaw`、`pit`、`rol` 的绝对值大于 0.05,底盘 `self_define` 不为 `NONE`,或 `launcher.isfire` 为真。活动源在线时持续使用;活动源离线后切换到另一路在线源;两路都离线时使用全零的离线数据。 -无其他模块依赖,仅使用 LibXR。DR16、VT13 以及底盘、云台、发射等模块依赖本模块。 +控制模式决定发布的内容: -## 构造接口 +- `CMD_OP_CTRL`(操作手控制):发布遥控数据。 +- `CMD_AUTO_CTRL`(自动控制):底盘命令在 AI 数据的 `chassis_online` 为真时取 AI 数据,否则取遥控数据;云台命令在 AI 数据的 `gimbal_online` 为真时取 AI 数据,否则取遥控数据;发射命令在 AI 与遥控的 `isfire` 同时为真时开火。 + +接口: + +- `FeedRC(const Data&)`、`FeedRC(RCInputSource, const Data&)`:写入遥控数据。 +- `FeedAI(const Data&)`:写入上位机或自动控制数据。 +- `SetCtrlMode(Mode)`、`GetCtrlMode()`:设置、读取控制模式。 +- `GetEvent()`:返回 CMD 的 `LibXR::Event`。在其上激活事件 ID `static_cast(CMD::Mode::CMD_OP_CTRL)` 或 `static_cast(CMD::Mode::CMD_AUTO_CTRL)` 即切换到对应的控制模式,`EventBinder` 等 Module 通过它绑定事件。 +- `Online()`:遥控器是否在线。 +- `GetAIGimbalStatus()`:AI 数据的 `gimbal_online`。 + +The remote-controller input has two channels, DR16 and VT13: `FeedRC(RCInputSource, const Data&)` names the input source and `FeedRC(const Data&)` uses DR16. A channel becomes the active source when the data written to it has `chassis_online` true and contains an operation. An operation means that the absolute value of the chassis `x`, `y`, `z` or of the gimbal `yaw`, `pit`, `rol` is greater than 0.05, that the chassis `self_define` is not `NONE`, or that `launcher.isfire` is true. The active source is used as long as it is online; when it goes offline, CMD switches to the other channel if that one is online; when both are offline, the all-zero offline data is used. + +The control mode determines what is published: + +- `CMD_OP_CTRL` (operator control): the remote-controller data is published. +- `CMD_AUTO_CTRL` (automatic control): the chassis command is taken from the AI data when its `chassis_online` is true, otherwise from the remote controller; the gimbal command is taken from the AI data when its `gimbal_online` is true, otherwise from the remote controller; the launcher fires when the `isfire` of both the AI data and the remote controller is true. + +Interface: + +- `FeedRC(const Data&)`, `FeedRC(RCInputSource, const Data&)`: write remote-controller data. +- `FeedAI(const Data&)`: write host or automatic control data. +- `SetCtrlMode(Mode)`, `GetCtrlMode()`: set and read the control mode. +- `GetEvent()`: returns the `LibXR::Event` of CMD. Activating the event ID `static_cast(CMD::Mode::CMD_OP_CTRL)` or `static_cast(CMD::Mode::CMD_AUTO_CTRL)` on it switches to the corresponding control mode; Modules such as `EventBinder` bind events through it. +- `Online()`: whether the remote controller is online. +- `GetAIGimbalStatus()`: the `gimbal_online` of the AI data. + +## 3. 构造接口 / Constructor ```cpp CMD(Mode mode = CMD::Mode::CMD_OP_CTRL, @@ -53,43 +59,69 @@ CMD(Mode mode = CMD::Mode::CMD_OP_CTRL, const char* launcher_cmd_topic_name = "launcher_cmd"); ``` -无依赖参数。 +依赖:无。 -配置: +配置参数: -- `mode`:初始控制模式,`CMD::Mode::CMD_OP_CTRL` 或 `CMD::Mode::CMD_AUTO_CTRL`, - 默认 `CMD_OP_CTRL`。 -- `chassis_cmd_topic_name`:底盘命令 Topic 名,默认 `"chassis_cmd"`。 -- `gimbal_cmd_topic_name`:云台命令 Topic 名,默认 `"gimbal_cmd"`。 -- `launcher_cmd_topic_name`:发射命令 Topic 名,默认 `"launcher_cmd"`。 +- `mode`:初始控制模式,`CMD::Mode::CMD_OP_CTRL` 或 `CMD::Mode::CMD_AUTO_CTRL`,默认 `CMD_OP_CTRL`。 +- `chassis_cmd_topic_name`:底盘命令 Topic 名称,默认 `"chassis_cmd"`。 +- `gimbal_cmd_topic_name`:云台命令 Topic 名称,默认 `"gimbal_cmd"`。 +- `launcher_cmd_topic_name`:发射命令 Topic 名称,默认 `"launcher_cmd"`。 -## 使用 +Dependencies: none. -```sh -xrobot module add QDU-Robomaster/CMD -xrobot setup -xrobot instance add QDU-Robomaster/CMD -``` +Configuration parameters: + +- `mode`: initial control mode, `CMD::Mode::CMD_OP_CTRL` or `CMD::Mode::CMD_AUTO_CTRL`, default `CMD_OP_CTRL`. +- `chassis_cmd_topic_name`: name of the chassis command Topic, default `"chassis_cmd"`. +- `gimbal_cmd_topic_name`: name of the gimbal command Topic, default `"gimbal_cmd"`. +- `launcher_cmd_topic_name`: name of the launcher command Topic, default `"launcher_cmd"`. + +## 4. Topic -`xrobot instance add` 在 `User/xrobot.yaml` 中写入一个实例,默认值按源码写出(CMD 没有 -依赖参数): +三个 Topic 均以多发布者模式创建。 + +| Topic(默认名) | 方向 | 类型 | 说明 | +| --- | --- | --- | --- | +| `chassis_cmd` | 发布 | `CMD::ChassisCMD` | 底盘命令:`x`、`y`、`z`(旋转)控制量与 `self_define`(`NONE`、`BOOST`、`STRETCH`) | +| `gimbal_cmd` | 发布 | `CMD::GimbalCMD` | 云台命令:`yaw`、`pit`、`rol` 及其一阶、二阶导数 | +| `launcher_cmd` | 发布 | `CMD::LauncherCMD` | 发射命令:`isfire` | + +All three Topics are created in multi-publisher mode. + +| Topic (default name) | Direction | Type | Meaning | +| --- | --- | --- | --- | +| `chassis_cmd` | Publish | `CMD::ChassisCMD` | Chassis command: `x`, `y`, `z` (rotation) control values and `self_define` (`NONE`, `BOOST`, `STRETCH`) | +| `gimbal_cmd` | Publish | `CMD::GimbalCMD` | Gimbal command: `yaw`, `pit`, `rol` and their first and second derivatives | +| `launcher_cmd` | Publish | `CMD::LauncherCMD` | Launcher command: `isfire` | + +## 5. 配置示例 / Configuration Example + +`xrobot instance add QDU-Robomaster/CMD` 写入的实例,各项为默认值: + +An instance written by `xrobot instance add QDU-Robomaster/CMD`, with all values at their defaults: ```yaml modules: - module: QDU-Robomaster/CMD - id: cmd_0 + id: cmd args: - mode: CMD::Mode::CMD_OP_CTRL - - chassis_cmd_topic_name: '"chassis_cmd"' - - gimbal_cmd_topic_name: '"gimbal_cmd"' - - launcher_cmd_topic_name: '"launcher_cmd"' + - chassis_cmd_topic_name: "chassis_cmd" + - gimbal_cmd_topic_name: "gimbal_cmd" + - launcher_cmd_topic_name: "launcher_cmd" ``` -CMD 不需要 BSP 对象,因此不需要 `XR_REGISTER`。其他模块(如 DR16、VT13)以 -`CMD&` 参数引用它时填写 CMD 的实例 id(上例为 `cmd_0`),并且 CMD 必须在 `modules:` -中排在它们前面。 +DR16、VT13、Gimbal 等 Module 以 `CMD&` 参数引用 CMD,配置中填写 CMD 的实例 id(上例为 `cmd`),CMD 实例列在它们之前。 + +Modules such as DR16, VT13 and Gimbal take CMD as a `CMD&` parameter; the configuration holds the instance id of CMD (`cmd` above), and the CMD instance is listed before them. + +## 6. 依赖与硬件 / Dependencies and Hardware + +依赖:LibXR。 + +硬件:无。输入数据由 DR16、VT13 等 Module 写入。 -填好后再次运行 `xrobot setup`,生成 `User/xrobot_main.hpp`。 +Dependencies: LibXR. -`xrobot module show .`(在本仓库中)或 `xrobot module show Modules/QDU-Robomaster/CMD` -(在 BSP 中)打印 manifest 和当前的构造函数。 +Hardware: none. The input data is written by Modules such as DR16 and VT13. From 41d47af123bc4170d406c1a9c861b457761970b2 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Sat, 3 Oct 2026 18:07:47 +0100 Subject: [PATCH 08/11] Clean up comments --- CMD.hpp | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/CMD.hpp b/CMD.hpp index 0bec939..36a77e4 100644 --- a/CMD.hpp +++ b/CMD.hpp @@ -2,17 +2,11 @@ /* clang-format off */ /* === MODULE MANIFEST V2 === -module_description: 控制命令模块 +module_description: 控制命令中枢:汇总遥控器与上位机输入,发布底盘、云台、发射命令 / Control command hub that merges remote-controller and host inputs and publishes chassis, gimbal and launcher commands depends: [] === END MANIFEST === */ /* clang-format on */ -/** - * @file CMD.hpp - * @brief 控制命令处理模块 - * @details 负责处理来自不同控制源的命令,并将其转发到相应的执行单元 - */ - #include #include @@ -150,7 +144,6 @@ class CMD /** * @brief 直接写入遥控器控制数据 - * @details 兼容接口,默认按DR16输入源写入 */ void FeedRC(const Data& rc_data) { @@ -223,7 +216,6 @@ class CMD /** * @brief 设置控制模式 * @param mode 要设置的控制模式 - * @details 根据不同的控制模式配置相应的数据处理回调函数 */ void SetCtrlMode(Mode mode) { this->mode_ = mode; } @@ -238,7 +230,6 @@ class CMD * @brief 注册控制器 * @tparam SourceDataType 源数据类型 * @param source 源主题 - * @details 将外部控制源的数据接入CMD系统,并进行预处理和分发 */ template void RegisterController(LibXR::Topic& source) @@ -263,7 +254,6 @@ class CMD RCInputSource active_rc_input_ = RCInputSource::RC_INPUT_DR16; /* 当前活动遥控输入源 */ uint32_t rc_update_seq_ = 0; /* 遥控输入数据更新序号 */ - /*--------------------------工具函数-------------------------------------------------*/ static bool IsRCInputOnline(const Data& rc_data) { return rc_data.chassis_online; } static bool IsRCInputActive(const Data& rc_data) From 426ccc28072b3500279aa3f7b741d6e7d17c2505 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Sat, 3 Oct 2026 18:09:20 +0100 Subject: [PATCH 09/11] Document the public interface --- CMD.hpp | 229 +++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 143 insertions(+), 86 deletions(-) diff --git a/CMD.hpp b/CMD.hpp index 36a77e4..a93ae35 100644 --- a/CMD.hpp +++ b/CMD.hpp @@ -15,135 +15,165 @@ depends: [] #include "message.hpp" /** - * @class CMD - * @brief 控制命令处理类 - * @details 接收来自不同控制源的命令,处理并转发到底盘和云台等执行单元 + * @brief 控制命令中枢:汇总遥控器与上位机输入,发布底盘、云台、发射命令。 + * Control command hub that merges remote-controller and host inputs and publishes + * chassis, gimbal and launcher commands. */ class CMD { public: /** - * @brief 控制源枚举 + * @brief 控制源。 + * Control source. */ enum class ControlSource : uint8_t { - CTRL_SOURCE_RC, /* 遥控器控制源 */ - CTRL_SOURCE_AI, /* AI控制源 */ - CTRL_SOURCE_NUM /* 控制源数量 */ + CTRL_SOURCE_RC, ///< 遥控器 Remote controller + CTRL_SOURCE_AI, ///< 上位机 / 自动控制 Host / automatic control + CTRL_SOURCE_NUM ///< 控制源数量 Number of control sources }; /** - * @brief 遥控链路输入源枚举 + * @brief 遥控链路输入源。 + * Remote-controller input source. */ enum class RCInputSource : uint8_t { - RC_INPUT_DR16, - RC_INPUT_VT13, - RC_INPUT_NUM + RC_INPUT_DR16, ///< DR16 遥控接收机 DR16 receiver + RC_INPUT_VT13, ///< VT13 图传链路遥控 VT13 video-link remote controller + RC_INPUT_NUM ///< 输入源数量 Number of input sources }; /** - * @brief 控制模式枚举 + * @brief 控制模式。 + * Control mode. */ enum class Mode : uint8_t { - CMD_OP_CTRL, /* 操作员控制模式 */ - CMD_AUTO_CTRL, /* 自动控制模式 */ + CMD_OP_CTRL, ///< 操作手控制 Operator control + CMD_AUTO_CTRL, ///< 自动控制 Automatic control }; /** - * @brief 底盘小模式枚举 + * @brief 底盘自定义模式。 + * Chassis custom mode. */ enum class ChasStat : int8_t { - NONE = 0, /*无模式*/ - BOOST = 1, /*加速*/ - STRETCH = 2, /*伸腿*/ + NONE = 0, ///< 无模式 No mode + BOOST = 1, ///< 加速 Boost + STRETCH = 2, ///< 伸腿 Leg stretch }; /** - * @brief 底盘控制命令结构体 + * @brief 底盘命令。 + * Chassis command. */ typedef struct { - float x; /* X轴方向控制量 */ - float y; /* Y轴方向控制量 */ - float z; /* Z轴方向控制量(旋转) */ - ChasStat self_define; /* 自定义按钮 */ + float x; ///< X 轴方向控制量 Control value along the X axis + float y; ///< Y 轴方向控制量 Control value along the Y axis + float z; ///< Z 轴方向控制量(旋转)Control value around the Z axis (rotation) + ChasStat self_define; ///< 自定义模式 Custom mode } ChassisCMD; /** - * @brief 云台控制命令结构体 + * @brief 云台命令。 + * Gimbal command. */ typedef struct { - float yaw; /* 偏航角(Yaw angle) */ - float pit; /* 俯仰角(Pitch angle) */ - float rol; /* 翻滚角(Roll angle) */ - float yaw_dot; /* yaw角速度 */ - float yaw_ddot; /* yaw角加速度 */ - float pit_dot; /* pit角速度 */ - float pit_ddot; /* pit角加速度 */ - float rol_dot; /* roll角速度 */ - float rol_ddot; /* roll角加速度 */ + float yaw; ///< 偏航角 Yaw angle + float pit; ///< 俯仰角 Pitch angle + float rol; ///< 翻滚角 Roll angle + float yaw_dot; ///< yaw 角速度 Yaw angular velocity + float yaw_ddot; ///< yaw 角加速度 Yaw angular acceleration + float pit_dot; ///< pit 角速度 Pitch angular velocity + float pit_ddot; ///< pit 角加速度 Pitch angular acceleration + float rol_dot; ///< rol 角速度 Roll angular velocity + float rol_ddot; ///< rol 角加速度 Roll angular acceleration } GimbalCMD; /** - * @brief 发射控制命令结构体 + * @brief 发射命令。 + * Launcher command. */ typedef struct { - bool isfire; + bool isfire; ///< 是否开火 Whether to fire } LauncherCMD; /** - * @brief 完整控制命令数据结构体 + * @brief 一个控制源的完整命令数据。 + * Complete command data of one control source. */ typedef struct { - GimbalCMD gimbal; /* 云台控制命令 */ - ChassisCMD chassis; /* 底盘控制命令 */ - LauncherCMD launcher; /* 发射控制命令 */ - bool chassis_online; /* 底盘在线状态 */ - bool gimbal_online; /* 云台在线状态 */ - ControlSource ctrl_source; /* 控制源 */ + GimbalCMD gimbal; ///< 云台命令 Gimbal command + ChassisCMD chassis; ///< 底盘命令 Chassis command + LauncherCMD launcher; ///< 发射命令 Launcher command + bool chassis_online; ///< 底盘命令有效 Chassis command valid (online) + bool gimbal_online; ///< 云台命令有效 Gimbal command valid (online) + ControlSource ctrl_source; ///< 控制源 Control source } Data; /** - * @brief 控制事件ID + * @brief CMD 事件 ID。 + * CMD event IDs. */ enum { - CMD_EVENT_START_CTRL = 0x13212508, /* 开始控制事件ID */ - CMD_EVENT_LOST_CTRL = 0x13212509 /* 丢失控制事件ID */ + CMD_EVENT_START_CTRL = 0x13212508, ///< 遥控器上线 Remote controller online + CMD_EVENT_LOST_CTRL = 0x13212509 ///< 遥控器离线 Remote controller offline }; /** - * @brief 获取当前控制模式 - * @return 当前控制模式 + * @brief 获取当前控制模式。 + * Get the current control mode. + * + * @return 当前控制模式。 + * Current control mode. */ Mode GetCtrlMode() { return this->mode_; } + /** + * @brief 获取 AI 数据的云台在线状态。 + * Get the gimbal online state of the AI data. + * + * @return AI 数据的 gimbal_online。 + * The gimbal_online of the AI data. + */ bool GetAIGimbalStatus() { return this->data_[static_cast(ControlSource::CTRL_SOURCE_AI)].gimbal_online; } /** - * @brief 获取CMD模块的事件处理器 - * @return 事件处理器引用 - * @details 用于其他模块绑定事件或激活事件 + * @brief 获取 CMD 的事件对象。 + * Get the event object of CMD. + * + * @return 事件对象引用,用于绑定事件或激活事件;激活 Mode 的数值即切换控制模式。 + * Event object reference for binding or activating events; activating the value + * of a Mode switches the control mode. */ LibXR::Event& GetEvent() { return cmd_event_; } /** - * @brief 获取在线状态 - * @return 是否在线 + * @brief 获取遥控器在线状态。 + * Get the remote-controller online state. + * + * @return 遥控器是否在线。 + * Whether the remote controller is online. */ bool Online() { return this->online_; } /** - * @brief 直接写入遥控器控制数据 + * @brief 以 DR16 输入源写入遥控器数据,并发布命令。 + * Write remote-controller data with the DR16 input source and publish the + * commands. + * + * @param rc_data 遥控器数据。 + * Remote-controller data. */ void FeedRC(const Data& rc_data) { @@ -151,7 +181,14 @@ class CMD } /** - * @brief 按遥控输入源写入控制数据 + * @brief 按遥控输入源写入遥控器数据,并发布命令。 + * Write remote-controller data of the given input source and publish the + * commands. + * + * @param source 遥控输入源,超出范围时忽略本次写入。 + * Remote-controller input source; the write is ignored when out of range. + * @param rc_data 遥控器数据。 + * Remote-controller data. */ void FeedRC(RCInputSource source, const Data& rc_data) { @@ -173,7 +210,11 @@ class CMD } /** - * @brief 直接写入 AI 控制数据 + * @brief 写入 AI 控制数据,并发布命令。 + * Write AI control data and publish the commands. + * + * @param ai_data AI 控制数据。 + * AI control data. */ void FeedAI(const Data& ai_data) { @@ -182,13 +223,20 @@ class CMD } /** - * @brief CMD构造函数 - * @param mode 控制模式,默认为操作员控制模式 - * @param chassis_cmd_topic_name 底盘命令主题名称 - * @param gimbal_cmd_topic_name 云台命令主题名称 + * @brief 构造 CMD,创建三路命令 Topic 并注册控制模式事件。 + * Construct CMD, create the three command Topics and register the control mode + * events. + * + * @param mode 初始控制模式,默认为操作手控制。 + * Initial control mode, operator control by default. + * @param chassis_cmd_topic_name 底盘命令 Topic 名称。 + * Name of the chassis command Topic. + * @param gimbal_cmd_topic_name 云台命令 Topic 名称。 + * Name of the gimbal command Topic. + * @param launcher_cmd_topic_name 发射命令 Topic 名称。 + * Name of the launcher command Topic. */ - CMD( - Mode mode = CMD::Mode::CMD_OP_CTRL, + CMD(Mode mode = CMD::Mode::CMD_OP_CTRL, const char* chassis_cmd_topic_name = "chassis_cmd", const char* gimbal_cmd_topic_name = "gimbal_cmd", const char* launcher_cmd_topic_name = "launcher_cmd") @@ -200,7 +248,7 @@ class CMD fire_data_tp_(LibXR::Topic::CreateTopic(launcher_cmd_topic_name, nullptr, true)) { - /* 创建事件回调函数 */ + // 创建事件回调函数 auto callback = LibXR::Callback::Create( [](bool in_isr, CMD* cmd, uint32_t event_id) { @@ -208,28 +256,37 @@ class CMD cmd->EventHandler(event_id); }, this); - /* 注册控制模式事件处理回调 */ + // 注册控制模式事件处理回调 this->cmd_event_.Register(static_cast(Mode::CMD_OP_CTRL), callback); this->cmd_event_.Register(static_cast(Mode::CMD_AUTO_CTRL), callback); } /** - * @brief 设置控制模式 - * @param mode 要设置的控制模式 + * @brief 设置控制模式。 + * Set the control mode. + * + * @param mode 控制模式。 + * Control mode. */ void SetCtrlMode(Mode mode) { this->mode_ = mode; } /** - * @brief 事件处理器 - * @param event_id 事件ID - * @details 处理来自事件系统的控制模式切换请求 + * @brief 处理控制模式事件,把事件 ID 作为控制模式。 + * Handle a control mode event, taking the event ID as the control mode. + * + * @param event_id 事件 ID,取值为 Mode 的数值。 + * Event ID, the numeric value of a Mode. */ void EventHandler(uint32_t event_id) { this->SetCtrlMode(static_cast(event_id)); } /** - * @brief 注册控制器 - * @tparam SourceDataType 源数据类型 - * @param source 源主题 + * @brief 保留的控制源注册接口,函数体为空。 + * Reserved control source registration interface with an empty body. + * + * @tparam SourceDataType 源数据类型。 + * Source data type. + * @param source 源 Topic。 + * Source Topic. */ template void RegisterController(LibXR::Topic& source) @@ -238,21 +295,22 @@ class CMD } private: - bool online_ = false; /* 在线状态 */ - Mode mode_; /* 当前控制模式 */ - LibXR::Event cmd_event_; /* 事件处理器 */ + bool online_ = false; ///< 遥控器在线状态 Remote-controller online state + Mode mode_; ///< 当前控制模式 Current control mode + LibXR::Event cmd_event_; ///< CMD 事件 CMD event std::array(ControlSource::CTRL_SOURCE_NUM)> - data_{}; /* 各控制源的数据 */ + data_{}; ///< 各控制源的数据 Data of each control source std::array(RCInputSource::RC_INPUT_NUM)> - rc_input_data_{}; /* 各遥控输入源的数据 */ + rc_input_data_{}; ///< 各遥控输入源的数据 Data of each remote-controller input source std::array(RCInputSource::RC_INPUT_NUM)> - rc_input_seq_{}; /* 各遥控输入源的数据序号 */ - LibXR::Topic chassis_data_tp_; /* 底盘命令主题 */ - LibXR::Topic gimbal_data_tp_; /* 云台命令主题 */ - LibXR::Topic fire_data_tp_; /* 开火命令主题 */ - LibXR::Topic host_euler_data_tp_; /* 上位机欧拉角主题 */ - RCInputSource active_rc_input_ = RCInputSource::RC_INPUT_DR16; /* 当前活动遥控输入源 */ - uint32_t rc_update_seq_ = 0; /* 遥控输入数据更新序号 */ + rc_input_seq_{}; ///< 各遥控输入源的数据序号 Sequence number of each RC input source + LibXR::Topic chassis_data_tp_; ///< 底盘命令 Topic Chassis command Topic + LibXR::Topic gimbal_data_tp_; ///< 云台命令 Topic Gimbal command Topic + LibXR::Topic fire_data_tp_; ///< 发射命令 Topic Launcher command Topic + LibXR::Topic host_euler_data_tp_; ///< 上位机欧拉角 Topic Host Euler angle Topic + RCInputSource active_rc_input_ = + RCInputSource::RC_INPUT_DR16; ///< 当前活动遥控输入源 Active remote-controller input source + uint32_t rc_update_seq_ = 0; ///< 遥控输入数据更新序号 Remote-controller update sequence number static bool IsRCInputOnline(const Data& rc_data) { return rc_data.chassis_online; } @@ -284,14 +342,14 @@ class CMD const auto vt13_index = static_cast(RCInputSource::RC_INPUT_VT13); const auto active_index = static_cast(this->active_rc_input_); - /* 当前活动源在线则持续使用 */ + // 当前活动源在线则持续使用 if (active_index < static_cast(RCInputSource::RC_INPUT_NUM) && this->IsRCInputOnline(this->rc_input_data_[active_index])) { return this->rc_input_data_[active_index]; } - /* 活动源离线后切换 */ + // 活动源离线后切换 if (this->active_rc_input_ == RCInputSource::RC_INPUT_DR16) { if (this->IsRCInputOnline(this->rc_input_data_[vt13_index])) @@ -349,7 +407,6 @@ class CMD } else { - /* CMD_AUTO_CTRL */ ChassisCMD out_chassis = ai_data.chassis_online ? ai_data.chassis : rc_data.chassis; GimbalCMD out_gimbal = ai_data.gimbal_online ? ai_data.gimbal : rc_data.gimbal; LauncherCMD out_launcher; From 36ca9068c8113d42fba911f2078f602406581423 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Sat, 3 Oct 2026 21:38:32 +0100 Subject: [PATCH 10/11] Describe where the CMD callbacks run --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6c074f7..8881706 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,13 @@ CMD 把遥控器(DR16、VT13)与上位机等来源的输入整理为三路命令 Topic:底盘命令、云台命令、发射命令。下游 Module 订阅这三个 Topic,输入来源由 CMD 内部选择。 -输入由其他 Module 调用 `FeedRC(...)` 或 `FeedAI(...)` 写入 `CMD::Data`,每次写入立即执行一轮处理并发布三路命令。CMD 自身不创建线程,由输入 Module 的调用驱动发布。 +输入由其他 Module 调用 `FeedRC(...)` 或 `FeedAI(...)` 写入 `CMD::Data`,每次写入立即执行一轮处理并发布三路命令。处理、命令 Topic 的发布以及遥控器上线与离线事件的激活都在调用者的上下文中同步完成,Topic 与事件上注册的回调函数在同一上下文中运行。控制模式事件的回调 `EventHandler` 在激活该事件的上下文中运行,`SetCtrlMode(...)`、`GetCtrlMode()`、`Online()`、`GetAIGimbalStatus()` 在调用者的上下文中直接读写 CMD 的成员。 遥控器在线状态变化时,CMD 在自己的事件上激活 `CMD_EVENT_START_CTRL`(`0x13212508`,遥控器上线)或 `CMD_EVENT_LOST_CTRL`(`0x13212509`,遥控器离线)。 CMD merges the input of the remote controllers (DR16, VT13) and of the host into three command Topics: the chassis command, the gimbal command and the launcher command. Downstream Modules subscribe to these Topics, and CMD selects the input source internally. -Other Modules write a `CMD::Data` through `FeedRC(...)` or `FeedAI(...)`; every write runs one processing pass and publishes the three commands immediately. CMD creates no thread of its own, and the publishing is driven by the calls of the input Modules. +Other Modules write a `CMD::Data` through `FeedRC(...)` or `FeedAI(...)`; every write runs one processing pass and publishes the three commands immediately. The processing, the publishing of the command Topics and the activation of the remote-controller online and offline events all complete synchronously in the context of the caller, and the callbacks registered on those Topics and events run in that same context. The callback `EventHandler` of the control mode events runs in the context that activates the event, and `SetCtrlMode(...)`, `GetCtrlMode()`, `Online()` and `GetAIGimbalStatus()` read and write the members of CMD directly in the context of the caller. When the remote-controller online state changes, CMD activates `CMD_EVENT_START_CTRL` (`0x13212508`, remote controller online) or `CMD_EVENT_LOST_CTRL` (`0x13212509`, remote controller offline) on its own event. From ec5218a7a345d2313beea905c5160c52e3ae5855 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Sun, 4 Oct 2026 09:38:56 +0100 Subject: [PATCH 11/11] README: match the Module documentation to the code --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 8881706..1c308fd 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,9 @@ ## 1. 模块作用 / Purpose -CMD 把遥控器(DR16、VT13)与上位机等来源的输入整理为三路命令 Topic:底盘命令、云台命令、发射命令。下游 Module 订阅这三个 Topic,输入来源由 CMD 内部选择。 +CMD 把遥控器(DR16、VT13)与上位机等来源的输入整理为三路命令 Topic:底盘命令、云台命令、发射命令。下游模块订阅这三个 Topic,输入来源由 CMD 内部选择。 -输入由其他 Module 调用 `FeedRC(...)` 或 `FeedAI(...)` 写入 `CMD::Data`,每次写入立即执行一轮处理并发布三路命令。处理、命令 Topic 的发布以及遥控器上线与离线事件的激活都在调用者的上下文中同步完成,Topic 与事件上注册的回调函数在同一上下文中运行。控制模式事件的回调 `EventHandler` 在激活该事件的上下文中运行,`SetCtrlMode(...)`、`GetCtrlMode()`、`Online()`、`GetAIGimbalStatus()` 在调用者的上下文中直接读写 CMD 的成员。 +输入由其他模块调用 `FeedRC(...)` 或 `FeedAI(...)` 写入 `CMD::Data`,每次写入立即执行一轮处理并发布三路命令。处理、命令 Topic 的发布以及遥控器上线与离线事件的激活都在调用者的上下文中同步完成,Topic 与事件上注册的回调函数在同一上下文中运行。控制模式事件的回调 `EventHandler` 在激活该事件的上下文中运行,`SetCtrlMode(...)`、`GetCtrlMode()`、`Online()`、`GetAIGimbalStatus()` 在调用者的上下文中直接读写 CMD 的成员。 遥控器在线状态变化时,CMD 在自己的事件上激活 `CMD_EVENT_START_CTRL`(`0x13212508`,遥控器上线)或 `CMD_EVENT_LOST_CTRL`(`0x13212509`,遥控器离线)。 @@ -30,7 +30,7 @@ When the remote-controller online state changes, CMD activates `CMD_EVENT_START_ - `FeedRC(const Data&)`、`FeedRC(RCInputSource, const Data&)`:写入遥控数据。 - `FeedAI(const Data&)`:写入上位机或自动控制数据。 - `SetCtrlMode(Mode)`、`GetCtrlMode()`:设置、读取控制模式。 -- `GetEvent()`:返回 CMD 的 `LibXR::Event`。在其上激活事件 ID `static_cast(CMD::Mode::CMD_OP_CTRL)` 或 `static_cast(CMD::Mode::CMD_AUTO_CTRL)` 即切换到对应的控制模式,`EventBinder` 等 Module 通过它绑定事件。 +- `GetEvent()`:返回 CMD 的 `LibXR::Event`。在其上激活事件 ID `static_cast(CMD::Mode::CMD_OP_CTRL)` 或 `static_cast(CMD::Mode::CMD_AUTO_CTRL)` 即切换到对应的控制模式,`EventBinder` 等模块通过它绑定事件。 - `Online()`:遥控器是否在线。 - `GetAIGimbalStatus()`:AI 数据的 `gimbal_online`。 @@ -112,7 +112,7 @@ modules: - launcher_cmd_topic_name: "launcher_cmd" ``` -DR16、VT13、Gimbal 等 Module 以 `CMD&` 参数引用 CMD,配置中填写 CMD 的实例 id(上例为 `cmd`),CMD 实例列在它们之前。 +DR16、VT13、Gimbal 等模块以 `CMD&` 参数引用 CMD,配置中填写 CMD 的实例 id(上例为 `cmd`),CMD 实例列在它们之前。 Modules such as DR16, VT13 and Gimbal take CMD as a `CMD&` parameter; the configuration holds the instance id of CMD (`cmd` above), and the CMD instance is listed before them. @@ -120,7 +120,7 @@ Modules such as DR16, VT13 and Gimbal take CMD as a `CMD&` parameter; the config 依赖:LibXR。 -硬件:无。输入数据由 DR16、VT13 等 Module 写入。 +硬件:无。输入数据由 DR16、VT13 等模块写入。 Dependencies: LibXR.