IPI FLY PRO Driver

Công cụ cấu hình chuột không dây IPI FLY PRO cho Linux và Windows: một binary Rust, không phụ thuộc, cargo build --release trên cả hai hệ điều hành.

• CLI: ipi dpi 2 1600, hợp cho script
• TUI: ipi không tham số, điều khiển bằng bàn phím hoặc chuột

Cài đặt

Chỉ cần Rust.

Linux

./packaging/install.sh

Script build, đặt ipi vào ~/.local/bin, thêm mục vào App launcher kèm icon.

Cài udev rule một lần (/dev/hidraw* mặc định chỉ root đọc được):

sudo cp packaging/70-ipi-fly-pro.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger

Rút receiver ra cắm lại (cắm dây thì không cần). Kiểm tra:

ipi devices        # phải thấy 3554:f517 (dongle) hoặc 3554:f515 (dây)

Windows

cargo build --release

File ở target\release\ipi.exe, copy đi đâu cũng chạy.

Bắt đầu

ipi            # mở TUI
ipi status     # kết nối và pin
ipi get        # toàn bộ thiết lập hiện tại

Mọi lệnh thất bại in lỗi ra stderr và thoát với mã khác 0.

TUI

ipi hoặc ipi tui (bấm đúp .exe trên Windows cũng chạy).

MAIN: Status (chỉ đọc), DPI, Performance, Lighting, Advanced. SETTINGS: General (English / Tiếng Việt), Modes (ẩn/hiện mục ở MAIN), Appearance (16 theme, mặc định IPI TUI vàng).

Phím	Việc
Tab / Shift+Tab	MAIN ↔ SETTINGS
↑ ↓ (hoặc k j)	chọn mục sidebar / chọn dòng nội dung
Enter / → / l	vào nội dung mục đang chọn (ở sidebar)
← → (hoặc h l)	đổi giá trị < … >, ghi ngay xuống chuột; hết dải thì quay vòng
Enter / Space	bật/tắt ô [x], chọn theme (ở trong nội dung)
Esc	về sidebar (không thoát)
r	đọc lại toàn bộ từ chuột
?	trợ giúp
q / Ctrl+C	thoát

Chuột: bấm tab, mục sidebar, dòng; bấm < > để giảm/tăng, bấm [ ] để bật/tắt; lăn bánh xe chỉ di chuyển con trỏ, không bao giờ đổi giá trị.

Theme, ngôn ngữ và mục đã ẩn lưu ở ~/.config/ipi/config.toml (Windows: %APPDATA%\ipi\config.toml).

Nút đổi DPI trên chuột được nhận ra: dòng Active stage đổi theo. Giá trị chỉ đổi trên màn hình sau khi chuột xác nhận ghi.

Lệnh CLI

Lệnh	Việc
ipi status / ipi get / ipi devices	Đọc trạng thái / mọi thiết lập / thiết bị HID
ipi dpi <1-4> <50-42000>	Đặt DPI cho một stage (bội số 50)
ipi stage <1-4>	Chọn stage đang dùng
ipi polling <125|250|500|1000|2000|4000|8000>	Polling rate (Hz)
ipi lod <0.7|1|2>	Lift-off distance (mm)
ipi debounce <0-20>	Debounce (ms)
ipi sleep <1-255>	Sleep timer (×10 giây, 30 = 5 phút)
ipi workmode <low|high|ultra>	Work mode
ipi toggle <motion-sync|linear|waveform|fps20k|long-distance> <on|off>	Bật/tắt
ipi led <solid|breathing|off> [--brightness 0-10] [--speed 1-5]	Đèn
ipi receiver-led <hz|battery|warning>	Đèn trên dongle
ipi rage <on|off> [--seconds <1|3|6|12|18|36|60|90>]	Full power
ipi angle <off|-45..45>	Angle snapping
ipi reset [--yes]	Khôi phục mặc định
ipi verify [--restore-only]	Round-trip test toàn bộ thiết lập (~1 phút)
ipi read <hex> / ipi raw <hex>	Nghiên cứu giao thức

Gõ ipi <lệnh> --help để xem giá trị hợp lệ.

IPI_DEBUG=1 ipi status in mọi HID interface khớp lúc mở, và frame bị bỏ qua.

Ý nghĩa từng thiết lập: docs/SETTINGS.md.

Xử lý sự cố

Permission denied (os error 13) Chưa cài udev rule. Xem Cài đặt, nhớ rút cắm lại receiver.

hid read timed out Chuột đang ngủ. Rê chuột rồi chạy lại, hoặc chữa tận gốc bằng ipi sleep 60.

FLY PRO not found Chưa cắm receiver, hoặc chuột chưa bật. ipi devices xem máy có thấy 3554:f517 (dongle) hay 3554:f515 (dây) không.

Không thấy app trong launcher Logout rồi login lại — một số môi trường desktop cache danh sách app.

Lệnh báo thành công nhưng giá trị không đổi Chạy ipi verify để biết chính xác thiết lập nào không ăn.

Phát triển

cargo test && cargo clippy --all-targets -- -D warnings && cargo fmt --check

File	Vai trò
src/protocol.rs	dựng frame HID và checksum, thuần, toàn bộ unit test
src/device.rs	tìm và mở HID interface, khớp reply, giãn nhịp ghi, thử lại
src/config.rs	thao tác thiết lập dựng trên protocol
src/cli.rs	phân tích dòng lệnh
src/tui/	giao diện terminal: app.rs (state, phím, chuột), nav.rs (cây mục), ui.rs (vẽ, hit test), mod.rs (vòng lặp, ghi xuống chuột), tests.rs
src/settings.rs	theme 0 và enum Lang; phần còn lại lấy từ crate sazvtui
src/verify.rs	round-trip kiểm chứng trên phần cứng thật

Giao thức HID: docs/PROTOCOL.md.