Kết nối thiết bị và giao thức T25

Tài liệu mô tả cách ứng dụng ScienEDU Pro (sensor_dashboard) kết nối tới thiết bị đo (USB Serial, Bluetooth LE, chế độ giả lập), luồng dữ liệu trong code, và định dạng frame / payload (giao thức T25 v1).

---

1. Tổng quan kiến trúc

Thiết bị  →  [USB / BLE / Mock]  →  ConnectionService  →  DataService / BleDataService
                                                              ↓
                                                    T25V1Protocol + T25PayloadProcessor
                                                              ↓
                                                    JSON (UTF-8)  →  UI / DeviceState

• ConnectionManager (lib/t25/device/connection_manager.dart): chọn loại kết nối hiện tại và lấy dịch vụ tương ứng.
• ConnectionFactory: ánh xạ ConnectionType → SimpleUsbSerialService / AndroidUsbSerialService / SimpleBleService / SimpleMockService.
• DeviceStateManager (lib/providers/device_provider.dart): mở kết nối, gửi lệnh discovery / ping / ghi dữ liệu, nhận byte thô và đưa qua DataService.process.

---

2. Các kiểu kết nối

Trạng thái kết nối: ConnectionStatus — DISCONNECTED, CONNECTING, CONNECTED, ERROR (lib/t25/connection/connection_service.dart).

2.1. USB Serial

• Quét cổng: SerialPort.availablePorts (Windows/desktop); Android dùng đường riêng trong AndroidUsbSerialService (xem scanAsync).
• Cấu hình mặc định (lib/t25/connection/usb/usb_serial.dart): 8 bit dữ liệu, không parity, 1 stop bit; RTS/DTR bật tùy cấu hình driver.
• Tốc độ baud: có thể đặt qua openConnection(..., baudRate: ...). Giá trị mặc định tham chiếu trong AppConfigs.serialBaudRate (921600). Lớp UsbSerial khởi tạo 115200 nếu không gọi setBaudRate trước khi mở cổng — cần đảm bảo UI/luồng kết nối truyền đúng baud thiết bị thực tế.
• Luồng nhận: SerialPortReader đẩy Uint8List vào listener; log debug có thể in hex (convert/hex).

2.2. Bluetooth LE

• Quét: UniversalBle.startScan(), khoảng 3 giây, kết quả gom trong cache (làm mới cache nếu lần quét trước cách > 10 giây). Chỉ giữ thiết bị có tên và deviceId.
• Kết nối: UniversalBle.connect, sau đó discoverServices, bật notification/indication cho mọi characteristic hỗ trợ.
• Ghi xuống thiết bị: trong code hiện tại, nhánh ghi BLE thực tế bị tắt (comment) để tránh PIN trên một số máy Samsung; write() chủ yếu dùng để đưa dữ liệu vào _processIncomingCommand (đường nội bộ). Thiết bị được giả định tự đẩy dữ liệu qua notify.
• Dữ liệu nhận: UTF-8 string, tách dòng theo ký tự xuống dòng \n (0x0A), buffer tạm ghép với lần nhận trước; giới hạn độ dài buffer: AppConfigs.maxBleBufferSize.

2.3. Chế độ Mock

Dùng để phát dữ liệu giả lập không cần phần cứng; cùng pipeline T25/JSON với USB khi tích hợp đúng.

---

3. Giao thức T25 v1 (lớp nhị phân)

Định nghĩa trong lib/t25/protocol/t25/v1/t25_v1_protocol.dart.

3.1. Cấu trúc gói (frame)

Mỗi gói T25 v1 có dạng:

• Độ dài payload tối đa trong một gói: 4095 byte (0x0FFF).
• Khi ghép nhiều gói trong buffer, parser tìm các vị trí 0x00 0x00 và tách từng khung.

3.2. Thuật toán mã hóa (CipherAlgorithm)

Factory mã hóa: lib/t25/protocol/encrypt/.

3.3. Gửi dữ liệu từ app (send)

DeviceProvider → DataService.send → T25V1Protocol.send(jsonEncode(cmd), sender):

1. JSON string được bọc thành payload văn bản (xem mục 4).
2. Payload được chia chunk (mặc định 1024 byte).
3. Mỗi chunk được mã hóa ChaCha20 (mặc định), rồi bọc thêm header T25 v1 và gửi qua connectionService.write.

3.4. Nhận dữ liệu (feed)

feed(Uint8List) nối byte vào buffer, tách frame theo 0x00 0x00, đọc DESC, cắt đúng payloadLength, sau đó:

• NONE → đưa payload thẳng tới bước tiếp;
• CHACHA20 / AES128 → giải mã rồi đưa tiếp.

Lỗi độ dài / frame không đủ byte → callback onError (chuỗi kiểu "Frame error").

---

4. Lớp payload văn bản (STX / ETX + JSON)

Định nghĩa trong lib/t25/protocol/t25/payload/t25_payload_processor.dart và ascii_control.dart.

• STX = 0x02 (Start of Text)
• ETX = 0x03 (End of Text)

Build: STX + UTF-8(JSON) + ETX.

Parse: Tích lũy byte trong buffer (tối đa ~500 KiB); khi gặp ETX, tìm STX gần nhất, lấy phần giữa làm nội dung JSON (string hoặc bytes tùy tham số isString).

Sau khi có chuỗi JSON, DeviceStateManager có thể chạy _fixDuplicateKeys để xử lý key trùng trong dataStructure hoặc live data.

---

5. Lệnh điề khiển (JSON)

Định nghĩa trong lib/t25/device/cmd/. Trường chính: s — mã tín hiệu (T25CmdSignal).

• PING: T25BaseCmd.PING là object rỗng {} — gửi định kỳ khi đã ổn định (_startPingPong).
• Discovery sau khi kết nối: timer gửi T25CmdDiscovery mỗi 2 giây cho tới khi nhận được JSON thiết bị và parse thành T25Device.

---

6. Mô hình thiết bị và dữ liệu sống

• T25Device (lib/t25/device/t25_device.dart): mô tả thiết bị sau discovery (JSON), gồm dataStructure — map các kênh (thường key "0"…"3") tới DeviceDataStructureDefinition (sensor s, presentation p, kiểu t).
• Dữ liệu đo trực tiếp: JSON object với key số dạng chuỗi "0", "1", … — giá trị số (double) tương ứng từng cổng cảm biến. UI/logic có thể kiểm tra đủ 4 key cho layout 4 kênh.

---

7. Đường BLE đặc thù (text + optional AES)

Khi dữ liệu đến từ BLE (sau khi decode UTF-8 và tách theo \n), chuỗi được đưa vào BleDataService (lib/t25/device/ble/ble_data_service.dart).

7.1. Định dạng khung văn bản

• Phân cách loại frame và payload bằng:
  • @ — phiên bản chuẩn / không mã hóa payload theo cấu hình;
  • : — phiên bản “pro”, payload thường được coi là đã mã hóa.
• Byte đầu (trước separator) là mã frame:
  • 0 — BLE_DEVICE_INFO_FRAME_VERSION (thông tin thiết bị, JSON string sau khi xử lý).
  • 1 — BLE_DATA_FRAME_VERSION (dữ liệu cảm biến).

Ví dụ ý tưởng: 1@<payload> hoặc 1:<hex hoặc ciphertext>.

• BleDataConfig.isEncrypted: nếu true, phần sau separator có thể được giải AES-128 qua CodecUtils.tryDecryptFromAes128 (khóa từ .env — AES_KEY).
• Thiết bị cũ không có separator: coi toàn bộ chuỗi là dữ liệu frame 1 (dữ liệu đo).

7.2. Payload dữ liệu đo (frame 1)

Chuỗi dạng các khối lặp:

A[<sensorType>:<giá trị>], B[...], C[...], D[...]

• Chữ cái A–D map sang key JSON "0"–"3".
• Giá trị sau dấu : là số thực (double).

Sau khi parse, app chuyển thành JSON kiểu {"0": 25.256, "1": 0.0, ...} (UTF-8 bytes) rồi bọc lại qua T25PayloadProcessor + T25V1Protocol với CipherAlgorithm.NONE để thống nhất pipeline với USB (_wrapIntoProtocol trong simple_ble_service.dart).

---

8. Hằng số cấu hình liên quan (AppConfigs)

File: lib/configs/app_configs.dart (một phần dùng cho tích hợp / lọc BLE trong tiện ích khác):

• bleServiceIds, typeSensorCharacteristicIds, writeCharacteristicIds — UUID GATT tham chiếu.
• blePrefix — tiền tố tên thiết bị gợi ý (ví dụ ScienEDU, BoThuNhanSoLieu).
• serialBaudRate — baud mặc định tham chiếu (921600).
• maxBleBufferSize, maxSerialBufferSize — giới hạn buffer.

---

9. Bảng tham chiếu file mã nguồn

---

10. Ghi chú triển khai

• Đồng bộ baud USB với firmware thiết bị; sai baud sẽ không parse được frame T25.
• BLE: đảm bảo firmware gửi đủ dòng kết thúc \n nếu dùng định dạng text; nếu bật mã hóa, cấu hình AES_KEY trùng với thiết bị.
• Bảo mật: khóa trong .env không commit lên kho công khai; luồng gửi mặc định dùng ChaCha20 — cần khớp với implementation phía thiết bị / gateway.

Tài liệu phản ánh trạng thái mã nguồn tại thời điểm viết; khi refactor SimpleBleService hoặc DataService, nên cập nhật lại mục tương ứng.