AutoCalib-Workshop/msg/agv_calib_control.proto

syntax = "proto3";

// 规范包名，确保与传感器外参标定业务（agv.calibration.sensor）严格物理与逻辑隔离
package agv.calibration.control;

// =========================================================
// 核心服务：AGV 底盘运动学标定与运控参数调优代理服务
// 部署端：Windows车端 (作为 gRPC Server)
// 调用端：Linux标定服务器 (作为 gRPC Client)
// =========================================================
service AgvCalibControlService {

  // ---------------------------------------------------------
  // 1. 权限接管与生命周期安全管控
  // ---------------------------------------------------------
  // 夺取车辆控制权，强制剥夺车端原生的激光避障与自主导航逻辑
  rpc SetControlMode(ModeRequest) returns (StandardResponse);
  
  // 软件级最高优看门狗急停（应对网络断连、越界飞车等紧急状况，底层必须无条件抱死电机）
  rpc EmergencyStop(Empty) returns (StandardResponse);

  // ---------------------------------------------------------
  // 2. 运动考题下发 (开环排雷 / 闭环寻优 / 波峰对齐)
  // ---------------------------------------------------------
  // 【场景A: 纯物理开环】要求车端切断所有PID/运动学逆解，直接将转速/PWM透传给底层电机
  rpc ExecuteOpenLoopCmd(OpenLoopRequest) returns (StandardResponse);
  
  // 【场景B: 算法闭环调优】下发测试轨迹，要求车端用"它自带的"运控算法(PID/MPC)去努力追踪
  rpc FollowTestTrajectory(TrajectoryRequest) returns (StandardResponse);

  // 【场景C: 波峰时序对齐】下发极短促的阶跃加速指令，人为制造绝对速度波峰，供Linux提取Time Offset
  rpc ExecuteStepResponse(StepResponseRequest) returns (StandardResponse);

  // ---------------------------------------------------------
  // 3. 运控参数 AI 寻优：动态热注入与最终固化
  // ---------------------------------------------------------
  // 寻优核心：将 Linux 算出的临时参数瞬间写入车端内存并立刻生效，准许开始下一圈测试
  rpc InjectTuningParameters(ControlParams) returns (StandardResponse);
  
  // 调优结束：通知车端将目前内存中的最高分参数，永久覆写进硬盘的 config.yaml 或注册表
  rpc CommitControlParameters(Empty) returns (StandardResponse);

  // ---------------------------------------------------------
  // 4. 高频数字孪生体感上报 (50Hz)
  // ---------------------------------------------------------
  // 注意: 使用 server-streaming 服务端持续推流。车端被调用一次后，
  // 需以 50Hz 频率疯狂向外广播自身底层状态，供 Linux 提取波峰并比对真值打分。
  rpc StreamTelemetry(Empty) returns (stream TelemetryData);
}

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

message StandardResponse {
  bool success = 1;
  string message = 2; // 包含执行成功的回执，或底盘卡死/驱动器报错等异常原因
}

// =========================================================
// 1. 模式控制结构体
// =========================================================
message ModeRequest {
  enum Mode {
    NORMAL_MODE = 0;       // 正常业务模式（打开避障和导航，出厂默认状态）
    OPEN_LOOP_MODE = 1;    // 物理开环标定模式（切断所有算法纠偏，提线木偶状态）
    TUNING_MODE = 2;       // 闭环调优模式（切断环境避障，但保留原生 PID/MPC 追踪算法）
  }
  Mode target_mode = 1;
}

// =========================================================
// 2. 动作指令请求载荷
// =========================================================
message OpenLoopRequest {
  double left_motor_cmd = 1;   // 左驱动轮目标转速 (RPM) 或占空比
  double right_motor_cmd = 2;  // 右驱动轮目标转速 (RPM) 或占空比
  double steering_angle = 3;   // 针对单/多舵轮底盘的绝对舵角指令 (度，差速轮忽略)
  
  // 🚨 极度关键的安全设计：指令超时时间
  // 车端若失去网络连接，超时后必须由底层代码强制将速度归零，严防撞墙！
  double duration_sec = 4;     
}

message TrajectoryPoint {
  double x_m = 1;              // 目标点 X 坐标 (米)
  double y_m = 2;              // 目标点 Y 坐标 (米)
  double yaw_rad = 3;          // 目标点 偏航角 (弧度)
  double target_speed_ms = 4;  // 到达该点时的期望线速度 (米/秒)
  double curvature = 5;        // 该点处的轨迹曲率 (可选项，用于辅助前瞻距离映射)
}

message TrajectoryRequest {
  string test_case_id = 1;           // 考题名称，如 "Bezier_Curve_S_Speed_1.2"
  repeated TrajectoryPoint path = 2; // 组成考题曲线的稠密坐标点阵列
}

message StepResponseRequest {
  double target_velocity_ms = 1; // 极速阶跃的目标线速度 (如猛烈加速到 1.5 m/s)
  double duration_sec = 2;       // 阶跃维持时间 (极短，如 1~2 秒即可，用于产生绝对波峰)
}

// =========================================================
// 3. 待调优运控参数载荷 (支持增量式热更新)
// =========================================================
message ControlParams {
  // 采用 optional 关键字，允许 Linux 每次只修改需要微调的单个参数，其余保持原样
  
  // --- 底盘物理运动学修正系数 (由 4.3 阶段开环算得) ---
  optional double wheel_radius_left_ratio = 1;   // 左侧真实有效轮径补偿乘数 (如 1.002)
  optional double wheel_radius_right_ratio = 2;  // 右侧真实有效轮径补偿乘数 (如 0.998)
  optional double effective_track_width_m = 3;   // 有效轮距 (m)
  optional double steering_zero_offset_deg = 4;  // 舵角机械零位静态偏差 (度)

  // --- 经典 PID 控制增益 ---
  optional double pid_kp_lateral = 5;  
  optional double pid_ki_lateral = 6;  
  optional double pid_kd_lateral = 7;  // 用于提供阻尼，抑制高频画龙震荡
  
  optional double pid_kp_heading = 8;
  optional double pid_ki_heading = 9;
  optional double pid_kd_heading = 10;
  
  // --- 先进算法核心参数 ---
  optional double pure_pursuit_lookahead_m = 11; // 纯追踪前瞻距离 Ld (m)
  optional double mpc_weight_q_lateral = 12;     // MPC Q矩阵：对横向误差的惩罚权重
  optional double mpc_weight_r_steering = 13;    // MPC R矩阵：对转向电机发力剧烈度的惩罚权重 (控制平顺性)
}

// =========================================================
// 4. 高频遥测推流载荷 (数字孪生状态汇报)
// =========================================================
message TelemetryData {
  // 🚨 互相关对齐的核心依据：
  // 必须使用 Windows 底层高精度单调时钟 (如 QueryPerformanceCounter) 的绝对微秒数。
  // 绝对禁止在车端人为做时序平滑或使用受 NTP 影响的系统时间！
  int64 hardware_timestamp_us = 1;     
  
  // --- 车端推算的内部里程计位姿 (Odom) ---
  double odom_x_m = 2;          
  double odom_y_m = 3;          
  double odom_yaw_rad = 4;        
  
  // --- 底层执行器真实物理反馈 (用于提取波峰) ---
  double feedback_linear_vel_ms = 5;   // 编码器解算的真实线速度 (m/s)
  double feedback_angular_vel_rads = 6;// 陀螺仪或编码器解算的真实角速度 (rad/s)
  
  // --- 硬件健康与功耗监控 (用于 Linux 诊断干涉卡死) ---
  double left_motor_current_amp = 7;     // 左驱动电机实时电流 (A)
  double right_motor_current_amp = 8;    // 右驱动电机实时电流 (A)
  double steering_motor_current_amp = 9; // 转向舵机实时电流 (A)
  
  // --- 算法控制输出量 (用于 Linux 识别死区或物理饱和) ---
  double cmd_steering_output = 10;       // 控制算法计算出的期望底层舵角指令 (度/弧度)
}