1. Là gì

HudLink là bộ producer nằm trong mod Waze (com.waze.gw.HudLink). Nó gom trạng thái HUD trực tiếp — tốc độ, giới hạn tốc độ, hướng rẽ kế, khoảng cách, đường hiện tại/kế, ETA, vùng đo tốc độ trung bình — thành JSON mỗi dòng (giao thức HLP/1) rồi đẩy qua một transport tới HUD ngoài. App hiện hỗ trợ Bluetooth Classic SPP và BLE GATT bằng cùng frame HLP/1.

Vì dữ liệu tách rời khỏi việc vẽ, bạn chế HUD tùy ý mà không phải build lại Waze. Nó còn tiếp tục đẩy dữ liệu kể cả khi màn điện thoại TẮT → dùng HUD ngoài cho phép tắt/giảm màn (mát hơn, đỡ pin).

2. Kiến trúc

Tiến trình Waze ──(hook smali)──► trạng thái Gateway.hud*
                                       │
                                       ▼
                      HudLinkService + HudConnectionManager
                                       │  snapshot HLP/1
                          ┌────────────┴────────────┐
                          ▼                         ▼
                BLE GATT (1–4 Hz)        Classic SPP (1–10 Hz)
                          │                         │
                          └──────────► HUD ngoài ◄──────────┘

• Foreground service HudLinkService sở hữu transport, handshake, writer và vòng kết nối lại. Hook nóng onSpeedo chỉ gửi yêu cầu khôi phục service theo cách idempotent và có giới hạn nhịp khi Android tạo lại process Waze.
• HudStateSnapshot đọc các field Gateway.hud* và phát snapshot đầy đủ mỗi message (không phải delta), nên mất một gói không làm hỏng trạng thái bên nhận.
• Phát khi có thay đổi và vẫn phát state không đổi ít nhất mỗi giây. BLE được giới hạn trong 1–4 Hz; Classic SPP mặc định 8 Hz và nhận yêu cầu tối đa 10 Hz.

3. Bật lên

Preferences (file SharedPreferences waze_hud_gw):

Mở Cài đặt Mod → Thiết bị → HUD Link, cấp quyền Thiết bị lân cận khi được hỏi, chọn đúng transport/thiết bị rồi bật HUD Link. Thiết bị Classic phải được pair trong Cài đặt Android trước; thiết bị BLE được tìm trong picker của app theo HLP service UUID cố định.

Bật log không tạo transport giả, nên không thể phát stream nếu chưa kết nối thiết bị. Khi chẩn đoán với thiết bị thật, chỉ bật hud_link_log tạm thời rồi xem:

adb logcat -s WazeHudLink WazeHudLink-BLE
# {"v":1,"t":"s","nav":0,"spd":47,"lim":50,...,"st":"Nguyễn Trãi","ts":124890}

Preference cũ hud_link_dev chỉ dùng để migrate. App chỉ chuyển nó thành một thiết bị bonded cụ thể khi tìm được đúng một kết quả không mơ hồ.

4. Luồng dữ liệu (HLP/1)

Mỗi dòng là 1 object JSON, UTF-8, kết bằng \n. Mọi message: {"v":1,"t":"...", ...}. Xem HLP_v1.md cho spec đầy đủ (handshake dev/hi, thương lượng năng lực, versioning).

Message trạng thái ("t":"s") — các field HUD cần:

Quy ước vắng: 0 cho lim/exit/avg*; -1 cho dst. alrV/alrs omit hẳn khi không có. Thiếu key ⇒ dùng giá trị mặc định.

Vùng cấm vượt (avg). VN không có camera đo tốc độ trung bình; editor tag hình học đó thành cấm vượt, Waze vẫn giao dưới dạng "avg-speed zone". Hiện biển cấm vượt + đếm ngược avgL, đừng vẽ camera. / Vietnam has no average-speed cameras; render a no-passing sign, not a camera.

Cảnh báo (alr/alrs). Khi có cảnh báo, alr/alrD/alrV mô tả biển gần nhất và mirror alrs[0] (consumer không parse mảng vẫn có biển gần nhất). alrs = danh sách đầy đủ (≤4, gần→xa), opt-in — phải khai alrs trong dev.want.fields mới nhận. Trong alrs, key loại là k (không phải t — t là key loại-message ở envelope): [{"k":2,"d":300},{"k":8,"d":800,"v":40}]. alrV/v chỉ có với biển mang giá trị (giảm tốc → giới hạn mới); còn lại omit. Enum alert: 1 police · 2 camera tốc · 3 camera đèn đỏ · 4 hazard · 5 tai nạn · 6 kẹt xe · 7 đóng đường · 8 giảm tốc (v=giới hạn mới) · 9 cấm vượt.

Enum rẽ (trn,trn2): 0 không · 1 đi thẳng · 2 trái · 3 phải · 4/5 chếch trái/phải · 6/7 gắt trái/phải · 8 quay đầu · 10-12 vòng xuyến / trái / phải (dùng exit) · 13/14 giữ trái/phải · 15/16 ra nhánh trái/phải · 17 đến nơi. (Bảng đầy đủ ở HLP_v1.md §4.1.)

5. Viết bên nhận (ESP32, Bluetooth SPP)

Sketch Arduino tối thiểu — đọc dòng, parse, vẽ:

#include "BluetoothSerial.h"
#include <ArduinoJson.h>

BluetoothSerial SerialBT;

void setup() {
  Serial.begin(115200);
  SerialBT.begin("WazeHUD");          // điện thoại kết nối tới tên này
}

void loop() {
  static char line[512];
  static size_t n = 0;
  while (SerialBT.available()) {
    char c = SerialBT.read();
    if (c == '\n') {                  // đã đủ 1 message HLP
      line[n] = 0; n = 0;
      StaticJsonDocument<512> doc;
      if (deserializeJson(doc, line)) continue;   // bỏ dòng hỏng, resync ở '\n' kế
      const char* t = doc["t"] | "";
      if (strcmp(t, "s") == 0) {
        int   spd = doc["spd"] | 0;
        int   lim = doc["lim"] | 0;
        int   trn = doc["trn"] | 0;
        int   dst = doc["dst"] | -1;
        const char* st = doc["st"] | "";
        // TODO: vẽ spd / lim / bitmap mũi tên theo trn / dst / st …
      }
    } else if (n < sizeof(line) - 1) {
      line[n++] = c;
    } else {
      n = 0;                          // tràn → resync
    }
  }
}

Bên nhận có thể (tùy chọn) gửi khai báo dev để thương lượng rate/fields; nếu im lặng, producer tự đẩy default hợp lý sau 500 ms (xem HLP_v1.md §2.5).

6. Trạng thái

• Producer: HLP/1 đã có trên Classic SPP bảo mật và BLE GATT.
• Ví dụ ESP32: đã có raw receiver BLE/SPP, framing giới hạn, handshake và ping/pong.
• Firmware sản phẩm: decoder field, driver màn hình và renderer tùy thuộc thiết bị.