Đặc tả giao thức HLP/1

Đây là data contract giữa bên phát (Waze mod Gateway → HudLink) và bên nhận (HUD ESP32/Arduino hoặc renderer bất kỳ). Giao thức không phụ thuộc transport: cùng một chuỗi byte có thể chạy qua Bluetooth SPP, BLE có phân mảnh, TCP hoặc cáp serial. Chỉ cần định nghĩa một lần và triển khai ở cả hai phía.

Mục tiêu thiết kế: rất dễ parse trên MCU, tương thích về sau, tự mô tả và chịu được kết nối mất gói. Mỗi message độc lập; mất một message chỉ khiến HUD cũ hơn một chút.

1. Đóng khung dữ liệu

• Mỗi dòng chứa đúng một message, mã hóa UTF-8 và kết thúc bằng \n (0x0A). Có thể có \r ngay trước \n. \r là khoảng trắng hợp lệ trong JSON nên parser chuẩn sẽ bỏ qua; bên nhận C dùng char buffer PHẢI xóa \r cuối dòng trước khi thêm null terminator, không chỉ bỏ qua nó lúc nhận.
• Mỗi dòng là một JSON object hoàn chỉnh. Một message không kéo dài qua nhiều dòng và một dòng không chứa hai message.
• Độ dài tối đa là 512 byte cho toàn bộ dòng UTF-8, gồm cả LF cuối, không phải số ký tự. Field chuỗi ban đầu bị giới hạn ở 40 code point. Sau đó Android encode toàn frame; nếu còn quá dài, nó lần lượt bỏ alrs, rút ngắn st/st2 và bỏ các field tùy chọn cho tới khi frame vừa giới hạn. Bên nhận nên dùng buffer 512 byte và bỏ dòng quá dài.
• Bên nhận parse từng dòng. Nếu dòng lỗi hoặc quá dài, hãy bỏ dòng đó và đồng bộ lại tại \n kế tiếp.
• Với BLE, nếu MTU nhỏ hơn độ dài dòng thì bên phát chia nhỏ raw byte; bên nhận ghép lại theo \n. Framing dựa trên byte stream nên việc chia packet là trong suốt với protocol.

2. Envelope của message

Mọi message đều có key loại t và phiên bản protocol v:

{"v":1,"t":"s", ...fields...}

Quy tắc tương thích về sau — cả hai phía PHẢI tuân theo:

• Bên nhận bỏ qua key lạ và giá trị t chưa biết.
• Bên nhận chấp nhận key bị thiếu và dùng giá trị mặc định đã ghi trong tài liệu.
• Trong v1 chỉ được bổ sung field mới; field hiện có không đổi ý nghĩa.
• Thay đổi phá vỡ tương thích phải tăng v. Bên nhận bỏ qua message có v không hỗ trợ.

2.5 Bắt tay và khai báo kết nối

Ở mỗi kết nối mới qua SPP, BLE hoặc TCP, hai phía khai báo trước khi stream để biết phiên bản protocol, capability và tùy chọn của nhau. Bên phát có quyền quyết định cuối cùng và echo tham số đã thương lượng trong hi; bên nhận thích ứng theo kết quả đó.

kết nối được thiết lập
  bên nhận ──► dev  (identity, phiên bản protocol, màn hình, capability, nhu cầu)
  bên phát ──► hi   (identity, protocol, capability và rate/field/protocol ĐÃ CHẤP NHẬN)
  bên phát ──► s …  (stream ở rate đã chấp nhận, chỉ mang field đã chấp nhận)
  ...ping/pong, heartbeat...
  một trong hai ──► bye

Fallback cho bên nhận đơn giản: thiết bị không gửi được declaration có thể chỉ lắng nghe. Nếu bên phát không nhận dev trong 500 ms sau khi kết nối, nó dùng mặc định proto:1, rate mặc định của transport và toàn bộ field baseline gọn, sau đó gửi hi rồi s. Binding BLE hiện tại chấp nhận rate 4 trong fallback này. Mảng tùy chọn alrs vẫn bị bỏ vì có thể chiếm phần lớn budget 512 byte. Nhờ vậy firmware chỉ đọc dòng và parse vẫn hoạt động mà không cần logic handshake.

hi có tính idempotent và CÓ THỂ được gửi lại. Bên nhận PHẢI chấp nhận hi mới và áp dụng tham số mới. Implementation hiện tại dùng việc này cho một trường hợp cụ thể:

• dev đến muộn, sau hi mặc định ở mốc 500 ms: bên phát thương lượng lại và gửi hi đã cập nhật. Không có race condition; hi cuối cùng thắng.

Android hiện tại không phát lại capability khi dữ liệu Waze xuất hiện hoặc biến mất. Hãy xem caps là nhóm field đã thương lượng cho session; việc widget hiện có dữ liệu hay không phải dựa vào giá trị mặc định của field bị thiếu trong từng state.

Danh tính session (sess). hi chứa một sess riêng cho từng session. Mỗi khi sess thay đổi, kể cả sau khi kết nối lại, bên nhận PHẢI coi đây là session mới: xóa state cache và gửi lại dev nếu có hỗ trợ declaration.

2.5.1 dev — khai báo của bên nhận

{
  "v": 1,
  "t": "dev",
  "name": "WazeHUD-ESP32",
  "fw": "1.0.0",
  "proto": [1],
  "disp": { "w": 240, "h": 240, "color": 1 },
  "can": ["speed", "limit", "turn", "street", "eta", "avgzone", "alerts"],
  "want": {
    "rate": 4,
    "fields": ["spd", "lim", "trn", "trn2", "dst", "exit", "st", "eta", "rmin"]
  }
}

Mọi key ngoài t và v đều không bắt buộc. Khi thiếu, bên phát dùng mặc định.

2.5.2 hi — khai báo bên phát và tham số được chấp nhận

{
  "v": 1,
  "t": "hi",
  "app": "waze",
  "appv": "5.20.90.901",
  "name": "WazeHUD",
  "sess": 48213,
  "proto": 1,
  "caps": ["speed", "limit", "turn", "street", "eta", "avgzone", "alerts"],
  "rate": 4,
  "fields": ["spd", "lim", "trn", "trn2", "dst", "exit", "st", "eta", "rmin"]
}

2.5.3 Capability token (can / caps)

Các nhóm tính năng cấp cao, độc lập với từng field:

Capability alerts bao gồm biển gần nhất qua alr/alrD/alrV. Mảng đầy đủ alrs mặc định không thuộc alerts; bên nhận phải ghi thêm alrs trong dev.want.fields. HUD chỉ khai báo can:["alerts"] vẫn nhận message nhỏ. Thiết bị không gửi declaration sẽ không nhận alrs.

Quy tắc thương lượng — bên phát quyết định và echo trong hi:

• Bên phát hiện tại chỉ hỗ trợ HLP/1. Nếu dev.proto có mặt nhưng không chứa 1, Android gửi UNSUPPORTED_VERSION rồi đóng session.
• rate bị giới hạn trong 1..4 Hz với BLE và 1..10 Hz với Classic SPP. Khi thiếu, mặc định là 4 Hz cho BLE và 8 Hz cho SPP.
• fields là giao của dev.want.fields và field được hỗ trợ. Nếu thiếu hoặc là "*", bên phát nhận toàn bộ field baseline nhưng vẫn loại alrs; muốn nhận mảng này phải ghi rõ alrs. Message s chỉ chứa các key đã chấp nhận cộng v, t, ts. Tên field lạ trong want.fields bị bỏ qua im lặng.
• can và disp hiện chỉ mang tính thông tin. caps được suy ra từ nhóm field đã chấp nhận; nó không được lọc động theo dữ liệu tuyến hiện tại hoặc theo dev.can.

2.6 Cấu hình thiết bị động (tùy chọn)

Thiết bị HLP có thể công bố cài đặt riêng trong Cài đặt Mod → Thiết bị. Đây là phần bổ sung tương thích ngược của HLP/1, nên peer cũ sẽ bỏ qua message lạ. Android không lưu hoặc tự tạo schema. Nếu không nhận đủ schema sau hi, vùng cấu hình thiết bị hoàn toàn không xuất hiện.

Thiết bị gửi một schema nguyên tử, tối đa 32 mục:

{"v":1,"t":"cfg_begin","rev":7,"count":2,"title":"Cấu hình HUD"}
{"v":1,"t":"cfg_item","rev":7,"id":"brightness","kind":"slider","label":"Độ sáng","value":70,"min":10,"max":100,"step":5}
{"v":1,"t":"cfg_item","rev":7,"id":"theme","kind":"selection","label":"Giao diện","value":"auto","options":[{"value":"auto","label":"Tự động"},{"value":"night","label":"Ban đêm"}]}
{"v":1,"t":"cfg_end","rev":7}

Hỗ trợ toggle (boolean), slider (số nguyên có min/max/step), selection (chuỗi và 1–32 options), integer (số nguyên có min/max) và text (UTF-8, maxLength tùy chọn, tối đa 128 code point). id phải khớp [A-Za-z0-9_.-]{1,40}; label tối đa 64 code point và description tối đa 160. Mỗi frame vẫn bị giới hạn 512 byte. Android chỉ publish schema đủ item, cùng revision và không trùng id.

Control chỉ sửa bản nháp cục bộ. Android không gửi gì cho tới khi bấm Áp dụng, sau đó enqueue nguyên tử một transaction chứa toàn bộ giá trị:

{"v":1,"t":"cfg_set_begin","tx":12,"rev":7,"count":2}
{"v":1,"t":"cfg_set","tx":12,"id":"brightness","value":80}
{"v":1,"t":"cfg_set","tx":12,"id":"theme","value":"night"}
{"v":1,"t":"cfg_set_commit","tx":12}

Thiết bị PHẢI giữ bản staging riêng, kiểm tra tx, rev, count, id, kiểu và range, chỉ thay đổi state đang chạy/NVS sau commit hợp lệ, rồi trả một trong hai dạng:

{"v":1,"t":"cfg_ack","tx":12,"ok":true,"rev":8}
{"v":1,"t":"cfg_ack","tx":12,"ok":false,"field":"brightness","error":"out of range"}

Android chỉ cho một transaction đang chờ, timeout sau 10 giây và chỉ nhận giá trị mới khi ACK thành công đúng tx. Link vật lý mới sẽ xóa schema của thiết bị trước. Project ESP-IDF mẫu đã có staging và NVS trong shared/hlp_device_config.c.

Xem Cấu hình thiết bị động để đọc hướng dẫn triển khai, bảng control, checklist production và kết quả kiểm thử trên thiết bị thật.

3. Field của message trạng thái s

Key được viết ngắn để tiết kiệm băng thông và RAM MCU. Mọi field đều tùy chọn; dùng mặc định khi thiếu.

Thứ tự và độ cũ: dùng (sess, ts) cùng nhau, không dùng riêng ts. ts là uptime chứ không phải wall clock. Nếu process bên phát được tạo lại trong cùng transport, ts quay về giá trị nhỏ. Message mới hơn khi sess khác—luôn chấp nhận session mới—hoặc khi sess giống và ts lớn hơn. sess lấy từ hi ở §2.5.

Định dạng số. Bên phát làm tròn rkm tới một chữ số thập phân trước khi đưa vào JSON. Bên nhận phải đọc nó như số; serializer có thể bỏ .0 khi kết quả là số nguyên.

avg = vùng cấm vượt. Waze giao dữ liệu dưới tên “average-speed-camera zone”, nhưng tại Việt Nam geometry này được editor dùng cho vùng cấm vượt. HUD phải vẽ biển cấm vượt cùng đếm ngược avgL, không vẽ camera. avgR là tốc độ Waze khuyến nghị.

alr/alrD/alrV và alrs. Ba field đầu mô tả cảnh báo gần nhất và mirror alrs[0], nên firmware không parse mảng vẫn dùng được. alrs là danh sách đầy đủ tối đa bốn cảnh báo, gần tới xa, và chỉ được gửi khi bên nhận ghi alrs trong dev.want.fields. Bên trong mảng, key loại là k, không phải t, để không nhầm với loại message ở envelope. k dùng cùng enum với alr; v là tùy chọn tương ứng alrV.

Ví dụ tối thiểu sau khi thương lượng một tập field nhỏ, khi không dẫn đường:

{ "v": 1, "t": "s", "spd": 0, "lim": 50, "st": "Nguyễn Trãi", "ts": 123456 }

Ví dụ đầy đủ khi đang dẫn đường:

{
  "v": 1,
  "t": "s",
  "nav": 1,
  "spd": 47,
  "lim": 50,
  "over": 0,
  "trn": 8,
  "trn2": 2,
  "dst": 47,
  "exit": 0,
  "st": "Nguyễn Trãi",
  "st2": "Khuất Duy Tiến",
  "eta": "20:01",
  "rmin": 23,
  "rkm": 6.7,
  "avg": 0,
  "alr": 2,
  "alrD": 300,
  "alrs": [
    { "k": 2, "d": 300 },
    { "k": 8, "d": 800, "v": 40 }
  ],
  "ts": 124890
}

4. Enum

4.1 Loại hướng rẽ trn, trn2

Đây là mã HUD ổn định. Bên phát map Instruction$Type nội bộ của Waze sang các mã này; bên nhận vẽ bitmap mũi tên cục bộ. Với mã lạ, không vẽ gì và xử lý như 0.

4.2 Loại cảnh báo alr

5. Nhịp gửi, kiểm tra sống và độ cũ

• Bên phát gửi hi khi kết nối, sau đó gửi message s.
• Gửi s khi bất kỳ field nào thay đổi và ít nhất một heartbeat s mỗi 1000 ms nếu state không đổi. BLE phát theo rate đã thương lượng, giới hạn trong 1–4 Hz. Heartbeat chỉ cần khi không có thay đổi trong ít nhất 1000 ms; khi dữ liệu đang đổi, rate đã thương lượng tự đảm bảo nhịp.
• Android hiện tại gửi ping mỗi 5000 ms trên cả hai transport. HUD nên gửi pong ngay, trước khi render hoặc làm tác vụ chậm khác. Android ghi nhận hoạt động của peer để hiển thị trạng thái/chẩn đoán, nhưng hiện không tự ngắt chỉ vì thiếu pong; kết nối lại được kích hoạt bởi transport disconnect hoặc write lỗi/timeout.
• Bên nhận coi kết nối là stale sau 3000 ms không có message và hiển thị “mất tín hiệu”.
• Mỗi message là snapshot đầy đủ, không phải delta. Mất một message không làm hỏng state; message kế tiếp cập nhật lại toàn bộ.

6. Đơn vị và quy ước chuẩn

• Tốc độ dùng số nguyên km/h. Khoảng cách tới sự kiện dùng số nguyên mét. Quãng đường còn lại dùng km với một chữ số thập phân.
• 0 nghĩa là không có đối với lim, exit, avg*, alr; -1 nghĩa là không có đối với dst, alrD, vì khoảng cách 0 m vẫn hợp lệ.
• alrV và alrs bị bỏ hoàn toàn khi không áp dụng, không dùng sentinel. alrV chỉ xuất hiện cho loại cảnh báo mang giá trị như SPEED_DROP.
• Chuỗi là UTF-8 và có thể chứa dấu tiếng Việt. Font phía bên nhận phải hỗ trợ hoặc transliterate.
• Bên phát là nguồn dữ liệu duy nhất; ngoài “message cuối cùng thắng”, bên nhận không cần giữ state nghiệp vụ.

7. Phiên bản

• Tài liệu này mô tả HLP/1 với v:1. Thay đổi không tương thích phải chuyển sang HLP/2 với v:2; trong giai đoạn chuyển tiếp bên phát có thể hỗ trợ cả hai. Field bổ sung vẫn thuộc v1.

Trạng thái: ĐÃ TRIỂN KHAI v1. SPP và BLE vận chuyển cùng một message logic. Codec tham chiếu Android và ESP32 đều áp dụng giới hạn frame 512 byte. Lần sửa protocol tiếp theo phải tăng v nếu thay đổi envelope hoặc ý nghĩa field.

8. Binding theo transport

Protocol ứng dụng giống nhau trên Classic RFCOMM SPP và BLE GATT.

Classic SPP dùng Bluetooth SIG Serial Port UUID 00001101-0000-1000-8000-00805F9B34FB. Android là RFCOMM client bảo mật; thiết bị ngoại vi publish SDP service.

BLE dùng các UUID 128-bit cố định:

Ranh giới packet BLE không mang ý nghĩa protocol. Một frame có thể bị chia qua nhiều write hoặc notification; bên nhận ghép byte cho tới LF. Android yêu cầu MTU 247 nhưng vẫn chạy với MTU 23, chia frame thành chunk tối đa MTU - 3 và tuần tự hóa write with response. Chunk mới chỉ được gửi sau callback của chunk trước; mỗi chunk có timeout ba giây. Firmware phải copy byte nhận vào queue giới hạn rồi thoát nhanh khỏi callback GATT.

Toàn bộ frame đã mã hóa, gồm LF cuối, dài tối đa 512 byte. Khi tràn, bên nhận bỏ byte tới LF kế tiếp rồi tiếp tục framing. UTF-8 lỗi, JSON lỗi, phiên bản không hỗ trợ, thương lượng không hợp lệ và các lỗi protocol khác có thể được báo bằng:

{ "v": 1, "t": "error", "code": "FRAME_TOO_LARGE", "detail": "..." }

Message lỗi chỉ phục vụ chẩn đoán và không bắt buộc với bên nhận legacy. Loại message chưa biết vẫn phải được bỏ qua để giữ tương thích về sau.