Cấu hình HUD động từ thiết bị

Thiết bị HLP/1 có thể tự công bố các cài đặt cho Waze Mod. Android chỉ dựng giao diện, giữ thay đổi ở dạng bản nháp và gửi một transaction nguyên tử khi người dùng bấm Áp dụng trên HUD. Thiết bị vẫn là nguồn dữ liệu chuẩn: tự kiểm tra, lưu bền vững, tăng revision rồi mới xác nhận.

Phần mở rộng này dùng được với cả BLE GATT và Bluetooth Classic SPP, hoàn toàn tùy chọn và tương thích ngược. Nếu thiết bị không gửi một schema hoàn chỉnh sau hi, phần cài đặt riêng của thiết bị sẽ để trống.

Kiểm thử trên Redmi K30 (Android 11), kết nối Ubuntu FakeHUD qua BLE GATT. Các control do HUD khai báo; app không định nghĩa sẵn chúng.

Cùng một schema còn có selection, số nguyên và text. Dòng “Đã lưu trên thiết bị” chỉ xuất hiện sau khi app nhận đúng cfg_ack thành công.

1. Vòng đời

Android                         ESP32 / HUD
   | ----------- hi -----------> |
   | <-------- cfg_begin -------- |
   | <-------- cfg_item --------- |  lặp đúng count lần
   | <--------- cfg_end --------- |
   |                              |
   |   người dùng chỉnh bản nháp  |
   |                              |
   | ------ cfg_set_begin ------> |
   | -------- cfg_set ----------> |  một message cho mỗi mục
   | ------ cfg_set_commit -----> |
   | <---------- cfg_ack -------- |  chỉ sau validate + lưu bền vững

1. Android hoàn tất handshake HLP và gửi hi; caps của app có device_config.
2. HUD công bố một schema trọn vẹn: cfg_begin, đúng count message cfg_item, rồi cfg_end. Tất cả phải có cùng rev.
3. Android chỉ đưa schema lên UI sau khi nhận đủ và kiểm tra hợp lệ. Chuỗi thiếu, sai revision hoặc sai kiểu sẽ bị bỏ toàn bộ.
4. Thao tác UI chưa ghi xuống HUD. Khi bấm Áp dụng trên HUD, app gửi toàn bộ giá trị hiện tại, kể cả giá trị không đổi, trong một transaction.
5. HUD đưa dữ liệu vào vùng staging, kiểm tra toàn bộ, lưu nguyên tử, tăng rev, rồi gửi cfg_ack.
6. Android chỉ nhận trạng thái mới khi ACK thành công có đúng tx. Mỗi lúc chỉ có một transaction đang chờ và app timeout sau 10 giây.
7. Khi kết nối lại, vòng đời bắt đầu lại từ hi. HUD phải công bố schema và giá trị đã lưu hiện tại. Android cố ý không lưu schema thuộc sở hữu thiết bị.

Xem HLP/1 §2.6 để đọc đặc tả wire chính thức.

2. Các loại control hỗ trợ

Mỗi item bắt buộc có v, t:"cfg_item", rev, id, kind, label và value đúng kiểu. description là tùy chọn.

Giới hạn an toàn hiện tại:

• tối đa 32 item mỗi schema;
• tối đa 32 option cho một selection;
• ID là định danh ASCII ổn định, không dùng label hiển thị làm ID;
• text tối đa 128 ký tự dù thiết bị công bố maxLength lớn hơn;
• kind lạ, ID trùng hoặc khoảng giá trị sai sẽ làm hỏng toàn bộ schema.

ID là hợp đồng tương thích. Hãy giữ brightness là brightness qua các bản firmware; chỉ dịch label. Khi thay đổi cấu trúc schema, phải tăng rev.

3. Công bố schema

Mở mã nguồn đầy đủ ngay trong trình xem source của trang tài liệu:

• Project ESP32 BLE GATT
• Project ESP32 Classic SPP
• shared/hlp_device_config.h
• shared/hlp_device_config.c

Hai file nằm tại docs/examples_for_hud_link/esp32-hlp-spp/shared/. Cả project BLE và SPP mẫu đều compile chung module này.

Khởi tạo sau NVS:

ESP_ERROR_CHECK(nvs_flash_init());
hlp_device_config_init();

Đưa các dòng HLP hoàn chỉnh qua parser dùng chung. Khi nhận hi, module gọi hlp_device_config_publish() và phát giá trị đang lưu:

{"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}

Không xen kẽ hai chuỗi schema. hi có thể lặp khi reconnect hoặc thương lượng lại, vì vậy việc công bố phải idempotent.

4. Áp dụng giá trị nguyên tử

Android gửi toàn bộ form, không phải delta:

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

Firmware nên xử lý như sau:

1. Từ chối rev cũ, count sai, ID trùng/lạ và giá trị không hợp lệ.
2. Copy cấu hình active sang struct staging khi nhận cfg_set_begin.
3. Trong lúc nhận cfg_set, chỉ ghi vào staging.
4. Khi commit, yêu cầu đủ mọi field đúng một lần.
5. Lưu toàn bộ staging bằng một transaction NVS hoặc cơ chế tương đương.
6. Chỉ thay active config và tăng revision sau khi lưu thành công.
7. Trả thành công:

{"v":1,"t":"cfg_ack","tx":12,"ok":true,"rev":8}

Nếu lỗi, giữ nguyên active config và trả lý do ngắn:

{"v":1,"t":"cfg_ack","tx":12,"ok":false,"field":"brightness","error":"invalid value"}

Không ACK thành công trước khi lưu bền vững xong. Nếu không, điện thoại có thể báo đã lưu nhưng HUD mất giá trị sau lần khởi động kế tiếp.

5. Chuyển code mẫu thành firmware thật

Sample có năm field (show_eta, brightness, theme, offset, label) chỉ để demo đủ mọi loại UI. Với firmware sản phẩm:

1. Thay device_config_t bằng cấu hình thật của thiết bị.
2. Đổi CFG_COUNT và các item trong hlp_device_config_publish().
3. Thêm kiểm tra nghiêm ngặt theo từng ID trong hlp_device_config_handle().
4. Đổi key/default của phần load/save NVS.
5. Chỉ áp dụng cấu hình mới lên màn hình sau commit thành công.
6. Nếu thao tác display/NVS có thể block, đưa việc xử lý ra queue thay vì chạy trong callback BLE.

Nếu sản phẩm không có cấu hình chỉnh sửa, đừng gửi schema cfg_*. Khu vực cấu hình HUD trong Waze Mod sẽ tự để trống đúng theo thiết kế.

6. Checklist production

• Gửi schema đầy đủ sau mọi lần hi/reconnect.
• rev và count đồng nhất trên toàn bộ schema.
• Mỗi ID ổn định, duy nhất và có giới hạn.
• Coi toàn bộ giá trị từ app là input không tin cậy và validate lại trên HUD.
• Transaction được staging và commit nguyên tử.
• Lỗi NVS trả ok:false và không thay active config.
• Packet set/commit lặp không làm apply hai lần.
• Vẫn bỏ qua message HLP lạ để tương thích tương lai.
• Không đưa mật khẩu Wi-Fi, token hoặc credential vào field có thể chỉnh.
• Callback BLE chỉ enqueue nếu display/NVS có thể block.

7. Kịch bản đã kiểm thử trên thiết bị thật

Luồng tham chiếu đã được smoke-test ngày 09/08/2026 với Waze Mod V9 Beta 8, Redmi K30 chạy Android 11 và Ubuntu FakeHUD qua BLE GATT:

• FakeHUD công bố năm control sau hi;
• độ sáng được đổi từ 70 lên 95 trong Waze Mod;
• Android gửi một transaction đầy đủ (tx=1, rev=1, count=5);
• FakeHUD kiểm tra và lưu cả năm giá trị, tăng lên revision 2 rồi trả ACK thành công đúng transaction;
• ping/pong và stream state tiếp tục chạy sau Apply, không reconnect và không crash.

Hai ảnh phía trên được chụp từ chính lần kiểm thử này.