# =============================================================================
# devices/grippers/dh_pgea/manifest.yaml
#
# 大寰（DH）夹爪驱动清单。覆盖两种型号：
#   PGEA —— 平行夹爪（左臂 89 使用）
#   RGI  —— 旋转夹爪（右臂 91 使用）
#
# 这里【不放现场数值】。串口 / 波特率 / 从站号 / 行程一律在 config/site.yaml。
# =============================================================================

id: dh_pgea
label: 大寰 PGEA 平行爪 / RGI 旋转爪
kind: gripper
vendor: dh
version: "Modbus RTU（工控机 USB-RS485 直连）"

# 从哪里读出「当前用哪个型号」。值是 config_schema 里的 field key。
# RGI 型号会在此基础上叠加 rotate 能力。
model_selector: model

description: >
  大寰夹爪。PGEA 提供开合，RGI 在开合之外提供绕轴旋转。
  通讯走工控机 USB 转 RS485，不经过机械臂控制器。

# --- 厂商物料放置要求 ------------------------------------------------------
assets:
  - path: protocol
    required: false
    what: 大寰 Modbus 协议手册与寄存器表
    format: 厂商原始 PDF / 文档
    naming: 保持原文件名
    where_used: 适配器实现寄存器读写时的依据
    notes: >
      寄存器表已固化进驱动代码（见 driver/）。此目录只作为排查时的对照资料，
      缺失不影响运行。

# --- 适配器 ----------------------------------------------------------------
driver:
  package: arm_driver_dh_gripper
  executable: dh_gripper_driver
  build: colcon

# --- 能力声明 --------------------------------------------------------------
capabilities:
  - open
  - close
  - move
  - get_status

# RGI 型号额外支持旋转。框架按 manifest 的型号分支决定是否暴露 rotate。
models:
  - id: PGEA-100-20-W
    label: PGEA 平行爪（左臂）
    capabilities: [open, close, move, get_status]
    stroke_mm: 20.0

  - id: RGI-100-30-O-S-M1
    label: RGI 旋转爪（右臂）
    capabilities: [open, close, move, rotate, get_status]
    stroke_mm: 30.0
    notes: >
      rotate 是通止规装配 S08 循环的核心原语，必须可独立调用且可随时中止。
      单次转角默认 180°（配置项 system.screw_step_deg），因为不确定基于工具系
      能转多少度是极限。

# --- 配置项声明 ------------------------------------------------------------
config_schema:
  - key: model
    site_path: robot.robots[].gripper.model
    type: str
    required: true
    doc: >
      当前使用的夹爪型号。必须与上面 models 列表里的某个 id 一致。
      型号决定是否具备 rotate 能力（PGEA 没有，RGI 有）。

  - key: port
    site_path: robot.robots[].gripper.port
    type: str
    required: true
    doc: 串口设备路径（如 /dev/ttyUSB0）。建议用 /dev/serial/by-id/ 下的稳定路径，
         因为 ttyUSB 编号会随插拔漂移。

  - key: baud
    site_path: gripper.baud
    type: int
    required: false
    default: 115200
    doc: 波特率。

  - key: slave_id
    site_path: gripper.slave_id
    type: int
    required: false
    default: 1
    doc: Modbus 从站号。

  - key: stroke_mm
    site_path: robot.robots[].gripper.stroke_mm
    type: float
    unit: mm
    required: true
    doc: 该爪的总行程。用于把 0–1000‰ 开度换算成毫米。

  - key: force_pct
    site_path: gripper.force_pct
    type: int
    unit: '%'
    required: false
    default: 20
    doc: 夹紧力百分比。低于 20 会被硬件钳位到 20。

  - key: speed_pct
    site_path: gripper.speed_pct
    type: int
    unit: '%'
    required: false
    default: 50
    doc: 动作速度百分比。

  - key: open_position
    site_path: gripper.open_position
    type: int
    unit: 千分比
    required: false
    default: 1000
    doc: 「张开」对应的开度。1000 = 全开。

  - key: close_position
    site_path: gripper.close_position
    type: int
    unit: 千分比
    required: false
    default: 0
    doc: 「夹紧」对应的开度。0 = 全合。
         注意：通止规是异形件，全合可能压不到，实际夹紧位需要按件标定后填这里。