ros_contorl/devices/sensors/orisys/manifest.yaml

# =============================================================================
# devices/sensors/orisys/manifest.yaml
#
# Orisys 视触觉传感器驱动清单（框架核心）。
#
# 这里【不放现场数值】。video 路径 / 型号 / 发布率一律在 config/site.yaml。
# =============================================================================

id: orisys
label: Orisys 视触觉传感器
kind: sensor
vendor: orisys
version: "待填 —— 放入 SDK 后在此记录实际版本号"

# 从哪里读出「当前用哪个型号」。值是 config_schema 里的 field key。
# 框架据此叠加该型号的额外能力（型号能力与顶层能力取并集）。
model_selector: model

description: >
  视触觉传感器，输出两路切向力 + 一路法向力，以及深度图与力矢量图。
  采用双指方案，左右指各一个独立进程（防止抢 CUDA 上下文）。
  是本框架的长期核心，后续所有项目围绕它开发。

# 重要：上层算法依赖的数据契约
outputs:
  - topic: tangential_1
    ros_topic: "/tactile/{left|right}/status"
    field: fshearx
    msg: arm_msgs/TactileStatus
    type: scalar
    unit: 任意单位（非牛顿）
    notes: 基线会漂移，所有阈值必须按「相对静止均值的增量」使用

  - topic: tangential_2
    ros_topic: "/tactile/{left|right}/status"
    field: fsheary
    msg: arm_msgs/TactileStatus
    type: scalar
    unit: 任意单位（非牛顿）
    notes: 与 tangential_1 正交。通止规装配需要确认哪一路对应哪个方向，见 README

  - topic: normal
    ros_topic: "/tactile/{left|right}/status"
    field: fnormal
    msg: arm_msgs/TactileStatus
    type: scalar
    unit: 任意单位（非牛顿）
    notes: 法向力。拧紧判定需要「法向力突增」这一条件

  - topic: depth
    ros_topic: "/tactile/{left|right}/image"
    msg: sensor_msgs/Image
    type: image
    unit: null
    notes: >
      接触面深度 / 形变图。编码随 SDK 返回值而定：float32 深度图是 32FC1，
      uint8 形变图是 mono8（image_utils 自动判断，判不出来就跳过并告警一次）。

      需要把 site.yaml 的 tactile.image_hz 设为 >0 才会发布 —— 默认 0（关闭），
      因为图像每帧几百 KB，不该让它挤占三力那条 30fps 的时序。

  - topic: force_vector
    ros_topic: "/tactile/{left|right}/vector"
    msg: sensor_msgs/Image
    type: image
    unit: null
    notes: >
      接触点力矢量场。每像素 2 个 float32（dx, dy），编码 32FC2 —— 这是 ROS 里
      表达矢量场的标准方式。

      Orisys 的绑定里没有一个明确叫 "force vector map" 的方法，所以实现按语义
      依次尝试 compute_flow / compute_hhd / compute_deformation，取第一个返回
      二维以上数组的。全都拿不到就不发这个话题（宁可没有，也不发一张假图）。

      同样需要 tactile.image_hz > 0。

# --- 厂商物料放置要求 ------------------------------------------------------
assets:
  - path: sdk
    required: true
    what: Orisys 厂商 SDK（Python 包或原生库）
    format: 厂商原始发布格式，不要转换、不要重新打包
    naming: 保持厂商原目录名与文件名，一律不要改名
    where_used: driver 通过 PYTHONPATH 或 pip install -e 加载
    notes: >
      SDK 内部常按自己的包名做导入与资源查找，改名会直接导致 ImportError。

  - path: models
    required: true
    what: 各传感器型号的配置
    format: 每个型号一个子目录，内含 config.json
    naming: 子目录名即型号名，会被 site.yaml 的 tactile.model 引用
    where_used: driver 按 site.yaml 选中的型号加载对应配置

# --- 适配器 ----------------------------------------------------------------
driver:
  package: arm_driver_orisys
  executable: orisys_tactile_driver
  build: colcon
  notes: >
    必须保持「左右指各一个独立进程」的架构，不要合并。
    必须保留退出时清理孤儿 worker 的逻辑（否则占死 /dev/video）。

# --- 能力声明 --------------------------------------------------------------
capabilities:
  - read_tangential
  - read_normal
  - read_depth
  - read_force_vector
  - measure_baseline

# --- 配置项声明 ------------------------------------------------------------
config_schema:
  - key: model
    site_path: tactile.model
    type: str
    required: true
    doc: 当前使用的传感器型号名。必须与 devices/sensors/orisys/models/ 下的子目录名一致。

  - key: left_video
    site_path: tactile.left_video
    type: str
    required: true
    doc: >
      左指相机路径。必须用 /dev/v4l/by-path/ 下的稳定路径，
      不要写 /dev/video0（编号会随插拔漂移）。

  - key: right_video
    site_path: tactile.right_video
    type: str
    required: true
    doc: 右指相机路径，同样用 by-path 稳定路径。

  - key: baseline_seconds
    site_path: tactile.baseline_seconds
    type: float
    unit: s
    required: false
    default: 2.0
    doc: 启动后采集静止基线的时间。所有力阈值都是相对这个基线的增量。

  - key: publish_hz
    site_path: tactile.publish_hz
    type: float
    unit: Hz
    required: false
    default: 20.0
    doc: 数据发布率。

  - key: image_hz
    site_path: tactile.image_hz
    type: float
    unit: Hz
    required: false
    default: 0.0
    doc: >
      视触觉图像（深度/形变图，话题 /tactile/<side>/image）与力矢量场
      （话题 /tactile/<side>/vector）的发布频率。0 = 关闭。

      默认关是因为图像每帧几百 KB，跨进程序列化 + ROS 发布的开销远大于三力；
      三力的 30fps 是接触判据的基础，不该被动到。图像走一条独立的
      maxsize=1 队列，满了丢旧留新，所以打开它也不会拖累三力。
      人工观察 / 调试设 5~10 即可，不必跟 target_fps 一样高。

  - key: cuda
    site_path: tactile.cuda
    type: bool
    required: false
    default: false
    doc: >
      双指并行时保持 false —— 开 GPU 会让两路互相抢 CUDA 上下文，反而更慢。

  - key: infer_backend
    site_path: tactile.infer_backend
    type: str
    required: false
    default: cpu
    doc: 推理后端。cpu / cupy / opencl。双指场景建议 cpu。

# --- 力阈值（通止规装配用）-------------------------------------------------
# 全部是「相对静止均值的增量」，不是绝对值。见 README 的坑点说明。
force_thresholds:
  - key: touch_delta
    site_path: hole_detect.stage3.touch_delta
    unit: 增量
    doc: 触面判定 —— 超过这个增量认为接触到了工件表面

  - key: screw_done_shear_delta
    site_path: system.screw_done_shear_delta
    unit: 增量
    doc: >
      拧紧判定条件之一 —— 切向力超过这个增量。
      必须与 screw_done_normal_delta 同时满足才判定拧紧到位。

  - key: screw_done_normal_delta
    site_path: system.screw_done_normal_delta
    unit: 增量
    doc: 拧紧判定条件之二 —— 法向力突增。

  - key: safe_delta
    site_path: hole_detect.stage3.safe_press_delta
    unit: 增量
    doc: 安全上限。任何时候超过立即抬升并报错。