LeKiwi 移动机械臂

Relevant source files

The following files were used as context for generating this wiki page:

LeKiwi 平台是集成到 IB-Robot 框架中的三轮全向移动机械臂。它把 6-DOF SO101 机械臂和自定义移动底盘组合在一起，通过 lekiwi_hardware 插件使用 Feetech STS 协议统一控制基于位置的机械臂关节和基于速度的底盘电机。

系统架构

LeKiwi 系统作为 ros2_control SystemInterface 运行，把 9 个物理电机（6 个机械臂，3 个底盘）抽象为标准 ROS 2 命令接口和状态接口。

硬件映射图

下图展示高层 ROS 2 控制器与底层 LeKiwiSystemHardware 实现之间的关系。

        graph TD
    subgraph "ROS 2 Control Layer"
        A[arm_position_controller] --> |"Joints 1-5"| HW["lekiwi_hardware/LeKiwiSystemHardware"]
        G[gripper_position_controller] --> |"Joint 6"| HW
        B[base_velocity_controller] --> |"Joints 7-9"| HW
        HW --> JS[joint_state_broadcaster]
    end

    subgraph "Physical Hardware (Feetech STS)"
        HW --> |"SyncWritePosEx (ID 1-6)"| ARM_MOTORS["6x STS Position Servos"]
        HW --> |"SyncWriteSpe (ID 7-9)"| BASE_MOTORS["3x Wheel Velocity Servos"]
        ARM_MOTORS --> |"SyncRead"| HW
        BASE_MOTORS --> |"SyncRead"| HW
    end

    subgraph "Code Entities"
        HW_CLASS["lekiwi_hardware::LeKiwiSystemHardware"]
        FEETECH_SDK["SMS_STS.h (Feetech SDK)"]
    end

来源: src/lekiwi_hardware/README.md:17-40, src/lekiwi_hardware/include/lekiwi_hardware/lekiwi_system_hardware.hpp:19-25, src/lekiwi_hardware/config/lekiwi_controllers.yaml:1-20

硬件接口（lekiwi_hardware）

lekiwi_hardware 包提供 LeKiwiSystemHardware 插件，实现 hardware_interface::SystemInterface src/lekiwi_hardware/include/lekiwi_hardware/lekiwi_system_hardware.hpp:25-25。它通过 1 Mbps 串口连接管理与 Feetech SMS_STS 舵机的通信 src/lekiwi_hardware/README.md:225-226。

关键函数和控制循环

坐标与单位转换

插件负责 ROS 2 标准单位（弧度、rad/s）与 Feetech 原始 ticks 之间的转换。转换逻辑集中在 lekiwi_conversions.hpp 中 src/lekiwi_hardware/README.md:210-210。

函数

用途

ticks_to_radians(raw_ticks)

机械臂位置：raw ticks → radians

radians_to_ticks(radians)

机械臂位置：radians → ticks（限幅到 [0, 4095]）

steps_to_rad_s(raw_speed)

速度：raw steps/s → rad/s

rad_s_to_steps(rad_per_sec)

速度：rad/s → steps/s（限幅到 [-32768, 32767]）

decode_motor_register(low, high)

解码 2 字节寄存器（bit 15 为符号位）

encode_homing_offset(offset)

编码回零偏移（bit 11 为符号位）

来源: src/lekiwi_hardware/src/lekiwi_system_hardware.cpp, src/lekiwi_hardware/README.md:172-180, src/lekiwi_hardware/include/lekiwi_hardware/lekiwi_conversions.hpp

机器人描述（lekiwi_description）

lekiwi_description 包包含平台的 URDF/Xacro 模型。主模型是 lekiwi_assembled.urdf.xacro，它把 SO101 机械臂与 LeKiwi 三轮底盘合并 src/lekiwi_description/urdf/lekiwi_assembled.urdf.xacro:5-8。

运动学配置

来源: src/lekiwi_description/urdf/lekiwi_assembled.urdf.xacro:1-161, src/lekiwi_description/urdf/base.common.xacro:1-32

机器人配置（lekiwi_navi）

lekiwi_navi.yaml 文件是移动操作任务的 Single Source of Truth，定义控制模式、导航参数和模型推理设置 src/robot_config/config/robots/lekiwi_navi.yaml:2-6。

控制模式

该配置定义三种运行模式：

  1. teleop: Human-in-the-loop 控制，使用 leader arm 和键盘控制底盘。推理被显式禁用 src/robot_config/config/robots/lekiwi_navi.yaml:40-56。

  2. model_inference: 使用 ACT（Action Chunking with Transformers）策略的自主控制，采用分布式执行模式 src/robot_config/config/robots/lekiwi_navi.yaml:58-78。

  3. navi: 集成导航与操作模式。该模式启用 action_dispatch 节点，并将 watermark_threshold 设置为 20，在移动任务中管理 action 队列，同时设置 navigation_mode 为 true，用于导航期间的显式底盘控制 src/robot_config/config/robots/lekiwi_navi.yaml:80-98。

导航集成

LeKiwi 使用 navigation 块中定义的完整导航栈：

Action Dispatch 数据流

下图描述 LeKiwi 平台如何处理推理结果。

        sequenceDiagram
    participant IS as InferenceService
    participant AD as ActionDispatcherNode
    participant TS as TemporalSmoother
    participant RC as ros2_control_controllers

    IS->>AD: DispatchInfer Result (Action Chunk)
    Note over AD: Decode VariantsList to Tensor
    AD->>TS: Raw Action Chunk
    Note over TS: Exponential Weighting Blending
    TS->>AD: Smoothed Actions
    loop 30Hz Control Loop
        AD->>RC: /arm_position_controller/commands (Joints 1-6)
        AD->>RC: /base_velocity_controller/commands (Joints 7-9)
    end

来源: src/robot_config/config/robots/lekiwi_navi.yaml:92-98

外设配置

该平台配备多个相机和传感器，作为 peripherals 定义：

来源: src/robot_config/config/robots/lekiwi_navi.yaml:209-246, src/lekiwi_description/urdf/base.common.xacro:1-32