Protocol tín hiệu xe ↔ máy chủ chấm điểm MỚI

Thiết kế cũ lấy PPS từ rover RTK. Vì RTK để sau, bo thu cần nguồn giờ riêng, và khi RTK lắp vào thì cả hai cùng dựa trên giờ GNSS nên tự khớp nhau.

• t_us: int64 micro giây UTC. Cạnh IO được bắt bằng ngắt + timer phần cứng, sai số ≤ 1 ms
• Mỗi snapshot mang clock: LOCKED (có PPS) · NTP · HOLDOVER · FREE. Engine được biết dữ liệu tin được tới đâu

Tên khoá trùng file config xe (Thu tín hiệu xe §9). Config lo phần dây đấu (pin, high/low-side, active); protocol chỉ mang nghĩa.

3.1 IO thân xe — bitmap io_bits (uint32)

3.2 Động cơ & chuyển động — từ OBD-II

3.3 Engine tự suy ra (không có trên dây)

Chỉ phần chấm bằng tín hiệu xe. Cột cuối là phần chờ RTK, đợt này chưa làm.

6.1 L0 — bo thu ↔ gateway

• UART 921600 8N1 (CAN 500k nếu gateway có). Khung: COBS( Envelope ‖ CRC-32 ) + byte 0x00 phân cách. Mất byte chỉ hỏng 1 khung, bắt nhịp lại ngay ở 0x00 kế tiếp
• Hai chiều: bo → gateway gửi Envelope; gateway → bo chuyển tiếp lệnh Down (bo thu là bên ký ACK)
• Bo thu có ring buffer RAM/flash riêng, nên gateway khởi động lại cũng không mất cạnh

6.2 L1 — xe ↔ máy chủ (MQTT 5)

hash_n     = SHA-256( hash_{n-1} ‖ serial ‖ boot_id ‖ seq_n ‖ body_bytes_n )   // mỗi Envelope, tính trên bo thu
Checkpoint (1 Hz) = { seq, hash_seq, sig = ECDSA-P256(device_key, serial‖boot_id‖seq‖hash_seq) }
Seal (cuối phiên) = { session_id, first_seq, last_seq, chain_head, n_io, n_obd, sig }

device_key sinh và nằm trong ATECC608B trên bo thu, không bao giờ rời chip.
Public key + seri đăng ký lúc sản xuất → CP cấp xuống WS sát hạch.

syntax = "proto3";
package suns.ys.v1;

// ===== Uplink: xe → máy chủ =====
message Envelope {
  uint32 proto_ver = 1;          // = 1
  string serial    = 2;          // seri toàn cục do SUNS cấp
  uint32 boot_id   = 3;
  uint32 seq       = 4;
  bool   replay    = 5;          // gửi lại từ journal
  bytes  prev_hash = 6;
  oneof body {
    Batch      batch       = 10;
    SessionAck session_ack = 11;
    CmdAck     cmd_ack     = 12;
    Checkpoint checkpoint  = 13;
    Seal       seal        = 14;
    Health     health      = 15;
  }
}

message Batch {
  string session_id = 1;         // rỗng khi ngoài phiên (vẫn ghi, vẫn gửi)
  repeated IoEdge io   = 2;
  repeated Obd    obd  = 3;
  State           state  = 4;    // 1 lần/giây
  reserved 5;                   // repeated Pose pose — RTK, làm sau
}

enum Clock { CLOCK_FREE = 0; HOLDOVER = 1; NTP = 2; LOCKED = 3; }

message IoEdge {
  sint64 t_us  = 1;
  uint32 bit   = 2;              // vị trí bit trong io_bits
  bool   value = 3;
  bool   raw   = 4;              // true = cạnh thô kênh xung (xi-nhan), để đối chất
}
message Obd {
  sint64 t_us = 1; sint64 t_req_us = 2;
  uint32 rpm  = 3; uint32 speed_kmh = 4; bool valid = 5;
}
message State {
  sint64 t_us = 1; uint32 io_bits = 2; uint32 vbat_mv = 3; Clock clock = 4;
}

message SessionAck {
  string session_id = 1; bool ok = 2;
  repeated string fail = 3;    // "CLOCK","TAMPER","OBD","CFG"…
  string fw_ver = 4; bytes cfg_hash = 5; uint32 first_seq = 6;
  reserved 7;                   // base_id — RTK, làm sau
}
message CmdAck     { uint32 cmd_id = 1; bool ok = 2; sint64 t_exec_us = 3; }
message Checkpoint { uint32 seq = 1; bytes hash = 2; bytes sig = 3; }
message Seal {
  string session_id = 1; uint32 first_seq = 2; uint32 last_seq = 3;
  bytes chain_head = 4; uint32 n_io = 5; uint32 n_obd = 6; bytes sig = 7;
}
message Health { sint32 temp_c = 1; uint32 journal_free_mb = 2; sint32 rssi = 3; uint32 uptime_s = 4; }

// ===== Downlink: máy chủ → xe =====
message Down {
  uint32 proto_ver = 1; uint32 cmd_id = 2;
  oneof body {
    SessionOpen   open     = 10;
    SessionClose  close    = 11;
    Backfill      backfill = 12;
    Announce      announce = 13;
    HazardTrigger hazard   = 14;
    LessonMark    lesson   = 15;
  }
}
message SessionOpen {
  string session_id = 1; string exam_id = 2;
  string candidate_ref = 3;      // mã tham chiếu — KHÔNG gửi PII xuống xe
  string license_class = 4; string vehicle_profile_ver = 5; string rules_ver = 6;
  reserved 7, 8;                // datum_id, map_ver — RTK, làm sau
}
message SessionClose  { string session_id = 1; }
message Backfill      { uint32 boot_id = 1; uint32 from_seq = 2; uint32 to_seq = 3; }
message Announce      { string text_key = 1; uint32 lesson = 2; sint32 points = 3; }
message HazardTrigger { uint32 kind = 1; }
message LessonMark    { uint32 lesson = 1; bool enter = 2; }