syntax = "proto3";

package cmvr.api;

import "cmvr/api/common.proto";

// 机械臂笛卡尔命令使用的参考坐标系。
enum ArmFrameType {
  // 机械臂基座坐标系，无单位。
  ARM_FRAME_BASE = 0;
  // 当前工具/TCP 坐标系，无单位。
  ARM_FRAME_TOOL = 1;
  // 世界坐标系，无单位。
  ARM_FRAME_WORLD = 2;
  // 用户自定义坐标系，无单位。
  ARM_FRAME_USER = 3;
}

// 关节位置命令；数组顺序必须与机械臂关节顺序一致。
message JointPositionCommand {
  // 各关节目标角度，单位：rad。
  repeated double position = 1;
}

// 关节速度命令；数组顺序必须与机械臂关节顺序一致。
message JointVelocityCommand {
  // 各关节目标角速度，单位：rad/s。
  repeated double velocity = 1;
}

// MoveJ 和 MoveL 共用的运动参数。
message MotionOptions {
  // 目标速度；MoveJ 单位为 rad/s，MoveL 单位为 m/s。
  double velocity = 1;
  // 目标加速度；MoveJ 单位为 rad/s^2，MoveL 单位为 m/s^2。
  double acceleration = 2;
  // 路径交融半径，单位：m；0 表示不交融。
  double blend_radius = 3;
  // 目标加加速度；MoveJ 单位为 rad/s^3，MoveL 单位为 m/s^3。
  double jerk = 4;
  // MoveL 规划时各关节的最大角速度限制，单位：rad/s。
  repeated double joint_velocity_limits = 5;
  // 是否异步执行；true 表示命令提交后立即返回，无单位。
  bool asynchronous = 6;
}

// TCP 的笛卡尔位姿。
message CartesianPose {
  // X 方向位置，单位：m。
  double x = 1;
  // Y 方向位置，单位：m。
  double y = 2;
  // Z 方向位置，单位：m。
  double z = 3;
  // 绕 X 轴的姿态分量，单位：rad。
  double rx = 4;
  // 绕 Y 轴的姿态分量，单位：rad。
  double ry = 5;
  // 绕 Z 轴的姿态分量，单位：rad。
  double rz = 6;
}

// TCP 的笛卡尔速度。
message CartesianVelocity {
  // X 方向线速度，单位：m/s。
  double vx = 1;
  // Y 方向线速度，单位：m/s。
  double vy = 2;
  // Z 方向线速度，单位：m/s。
  double vz = 3;
  // 绕 X 轴角速度，单位：rad/s。
  double wx = 4;
  // 绕 Y 轴角速度，单位：rad/s。
  double wy = 5;
  // 绕 Z 轴角速度，单位：rad/s。
  double wz = 6;
}

// 4x4 齐次变换矩阵；前三列为无量纲旋转矩阵，第四列前三项为平移量（m）。
message TransformMatrix4x4 {
  // 第一行：m00~m02 无单位，m03 单位为 m。
  double m00 = 1; double m01 = 2; double m02 = 3; double m03 = 4;
  // 第二行：m10~m12 无单位，m13 单位为 m。
  double m10 = 5; double m11 = 6; double m12 = 7; double m13 = 8;
  // 第三行：m20~m22 无单位，m23 单位为 m。
  double m20 = 9; double m21 = 10; double m22 = 11; double m23 = 12;
  // 齐次矩阵最后一行，均无单位，通常为 [0, 0, 0, 1]。
  double m30 = 13; double m31 = 14; double m32 = 15; double m33 = 16;
}

// 关节空间点到点运动命令。
message MoveJ {
  // MoveJ 请求。
  message Request {
    // 通用请求头，包含目标设备 ID 和请求时间戳。
    CommandHeader.Request header = 1;
    // 关节目标位置，单位：rad。
    JointPositionCommand target = 2;
    // 运动参数；速度/加速度/加加速度单位分别为 rad/s、rad/s^2、rad/s^3。
    MotionOptions options = 3;
  }

  // MoveJ 执行结果。
  message Response {
    // 通用响应头，包含成功标志、错误信息和响应时间戳。
    CommandHeader.Feedback header = 1;
  }
}

// TCP 笛卡尔直线运动命令。
message MoveL {
  // MoveL 请求。
  message Request {
    // 通用请求头，包含目标设备 ID 和请求时间戳。
    CommandHeader.Request header = 1;
    // TCP 目标位姿；位置单位为 m，姿态单位为 rad。
    CartesianPose target = 2;
    // 运动参数；速度/加速度/加加速度单位分别为 m/s、m/s^2、m/s^3。
    MotionOptions options = 3;
    // 未指定命名坐标系时使用的参考坐标系，无单位。
    ArmFrameType frame = 4;
    // 可选基准坐标系名称，无单位；不传或为空时使用驱动配置的默认基准坐标系。
    optional string base_frame = 5;
    // 可选 TCP 坐标系名称，无单位；不传或为空时使用驱动配置的默认 TCP 坐标系。
    optional string tcp_frame = 6;
  }

  // MoveL 执行结果。
  message Response {
    // 通用响应头，包含成功标志、错误信息和响应时间戳。
    CommandHeader.Feedback header = 1;
  }
}

// 查询机械臂可用坐标系名称。
message ListFrame {
  // 坐标系列表查询请求。
  message Request {
    // 通用请求头，包含目标设备 ID 和请求时间戳。
    CommandHeader.Request header = 1;
  }

  // 坐标系列表查询结果。
  message Response {
    // 通用响应头，包含成功标志、错误信息和响应时间戳。
    CommandHeader.Feedback header = 1;
    // 可选坐标系名称列表，无单位。
    repeated string frame_names = 2;
  }
}

// 关节速度运动命令。
message SpeedJ {
  // SpeedJ 请求。
  message Request {
    // 通用请求头，包含目标设备 ID 和请求时间戳。
    CommandHeader.Request header = 1;
    // 各关节目标角速度，单位：rad/s。
    JointVelocityCommand velocity = 2;
    // 关节角加速度，单位：rad/s^2。
    double acceleration = 3;
    // 速度命令持续时间，单位：s；具体停止语义由机械臂驱动实现。
    double duration = 4;
  }

  // SpeedJ 执行结果。
  message Response {
    // 通用响应头，包含成功标志、错误信息和响应时间戳。
    CommandHeader.Feedback header = 1;
  }
}

// TCP 笛卡尔速度运动命令。
message SpeedL {
  // SpeedL 请求。
  message Request {
    // 通用请求头，包含目标设备 ID 和请求时间戳。
    CommandHeader.Request header = 1;
    // TCP 目标速度；线速度单位为 m/s，角速度单位为 rad/s。
    CartesianVelocity velocity = 2;
    // TCP 线加速度，单位：m/s^2。
    double acceleration = 3;
    // 速度命令持续时间，单位：s；具体停止语义由机械臂驱动实现。
    double duration = 4;
    // 速度向量所在的参考坐标系，无单位。
    ArmFrameType frame = 5;
  }

  // SpeedL 执行结果。
  message Response {
    // 通用响应头，包含成功标志、错误信息和响应时间戳。
    CommandHeader.Feedback header = 1;
  }
}

// 关节位置实时伺服命令。
message ServoJ {
  // ServoJ 请求。
  message Request {
    // 通用请求头，包含目标设备 ID 和请求时间戳。
    CommandHeader.Request header = 1;
    // 本周期各关节目标角度，单位：rad。
    JointPositionCommand target = 2;
  }

  // ServoJ 执行结果。
  message Response {
    // 通用响应头，包含成功标志、错误信息和响应时间戳。
    CommandHeader.Feedback header = 1;
  }
}

// 机械臂关节状态。
message JointState {
  // 关节名称列表，无单位；与 position、velocity、effort 按索引对应。
  repeated string name = 1;
  // 关节实际角度，单位：rad。
  repeated double position = 2;
  // 关节实际角速度，单位：rad/s。
  repeated double velocity = 3;
  // 关节实际力矩，单位：N·m。
  repeated double effort = 4;
  // 状态采样的 Unix 时间戳，单位：s。
  double timestamp = 5;
}

// 查询关节状态的请求。
message JointRequest {
  // 通用请求头，包含目标设备 ID 和请求时间戳。
  CommandHeader.Request header = 1;
}

// 查询关节状态的响应。
message JointResponse {
  // 通用响应头，包含成功标志、错误信息和响应时间戳。
  CommandHeader.Feedback header = 1;
  // 当前关节状态。
  JointState state = 2;
}

// 查询 TCP 位姿。
message GetPose {
  // 位姿查询请求。
  message Request {
    // 通用请求头，包含目标设备 ID 和请求时间戳。
    CommandHeader.Request header = 1;
    // 参考坐标系名称，无单位；为空时使用驱动默认基准坐标系。
    string base_link = 2;
    // 末端坐标系名称，无单位；为空时使用驱动默认 TCP 坐标系。
    string ee_link = 3;
  }

  // 位姿查询结果。
  message Response {
    // 通用响应头，包含成功标志、错误信息和响应时间戳。
    CommandHeader.Feedback header = 1;
    // TCP 位姿；位置单位为 m，姿态单位为 rad。
    CartesianPose pose = 2;
  }
}

// 指定关节的零位标定命令。
message CalibrateZeroQ {
  // 零位标定请求。
  message Request {
    // 通用请求头，包含目标设备 ID 和请求时间戳。
    CommandHeader.Request header = 1;
    // 待标定关节名称，无单位。
    string joint_name = 2;
  }

  // 零位标定结果。
  message Response {
    // 通用响应头，包含成功标志、错误信息和响应时间戳。
    CommandHeader.Feedback header = 1;
  }
}

// 查询两个坐标系之间的齐次变换矩阵。
message GetPoseMatrix {
  // 变换矩阵查询请求。
  message Request {
    // 通用请求头，包含目标设备 ID 和请求时间戳。
    CommandHeader.Request header = 1;
    // 参考坐标系名称，无单位。
    string base_link = 2;
    // 目标末端坐标系名称，无单位。
    string ee_link = 3;
  }

  // 变换矩阵查询结果。
  message Response {
    // 通用响应头，包含成功标志、错误信息和响应时间戳。
    CommandHeader.Feedback header = 1;
    // 齐次变换矩阵；旋转元素无单位，平移元素单位为 m。
    TransformMatrix4x4 matrix = 2;
  }
}

// 根据关节角计算正运动学变换矩阵。
message ComputeForwardKinematics {
  // 正运动学计算请求。
  message Request {
    // 通用请求头，包含目标设备 ID 和请求时间戳。
    CommandHeader.Request header = 1;
    // 参考坐标系名称，无单位。
    string base_link = 2;
    // 目标末端坐标系名称，无单位。
    string ee_link = 3;
    // 用于计算的关节角，单位：rad。
    JointPositionCommand joints = 4;
  }

  // 正运动学计算结果。
  message Response {
    // 通用响应头，包含成功标志、错误信息和响应时间戳。
    CommandHeader.Feedback header = 1;
    // 齐次变换矩阵；旋转元素无单位，平移元素单位为 m。
    TransformMatrix4x4 matrix = 2;
  }
}