From 0e6f0715276f248c2eecc4773e598ec4c7baa3b6 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Tue, 15 Sep 2026 04:38:11 +0100 Subject: [PATCH 01/11] feat: adopt static module construction --- HostData.hpp | 83 ++++++++++++++++++++++++++-------------------------- 1 file changed, 41 insertions(+), 42 deletions(-) diff --git a/HostData.hpp b/HostData.hpp index 38fe2e3..182c919 100644 --- a/HostData.hpp +++ b/HostData.hpp @@ -3,19 +3,13 @@ // clang-format off /* === MODULE MANIFEST V2 === module_description: No description provided -constructor_args: - - cmd: '@cmd' - - host_euler_topic_name: "target_eulr" - - host_chassis_data_topic_name: "host_chassis_data" - - host_fire_topic_name: "host_fire_notify" -template_args: [] -required_hardware: [] -depends: [] +depends: +- id: QDU-Robomaster/CMD + ref: same-or-dev === END MANIFEST === */ // clang-format on #include "CMD.hpp" -#include "app_framework.hpp" #include "libxr_cb.hpp" #include "libxr_def.hpp" #include "libxr_time.hpp" @@ -32,19 +26,23 @@ depends: [] * @brief 上位机数据接入模块 * @details 将上位机发送的云台、底盘、发射命令转换为 CMD::Data 并喂给 CMD 模块。 */ -class HostData : public LibXR::Application { +class HostData +{ public: - struct HostChassisTarget { + struct HostChassisTarget + { float vx; float vy; float w; }; - struct LauncherCMD { + struct LauncherCMD + { bool isfire; }; - struct HostGimbalTarget { + struct HostGimbalTarget + { float rol, pit, yaw; float rol_dot, pit_dot, yaw_dot; float rol_ddot, pit_ddot, yaw_ddot; @@ -52,32 +50,26 @@ class HostData : public LibXR::Application { /** * @brief 构造 HostData 模块 - * @param hw 硬件容器 - * @param app 应用管理器 * @param cmd CMD 模块引用 * @param host_euler_topic_name 云台目标欧拉角 Topic * @param host_chassis_data_topic_name 底盘目标速度 Topic * @param host_fire_topic_name 发射控制 Topic */ - HostData(LibXR::HardwareContainer& hw, LibXR::ApplicationManager& app, - CMD& cmd, const char* host_gimbal_topic_name, - const char* host_chassis_data_topic_name, - const char* host_fire_topic_name) + HostData(CMD& cmd, const char* host_gimbal_topic_name, + const char* host_chassis_data_topic_name, const char* host_fire_topic_name) : cmd_(&cmd), - host_gimbal_data_tp_(LibXR::Topic::CreateTopic( - host_gimbal_topic_name)), - host_chassis_data_tp_(LibXR::Topic::CreateTopic( - host_chassis_data_topic_name)), - host_fire_notify_tp_( - LibXR::Topic::CreateTopic(host_fire_topic_name)) { - UNUSED(hw); - + host_gimbal_data_tp_( + LibXR::Topic::CreateTopic(host_gimbal_topic_name)), + host_chassis_data_tp_( + LibXR::Topic::CreateTopic(host_chassis_data_topic_name)), + host_fire_notify_tp_(LibXR::Topic::CreateTopic(host_fire_topic_name)) + { auto euler_callback = LibXR::Topic::Callback::Create( - [](bool in_isr, HostData* host_data, LibXR::RawData& raw_data) { + [](bool in_isr, HostData* host_data, LibXR::RawData& raw_data) + { HostGimbalTarget t; LibXR::Memory::FastCopy(&t, raw_data.addr_, sizeof(t)); - host_data->host_euler_ = - LibXR::EulerAngle(t.rol, t.pit, t.yaw); + host_data->host_euler_ = LibXR::EulerAngle(t.rol, t.pit, t.yaw); host_data->host_gyro_ = Eigen::Matrix(t.rol_dot, t.pit_dot, t.yaw_dot); host_data->host_accl_ = @@ -88,16 +80,18 @@ class HostData : public LibXR::Application { this); auto chassis_callback = LibXR::Topic::Callback::Create( - [](bool in_isr, HostData* host_data, LibXR::RawData& raw_data) { - LibXR::Memory::FastCopy(&host_data->host_chassis_data_, - raw_data.addr_, sizeof(HostChassisTarget)); + [](bool in_isr, HostData* host_data, LibXR::RawData& raw_data) + { + LibXR::Memory::FastCopy(&host_data->host_chassis_data_, raw_data.addr_, + sizeof(HostChassisTarget)); host_data->last_chassis_time_ = LibXR::Timebase::GetMilliseconds(); host_data->HostCMD(in_isr); }, this); auto fire_callback = LibXR::Topic::Callback::Create( - [](bool in_isr, HostData* host_data, LibXR::RawData& raw_data) { + [](bool in_isr, HostData* host_data, LibXR::RawData& raw_data) + { LibXR::Memory::FastCopy(&host_data->host_fire_notify_, raw_data.addr_, sizeof(LauncherCMD)); host_data->last_fire_time_ = LibXR::Timebase::GetMilliseconds(); @@ -108,33 +102,38 @@ class HostData : public LibXR::Application { host_gimbal_data_tp_.RegisterCallback(euler_callback); host_chassis_data_tp_.RegisterCallback(chassis_callback); host_fire_notify_tp_.RegisterCallback(fire_callback); - - app.Register(*this); } /** * @brief 汇总并下发 Host 命令 * @param in_isr 是否在中断上下文(当前未使用) */ - void HostCMD(bool in_isr) { + void HostCMD(bool in_isr) + { UNUSED(in_isr); CMD::Data host_cmd; if (host_chassis_data_.vx == 0.0f && host_chassis_data_.vy == 0.0f && - host_chassis_data_.w == 0.0f) { + host_chassis_data_.w == 0.0f) + { host_cmd.chassis = {0, 0, 0}; host_cmd.chassis_online = false; - } else { + } + else + { host_cmd.chassis.x = host_chassis_data_.vx; host_cmd.chassis.y = host_chassis_data_.vy; host_cmd.chassis.z = host_chassis_data_.w; host_cmd.chassis_online = true; } - if (host_euler_.Pitch() == 0.0f && host_euler_.Yaw() == 0.0f) { + if (host_euler_.Pitch() == 0.0f && host_euler_.Yaw() == 0.0f) + { host_cmd.gimbal = {0, 0, 0, 0, 0, 0, 0, 0, 0}; host_cmd.gimbal_online = false; - } else { + } + else + { host_cmd.gimbal.pit = host_euler_.Pitch(); host_cmd.gimbal.yaw = host_euler_.Yaw(); host_cmd.gimbal.pit_dot = host_gyro_.y(); @@ -153,7 +152,7 @@ class HostData : public LibXR::Application { /** * @brief 监控回调 */ - void OnMonitor() override {} + void OnMonitor() {} private: CMD* cmd_; From 09ae732c9c4442a180ac55a39e0ce7bc1bc0ce00 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Fri, 18 Sep 2026 01:50:37 +0100 Subject: [PATCH 02/11] Migrate to static assembly --- .github/workflows/build.yml | 240 ++++++++++++++++++------------------ HostData.hpp | 7 +- 2 files changed, 126 insertions(+), 121 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index bc0e690..3e201c8 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -1,130 +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 CMD module - uses: actions/checkout@v4 - with: - repository: QDU-Robomaster/CMD - path: Modules/CMD - - - 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 - run: | - pip3 install xrobot libxr - - - name: Run xrobot_setup - run: | - xrobot_setup || true - - - name: Run xrobot_init_mod - run: | - xrobot_init_mod - - - name: Add BlinkLED module - run: | - xrobot_add_mod BlinkLED --instance-id BlinkLED_0 - xrobot_add_mod CMD --instance-id cmd - - - name: Add this repo module - run: | - xrobot_add_mod ${{ env.XR_MODULE_NAME }} && 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/HostData.hpp b/HostData.hpp index 182c919..e845510 100644 --- a/HostData.hpp +++ b/HostData.hpp @@ -55,8 +55,11 @@ class HostData * @param host_chassis_data_topic_name 底盘目标速度 Topic * @param host_fire_topic_name 发射控制 Topic */ - HostData(CMD& cmd, const char* host_gimbal_topic_name, - const char* host_chassis_data_topic_name, const char* host_fire_topic_name) + HostData( + CMD& cmd, + const char* host_gimbal_topic_name = "target_euler", + const char* host_chassis_data_topic_name = "host_chassis_data", + const char* host_fire_topic_name = "host_fire_notify") : cmd_(&cmd), host_gimbal_data_tp_( LibXR::Topic::CreateTopic(host_gimbal_topic_name)), From 41521271392871a203a9041349e903718976fbc4 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Mon, 28 Sep 2026 20:47:32 +0100 Subject: [PATCH 03/11] Receive host topics with their concrete payload types The target, chassis and fire callbacks registered LibXR::RawData& payloads on typed topics, which LibXR rejects when the callback is registered. They now take const HostGimbalTarget&, const HostChassisTarget& and const LauncherCMD&; the copied values and the HostCMD() call are unchanged. --- HostData.hpp | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/HostData.hpp b/HostData.hpp index e845510..305261f 100644 --- a/HostData.hpp +++ b/HostData.hpp @@ -68,10 +68,8 @@ class HostData host_fire_notify_tp_(LibXR::Topic::CreateTopic(host_fire_topic_name)) { auto euler_callback = LibXR::Topic::Callback::Create( - [](bool in_isr, HostData* host_data, LibXR::RawData& raw_data) + [](bool in_isr, HostData* host_data, const HostGimbalTarget& t) { - HostGimbalTarget t; - LibXR::Memory::FastCopy(&t, raw_data.addr_, sizeof(t)); host_data->host_euler_ = LibXR::EulerAngle(t.rol, t.pit, t.yaw); host_data->host_gyro_ = Eigen::Matrix(t.rol_dot, t.pit_dot, t.yaw_dot); @@ -83,20 +81,18 @@ class HostData this); auto chassis_callback = LibXR::Topic::Callback::Create( - [](bool in_isr, HostData* host_data, LibXR::RawData& raw_data) + [](bool in_isr, HostData* host_data, const HostChassisTarget& chassis) { - LibXR::Memory::FastCopy(&host_data->host_chassis_data_, raw_data.addr_, - sizeof(HostChassisTarget)); + host_data->host_chassis_data_ = chassis; host_data->last_chassis_time_ = LibXR::Timebase::GetMilliseconds(); host_data->HostCMD(in_isr); }, this); auto fire_callback = LibXR::Topic::Callback::Create( - [](bool in_isr, HostData* host_data, LibXR::RawData& raw_data) + [](bool in_isr, HostData* host_data, const LauncherCMD& fire) { - LibXR::Memory::FastCopy(&host_data->host_fire_notify_, raw_data.addr_, - sizeof(LauncherCMD)); + host_data->host_fire_notify_ = fire; host_data->last_fire_time_ = LibXR::Timebase::GetMilliseconds(); host_data->HostCMD(in_isr); }, From 8592319612ad05ba579721c9d694c9da01bef1a8 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Mon, 28 Sep 2026 20:55:14 +0100 Subject: [PATCH 04/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. --- HostData.hpp | 5 ----- README.md | 1 - 2 files changed, 6 deletions(-) diff --git a/HostData.hpp b/HostData.hpp index 305261f..43de899 100644 --- a/HostData.hpp +++ b/HostData.hpp @@ -148,11 +148,6 @@ class HostData cmd_->FeedAI(host_cmd); } - /** - * @brief 监控回调 - */ - void OnMonitor() {} - private: CMD* cmd_; HostChassisTarget host_chassis_data_; diff --git a/README.md b/README.md index c53bb9b..d412ad2 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,6 @@ ## 2. 主要函数说明 1. HostCMD: 汇总云台/底盘/发射数据并喂给 CMD。 2. 构造函数中的三个 Topic 回调: 接收 euler、chassis、fire 数据。 -3. OnMonitor: 监控钩子(当前为空实现)。 ## 3. 接入步骤 1. 添加模块并配置 host 侧 Topic 名称。 From 07736b84720a3a92fa58ee46937541d1a706ebcc Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Mon, 28 Sep 2026 21:51:27 +0100 Subject: [PATCH 05/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 f244818073c3f7325df89a2541f74c9711403dfd Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Mon, 28 Sep 2026 21:53:35 +0100 Subject: [PATCH 06/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 c1ea519704390c4005d7141d2333e76d55783a69 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Mon, 28 Sep 2026 22:12:49 +0100 Subject: [PATCH 07/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 | 111 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 74 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index d412ad2..317b63a 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,76 @@ # HostData -## 1. 模块作用 -上位机数据接入模块。把主机侧目标转换为 CMD 输入。 - -## 2. 主要函数说明 -1. HostCMD: 汇总云台/底盘/发射数据并喂给 CMD。 -2. 构造函数中的三个 Topic 回调: 接收 euler、chassis、fire 数据。 - -## 3. 接入步骤 -1. 添加模块并配置 host 侧 Topic 名称。 -2. 保证上位机发布数据结构与本模块一致。 -3. 检查 CMD 是否收到 AI 控制输入。 - -标准命令流程: - xrobot_add_mod HostData --instance-id hostdata - xrobot_gen_main - cube-cmake --build /home/leo/Documents/bsp-dev-c/build/debug -- - -## 4. 配置示例(YAML) -module: HostData -entry_header: Modules/HostData/HostData.hpp -constructor_args: - - cmd: '@cmd' - - host_euler_topic_name: "target_eulr" - - host_chassis_data_topic_name: "host_chassis_data" - - host_fire_topic_name: "host_fire_notify" -template_args: -[] - -## 5. 依赖与硬件 -Required Hardware: -[] - -Depends: -[] - -## 6. 代码入口 -Modules/HostData/HostData.hpp +上位机数据接入模块:把上位机发来的云台目标、底盘速度和发射命令汇总为 `CMD::Data`, +以 AI 控制源喂给 CMD 模块。 + +- 构造时创建三个 Topic(名字由构造参数给出)并在其上注册回调: + + | 参数 | 默认名字 | 类型 | 内容 | + | --- | --- | --- | --- | + | `host_gimbal_topic_name` | `target_euler` | `HostData::HostGimbalTarget` | 目标 `rol, pit, yaw` 及其一阶(`*_dot`)、二阶(`*_ddot`)导数 | + | `host_chassis_data_topic_name` | `host_chassis_data` | `HostData::HostChassisTarget` | 底盘速度 `vx, vy, w` | + | `host_fire_topic_name` | `host_fire_notify` | `HostData::LauncherCMD` | 发射命令 `isfire` | + + 上位机链路(例如 `xrobot-org/SharedTopic`)向这些 Topic 发布数据,数据结构必须与上表一致。 +- 任一 Topic 收到数据时,回调用三路最新数据组成一帧 `CMD::Data`,`ctrl_source` 设为 + `CMD::ControlSource::CTRL_SOURCE_AI`,调用 `cmd.FeedAI()`: + - 底盘:`vx, vy, w` 写入 `chassis.x / y / z`;三者全为 0 时 `chassis_online = false`,否则为 `true`。 + - 云台:写入 `pit`、`yaw` 及 `pit_dot`、`pit_ddot`、`yaw_dot`、`yaw_ddot`(roll 不使用); + pitch 与 yaw 都为 0 时 `gimbal_online = false` 且云台数据清零,否则为 `true`。 + - 发射:`launcher.isfire` 取最近一次发射命令。 +- 回调在发布方的上下文中执行,模块没有自己的线程。 + +## 依赖 + +- `QDU-Robomaster/CMD`:`CMD::Data` 类型与 `FeedAI()` 入口。 + +无外部软件包,仅使用 LibXR。 + +## 构造接口 + +```cpp +HostData(CMD& cmd, + const char* host_gimbal_topic_name = "target_euler", + const char* host_chassis_data_topic_name = "host_chassis_data", + const char* host_fire_topic_name = "host_fire_notify"); +``` + +依赖: + +- `cmd`:`CMD` 实例,接收 AI 数据。 + +配置: + +- `host_gimbal_topic_name`:云台目标 Topic 名,默认 `"target_euler"`。 +- `host_chassis_data_topic_name`:底盘速度 Topic 名,默认 `"host_chassis_data"`。 +- `host_fire_topic_name`:发射命令 Topic 名,默认 `"host_fire_notify"`。 + +## 使用 + +```sh +xrobot module add QDU-Robomaster/HostData +xrobot setup +xrobot instance add QDU-Robomaster/HostData +``` + +`xrobot instance add` 在 `User/xrobot.yaml` 中写入一个实例,依赖项留空,默认值按源码写出; +把 `cmd` 填为 CMD 实例的 id: + +```yaml +modules: + - module: QDU-Robomaster/HostData + id: hostdata_0 + args: + - cmd: cmd + - host_gimbal_topic_name: '"target_euler"' + - host_chassis_data_topic_name: '"host_chassis_data"' + - host_fire_topic_name: '"host_fire_notify"' +``` + +`cmd` 是 `QDU-Robomaster/CMD` 实例的 id,须在本实例之前列出。本例没有需要 BSP 用 `XR_REGISTER` +注册的对象。Topic 名是 C++ 字符串字面量,需与上位机链路使用的名字一致。 + +填好后再次运行 `xrobot setup`,生成 `User/xrobot_main.hpp`。 + +`xrobot module show .`(在本仓库中)或 `xrobot module show Modules/QDU-Robomaster/HostData` +(在 BSP 中)打印当前的构造函数。 From aa9db85bc15188666457d7c6b0cdc6af5ef3ab0c Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Sat, 3 Oct 2026 18:24:44 +0100 Subject: [PATCH 08/11] Rewrite the README to the Module README structure --- README.md | 109 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 67 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 317b63a..0dce5ea 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,30 @@ # HostData -上位机数据接入模块:把上位机发来的云台目标、底盘速度和发射命令汇总为 `CMD::Data`, -以 AI 控制源喂给 CMD 模块。 +上位机数据接入模块:把上位机发来的云台目标、底盘速度和发射命令汇总为 CMD 的 AI 控制数据 / Host data Module that combines the gimbal target, chassis speed and fire command from the host into AI control data for CMD -- 构造时创建三个 Topic(名字由构造参数给出)并在其上注册回调: +## 1. 模块作用 / Purpose - | 参数 | 默认名字 | 类型 | 内容 | - | --- | --- | --- | --- | - | `host_gimbal_topic_name` | `target_euler` | `HostData::HostGimbalTarget` | 目标 `rol, pit, yaw` 及其一阶(`*_dot`)、二阶(`*_ddot`)导数 | - | `host_chassis_data_topic_name` | `host_chassis_data` | `HostData::HostChassisTarget` | 底盘速度 `vx, vy, w` | - | `host_fire_topic_name` | `host_fire_notify` | `HostData::LauncherCMD` | 发射命令 `isfire` | +构造时,HostData 按构造参数给出的名字创建三个 Topic 并在其上注册回调。上位机链路(例如 `xrobot-org/SharedTopic`)向这些 Topic 发布数据,数据结构与第 3 节的类型一致。 - 上位机链路(例如 `xrobot-org/SharedTopic`)向这些 Topic 发布数据,数据结构必须与上表一致。 -- 任一 Topic 收到数据时,回调用三路最新数据组成一帧 `CMD::Data`,`ctrl_source` 设为 - `CMD::ControlSource::CTRL_SOURCE_AI`,调用 `cmd.FeedAI()`: - - 底盘:`vx, vy, w` 写入 `chassis.x / y / z`;三者全为 0 时 `chassis_online = false`,否则为 `true`。 - - 云台:写入 `pit`、`yaw` 及 `pit_dot`、`pit_ddot`、`yaw_dot`、`yaw_ddot`(roll 不使用); - pitch 与 yaw 都为 0 时 `gimbal_online = false` 且云台数据清零,否则为 `true`。 - - 发射:`launcher.isfire` 取最近一次发射命令。 -- 回调在发布方的上下文中执行,模块没有自己的线程。 +任一 Topic 收到数据时,回调用三路最新数据组成一帧 `CMD::Data`,`ctrl_source` 设为 `CMD::ControlSource::CTRL_SOURCE_AI`,并调用 `cmd.FeedAI()`: -## 依赖 +- 底盘:`vx, vy, w` 写入 `chassis.x / y / z`;三者全为 0 时 `chassis_online = false`,否则为 `true`。 +- 云台:写入 `pit`、`yaw` 及 `pit_dot`、`pit_ddot`、`yaw_dot`、`yaw_ddot`;pitch 与 yaw 都为 0 时 `gimbal_online = false` 且云台数据清零,否则为 `true`。 +- 发射:`launcher.isfire` 取最近一次发射命令。 -- `QDU-Robomaster/CMD`:`CMD::Data` 类型与 `FeedAI()` 入口。 +回调在发布方的上下文中执行。 + +Upon construction, HostData creates three Topics with the names given by the constructor parameters and registers a callback on each. The host link (for example `xrobot-org/SharedTopic`) publishes data to these Topics, with data structures matching the types in section 3. + +When any Topic receives data, the callback composes one `CMD::Data` frame from the latest data of the three Topics, sets `ctrl_source` to `CMD::ControlSource::CTRL_SOURCE_AI`, and calls `cmd.FeedAI()`: -无外部软件包,仅使用 LibXR。 +- Chassis: `vx, vy, w` are written to `chassis.x / y / z`; `chassis_online = false` when all three are 0, otherwise `true`. +- Gimbal: `pit`, `yaw`, `pit_dot`, `pit_ddot`, `yaw_dot` and `yaw_ddot` are written; `gimbal_online = false` and the gimbal data is cleared when pitch and yaw are both 0, otherwise `true`. +- Fire: `launcher.isfire` takes the latest fire command. -## 构造接口 +The callbacks run in the context of the publisher. + +## 2. 构造接口 / Constructor ```cpp HostData(CMD& cmd, @@ -37,40 +35,67 @@ HostData(CMD& cmd, 依赖: -- `cmd`:`CMD` 实例,接收 AI 数据。 +- `cmd`:`CMD` 实例,接收 AI 控制数据。 -配置: +配置参数: -- `host_gimbal_topic_name`:云台目标 Topic 名,默认 `"target_euler"`。 -- `host_chassis_data_topic_name`:底盘速度 Topic 名,默认 `"host_chassis_data"`。 -- `host_fire_topic_name`:发射命令 Topic 名,默认 `"host_fire_notify"`。 +- `host_gimbal_topic_name`:云台目标 Topic 名称,默认 `"target_euler"`。 +- `host_chassis_data_topic_name`:底盘速度 Topic 名称,默认 `"host_chassis_data"`。 +- `host_fire_topic_name`:发射命令 Topic 名称,默认 `"host_fire_notify"`。 -## 使用 +Dependencies: -```sh -xrobot module add QDU-Robomaster/HostData -xrobot setup -xrobot instance add QDU-Robomaster/HostData -``` +- `cmd`: the `CMD` instance that receives the AI control data. + +Configuration parameters: + +- `host_gimbal_topic_name`: name of the gimbal target Topic, default `"target_euler"`. +- `host_chassis_data_topic_name`: name of the chassis speed Topic, default `"host_chassis_data"`. +- `host_fire_topic_name`: name of the fire command Topic, default `"host_fire_notify"`. + +## 3. Topic + +| Topic | 方向 | 类型 | 说明 | +| --- | --- | --- | --- | +| `host_gimbal_topic_name`(默认 `target_euler`) | 创建并订阅 | `HostData::HostGimbalTarget` | 目标 `rol, pit, yaw` 及其一阶(`*_dot`)、二阶(`*_ddot`)导数 | +| `host_chassis_data_topic_name`(默认 `host_chassis_data`) | 创建并订阅 | `HostData::HostChassisTarget` | 底盘速度 `vx, vy, w` | +| `host_fire_topic_name`(默认 `host_fire_notify`) | 创建并订阅 | `HostData::LauncherCMD` | 发射命令 `isfire` | -`xrobot instance add` 在 `User/xrobot.yaml` 中写入一个实例,依赖项留空,默认值按源码写出; -把 `cmd` 填为 CMD 实例的 id: +| Topic | Direction | Type | Meaning | +| --- | --- | --- | --- | +| `host_gimbal_topic_name` (default `target_euler`) | Create and subscribe | `HostData::HostGimbalTarget` | Target `rol, pit, yaw` with their first (`*_dot`) and second (`*_ddot`) derivatives | +| `host_chassis_data_topic_name` (default `host_chassis_data`) | Create and subscribe | `HostData::HostChassisTarget` | Chassis speed `vx, vy, w` | +| `host_fire_topic_name` (default `host_fire_notify`) | Create and subscribe | `HostData::LauncherCMD` | Fire command `isfire` | + +## 4. 配置示例 / Configuration Example + +`xrobot instance add QDU-Robomaster/HostData` 写入的实例,`cmd` 填写为 `QDU-Robomaster/CMD` 实例的 id,该实例在 `modules:` 中排在本实例之前。Topic 名称与上位机链路使用的名称一致;示例中的 `fire_notify` 与 Dart 订阅的发射命令 Topic 名称相同。 + +An instance written by `xrobot instance add QDU-Robomaster/HostData`, with `cmd` set to the id of the `QDU-Robomaster/CMD` instance, which is listed before this instance in `modules:`. The Topic names match the names used by the host link; `fire_notify` in the example is the fire command Topic name that Dart subscribes to. ```yaml modules: - module: QDU-Robomaster/HostData - id: hostdata_0 + id: hostdata args: - cmd: cmd - - host_gimbal_topic_name: '"target_euler"' - - host_chassis_data_topic_name: '"host_chassis_data"' - - host_fire_topic_name: '"host_fire_notify"' + - host_gimbal_topic_name: "target_euler" + - host_chassis_data_topic_name: "chassis_data" + - host_fire_topic_name: "fire_notify" ``` -`cmd` 是 `QDU-Robomaster/CMD` 实例的 id,须在本实例之前列出。本例没有需要 BSP 用 `XR_REGISTER` -注册的对象。Topic 名是 C++ 字符串字面量,需与上位机链路使用的名字一致。 +## 5. 依赖与硬件 / Dependencies and Hardware + +依赖: + +- `QDU-Robomaster/CMD`:`CMD::Data` 类型与 `FeedAI()` 入口。 +- LibXR。 + +硬件:无。 + +Dependencies: -填好后再次运行 `xrobot setup`,生成 `User/xrobot_main.hpp`。 +- `QDU-Robomaster/CMD`: the `CMD::Data` type and the `FeedAI()` entry. +- LibXR. -`xrobot module show .`(在本仓库中)或 `xrobot module show Modules/QDU-Robomaster/HostData` -(在 BSP 中)打印当前的构造函数。 +Hardware: none. From b552d5ce77fa6c88b4816ac40729acc51f3f1af6 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Sat, 3 Oct 2026 18:24:52 +0100 Subject: [PATCH 09/11] Clean up comments --- HostData.hpp | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/HostData.hpp b/HostData.hpp index 43de899..a161c07 100644 --- a/HostData.hpp +++ b/HostData.hpp @@ -2,7 +2,7 @@ // clang-format off /* === MODULE MANIFEST V2 === -module_description: No description provided +module_description: 上位机数据接入模块:把上位机发来的云台目标、底盘速度和发射命令汇总为 CMD 的 AI 控制数据 / Host data Module that combines the gimbal target, chassis speed and fire command from the host into AI control data for CMD depends: - id: QDU-Robomaster/CMD ref: same-or-dev @@ -24,7 +24,7 @@ module_description: No description provided /** * @brief 上位机数据接入模块 - * @details 将上位机发送的云台、底盘、发射命令转换为 CMD::Data 并喂给 CMD 模块。 + * @details 将上位机发送的云台、底盘、发射命令转换为 CMD::Data,通过 CMD 的 AI 控制入口提交。 */ class HostData { @@ -51,7 +51,7 @@ class HostData /** * @brief 构造 HostData 模块 * @param cmd CMD 模块引用 - * @param host_euler_topic_name 云台目标欧拉角 Topic + * @param host_gimbal_topic_name 云台目标欧拉角 Topic * @param host_chassis_data_topic_name 底盘目标速度 Topic * @param host_fire_topic_name 发射控制 Topic */ From 85b5d03253ae26b284a8ac04360e3d7743e3417c Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Sat, 3 Oct 2026 18:25:14 +0100 Subject: [PATCH 10/11] Document the public interface --- HostData.hpp | 64 +++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 48 insertions(+), 16 deletions(-) diff --git a/HostData.hpp b/HostData.hpp index a161c07..f79e092 100644 --- a/HostData.hpp +++ b/HostData.hpp @@ -23,37 +23,65 @@ module_description: 上位机数据接入模块:把上位机发来的云台目 #include "transform.hpp" /** - * @brief 上位机数据接入模块 - * @details 将上位机发送的云台、底盘、发射命令转换为 CMD::Data,通过 CMD 的 AI 控制入口提交。 + * @brief 上位机数据接入模块:把上位机发来的云台目标、底盘速度和发射命令汇总为 + * `CMD::Data`,通过 CMD 的 AI 控制入口提交。 + * Host data Module that combines the gimbal target, chassis speed and fire command + * from the host into `CMD::Data` and submits it through the AI control entry of + * CMD. */ class HostData { public: + /** + * @brief 上位机给出的底盘目标速度。 + * Chassis target speed from the host. + */ struct HostChassisTarget { - float vx; - float vy; - float w; + float vx; ///< x 方向速度 Velocity along x + float vy; ///< y 方向速度 Velocity along y + float w; ///< 旋转角速度 Rotation angular velocity }; + /** + * @brief 上位机给出的发射命令。 + * Fire command from the host. + */ struct LauncherCMD { - bool isfire; + bool isfire; ///< 是否开火 Whether to fire }; + /** + * @brief 上位机给出的云台目标欧拉角及其一阶、二阶导数。 + * Gimbal target Euler angles from the host with their first and second + * derivatives. + */ struct HostGimbalTarget { - float rol, pit, yaw; - float rol_dot, pit_dot, yaw_dot; - float rol_ddot, pit_ddot, yaw_ddot; + float rol; ///< 目标 roll Target roll + float pit; ///< 目标 pitch Target pitch + float yaw; ///< 目标 yaw Target yaw + float rol_dot; ///< roll 一阶导数 First derivative of roll + float pit_dot; ///< pitch 一阶导数 First derivative of pitch + float yaw_dot; ///< yaw 一阶导数 First derivative of yaw + float rol_ddot; ///< roll 二阶导数 Second derivative of roll + float pit_ddot; ///< pitch 二阶导数 Second derivative of pitch + float yaw_ddot; ///< yaw 二阶导数 Second derivative of yaw }; /** - * @brief 构造 HostData 模块 - * @param cmd CMD 模块引用 - * @param host_gimbal_topic_name 云台目标欧拉角 Topic - * @param host_chassis_data_topic_name 底盘目标速度 Topic - * @param host_fire_topic_name 发射控制 Topic + * @brief 构造 HostData,创建三个 Topic 并注册回调。 + * Construct HostData, create the three Topics and register the callbacks. + * + * @param cmd CMD 实例,接收 AI 控制数据。 + * CMD instance that receives the AI control data. + * @param host_gimbal_topic_name 云台目标 Topic 名称。 + * Name of the gimbal target Topic. + * @param host_chassis_data_topic_name 底盘目标速度 Topic 名称。 + * Name of the chassis target speed Topic. + * @param host_fire_topic_name 发射命令 Topic 名称。 + * Name of the fire command Topic. */ HostData( CMD& cmd, @@ -104,8 +132,12 @@ class HostData } /** - * @brief 汇总并下发 Host 命令 - * @param in_isr 是否在中断上下文(当前未使用) + * @brief 用三路最新数据组成一帧 `CMD::Data` 并调用 `cmd.FeedAI()`。 + * Compose one `CMD::Data` frame from the latest data of the three Topics and + * call `cmd.FeedAI()`. + * + * @param in_isr 是否在中断上下文。 + * Whether called from interrupt context. */ void HostCMD(bool in_isr) { From a052d1eee12bf2c851d8d5a3a81cfadd79e52814 Mon Sep 17 00:00:00 2001 From: Jiu-xiao <2592509183@qq.com> Date: Sat, 3 Oct 2026 18:25:15 +0100 Subject: [PATCH 11/11] Write struct defaults with field names --- HostData.hpp | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/HostData.hpp b/HostData.hpp index f79e092..ccec702 100644 --- a/HostData.hpp +++ b/HostData.hpp @@ -83,11 +83,9 @@ class HostData * @param host_fire_topic_name 发射命令 Topic 名称。 * Name of the fire command Topic. */ - HostData( - CMD& cmd, - const char* host_gimbal_topic_name = "target_euler", - const char* host_chassis_data_topic_name = "host_chassis_data", - const char* host_fire_topic_name = "host_fire_notify") + HostData(CMD& cmd, const char* host_gimbal_topic_name = "target_euler", + const char* host_chassis_data_topic_name = "host_chassis_data", + const char* host_fire_topic_name = "host_fire_notify") : cmd_(&cmd), host_gimbal_data_tp_( LibXR::Topic::CreateTopic(host_gimbal_topic_name)),