diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index ace43a9..591717e 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -1,129 +1,13 @@ -name: XRobot Module Build Test - +name: Module CI on: push: pull_request: - schedule: - - cron: '0 3 1 * *' # 每月1日凌晨3点(UTC)自动触发 - + workflow_dispatch: jobs: build: - runs-on: ubuntu-latest - container: - image: ghcr.io/xrobot-org/docker-image-linux:main - options: --user 0 - - env: - XR_MODULE_NAME: ${{ github.event.repository.name }} - - 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}`); + uses: xrobot-org/XRobot/.github/workflows/module-ci.yml@dev + with: + xrobot-ref: dev + libxr-ref: dev + dependency-ref: refs/heads/dev + template-args: '[]' diff --git a/CMD.hpp b/CMD.hpp index e85ced5..a93ae35 100644 --- a/CMD.hpp +++ b/CMD.hpp @@ -2,168 +2,207 @@ /* 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" +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 -#include "app_framework.hpp" #include "event.hpp" #include "libxr_def.hpp" #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 LibXR::Application { +class CMD +{ public: /** - * @brief 控制源枚举 + * @brief 控制源。 + * Control source. */ - enum class ControlSource : uint8_t { - CTRL_SOURCE_RC, /* 遥控器控制源 */ - CTRL_SOURCE_AI, /* AI控制源 */ - CTRL_SOURCE_NUM /* 控制源数量 */ + enum class ControlSource : uint8_t + { + 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 + enum class RCInputSource : uint8_t + { + 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, /* 自动控制模式 */ + enum class Mode : uint8_t + { + 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, /*伸腿*/ + enum class ChasStat : int8_t + { + 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; /* 自定义按钮 */ + typedef struct + { + 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角加速度 */ + typedef struct + { + 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; + typedef struct + { + 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; /* 控制源 */ + typedef struct + { + 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 */ + enum + { + 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_; } - bool GetAIGimbalStatus() { - return this->data_[static_cast(ControlSource::CTRL_SOURCE_AI)] - .gimbal_online; + /** + * @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 直接写入遥控器控制数据 - * @details 兼容接口,默认按DR16输入源写入 + * @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) { + void FeedRC(const Data& rc_data) + { this->FeedRC(RCInputSource::RC_INPUT_DR16, rc_data); } /** - * @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) { + 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; } @@ -171,103 +210,112 @@ class CMD : public LibXR::Application { } /** - * @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) { + 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 云台命令主题名称 + * @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(LibXR::HardwareContainer& hw, LibXR::ApplicationManager& app, 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)), - gimbal_data_tp_(LibXR::Topic::CreateTopic( - gimbal_cmd_topic_name, nullptr, true)), - fire_data_tp_(LibXR::Topic::CreateTopic( - launcher_cmd_topic_name, 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); } /** - * @brief 设置控制模式 - * @param mode 要设置的控制模式 - * @details 根据不同的控制模式配置相应的数据处理回调函数 + * @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)); - } + void EventHandler(uint32_t event_id) { this->SetCtrlMode(static_cast(event_id)); } /** - * @brief 注册控制器 - * @tparam SourceDataType 源数据类型 - * @param source 源主题 - * @details 将外部控制源的数据接入CMD系统,并进行预处理和分发 + * @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) { + void RegisterController(LibXR::Topic& source) + { UNUSED(source); } - /** - * @brief 监控函数重写 - */ - void OnMonitor() override {} - 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_; /* 上位机欧拉角主题 */ + 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; /* 当前活动遥控输入源 */ - uint32_t rc_update_seq_ = 0; /* 遥控输入数据更新序号 */ + 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; - } + 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 +324,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 +336,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 +380,37 @@ 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 { - /* 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; + } + else + { + 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; 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. diff --git a/README.md b/README.md index 7569c8e..1c308fd 100644 --- a/README.md +++ b/README.md @@ -1,77 +1,127 @@ # CMD -用于统一汇总控制输入并发布控制命令的中枢模块。 +控制命令中枢:汇总遥控器与上位机输入,发布底盘、云台、发射命令 / Control command hub that merges remote-controller and host inputs and publishes chassis, gimbal and launcher commands -CMD 把不同来源(例如遥控、上位机)统一整理为三路命令: +## 1. 模块作用 / Purpose -1. 底盘命令 -2. 云台命令 -3. 发射命令 +CMD 把遥控器(DR16、VT13)与上位机等来源的输入整理为三路命令 Topic:底盘命令、云台命令、发射命令。下游模块订阅这三个 Topic,输入来源由 CMD 内部选择。 -## 解决什么问题 +输入由其他模块调用 `FeedRC(...)` 或 `FeedAI(...)` 写入 `CMD::Data`,每次写入立即执行一轮处理并发布三路命令。处理、命令 Topic 的发布以及遥控器上线与离线事件的激活都在调用者的上下文中同步完成,Topic 与事件上注册的回调函数在同一上下文中运行。控制模式事件的回调 `EventHandler` 在激活该事件的上下文中运行,`SetCtrlMode(...)`、`GetCtrlMode()`、`Online()`、`GetAIGimbalStatus()` 在调用者的上下文中直接读写 CMD 的成员。 -CMD 主要解决三件事: +遥控器在线状态变化时,CMD 在自己的事件上激活 `CMD_EVENT_START_CTRL`(`0x13212508`,遥控器上线)或 `CMD_EVENT_LOST_CTRL`(`0x13212509`,遥控器离线)。 -1. 统一控制源输入接口(`FeedRC` / `FeedAI`)。 -2. 统一控制模式切换(操作手/自动等)。 -3. 统一命令发布出口(下游模块只订阅 Topic,不关心输入来源)。 +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. 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. -CMD 的典型流程是: +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. -1. 输入模块调用 `FeedRC(...)` 或 `FeedAI(...)`。 -2. CMD 内部执行 `ProcessAndPublish()`。 -3. 发布 `chassis_cmd`、`gimbal_cmd`、`launcher_cmd`。 -4. 底盘/云台/发射模块各自订阅并执行。 +## 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` 为真。活动源在线时持续使用;活动源离线后切换到另一路在线源;两路都离线时使用全零的离线数据。 -1. `FeedRC(const Data&)`:喂入遥控控制数据。 -2. `FeedAI(const Data&)`:喂入上位机/自动控制数据。 -3. `SetCtrlMode(Mode)`:切换控制模式。 -4. `EventHandler(uint32_t)`:响应外部事件切换模式。 -5. `ProcessAndPublish()`:统一整理并发布命令。 -6. `GetEvent()`:提供事件绑定入口给 EventBinder 等模块使用。 +控制模式决定发布的内容: -## 最小接入示例 +- `CMD_OP_CTRL`(操作手控制):发布遥控数据。 +- `CMD_AUTO_CTRL`(自动控制):底盘命令在 AI 数据的 `chassis_online` 为真时取 AI 数据,否则取遥控数据;云台命令在 AI 数据的 `gimbal_online` 为真时取 AI 数据,否则取遥控数据;发射命令在 AI 与遥控的 `isfire` 同时为真时开火。 -1. 添加模块: +接口: -```bash -xrobot_add_mod CMD --instance-id cmd -xrobot_gen_main +- `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` 等模块通过它绑定事件。 +- `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, + const char* chassis_cmd_topic_name = "chassis_cmd", + const char* gimbal_cmd_topic_name = "gimbal_cmd", + const char* launcher_cmd_topic_name = "launcher_cmd"); ``` -2. 典型配置(来自模块 manifest): +依赖:无。 + +配置参数: + +- `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. + +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 + +三个 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 -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 + 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。 +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. + +## 6. 依赖与硬件 / Dependencies and Hardware -## 使用约定 +依赖:LibXR。 -1. 推荐先初始化 CMD,再初始化依赖它的控制模块。 -2. 控制源切换尽量都走 CMD 的 `SetCtrlMode` / 事件入口。 -3. 不同来源数据结构最终都转换成 `CMD::Data` 再进入 CMD。 +硬件:无。输入数据由 DR16、VT13 等模块写入。 -## 模块信息 +Dependencies: LibXR. -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 +Hardware: none. The input data is written by Modules such as DR16 and VT13.