ccg-ros2-workflow 2.2.1 → 3.0.0

package/templates/skills/domains/ros2-hardware/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: ros2-hardware
+description: ROS2 硬件集成技能。串口、CAN 总线、I2C/SPI、传感器驱动、udev 规则、权限配置。当用户提到串口、CAN、Modbus、ttyUSB、ttyACM、udev、设备权限、硬件抽象时使用。
+user-invocable: false
+category: domain
+---
+
+# ROS2 硬件集成技能
+
+## 适用场景
+
+物理机器人硬件接入,涉及驱动开发、协议解析、设备权限。
+
+### 触发关键词
+
+- 串口 / Serial / RS232 / RS485 / ttyUSB / ttyACM
+- CAN / SocketCAN / can0 / candump / cansend
+- I2C / SPI / GPIO
+- USB / udev / 设备权限
+- Modbus / Modbus RTU / Modbus TCP
+
+---
+
+## 串口通信
+
+### ROS2 推荐库:`serial_driver` (transport_drivers)
+
+```cpp
+#include <io_context/io_context.hpp>
+#include <serial_driver/serial_driver.hpp>
+
+using drivers::common::IoContext;
+using drivers::serial_driver::SerialDriver;
+using drivers::serial_driver::SerialPortConfig;
+
+IoContext ctx(2);
+SerialPortConfig config(115200,  // baud_rate
+                        drivers::serial_driver::FlowControl::NONE,
+                        drivers::serial_driver::Parity::NONE,
+                        drivers::serial_driver::StopBits::ONE);
+auto driver = std::make_unique<SerialDriver>(ctx);
+driver->init_port("/dev/ttyUSB0", config);
+driver->port()->open();
+
+driver->port()->async_receive([](const std::vector<uint8_t>& buffer, size_t bytes_transferred) {
+  // 处理接收数据
+});
+
+std::vector<uint8_t> data{0xAA, 0x55};
+driver->port()->async_send(data);
+```
+
+### 简单方案:Python pyserial
+
+```python
+import serial
+
+ser = serial.Serial('/dev/ttyUSB0', 115200, timeout=1.0)
+ser.write(b'\xAA\x55')
+data = ser.read(8)
+ser.close()
+```
+
+---
+
+## CAN 总线
+
+### SocketCAN 配置
+
+```bash
+# 启用 CAN0
+sudo ip link set can0 up type can bitrate 1000000
+
+# 检查状态
+ip -details link show can0
+
+# 抓包调试
+candump can0
+cansend can0 100#1122334455667788
+```
+
+### ROS2 推荐:`ros2_socketcan`
+
+```bash
+ros2 launch ros2_socketcan socket_can_bridge.launch.xml \
+  interface:=can0
+```
+
+发布的话题:
+- `/from_can_bus` (can_msgs/Frame): 接收的 CAN 帧
+- `/to_can_bus` (can_msgs/Frame): 发送的 CAN 帧
+
+### C++ SocketCAN 直接调用
+
+```cpp
+#include <linux/can.h>
+#include <linux/can/raw.h>
+#include <sys/ioctl.h>
+#include <net/if.h>
+
+int sock = socket(PF_CAN, SOCK_RAW, CAN_RAW);
+struct ifreq ifr;
+strcpy(ifr.ifr_name, "can0");
+ioctl(sock, SIOCGIFINDEX, &ifr);
+
+struct sockaddr_can addr = {};
+addr.can_family = AF_CAN;
+addr.can_ifindex = ifr.ifr_ifindex;
+bind(sock, (struct sockaddr*)&addr, sizeof(addr));
+
+struct can_frame frame;
+read(sock, &frame, sizeof(frame));  // 阻塞接收
+```
+
+---
+
+## udev 规则(关键!)
+
+避免 `/dev/ttyUSB0` 编号变化导致驱动失效。
+
+### 创建规则文件
+
+```bash
+sudo nano /etc/udev/rules.d/99-my-robot.rules
+```
+
+```
+# RPLidar A2
+SUBSYSTEM=="tty", ATTRS{idVendor}=="10c4", ATTRS{idProduct}=="ea60", \
+  MODE="0666", SYMLINK+="rplidar"
+
+# 电机驱动
+SUBSYSTEM=="tty", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", \
+  ATTRS{serial}=="A12345", MODE="0666", SYMLINK+="motor_driver"
+```
+
+### 重载规则
+
+```bash
+sudo udevadm control --reload-rules
+sudo udevadm trigger
+ls -l /dev/rplidar  # 验证 symlink
+```
+
+### 查询设备信息
+
+```bash
+# 查看 USB 设备 vendor/product ID
+lsusb
+
+# 查看串口完整属性
+udevadm info -a -n /dev/ttyUSB0
+```
+
+---
+
+## 设备权限
+
+### 添加用户到 dialout 组(串口)
+
+```bash
+sudo usermod -aG dialout $USER
+# 重新登录生效
+```
+
+### CAN 用户权限
+
+```bash
+sudo usermod -aG can $USER
+# 或在 udev 规则中设置 GROUP="can"
+```
+
+---
+
+## I2C / SPI
+
+### Linux i2c-tools
+
+```bash
+sudo apt install i2c-tools
+i2cdetect -y 1   # 扫描总线 1
+i2cget -y 1 0x68 0x75   # 读寄存器
+i2cset -y 1 0x68 0x6B 0x00   # 写寄存器
+```
+
+### ROS2 节点示例 (libi2c-dev)
+
+```cpp
+#include <fcntl.h>
+#include <linux/i2c-dev.h>
+#include <sys/ioctl.h>
+
+int fd = open("/dev/i2c-1", O_RDWR);
+ioctl(fd, I2C_SLAVE, 0x68);  // IMU 地址
+
+uint8_t reg = 0x3B;
+write(fd, &reg, 1);
+uint8_t buf[14];
+read(fd, buf, 14);
+```
+
+---
+
+## 硬件抽象层 (HAL) 设计
+
+### 接口模式
+
+```cpp
+class HardwareInterface {
+public:
+  virtual ~HardwareInterface() = default;
+  virtual bool connect() = 0;
+  virtual bool disconnect() = 0;
+  virtual bool read(uint8_t* data, size_t len) = 0;
+  virtual bool write(const uint8_t* data, size_t len) = 0;
+};
+
+class SerialHardware : public HardwareInterface { /* ... */ };
+class CanHardware : public HardwareInterface { /* ... */ };
+```
+
+### 错误处理
+
+```cpp
+class HardwareDriver : public rclcpp::Node {
+private:
+  void publish_diagnostic() {
+    diagnostic_msgs::msg::DiagnosticStatus status;
+    status.name = "Motor Driver";
+    if (!hw_->is_connected()) {
+      status.level = DiagnosticStatus::ERROR;
+      status.message = "Hardware disconnected";
+    } else {
+      status.level = DiagnosticStatus::OK;
+    }
+    diag_pub_->publish(status);
+  }
+
+  // 自动重连
+  void reconnect_loop() {
+    if (!hw_->is_connected()) {
+      RCLCPP_WARN(this->get_logger(), "Reconnecting...");
+      hw_->connect();
+    }
+  }
+};
+```
+
+---
+
+## 调试工具
+
+```bash
+# 串口
+sudo apt install minicom screen
+screen /dev/ttyUSB0 115200
+
+# CAN
+sudo apt install can-utils
+candump -tz can0
+cangen can0 -v   # 生成测试帧
+
+# 系统设备
+dmesg | tail   # 查看插拔日志
+udevadm monitor   # 实时监控 udev 事件
+```
+
+---
+
+## 安全清单
+
+- [ ] udev 规则避免设备编号漂移
+- [ ] 软件层面的硬件超时检测
+- [ ] 自动重连逻辑
+- [ ] 硬件诊断话题 `/diagnostics`
+- [ ] 急停按钮独立硬件回路(不经软件)
+- [ ] 看门狗定时器(硬件级)

package/templates/skills/domains/ros2-manipulation/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: ros2-manipulation
+description: ROS2 机械臂操作技能。MoveIt 2、运动规划、抓取规划、逆运动学、笛卡尔规划。当用户提到 MoveIt、机械臂、抓取、IK、URDF、joint_trajectory、planning scene 时使用。
+user-invocable: false
+category: domain
+---
+
+# ROS2 机械臂操作技能
+
+## 适用场景
+
+机械臂运动规划、抓取、操作任务。
+
+### 触发关键词
+
+- MoveIt / MoveIt2 / move_group
+- 机械臂 / manipulator / arm
+- 抓取 / grasp / pick / place
+- 逆运动学 / IK / FK / 运动学
+- URDF / SRDF / xacro
+- 轨迹 / trajectory / OMPL / CHOMP / STOMP
+
+---
+
+## MoveIt 2 架构
+
+```
+[move_group] (核心节点)
+    ├── [Planning Pipeline] (OMPL/CHOMP/STOMP)
+    ├── [Planning Scene] (碰撞检测)
+    ├── [Trajectory Execution] (FollowJointTrajectory Action)
+    └── [Robot State] (joint_states)
+```
+
+### 启动 MoveIt 2
+
+```bash
+ros2 launch <robot>_moveit_config demo.launch.py
+```
+
+---
+
+## URDF/SRDF 基础
+
+### URDF 关键元素
+
+```xml
+<robot name="my_robot">
+  <link name="base_link">
+    <visual>
+      <geometry><cylinder length="0.1" radius="0.05"/></geometry>
+    </visual>
+    <collision>
+      <geometry><cylinder length="0.1" radius="0.05"/></geometry>
+    </collision>
+    <inertial>
+      <mass value="1.0"/>
+      <inertia ixx="0.01" iyy="0.01" izz="0.01" ixy="0" ixz="0" iyz="0"/>
+    </inertial>
+  </link>
+
+  <joint name="joint1" type="revolute">
+    <parent link="base_link"/>
+    <child link="link1"/>
+    <origin xyz="0 0 0.1" rpy="0 0 0"/>
+    <axis xyz="0 0 1"/>
+    <limit lower="-3.14" upper="3.14" effort="10" velocity="1.0"/>
+  </joint>
+</robot>
+```
+
+### SRDF 规划组
+
+```xml
+<robot name="my_robot">
+  <group name="arm">
+    <chain base_link="base_link" tip_link="end_effector"/>
+  </group>
+  <group_state name="home" group="arm">
+    <joint name="joint1" value="0"/>
+    <joint name="joint2" value="-1.57"/>
+  </group_state>
+</robot>
+```
+
+---
+
+## C++ MoveIt 2 API
+
+```cpp
+#include <moveit/move_group_interface/move_group_interface.h>
+
+auto move_group = std::make_shared<moveit::planning_interface::MoveGroupInterface>(
+    node, "arm");
+
+// 设置目标位姿
+geometry_msgs::msg::Pose target;
+target.position.x = 0.5;
+target.position.y = 0.0;
+target.position.z = 0.5;
+target.orientation.w = 1.0;
+move_group->setPoseTarget(target);
+
+// 规划
+moveit::planning_interface::MoveGroupInterface::Plan plan;
+auto success = (move_group->plan(plan) ==
+                moveit::core::MoveItErrorCode::SUCCESS);
+
+if (success) {
+  move_group->execute(plan);
+}
+```
+
+### 笛卡尔路径
+
+```cpp
+std::vector<geometry_msgs::msg::Pose> waypoints;
+waypoints.push_back(start_pose);
+waypoints.push_back(mid_pose);
+waypoints.push_back(end_pose);
+
+moveit_msgs::msg::RobotTrajectory trajectory;
+double fraction = move_group->computeCartesianPath(
+    waypoints, 0.01, 0.0, trajectory);
+
+if (fraction > 0.95) {
+  move_group->execute(trajectory);
+}
+```
+
+---
+
+## Python MoveIt 2 (pymoveit2)
+
+```python
+from pymoveit2 import MoveIt2
+from rclpy.executors import MultiThreadedExecutor
+
+moveit2 = MoveIt2(
+    node=node,
+    joint_names=["joint1", "joint2", "joint3"],
+    base_link_name="base_link",
+    end_effector_name="end_effector",
+    group_name="arm",
+)
+
+# 关节空间运动
+moveit2.move_to_configuration([0.0, -1.57, 0.0])
+moveit2.wait_until_executed()
+
+# 笛卡尔运动
+moveit2.move_to_pose(
+    position=[0.5, 0.0, 0.5],
+    quat_xyzw=[0.0, 0.0, 0.0, 1.0],
+    cartesian=True,
+)
+```
+
+---
+
+## 抓取规划
+
+### Grasp Pose 生成
+
+```cpp
+moveit_msgs::msg::Grasp grasp;
+grasp.grasp_pose.header.frame_id = "base_link";
+grasp.grasp_pose.pose.position.x = 0.5;
+grasp.grasp_pose.pose.position.y = 0.0;
+grasp.grasp_pose.pose.position.z = 0.3;
+
+// 接近
+grasp.pre_grasp_approach.direction.vector.z = -1.0;
+grasp.pre_grasp_approach.min_distance = 0.05;
+grasp.pre_grasp_approach.desired_distance = 0.1;
+
+// 抓取后撤
+grasp.post_grasp_retreat.direction.vector.z = 1.0;
+grasp.post_grasp_retreat.min_distance = 0.05;
+grasp.post_grasp_retreat.desired_distance = 0.15;
+
+move_group->pick("target_object", {grasp});
+```
+
+---
+
+## Planning Scene 管理
+
+### 添加碰撞物体
+
+```cpp
+moveit_msgs::msg::CollisionObject obj;
+obj.header.frame_id = "base_link";
+obj.id = "table";
+
+shape_msgs::msg::SolidPrimitive box;
+box.type = box.BOX;
+box.dimensions = {1.0, 1.0, 0.05};
+obj.primitives.push_back(box);
+
+geometry_msgs::msg::Pose pose;
+pose.position.z = -0.025;
+pose.orientation.w = 1.0;
+obj.primitive_poses.push_back(pose);
+
+obj.operation = obj.ADD;
+
+moveit::planning_interface::PlanningSceneInterface psi;
+psi.applyCollisionObject(obj);
+```
+
+---
+
+## 规划器对比
+
+| 规划器 | 类型 | 特点 |
+|--------|------|------|
+| **OMPL/RRTConnect** | 采样 | 默认,快速找解 |
+| **OMPL/RRTstar** | 采样 | 渐近最优 |
+| **CHOMP** | 优化 | 平滑轨迹 |
+| **STOMP** | 优化 | 处理硬约束 |
+| **Pilz** | 工业 | 直线/圆弧/PTP |
+
+---
+
+## 调试
+
+```bash
+# 可视化规划场景
+rviz2 -d moveit.rviz
+
+# 查看规划组
+ros2 topic echo /move_group/planning_scene
+
+# 监控执行状态
+ros2 topic echo /joint_trajectory_controller/state
+```

package/templates/skills/domains/ros2-navigation/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: ros2-navigation
+description: ROS2 导航技能。Nav2 栈、SLAM、路径规划、costmap、全局/局部规划器。当用户提到 Nav2、SLAM、slam_toolbox、Cartographer、AMCL、costmap、规划器、navfn 时使用。
+user-invocable: false
+category: domain
+---
+
+# ROS2 导航技能
+
+## 适用场景
+
+机器人自主导航,从 SLAM 建图到 Nav2 路径规划。
+
+### 触发关键词
+
+- 导航 / Nav2 / navigation_stack
+- SLAM / slam_toolbox / Cartographer / RTAB-Map
+- 定位 / AMCL / 蒙特卡洛
+- 地图 / map_server / OccupancyGrid
+- 规划 / planner / Dijkstra / A* / DWB / Hybrid A*
+- 代价地图 / costmap / 膨胀层 / 障碍层
+
+---
+
+## Nav2 栈架构
+
+```
+[BT Navigator] (行为树)
+    ├── [Planner Server] (NavfnPlanner / SmacPlanner)
+    ├── [Controller Server] (DWBController / RPP / MPPI)
+    ├── [Recovery Server] (Spin / BackUp / Wait)
+    └── [Costmap 2D] (Global + Local)
+```
+
+### 标准启动
+
+```bash
+ros2 launch nav2_bringup bringup_launch.py \
+  map:=/path/to/map.yaml \
+  use_sim_time:=false \
+  params_file:=/path/to/nav2_params.yaml
+```
+
+### nav2_params.yaml 关键配置
+
+```yaml
+amcl:
+  ros__parameters:
+    use_sim_time: False
+    alpha1: 0.2
+    alpha2: 0.2
+    base_frame_id: "base_footprint"
+    odom_frame_id: "odom"
+    global_frame_id: "map"
+    laser_model_type: "likelihood_field"
+    max_particles: 2000
+    min_particles: 500
+
+global_costmap:
+  global_costmap:
+    ros__parameters:
+      update_frequency: 1.0
+      publish_frequency: 1.0
+      global_frame: map
+      robot_base_frame: base_link
+      robot_radius: 0.22
+      resolution: 0.05
+      plugins: ["static_layer", "obstacle_layer", "inflation_layer"]
+      obstacle_layer:
+        plugin: "nav2_costmap_2d::ObstacleLayer"
+        observation_sources: scan
+        scan:
+          topic: /scan
+          max_obstacle_height: 2.0
+          clearing: True
+          marking: True
+          data_type: "LaserScan"
+      inflation_layer:
+        plugin: "nav2_costmap_2d::InflationLayer"
+        cost_scaling_factor: 3.0
+        inflation_radius: 0.55
+
+planner_server:
+  ros__parameters:
+    planner_plugins: ["GridBased"]
+    GridBased:
+      plugin: "nav2_navfn_planner/NavfnPlanner"
+      tolerance: 0.5
+      use_astar: false
+      allow_unknown: true
+
+controller_server:
+  ros__parameters:
+    controller_frequency: 20.0
+    controller_plugins: ["FollowPath"]
+    FollowPath:
+      plugin: "dwb_core::DWBLocalPlanner"
+      min_vel_x: 0.0
+      max_vel_x: 0.5
+      max_vel_theta: 1.0
+```
+
+---
+
+## SLAM 选型
+
+| 工具 | 适用场景 | 特点 |
+|------|----------|------|
+| **slam_toolbox** | 2D 室内 | 在线建图 + 离线优化,推荐 |
+| **Cartographer** | 2D/3D 室内外 | Google 维护,稳定 |
+| **RTAB-Map** | 3D + 视觉 | 视觉惯性,大场景 |
+| **LIO-SAM** | 3D 户外 | 激光 + IMU 紧耦合 |
+
+### slam_toolbox 启动
+
+```bash
+ros2 launch slam_toolbox online_async_launch.py \
+  use_sim_time:=false \
+  params_file:=/path/to/mapper_params.yaml
+```
+
+### 保存地图
+
+```bash
+ros2 run nav2_map_server map_saver_cli -f my_map
+```
+
+---
+
+## 行为树 (BT)
+
+### 自定义行为节点
+
+```xml
+<root main_tree_to_execute="MainTree">
+  <BehaviorTree ID="MainTree">
+    <RecoveryNode number_of_retries="6" name="NavigateRecovery">
+      <PipelineSequence name="NavigateWithReplanning">
+        <RateController hz="1.0">
+          <RecoveryNode number_of_retries="1" name="ComputePathToPose">
+            <ComputePathToPose goal="{goal}" path="{path}" planner_id="GridBased"/>
+            <ClearEntireCostmap name="ClearGlobalCostmap-Context"
+                                 service_name="global_costmap/clear_entirely_global_costmap"/>
+          </RecoveryNode>
+        </RateController>
+        <RecoveryNode number_of_retries="1" name="FollowPath">
+          <FollowPath path="{path}" controller_id="FollowPath"/>
+          <ClearEntireCostmap name="ClearLocalCostmap-Context"
+                               service_name="local_costmap/clear_entirely_local_costmap"/>
+        </RecoveryNode>
+      </PipelineSequence>
+    </RecoveryNode>
+  </BehaviorTree>
+</root>
+```
+
+---
+
+## 程序化导航
+
+### Nav2 Action Client
+
+```python
+from nav2_simple_commander.robot_navigator import BasicNavigator
+from geometry_msgs.msg import PoseStamped
+
+navigator = BasicNavigator()
+navigator.waitUntilNav2Active()
+
+goal = PoseStamped()
+goal.header.frame_id = 'map'
+goal.pose.position.x = 5.0
+goal.pose.position.y = 3.0
+goal.pose.orientation.w = 1.0
+
+navigator.goToPose(goal)
+
+while not navigator.isTaskComplete():
+    feedback = navigator.getFeedback()
+    print(f'Distance remaining: {feedback.distance_remaining}')
+```
+
+---
+
+## 调试与可视化
+
+```bash
+# RViz2 with Nav2 plugin
+rviz2 -d $(ros2 pkg prefix nav2_bringup)/share/nav2_bringup/rviz/nav2_default_view.rviz
+
+# 查看代价地图
+ros2 topic echo /global_costmap/costmap
+
+# 检查 TF 树
+ros2 run tf2_tools view_frames
+```