syntax = "proto3";

// 规范包名，确保与运控调优(control)和传感器外参(sensor)在逻辑上严格物理隔离
package agv.calibration.chassis;

// =========================================================
// 核心服务：AGV 底盘底层硬件自诊与物理运动学标定代理服务
// 部署端：Windows车端 (直连底层电机驱动器/PLC 的网关层)
// 调用端：Linux标定服务器 (掌控外部高精雷达真值)
// =========================================================
service AgvCalibChassisService {

  // ---------------------------------------------------------
  // 1. 底层硬件接管与安全熔断
  // ---------------------------------------------------------
  // 强制接管底层驱动器。注意：这里不仅要切断避障，还要切断底盘的“运动学正逆解算法”
  rpc SetDiagnosticMode(DiagnosticModeRequest) returns (StandardResponse);
  
  // 硬件级绝对急停 (直接向驱动器下发 Safe Torque Off / 机械抱死指令，无视任何上层状态)
  rpc HardwareEmergencyBrake(Empty) returns (StandardResponse);

  // ---------------------------------------------------------
  // 2. 原始物理开环指令下发 (对应方案 4.2 诊断 与 4.3 物理标定)
  // ---------------------------------------------------------
  // 允许 Linux 越过底盘协同模型，直接对指定驱动轮下发最原始的转速(RPM)或占空比
  // 核心用途：暴露真实的机械阻力差、诊断减速机卡死、测试轮胎滑移率
  rpc ExecuteRawDriveCommand(RawDriveRequest) returns (StandardResponse);
  
  // 允许 Linux 直接对转向机构下发绝对物理角度或往复扫频
  // 核心用途：测定舵机机械死区、往复间隙(Backlash)与静态机械零位偏差
  rpc ExecuteRawSteerCommand(RawSteerRequest) returns (StandardResponse);

  // ---------------------------------------------------------
  // 3. 物理运动学本底参数持久化 (出厂定稿写值)
  // ---------------------------------------------------------
  // Linux 结合外部真值算出真实的物理机械参数后，下发并直接覆写到底盘驱动板 EEPROM 或底层配置中
  rpc CommitKinematicParameters(KinematicParams) returns (StandardResponse);

  // ---------------------------------------------------------
  // 4. 原始硬件级高频遥测 (数字孪生健康诊断的唯一依据)
  // ---------------------------------------------------------
  // 🚨 严禁推流经过滤波后的数据！必须是最底层的“原始编码器 Tick”和“绝对相电流”！
  rpc StreamHardwareTelemetry(Empty) returns (stream HardwareState);
}

// =========================================================
// 基础通用消息结构
// =========================================================
message Empty {}

message StandardResponse {
  bool success = 1;
  string message = 2; // 异常时返回驱动器底层故障码 (如 "ERR_MOTOR_OVERCURRENT")
}

message DiagnosticModeRequest {
  enum Mode {
    NORMAL_KINEMATICS = 0; // 正常模式 (底盘接收 V_x, Omega，由底层执行运动学逆解分配)
    DIRECT_RAW_DRIVE = 1;  // 直驱模式 (切断逆解，允许 Linux 直接独立控制左/右轮转速)
  }
  Mode target_mode = 1; 
}

// =========================================================
// 2. 原始驱动指令 (发考题：逼迫底盘暴露出机械缺陷)
// =========================================================
message RawDriveRequest {
  string test_case_id = 1;    // 测试用例 (如 "Slip_Test_0.5m", "Straight_Friction_Test")
  
  // 直接下发给电机的原始指令 (若是两驱车，后轮填 0 即可)
  double fl_motor_rpm = 2;    // 左前轮 (Front-Left) 目标物理转速 (RPM)
  double fr_motor_rpm = 3;    // 右前轮 (Front-Right) 目标物理转速 (RPM)
  double rl_motor_rpm = 4;    // 左后轮 (Rear-Left) 目标物理转速 (RPM)
  double rr_motor_rpm = 5;    // 右后轮 (Rear-Right) 目标物理转速 (RPM)
  
  double duration_sec = 6;    // 动作维持时间，断网防飞车底线：超时底层必须自动刹车
}

message RawSteerRequest {
  string test_case_id = 1;    // 测试用例 (如 "Deadzone_Sweep_5deg")
  
  // 针对舵机/转向推杆的绝对物理指令 (度)
  double front_steer_angle_deg = 2; 
  double rear_steer_angle_deg = 3;  
  
  // 专门用于 4.2节 测定机械间隙的扫频参数
  optional double sweep_amplitude_deg = 4; // 往复抖动幅度 (度)
  optional double sweep_frequency_hz = 5;  // 抖动频率 (Hz)
  
  double duration_sec = 6;
}

// =========================================================
// 3. 运动学本底参数定稿载荷 (纯物理修正系数)
// =========================================================
message KinematicParams {
  // --- 1. 真实有效物理轮径 (解决“开环走直线画大弧”及闭环位移不准) ---
  optional double wheel_radius_fl_m = 1; 
  optional double wheel_radius_fr_m = 2;
  optional double wheel_radius_rl_m = 3;
  optional double wheel_radius_rr_m = 4;

  // --- 2. 机械零位绝对偏差补偿 (解决“指令0度但车子斜着跑”) ---
  optional double steer_zero_offset_front_deg = 5; 
  optional double steer_zero_offset_rear_deg = 6;

  // --- 3. 旋转几何协同参数 (解决“原地打转时车体画圆甩尾摆动”) ---
  optional double effective_track_width_m = 7; // 有效轮距 (左右轮真实物理间距)
  optional double effective_wheel_base_m = 8;  // 有效轴距 (前后轮真实物理间距)
  
  // 针对四驱四转等多舵轮底盘：瞬时旋转中心(ICR)的物理几何偏移
  optional double icr_offset_x_m = 9;          
  optional double icr_offset_y_m = 10;         
}

// =========================================================
// 4. 原始硬件遥测数据流 (Linux 用来排雷、熔断和算滑移率的裸数据)
// =========================================================
message HardwareState {
  int64 hardware_timestamp_us = 1;     // 底层获取到脉冲那一瞬间的高精度单调系统时钟 (微秒)
  
  // --- A. 原始编码器反馈 (用于 4.2 阶段 Linux 计算轮胎打滑率 Slip Ratio) ---
  // 🚨 严禁返回平滑后的速度(m/s)，必须返回最原始的累计脉冲！
  int64 encoder_ticks_fl = 2;         
  int64 encoder_ticks_fr = 3;         
  int64 encoder_ticks_rl = 4;         
  int64 encoder_ticks_rr = 5;         
  
  // 实际物理舵角反馈 (度，用于 4.2 阶段比对指令下发时间，测定机械死区和相位滞后)
  double actual_steer_angle_front_deg = 6; 
  double actual_steer_angle_rear_deg = 7;
  
  // --- B. 动力与负载健康状态 (用于 4.2 阶段诊断减速机干涉或刹车未放) ---
  // 若维持低速所需的电流异常激增，说明机械装配存在过载阻力，Linux 将立刻熔断报警
  double current_fl_amp = 8;          // 左前电机实际相电流 (安培)
  double current_fr_amp = 9;          
  double current_rl_amp = 10;         
  double current_rr_amp = 11;         
  double current_steer_front_amp = 12;// 前转向舵机电流
  
  // --- C. 驱动器底层硬件报警位 ---
  uint32 driver_error_code = 13;      // 0x00=健康, 0x01=过压, 0x02=堵转过流, 0x03=过热等
}