Mira_Firmware_Loader/docs/scanner_docs.md

Tài liệu Kỹ thuật: Cơ chế Quét IP trên Mạng (Network Scanner)

1. Tổng quan

Thành phần quét IP trong scanner.py dò tìm và liệt kê tất cả thiết bị đang thực sự online trên một dải mạng (ví dụ: 192.168.1.0/24), trả về danh sách chứa IP và MAC Address của từng thiết bị.

Scanner hoạt động theo cơ chế 2 bước (Ping trước → ARP sau):

1. ICMP Ping Sweep: Chỉ những IP có phản hồi ping mới được ghi nhận là online.
2. ARP Lookup: Ngay sau khi IP phản hồi ping, OS tự động cập nhật ARP cache cho IP đó. Scanner lập tức query ARP table để lấy MAC chính xác nhất.

Giải quyết vấn đề ARP cache cũ (stale entries): Khác với phương pháp ARP scan truyền thống (arp -a liệt kê toàn mạng) thường dính thiết bị đã ngắt kết nối do bị cache, cách làm này chỉ query ARP cho những IP vừa pass qua bài test ping. Thiết bị offline sẽ rớt ở bước ping và không bao giờ được đưa vào danh sách.

---

2. Luồng hoạt động chính (Hàm scan_network)

scan_network(network)
    │
    ├── stage_cb("ping")          ← Thông báo UI bắt đầu quét
    │
    ├── _ping_sweep(network)      ← Ping đồng thời toàn bộ host
    │       │
    │       ├── _ping_one(ip) × N ← Mỗi host 1 thread
    │       │
    │       └── return [alive IPs]
    │
    ├── stage_cb("mac")           ← Thông báo UI bắt đầu lấy MAC
    │
    ├── _get_mac_from_arp(ip) × K ← Tra MAC song song cho K IP alive
    │
    └── return [{"ip": ..., "mac": "AA:BB:CC:..."}, ...]   ← Sorted by IP

Bước 1 — Ping Sweep

• Gọi _ping_sweep(network): gửi ICMP Echo Request đồng thời tới toàn bộ host trong dải mạng.
• Chỉ các IP có returncode == 0 (phản hồi thành công) mới được đưa vào danh sách alive_ips.

Bước 2 — Địa chỉ MAC (ARP Lookup)

• Từ danh sách alive_ips, tạo ThreadPoolExecutor (max_workers=32) để gọi _get_mac_from_arp(ip) đồng thời.
• Trích xuất MAC address bằng pattern matching chéo nền tảng.

Bước 3 — Trả về kết quả

• Danh sách sort tăng dần theo IP: [{"ip": "192.168.1.2", "mac": "AA:BB:CC:DD:EE:FF"}, ...]

---

3. Phân tích chi tiết các hàm

_ping_one(ip, is_win)

Ping một IP đơn lẻ, trả về True nếu host phản hồi, False nếu không.

Timeout tối ưu theo nền tảng:

OS	Lệnh	Timeout wait	Timeout process
Windows	ping -n 1 -w 300	300ms	2s
macOS	ping -c 1 -W 300	300ms	2s
Linux	ping -c 1 -W 1	1s	2s

macOS và Linux dùng cùng flag -W nhưng đơn vị khác nhau (macOS: ms, Linux: giây) — được xử lý tách biệt theo sys.platform.

Windows sử dụng CREATE_NO_WINDOW flag để tránh mở cửa sổ console cho mỗi subprocess.

_ping_sweep(network, progress_cb)

• Tạo ThreadPoolExecutor(max_workers=len(hosts)) — toàn bộ host ping đồng thời, không batching.
• Giới hạn an toàn: chỉ chạy với subnet /24 trở xuống (num_addresses <= 256).
• Trả về danh sách IP (string) đã phản hồi thành công.
• Gọi progress_cb(done, total) sau mỗi ping để UI cập nhật thanh tiến độ.

_get_mac_from_arp(ip)

• Gọi lệnh hệ điều hành để đọc ARP cache cho IP cụ thể:
  • Windows: arp -a <ip>
  • macOS / Linux: arp -n <ip>
• Sử dụng Regex để parse MAC address và trả về dưới format chuẩn AA:BB:CC:DD:EE:FF.
• Nếu không tìm thấy, fallback thành "N/A".

scan_network(network, progress_cb, stage_cb)

• Entry point chính.
• stage_cb("ping") và stage_cb("mac") thông báo UI giai đoạn hiện tại.
• Trả về list[dict] với format {"ip": str, "mac": str}, sorted theo IP tăng dần.

---

4. Hiệu năng

Thông số	Giá trị
Ping workers	len(hosts) (~254, tất cả cùng lúc)
Ping timeout — Windows	300ms
Ping timeout — macOS	300ms
Ping timeout — Linux	1s
Process timeout	2s
Tổng thời gian scan /24	~1–2s

---

5. Ưu & Nhược điểm

Ưu điểm:

• Có đầy đủ IP và MAC, rất hữu ích cho log và tracking lịch sử thiết bị nạp FW.
• Không bị dính ARP cache cũ: Do chỉ lấy MAC của các IP vừa ping thành công.
• Không cần quyền Admin/Root.
• Không phụ thuộc thư viện bên ngoài (không cần Npcap / Scapy phức tạp).
• Tương thích đa nền tảng (Windows/macOS/Linux).
• Cực nhanh nhờ cơ chế full-parallel.

Nhược điểm:

• Thiết bị cố tình chặn gói tin ICMP (tắt ping) sẽ không bị phát hiện.
• Ping 254 thiết bị cùng lúc bằng tiến trình con (subprocess) trên Windows có overhead hệ thống cao hơn Unix.