# 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>`