Load FW bằng SSH, Thêm tính năng update FW (SSH)

docs/load_fw_ssh_docs.md

@@ -0,0 +1,58 @@
+# Tài liệu Kỹ thuật: Nạp Mới Firmware (LoadFW bằng SSH)
+
+Tính năng **Nạp Mới FW** trong module `ssh_flasher.py` được thiết kế để cấp cứu và cài đặt lại Firmware cho các thiết bị OpenWrt trắng (mới xuất xưởng) hoặc vừa trải qua Hardware Factory Reset.
+
+---
+
+## 🚀 Tính năng Báo Cáo Tiến Độ Lên UI
+
+Tính năng này được thiết kế theo chuẩn hướng sự kiện (Callback). Module liên tục báo cáo dữ liệu thời gian thực lên cột Status của bảng thiết bị:
+
+1. `Checking Telnet port for raw device...` (Nếu thiết bị mới bị khóa SSH)
+2. `Setting password via SSH...` / `Password set via Telnet...`
+3. `Uploading firmware via SCP...` (Đẩy file vào RAM Disk)
+4. `Verifying firmware...`
+5. `Syncing filesystem...`
+6. `Flashing firmware (sysupgrade)...`
+7. `Rebooting...`
+
+---
+
+## 🛠 Flow Hoạt Động Mạch Trắng (Workflows)
+
+Tính năng Flash qua luồng này hoạt động theo một quy trình 5 bước cực kỳ nghiêm ngặt:
+
+### Bước 0: Thiết lập Mật khẩu Đa Kênh qua Cổng 23 (Fallback Mechanism)
+
+- **Vấn đề của OpenWrt:** Router OpenWrt vừa xuất xưởng (chưa có pass) sẽ **CẤM đăng nhập SSH** cho tài khoản `root`. Lúc này, chỉ cổng cục bộ Telnet (Port 23) là mở.
+- **Cách Tool vượt qua:**
+  1. Tool tiên phong chọc thẳng bằng **Giao thức Telnet (Port 23)**.
+  2. Dùng chuỗi lệnh `passwd` để thiết lập mật khẩu thành `admin123a` 2 lần. Đợi 3s để OpenWrt kịp đánh thức Server Dropbear (Mở cổng 22 SSH).
+  3. Nếu thiết bị đã có Pass, Tool sẽ mượt mà Rơi xuống nhánh SSH (`old_password` -> `admin123a`).
+
+### Bước 1: Khởi tạo Kết nối SSH
+
+- Sử dụng cờ `AutoAddPolicy` của Python `paramiko` ép kết nối âm thầm chấp nhận mọi Host Certificate mà không bật popup cảnh báo.
+
+### Bước 2: Truyền File bảo mật (SCP vào RAM)
+
+- Thực hiện SCP đẩy BIN firmware (`tim_uImage` hoặc `.bin`) vào phân vùng ảo: `/tmp/<tên_file>.bin`. Đây là khu vực RAM Disk (Ghi siêu tốc, không làm mòn chip nhớ).
+
+### Bước 3 & 4: Xác thực và Đồng bộ (Verify & Sync)
+
+- Gửi lệnh `test -f /tmp/...` để xác nhận file.
+- Gọi lệnh `sync` ép File System đẩy transaction xuống vùng nhớ cứng.
+
+### Bước 5: Sysupgrade (Cài Đặt Lõm)
+
+- Chạy lệnh ngầm: `sysupgrade -F -v -n /tmp/<tên_file>`.
+  - Cờ `-n`: Clean Flash sạch trơn, không giữ Configuration.
+  - Cờ `-F` (Force): Bỏ qua bộ kiểm tra Image Metadata cho những File thiếu hụt Metadata (uImage).
+- **Đứt Kết Nối Đột Ngột** khi script đang đợi (sau khoảng 4s trở đi) sẽ mặc định được coi là tín hiệu Thành Công (Server SSH sập nguồn để Reboot).
+
+---
+
+## 🔎 Trình Gỡ Lỗi (Debugging)
+
+Chạy file `debug_ssh.py` độc lập trên Terminal ở cấp độ TCP Verbose để soi quá trình nạp mới:
+`./venv/bin/python debug_ssh.py <IP> <DUONG_DAN_FIRMWARE> <PASS>`