# =============================================================================
# devices/robots/flexiv/manifest.yaml
#
# 非夕机械臂（Flexiv Rizon / AICO）驱动清单。
# 框架启动时读这个文件，决定加载哪个适配器、校验哪些配置、检查哪些外部物料。
#
# 这里【不放现场数值】。SN / IP / 速度 / 悬高一律在 config/site.yaml。
# =============================================================================

id: flexiv
label: 非夕 Flexiv Rizon / AICO
kind: robot
vendor: flexiv
version: "RDK 1.9.x（与 flexiv_ros2 humble-v1 v1.9.1 配套）"

description: >
  非夕七轴力控机械臂。当前项目使用 Rizon4 双臂（SN 尾号 89 / 91）。
  上层通过 ros2_control + rizon_arm_controller 下发关节轨迹，柔顺下臂走 RDK 力控原语。

# --- 厂商物料放置要求 ------------------------------------------------------
# 每个条目会在框架启动时被检查；required: true 且文件缺失时直接报错。
assets:
  - path: rdk
    required: true
    what: Flexiv RDK 源码或安装包
    format: 厂商原始发布格式，不要转换、不要重新打包
    naming: 保持厂商原目录名与文件名，一律不要改名
    where_used: driver 通过此路径加载 RDK
    notes: >
      与 flexiv_ros2 humble-v1 配套的是 RDK 1.9.x。仓库外的已编译安装位于
      ~/flexiv_install（由 scripts/env.sh 与 run_real.sh 注入 LD_LIBRARY_PATH）。
      离线安装库在 vendor/rdk_libs/。

# --- 适配器 ----------------------------------------------------------------
driver:
  package: arm_driver_flexiv
  executable: flexiv_arm_driver
  build: colcon

# --- 能力声明 --------------------------------------------------------------
# 框架上层只会调用这里列出的能力。少写一项，上层用到时会启动即报错。
capabilities:
  - get_arm_state
  - follow_joint_trajectory
  - set_named_pose
  - servo_joint
  - servo_cartesian
  - compliant_descent
  - set_tool
  - switch_tool
  - home
  - enable
  - clear_fault
  - soft_drag              # 软拖拽，手眼标定走点用

# --- 配置项声明 ------------------------------------------------------------
# 框架启动时按 site_path 去 config/site.yaml 取值，required 的键缺失即报错。
# unit 会打印在人读的错误信息里，避免「填了毫米但代码按米」这类问题。
config_schema:
  - key: sn
    site_path: robot.robots[].sn
    type: str
    required: true
    doc: 机械臂完整 SN（如 Rizon4-063989）。必须与示教器上显示的一致。

  - key: ip
    site_path: robot.robots[].ip
    type: str
    required: true
    doc: 控制柜 IP。同一网段的工控机地址填 pc_ip。

  - key: pc_ip
    site_path: robot.robots[].pc_ip
    type: str
    required: true
    doc: 工控机在本网段的地址，RDK 白名单用。

  - key: iface
    site_path: robot.robots[].iface
    type: str
    required: true
    doc: 连接控制柜的网卡名（如 enp4s0）。

  - key: tool_name
    site_path: robot.tool_name
    type: str
    required: false
    default: ""
    doc: 示教器 Studio 里的工具坐标系名。留空表示不切换。
         本项目要求 tool1 全程保持垂直向下且位姿锁定，需在此指定。

  - key: tool_z_extend_m
    site_path: robot.tool_z_extend_m
    type: float
    unit: m
    required: false
    default: 0.0
    doc: >
      工具坐标系沿 Z 的延长量。用于补偿「夹具 + 夹持物」超出原质心的距离。
      当前 tool1 质心在未装夹具的平行夹爪末端，装上夹具并夹持通止规后需沿 Z 延长。
      标定方法见 docs/TOOL_FRAME.md。

  - key: ee_z_m
    site_path: robot.robots[].servo.ee_z_m
    type: float
    unit: m
    required: true
    doc: 视觉跟踪锁高 —— 法兰相对基座系的 Z。
         注意与悬高（相对工具系）区分，两者是不同概念。

  - key: safe_z_m
    site_path: robot.robots[].servo.safe_z_m
    type: float
    unit: m
    required: true
    doc: 防撞安全高度。启动归位时先抬到这个高度再水平移动。