logic ready

docs/diagnostics.md

@@ -140,7 +140,33 @@ Ngoài dữ liệu trên wire, bản thân driver cung cấp lớp chẩn đoán
 Chiến lược giám sát khuyến nghị cho app: coi cảm biến **healthy** khi và chỉ
 khi `recv_scan()` thành công đều đặn **và** `get_diagnostics().has_fault() == false`.
 
-## 7. API
+## 7. Kiểm tra sẵn sàng: `is_ready()` / `wait_ready()`
+
+Chiến lược trên được gói sẵn trong hai hàm của `Lidar`:
+
+```cpp
+lidar->open();
+if (!lidar->wait_ready(5000)) {          // bơm recv_scan() tới khi ready
+    // timeout: xem last_error() (Timeout, DeviceDisconnected...)
+}
+// ... vòng lặp chính đang bơm recv_scan()/spin_once() ...
+if (!lidar->is_ready()) { /* mất dữ liệu hoặc thiết bị báo fault */ }
+```
+
+- `is_ready(max_age_ms = 3000)` = `is_open()` **và** `get_diagnostics().healthy()`
+  **và** scan decode gần nhất chưa quá `max_age_ms` (truyền `0` để bỏ kiểm tra
+  tuổi). Kiểm tra tuổi giúp phát hiện cảm biến chết giữa chừng — socket UDP
+  vẫn "mở" và snapshot diagnostics vẫn "khỏe" dù thiết bị đã ngừng phát.
+  Diagnostics chỉ được cập nhật bởi `recv_scan()`/`spin_once()`, nên phải có
+  vòng lặp đang bơm dữ liệu thì `is_ready()` mới có nghĩa.
+- `wait_ready(timeout_ms = 5000)` = bơm `recv_scan()` (bỏ qua dữ liệu, không
+  gọi callback) cho tới khi `is_ready()` hoặc hết giờ — dùng lúc khởi động,
+  trước khi giao quyền bơm cho vòng lặp chính.
+- `is_ready()` **không** tính `has_warning()` (kính bẩn nhẹ vẫn đo được →
+  vẫn ready); app muốn chặt hơn thì tự kiểm tra thêm
+  `!get_diagnostics().has_warning()`.
+
+## 8. API
 
 ```cpp
 #include "lidarlib/lidarlib.hpp"
@@ -150,7 +176,7 @@ if (lidar->recv_scan(r, 1000)) {
     lidarlib::Diagnostics d = lidar->get_diagnostics();
 
     if (!d.valid) {
-        // chưa có scan nào được decode (hoặc driver không hỗ trợ — SICK)
+        // chưa có scan nào được decode
     } else if (d.has_fault()) {
         // Family A: đọc từng bit
         if (d.voltage_fault())     /* điện áp bất thường */;
@@ -181,7 +207,7 @@ if (lidar->recv_scan(r, 1000)) {
   nano contamination error/manipulation); `has_warning()` gộp các mức cảnh
   báo kính bẩn.
 
-## 8. Hướng mở rộng
+## 9. Hướng mở rộng
 
 - **SICK SOPAS query chủ động**: `sRN SCdevicestate` (0=busy, 1=ready,
   2=error), `sRN LCMstate` (mức nhiễm bẩn chi tiết) — cần cơ chế