Android HUD Link

Kiến trúc

Gateway phát các field của Waze. HudLinkService quản lý vòng đời process và notification. HudConnectionManager quản lý một thế hệ state machine cùng lịch retry. RfcommHudTransport và BleGattHudTransport chỉ chịu trách nhiệm vận chuyển byte. HlpProtocol.Session thực hiện thương lượng HLP, còn HudStateSnapshot chụp một frame bất biến đã chuẩn hóa đơn vị. HlpFrameCodec được dùng chung cho cả hai transport và áp dụng giới hạn 512 byte.

Service sử dụng START_STICKY, nhưng Android vẫn có thể kết thúc bất kỳ process nào. Người dùng bật tính năng tại Cài đặt Mod → Thiết bị → HUD Link sau khi cấp quyền Thiết bị lân cận. Android 14+ yêu cầu connected-device foreground service để truyền dữ liệu nền trong thời gian dài.

Quyền truy cập

Android 12+ yêu cầu runtime permission BLUETOOTH_CONNECT và BLUETOOTH_SCAN. Implementation không lưu hud_link=true cho tới khi các quyền này được cấp. Android 10/11 sử dụng các quyền Bluetooth legacy hiện có; việc scan BLE trên các phiên bản này còn cần quyền vị trí.

Package đã dùng vị trí cho các tính năng Waze, vì vậy không khai báo neverForLocation ở phạm vi toàn package nếu chưa audit đầy đủ.

Chọn thiết bị

Picker lưu chính xác địa chỉ Bluetooth và transport. Giá trị hud_link_dev legacy chỉ được migrate khi có đúng một thiết bị đã bond khớp điều kiện. Nếu nhiều thiết bị trùng tên, hệ thống không tự chọn ngẫu nhiên. Thiết bị Classic được pair trong phần cài đặt Android; thiết bị BLE được lọc bằng HLP service UUID cố định.

UUID của transport

SPP sử dụng Bluetooth SIG Serial Port UUID 00001101-0000-1000-8000-00805F9B34FB.

Với BLE, TX bắt buộc hỗ trợ write with response. RX bắt buộc hỗ trợ notification và CCCD 0x2902; capabilities và status vẫn là tùy chọn. Android yêu cầu MTU 247, chia mỗi frame HLP đã mã hóa thành chunk không lớn hơn MTU - 3, tuần tự hóa mọi GATT operation và áp timeout ba giây cho mỗi chunk. Firmware vẫn phải nhận được với MTU mặc định 23.

Handshake và nhịp BLE

Sau khi RX notification được bật, HUD nên gửi ngay declaration dev. Android trả lời bằng hi rồi bắt đầu gửi state. Nếu không nhận dev trong 500 ms, Android vào chế độ legacy nhưng vẫn gửi hi và state; dev đến muộn vẫn được chấp nhận và tạo một hi cập nhật. Rate BLE được giới hạn trong 1–4 Hz, còn state không đổi vẫn được phát ít nhất mỗi giây.

Android gửi ping mỗi năm giây. HUD nên trả pong ngay, trước khi render hoặc làm tác vụ chậm khác. Hoạt động của peer được lưu cho trạng thái và chẩn đoán. Android hiện không tự ngắt chỉ vì thiếu pong; kết nối lại bắt đầu khi transport thật sự disconnect hoặc write lỗi/timeout.

Kết nối lại BLE

GATT disconnect thật hoặc write lỗi/timeout sẽ đóng session hiện tại. Callback lỗi trùng thuộc cùng một connection attempt được gộp lại. Retry dùng exponential delay có jitter khoảng 1,5; 3; 6; 12; 24 và 48 giây, sau đó giữ quanh 48 giây với jitter ±20% (dưới 60 giây); backoff reset sau 30 giây kết nối ổn định. Khi Bluetooth bật lại, hệ thống bắt đầu một lần kết nối mới.

Chẩn đoán

waze_hud_gw lưu hud_link_status, hud_link_error, transport đang hoạt động, rate đã thương lượng và monotonic timestamp của trạng thái gần nhất. Log payload thô mặc định bị tắt. Chỉ bật hud_link_log khi debug cục bộ vì payload chứa thông tin tuyến đường và tên đường.

Xử lý lỗi

• PERMISSION_REQUIRED: cấp quyền Thiết bị ở gần trong cài đặt ứng dụng Android rồi thử lại.
• BLUETOOTH_OFF: bật Bluetooth rồi thử lại.
• No device selected: mở picker. Với module Classic, hãy pair trong phần cài đặt Android trước.
• selected Classic device is not bonded: xóa pairing, pair lại module rồi chọn lại.
• BLE HLP characteristics missing: xác nhận firmware đang advertise đúng HLP service UUID cố định.
• FRAME_TOO_LARGE hoặc MALFORMED_UTF8: kiểm tra buffer và encoder của firmware phía thiết bị.

Các luồng hoạt động

Xem chi tiết ping/pong 5 giây, timeout GATT và exponential backoff tại tài liệu Cơ chế duy trì & tự động kết nối lại.