update Diagnostics

README.md

@@ -95,6 +95,41 @@ Trạng thái instance:
   hai lần là no-op; `open()` hai lần trả `AlreadyOpen` và không đụng kết nối
   đang chạy; sau `close()` có thể `open()` lại (state scan dở được reset).
 
+### Chẩn đoán thiết bị (diagnostics)
+
+Lidar OLEI nhúng thông tin tự chẩn đoán trong header gói dữ liệu (không có
+kênh query riêng). API đọc ra qua `lidarlib/diagnostics.hpp` — nghiên cứu
+chi tiết layout từng family xem [docs/diagnostics.md](docs/diagnostics.md).
+
+```cpp
+lidarlib::Diagnostics d = lidar->get_diagnostics();
+if (!d.valid) {
+    // chưa decode được scan nào
+} else if (d.has_fault()) {
+    // OLEI Family A
+    d.monitor_fault();      // motor/giám sát bất thường
+    d.voltage_fault();      // điện áp ngoài dải
+    d.temperature_fault();  // nhiệt độ bất thường
+    // SICK
+    d.sick_error();          // TiM: device error
+    d.pollution_error();     // TiM: kính bẩn nặng
+    d.contamination_error(); // nanoScan3: kính bẩn nặng
+    d.manipulation();        // nanoScan3: nghi bị che/can thiệp
+    printf("lidar fault: %s\n", lidarlib::to_string(d).c_str());
+} else if (d.has_warning()) {
+    // pollution_warning() / contamination_warning() — kính bẩn nhẹ, nên lau
+}
+```
+
+- `get_diagnostics()` — snapshot từ vòng quét gần nhất; gọi cùng thread với
+  `recv_scan()`/`spin_once()`. `d.healthy()` = có data và không có fault.
+- `decode_diagnostics(result.info)` — decode gắn với một scan cụ thể.
+- Nguồn dữ liệu: OLEI Family A byte lỗi + `rotation_raw` + timestamp;
+  Family B không có gì trên wire; Family C `input/output/field_status`,
+  `status_flags` (raw, chưa verify); SICK TiM cặp device status trong
+  `LMDscandata`; nanoScan3 block General System State (cần bật trong
+  Safety Designer).
+
 ## Cấu hình (config.json)
 
 `lidar_app` là app mẫu headless: đọc `config.json`, mở từng lidar bằng
@@ -185,6 +220,7 @@ parse datagram; **đích UDP phải cấu hình sẵn trong SICK Safety Designer
 | File | Vai trò |
 |---|---|
 | `include/lidarlib/error.hpp` | `enum class ErrorCode` + `to_string()` |
+| `include/lidarlib/diagnostics.hpp` | `Diagnostics`, bit lỗi Family A, `decode_diagnostics()` |
 | `include/lidarlib/lidar.hpp` | Data model, interface `Lidar`, driver OLEI, các `MODEL_*` OLEI |
 | `include/lidarlib/sick_lidar.hpp` | `SickDriver`, `NanoScanDriver`, các `MODEL_SICK_*` |
 | `include/lidarlib/config.hpp` | `LidarConfig`, load/save JSON, `make_lidar()` |
@@ -202,6 +238,42 @@ parse datagram; **đích UDP phải cấu hình sẵn trong SICK Safety Designer
 
 ## Changelog
 
+### 2026-07-07 — Diagnostics API cho SICK
+
+- **`SickDriver` (TiM)**: decode cặp Device Status của `LMDscandata`
+  (0 ok / 1 error / 2 pollution warning / 4 pollution error) vào
+  `Diagnostics` — `sick_error()`, `pollution_warning()`, `pollution_error()`.
+  `info.sick_device_status` là trường mới; `info.error_status` **không còn**
+  nhận `status0` (trường đó thuộc Family A OLEI).
+- **`NanoScanDriver`**: parse block General System State (offset header
+  `[32]/[34]`, byte 0) → `contamination_warning()`, `contamination_error()`,
+  `manipulation()`. Layout theo `sick_safetyscanners`, chưa verify phần cứng;
+  block phải được bật trong Safety Designer.
+- **`Diagnostics` thêm `has_warning()`** (kính bẩn mức cảnh báo) và
+  `to_string()` in thêm `WARN: pollution` / `FAULT: ... contamination`.
+- Test loopback: TiM server TCP giả (status `0 4` → pollution error) và gói
+  nanoScan3 tổng hợp (state `0x09` → contamination error, gói sạch →
+  `healthy()`); tài liệu tại [docs/diagnostics.md](docs/diagnostics.md) §4-5.
+
+### 2026-07-07 — Diagnostics API
+
+- **Header mới `lidarlib/diagnostics.hpp`**: struct `Diagnostics` (bit lỗi
+  Family A decode sẵn: `monitor/voltage/temperature_fault()`, `has_fault()`,
+  `healthy()`; trường raw Family C), hằng `kFaultMonitor/Voltage/Temperature`,
+  `to_string()` để log.
+- **`Lidar::get_diagnostics()`**: snapshot chẩn đoán từ vòng quét decode gần
+  nhất; `valid = false` khi chưa có scan. Driver OLEI implement đầy đủ;
+  SICK tạm trả mặc định.
+- **`decode_diagnostics(const ExtraInfo&)`**: decode gắn với một
+  `ScanResult` cụ thể.
+- **Tài liệu nghiên cứu [docs/diagnostics.md](docs/diagnostics.md)**: layout
+  byte chẩn đoán từng family (A: byte lỗi `[5]` + rotation + timestamp;
+  B: không có; C: input/output/field/status raw), chẩn đoán tầng transport,
+  hướng mở rộng SICK.
+- Đã test bằng gói Family A tổng hợp qua loopback (fault set → decode đúng
+  từng bit, vòng sạch → `healthy()`); bit map lấy theo tài liệu OLEI, chưa
+  tái tạo fault trên phần cứng thật.
+
 ### 2026-07-06 — Error handling & lifecycle API
 
 - **Header mới `lidarlib/error.hpp`**: `enum class ErrorCode` — `Ok`,