RuView

1. RuView là gì?

RuView là một dự án mã nguồn mở dùng sóng WiFi để "cảm nhận" con người trong phòng mà không cần camera. Nguyên lý: sóng WiFi lấp đầy căn phòng, và khi có người đi lại, thậm chí chỉ hít thở, sóng bị nhiễu theo cách đo được. RuView đọc các nhiễu đó để suy ra có người hay không, họ đang chuyển động ra sao, và ước lượng nhịp thở, nhịp tim.

Cần nói thẳng ba điều trước khi bạn cài:

• Đây là phần mềm beta, mang tính nghiên cứu. Tác giả ghi rõ API và firmware còn thay đổi.
• Muốn cảm biến thật thì phải mua phần cứng. Cần mạch ESP32-S3 (một loại mạch vi điều khiển nhỏ có WiFi, khoảng 9 USD một mạch theo README). Laptop thường chỉ đo được cường độ sóng, đủ để nhận biết thô là có người hoặc có chuyển động.
• Bản chạy bằng Docker dùng dữ liệu mô phỏng. Nó cho bạn xem giao diện và cách hệ thống hoạt động, không phải đang nhìn xuyên tường nhà bạn.

Dự án theo giấy phép MIT, miễn phí. Tác giả cũng tự đính chính các con số quá đà trước đây: mô hình dựng khung xương 17 điểm chạy trực tiếp trên một mạch ESP32 hiện mới ở mức thử nghiệm, độ chính xác còn thấp hơn mục tiêu của chính dự án.

Lưu ý: README ghi rõ đây là ứng dụng nghiên cứu và thử nghiệm, không phải thiết bị y tế, không phải hệ thống cấp cứu hay thiết bị an toàn đã được chứng nhận. Đừng dựa vào nó để theo dõi sức khỏe người thân.

Hợp với bạn nếu:

• Bạn tò mò và muốn xem tận mắt giao diện "WiFi nhìn thấy người" trông ra sao.
• Bạn thích vọc phần cứng, sẵn sàng mua vài mạch ESP32-S3 và nạp firmware.
• Bạn làm nghiên cứu hoặc nhà thông minh và cần cảm biến hiện diện không dùng camera.

Chưa hợp nếu:

• Bạn mong cài xong là điện thoại hay laptop nhìn được xuyên tường. Điều đó không xảy ra.
• Bạn cần một sản phẩm hoàn thiện, cắm là chạy, có bảo hành.

2. Cần chuẩn bị gì?

Để xem bản demo trên web: chỉ cần trình duyệt, trên điện thoại cũng được.

Để chạy bản mô phỏng trên máy:

Thứ cần có	Tối thiểu	Khuyến nghị
Hệ điều hành	Windows 10/11, macOS 10.15, Ubuntu 18.04	Bản ổn định mới nhất
RAM	4 GB	8 GB trở lên
Ổ đĩa trống	2 GB	5 GB
Docker	Bản 20 trở lên	Bản 24 trở lên

• Docker: phần mềm chạy ứng dụng trong một "hộp" đóng gói sẵn, nhờ đó bạn không phải cài từng thành phần. Người dùng Windows và macOS tải Docker Desktop tại https://www.docker.com/products/docker-desktop/
• Không cần tài khoản, không cần khóa API.

Để cảm biến thật (tùy chọn, nâng cao):

• Mạch ESP32-S3. Theo tài liệu, một cụm 3 đến 6 mạch tốn khoảng 54 USD. Một mạch đơn lẻ vẫn chạy nhưng độ phân giải không gian hạn chế; tác giả khuyên dùng từ 2 mạch trở lên.
• Một bộ phát WiFi và một máy tính chạy phần mềm nhận dữ liệu.
• Python (để chạy công cụ nạp firmware và cấu hình mạch). Tải tại https://www.python.org/downloads/

Lưu ý: README ghi mạch ESP32-C3 và ESP32 đời đầu không được hỗ trợ. Xem kỹ tên mạch trước khi mua.

3. Cài đặt từng bước

Cách 1: Xem demo trên web (không cài gì)

Bước 1: Mở trang demo

Vào https://ruvnet.github.io/RuView/ bằng trình duyệt. Đây là trang "Live Observatory Demo" do tác giả dựng sẵn.

Đúng là khi: bạn thấy giao diện 3D hiển thị khung xương người và các thông số. Đây là hình minh họa, không phải dữ liệu từ nhà bạn.

Nếu bạn chỉ muốn biết RuView trông ra sao, dừng ở đây là đủ.

Cách 2: Chạy bản mô phỏng trên máy bằng Docker

Bước 1: Cài và mở Docker Desktop

Tải bộ cài từ https://www.docker.com/products/docker-desktop/, cài như một phần mềm thông thường rồi mở lên. Chờ đến khi Docker báo đang chạy.

Kiểm tra bằng lệnh:

docker --version

Đúng là khi: máy in ra số phiên bản từ 20 trở lên.

Bước 2: Tải bản đóng gói của RuView

docker pull ruvnet/wifi-densepose:latest

Tên wifi-densepose là tên cũ của dự án, vẫn được dùng cho bản đóng gói. Bản này chạy được trên cả máy Intel / AMD lẫn máy Mac chip Apple Silicon.

Đúng là khi: các thanh tiến trình tải chạy hết và dòng nhắc lệnh trở lại, không báo lỗi.

Bước 3: Chạy

docker run -p 3000:3000 -p 3001:3001 ruvnet/wifi-densepose:latest

Hai cụm -p mở hai cổng để trình duyệt nói chuyện được với chương trình: cổng 3000 cho trang web, cổng 3001 cho dữ liệu trực tiếp.

Đúng là khi: cửa sổ dòng lệnh hiện các dòng nhật ký và không tự thoát. Hãy để nguyên cửa sổ này.

Bước 4: Mở giao diện

Mở trình duyệt và vào:

http://localhost:3000

Đúng là khi: bạn thấy giao diện có khung xương 3D (17 điểm khớp), bản đồ nhiệt biên độ tín hiệu, đồ thị pha và bảng nhịp thở, nhịp tim.

Cách 3: Cảm biến thật với mạch ESP32-S3 (nâng cao)

Phần này dành cho người đã quen nạp firmware cho mạch vi điều khiển. Trình tự tóm tắt:

1. Tải firmware dựng sẵn từ trang Releases: https://github.com/ruvnet/RuView/releases. Tài liệu dặn luôn dùng bản v0.4.3.1 trở lên; bản cũ hơn bị báo ngã sai hoặc chưa bật tính năng đo.
2. Nạp firmware vào mạch bằng công cụ esptool. Lệnh nạp đầy đủ và tên từng file nằm trong mục "ESP32-S3 Mesh" của User Guide: https://github.com/ruvnet/RuView/blob/main/docs/user-guide.md
3. Tải mã nguồn RuView về máy (cần Git, tải tại https://git-scm.com/downloads) vì công cụ cấu hình mạch nằm trong đó:

git clone https://github.com/ruvnet/RuView.git
cd RuView

4. Khai báo WiFi cho mạch và chỉ cho nó địa chỉ máy tính nhận dữ liệu. Thay COM7, tên WiFi, mật khẩu và địa chỉ IP bằng thông số của bạn:

python firmware/esp32-csi-node/provision.py --port COM7 --ssid "YourWiFi" --password "YourPassword" --target-ip 192.168.1.20

5. Chạy RuView ở chế độ nhận dữ liệu từ mạch:

docker run -p 3000:3000 -p 3001:3001 -p 5005:5005/udp -e CSI_SOURCE=esp32 ruvnet/wifi-densepose:latest

Đúng là khi: giao diện ở http://localhost:3000 hiển thị dữ liệu thay đổi khi bạn di chuyển trong phòng.

4. Dùng lần đầu

Với bản mô phỏng (Cách 2), làm thử ba việc:

Xem bảng điều khiển. Mở http://localhost:3000/ui/index.html. Đây là bảng theo dõi dạng thẻ, gồm mô hình cơ thể 3D xoay được, bản đồ nhiệt tín hiệu, đồ thị pha và ô hiển thị nhịp thở, nhịp tim. Ở chế độ mô phỏng, các chỉ số sinh tồn xuất hiện sau vài giây khởi động.

Xem chế độ Observatory. Mở http://localhost:3000/ui/observatory.html để thấy căn phòng 3D với các hình người dạng khung dây.

Kiểm tra chương trình có đang chạy đúng không. Mở một cửa sổ dòng lệnh thứ hai và gõ:

curl http://localhost:3000/health

Kết quả đúng là một dòng chữ có "status":"ok" và "source":"simulated". Chữ simulated xác nhận bạn đang xem dữ liệu mô phỏng.

Khi xem xong, quay lại cửa sổ đang chạy Docker và bấm Ctrl+C để dừng.

5. Lỗi thường gặp và cách sửa

Dấu hiệu	Nguyên nhân	Cách sửa
Gõ docker báo "command not found" / "not recognized", hoặc báo không kết nối được tới Docker	Chưa cài Docker, hoặc Docker Desktop chưa được mở	Cài Docker Desktop, mở nó lên, chờ báo đang chạy rồi thử lại
Trình duyệt báo "Connection refused" ở localhost:3000	Chạy thiếu phần mở cổng	Chạy lại đúng lệnh ở Bước 3, có đủ -p 3000:3000 -p 3001:3001
Giao diện hiện lên nhưng không có dữ liệu chạy	Thiếu cổng dữ liệu trực tiếp 3001	Dừng chương trình, chạy lại lệnh có -p 3001:3001
Trên Mac báo "no matching manifest for linux/arm64"	Docker đang giữ thông tin cũ về bản đóng gói	Chạy lại docker pull ruvnet/wifi-densepose:latest. Nếu vẫn lỗi, dùng lệnh bên dưới bảng
Nhịp thở, nhịp tim hiện 0	Ở chế độ mô phỏng cần vài giây khởi động; với laptop chỉ đo cường độ sóng thì không đủ độ phân giải	Chờ thêm vài giây. Muốn đo thật cần mạch ESP32
Observatory hiện chữ DEMO thay vì LIVE	Bạn mở trang từ file trên máy, hoặc trình duyệt còn giữ cài đặt cũ	Mở qua địa chỉ http://localhost:3000/ui/observatory.html và bấm Ctrl+Shift+R để tải lại hẳn
Mạch ESP32 đã nạp nhưng không có dữ liệu về	Mạch khác mạng WiFi, sai địa chỉ máy nhận, hoặc tường lửa chặn	Kiểm tra mạch và máy tính cùng một mạng WiFi, chạy lại provision.py với đúng địa chỉ IP của máy tính, và mở cổng UDP 5005 trên tường lửa

Lệnh tải riêng cho Mac chip Apple Silicon khi gặp lỗi "no matching manifest":

docker pull --platform linux/arm64 ruvnet/wifi-densepose:latest

Lỗi khác: tìm hoặc hỏi tại https://github.com/ruvnet/RuView/issues

6. Gỡ cài đặt / cập nhật

Cập nhật bản Docker: tải lại bản mới rồi chạy như cũ.

docker pull ruvnet/wifi-densepose:latest

Gỡ bản Docker:

1. Dừng chương trình bằng Ctrl+C ở cửa sổ đang chạy.
2. Xem danh sách các lần chạy còn lưu lại:

docker ps -a

3. Xóa từng mục có tên bản đóng gói ruvnet/wifi-densepose, dùng mã ở cột đầu tiên:

docker rm MA_CONTAINER

4. Xóa bản đóng gói để lấy lại dung lượng:

docker rmi ruvnet/wifi-densepose:latest

Nếu không còn dùng Docker cho việc gì khác, gỡ Docker Desktop như gỡ một phần mềm thông thường.

Firmware trên mạch ESP32: cập nhật bằng cách nạp bản mới từ trang Releases. Bản firmware mới nhất lúc viết bài là 0.8.13 (29/9/2026), được đánh dấu là bản thử (pre-release). Ghi chú phát hành cho biết nạp bản mới vẫn giữ cấu hình WiFi đã lưu. Bản ổn định mà User Guide khuyên dùng cho cụm ESP32-S3 là v0.5.0.

7. Câu hỏi hay gặp

Có mất tiền không? Phần mềm miễn phí, giấy phép MIT. Bản demo web và bản mô phỏng bằng Docker không tốn gì. Chỉ mất tiền nếu bạn mua mạch ESP32-S3 để cảm biến thật.

Có cần mạng không? Cần mạng để tải Docker và bản đóng gói. Khi đã chạy, README ghi hệ thống chạy hoàn toàn trên thiết bị tại chỗ, không cần đám mây, không cần internet.

Dữ liệu có bị gửi đi đâu không? Theo README, RuView xử lý tại chỗ và không dùng camera nên không có hình ảnh nào được ghi lại. Các tính năng kết nối thêm như Home Assistant hay thiết bị Cognitum Seed là tùy chọn, bạn phải tự bật.

Chỉ có laptop, không mua mạch thì làm được gì? Bạn xem được bản mô phỏng. Ngoài ra laptop có thể nhận biết thô là có người hoặc có chuyển động dựa trên cường độ sóng, nhưng cách này phải tự dựng chương trình từ mã nguồn, không dựng khung xương và không đo được nhịp tim một cách đáng tin.

Nó có thật sự nhìn xuyên tường không? README ghi khả năng cảm biến xuyên tường tới khoảng 5 mét và phụ thuộc vào tín hiệu. Đó là phát hiện có người và chuyển động, không phải hình ảnh như camera. Chính tác giả đã rút lại con số "100% phát hiện hiện diện" trước đây và thay bằng số đo thận trọng hơn.