packageName: robot.test.org
version: 0.1.0
kind: AtomAbility
metadata:
  name: HeadAbility

spec:
  schema:
    openAPIV3Schema:
      type: object
      properties:
        config:
          type: object
          properties:
            robotUri:
              type: string
          required: [robotUri]
      
      # 定义数据类型
      types:
        HeadJointState:
          type: object
          description: 头部关节状态
          properties:
            yaw:
              type: number
              description: 当前yaw角度（弧度）
            pitch:
              type: number
              description: 当前pitch角度（弧度）
      
      # 定义能力相关任务
      tasks:
        - taskType: 0
          taskName: HeadJointControl
          summary: 控制头部关节角度到指定位置
          params:
            - name: yaw
              type: number
              description: 目标yaw角度（弧度，必填）
              required: true
            - name: pitch
              type: number
              description: 目标pitch角度（弧度，必填）
              required: true
            - name: yaw_threshold
              type: number
              description: yaw角度阈值（弧度），默认0.1
              default: 0.1
            - name: pitch_threshold
              type: number
              description: pitch角度阈值（弧度），默认0.1
              default: 0.1
            - name: timeout
              type: number
              description: 超时时间（秒），默认10
              default: 10.0
            - name: interval
              type: number
              description: 状态反馈间隔（秒），默认1
              default: 1.0
          returns:
            type: HeadJointState
            description: 执行过程中返回当前yaw和pitch，执行成功后payload为空
        
        - taskType: 1
          taskName: TargetTracking
          summary: 头部追踪指定空间位置的目标
          params:
            - name: source
              type: string
              description: 坐标系来源，可选值：camera/base/odom（必填）
              required: true
              enum: [camera, base, odom]
            - name: position
              type: Point3d
              description: 目标位置（必填）
              required: true
            - name: camera_height
              type: number
              description: 摄像头在机器人坐标系下的高度（米），默认0.75
              default: 0.75
              required: true
            - name: interval
              type: number
              description: 追踪更新间隔（秒），默认1
              default: 1.0
          returns:
            type: object
            description: 追踪任务持续运行直到被取消
          cancellable: true
        
        - taskType: 2
          taskName: GetHeadPose
          summary: 获取当前头部姿态
          params: []
          returns:
            type: HeadJointState
            description: 返回当前头部的yaw和pitch角度（弧度）