# ESP32-S3 LD2453 Radar — Orange Pi Visualizer

Hướng dẫn cài đặt và sử dụng script Python trên Orange Pi để visualize dữ liệu radar realtime.

---

## 1. Chuẩn bị

### 1.1 Yêu cầu hệ thống
- Orange Pi (mọi model đều được, cần Python 3.8+)
- Kết nối mạng cùng LAN với ESP32 (WiFi hoặc LAN cổng)
- Biết IP của ESP32 (xem Serial Monitor khi boot, hoặc vào router check)

### 1.2 Cài đặt thư viện hệ thống (nếu dùng GUI tkinter)
```bash
sudo apt update
sudo apt install -y python3-tk python3-pip
```

### 1.3 Copy file lên Orange Pi
Copy 2 file này vào Orange Pi:
- `orange_pi_visualizer.py`
- `orange_pi_requirements.txt`

Ví dụ dùng SCP:
```bash
scp orange_pi_visualizer.py orange_pi_requirements.txt orangepi@<ORANGE_PI_IP>:/home/orangepi/
```

Hoặc dùng USB, hoặc clone repo trực tiếp.

---

## 2. Cài đặt Python dependencies

```bash
cd /home/orangepi
python3 -m venv venv
source venv/bin/activate

pip install -r orange_pi_requirements.txt
```

**Hoặc cài global (không khuyến nghị nhưng nhanh):**
```bash
pip3 install websockets aiohttp
```

---

## 3. Sử dụng

### 3.1 Bật ESP32 ở chế độ Full Stage
Trong `config.h` trên Arduino IDE:
```cpp
#define DIAGNOSTIC_MODE 0   // Full mode: WiFi + WebSocket + REST API
```
Flash code, mở Serial Monitor lấy IP ESP32. Ví dụ: `192.168.1.100`

### 3.2 Chạy Visualizer trên Orange Pi

#### Chế độ GUI (Tkinter) — Mặc định
Cần môi trường desktop (có màn hình gắn vào Orange Pi):
```bash
source venv/bin/activate
python3 orange_pi_visualizer.py 192.168.1.100
```

#### Chế độ Headless (Console)
Dùng khi Orange Pi không có màn hình, chạy SSH remote:
```bash
python3 orange_pi_visualizer.py 192.168.1.100 --headless
```

---

## 4. Mô tả giao diện

### 4.1 GUI Tkinter
- **Canvas 900x700**: Biểu diễn không gian phòng theo tỷ lệ thực (mm)
  - **Trục X (ngang)**: -5m ← 0 (radar) → +5m
  - **Trục Y (dọc)**: 0 (radar ở dưới cùng) ↑ đến 7m (phía trước)
- **Grid**: Mỗi ô = 1 mét
- **Radar**: Hình tròn màu đỏ ở cạnh dưới giữa
- **3 Zones**:
  - Zone 1 (Xanh lá): Bên trái radar (-4m → -1mm, 1mm → 4m)
  - Zone 2 (Cam): Bên phải radar (1mm → 4m, 1mm → 4m)
  - Zone 3 (Đỏ): Khu vực xa hơn (từ 4m → 6m, toàn bộ bề ngang)
  - Khi có người: Màu đậm, chữ CO
  - Khi trống: Màu nhạt, gạch nét, chữ TRONG
- **Targets (3 điểm)**:
  - Màu: Vàng (Slot1), Tím (Slot2), Xanh (Slot3)
  - Mũi tên: Tốc độ (độ dài tỉ lệ với tốc độ cm/s)
  - Label: `T1  X,Y mm  speed cm/s`

### 4.2 Console (headless)
Cập nhật 2 lần/giây, hiển thị:
```
============================================================
  ESP32 LD2453 — Node: RADAR_A   Seq: 12345
============================================================
  Frames received: 1200
  Target count    : 2/3
  Last update     : 0.1s ago
------------------------------------------------------------
  Slot 1: DETECTED
    X=  850mm  Y= 2340mm  Speed=+12cm/s  Dist= 2488mm  Angle=+19.9°
  Slot 2: FREE
  Slot 3: RECENT (2s)
------------------------------------------------------------
  Zone 1:   TRONG  [-4000,    1] -> [   -1, 4000]
  Zone 2: X CO     [    1,    1] -> [ 4000, 4000]
  Zone 3:   TRONG  [-4001, 4001] -> [ 4001, 6000]
============================================================
```

---

## 5. Tùy chỉnh

### 5.1 Thay đổi zone layout
Cách 1: Từ giao diện web ESP32
- Mở trình duyệt vào `http://<ESP32_IP>/zones` xem hiện tại
- Cập nhật bằng POST request:
```bash
curl -X POST http://192.168.1.100/updateZones -H "Content-Type: application/json" -d '[
  {"id":1,"x1":-3000,"y1":500,"x2":-1,"y2":3000},
  {"id":2,"x1":1,"y1":500,"x2":3000,"y2":3000},
  {"id":3,"x1":-3000,"y1":3001,"x2":3000,"y2":5000}
]'
```
Script visualizer sẽ tự động lấy zones mới sau khi reconnect WebSocket (hoặc restart script).

Cách 2: Edit hằng số đầu file `orange_pi_visualizer.py`:
```python
# Default zones (giong ESP32)
state.zones[0] = Zone(1, x1=-4000, y1=1, x2=-1, y2=4000)
state.zones[1] = Zone(2, x1=1, y1=1, x2=4000, y2=4000)
state.zones[2] = Zone(3, x1=-4001, y1=4001, x2=4001, y2=6000)
```

### 5.2 Thay đổi kích thước/range hiển thị
Trong class `TkinterVisualizer`:
```python
CANVAS_W = 900
CANVAS_H = 700
ROOM_X_MIN = -5000
ROOM_X_MAX = 5000
ROOM_Y_MIN = 0
ROOM_Y_MAX = 7000
```

### 5.3 Chạy nền (background) trên Orange Pi
Dùng `tmux` hoặc `systemd`:

#### tmux
```bash
tmux new -s radar
python3 orange_pi_visualizer.py 192.168.1.100 --headless
# Ctrl+B D de detach
# tmux attach -t radar de quay lai
```

#### systemd service (tự chạy khi boot)
Tạo file `/etc/systemd/system/radar-vis.service`:
```ini
[Unit]
Description=LD2453 Radar Visualizer
After=network-online.target

[Service]
Type=simple
User=orangepi
WorkingDirectory=/home/orangepi
ExecStart=/home/orangepi/venv/bin/python3 /home/orangepi/orange_pi_visualizer.py 192.168.1.100 --headless
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```
Sau đó:
```bash
sudo systemctl daemon-reload
sudo systemctl enable radar-vis
sudo systemctl start radar-vis
journalctl -u radar-vis -f   # xem log realtime
```

---

## 6. Troubleshooting

### "No such file directory python3-tk"
```bash
sudo apt update && sudo apt install -y python3-tk
```

### Không kết nối được WebSocket
1. Ping ESP32: `ping 192.168.1.100`
2. Test REST API: `curl http://192.168.1.100/status` → phải trả về `{"status":"ok",...}`
3. Tường lửa Orange Pi? `sudo ufw status`
4. ESP32 ở chế độ `DIAGNOSTIC_MODE 1`? → phải `0` mới có WiFi/WebSocket.

### Tốc độ cập nhật chậm
- Mặc định LD2453 gửi ~2 fps. Đây là giới hạn của radar.
- Để giảm lag GUI: tăng giảm `_last_print` trong ConsoleVisualizer (dòng `now - self._last_print < 0.5`)

### Target số không chính xác/khớp
- Parser trên ESP32 đang trong giai đoạn đầu. Nếu thấy dữ liệu kỳ lạ (tọa độ không hợp lý, target nhảy lung tung):
  1. Bật `DEBUG_RADAR_RAW 1` trên ESP32, lấy RAW dump
  2. Gửi cho việc điều chỉnh lại byte layout.

---

## 7. Đối chiếu với dự án gốc ESP32-LD2450
File này dựa trên pattern của `https://github.com/thanhtantran/ESP32-LD2450`:
- Cùng WebSocket path `/ws`
- Cùng format JSON (`node_id`, `sequence`, `targets[]` với `x`, `y`, `speed`)
- Cùng REST API `/zones` + `/updateZones` + `/status`
- Thêm vào đây: `target_count` tổng hợp, fields `distance` & `angle` cho tiện tính toán.