Robot App Web (RBS)

Giao diện web quản lý robot: mission, map, dashboard, user, Modbus/REST tích hợp.

Tài liệu UI/UX và trạng thái tính năng: [docs/Reference_guide.md](docs/Reference_guide.md).

Backend: C++ executable robot_app (src/app/robot_app.cpp, class RobotApp).
Frontend: static www/ (vanilla JS).

Chức năng chính:

• Đăng ký danh sách cảm biến LiDAR (tên, ip, port)
• Đăng ký IMU (tên, frame_id, topic, nguồn) và pose trên robot
• Kéo thả icon LiDAR/IMU trên canvas để set vị trí (robot frame)
• Nhiều layout — mỗi layout lưu profile trong SQLite (layout_profiles); catalog trong document state
• Mission editor, map editor, dashboard, transitions, paths, path guides, I/O modules

Dữ liệu

Thành phần	Vị trí
Database chính	data/RBS.db (SQLite, WAL) — auth, users, missions, queue, maps, dashboards, …
Media map	data/maps/{map_id}/
Media sound	data/sounds/{sound_id}/
Recordings (stub)	data/recordings/
Layout catalog	document state trong DB + data/state.json (legacy)

Lần khởi động đầu, server import các file JSON cũ (nếu có) vào SQLite: auth.json, missions.json, mission_queue.json, robot_runtime.json.

Site import/export (Setup → Maps): bundle JSON gồm maps, io_modules, transitions, paths — POST /api/sites/{site_id}/import.

Build

# Ubuntu/Debian: sudo apt install libsqlite3-dev cmake build-essential
cmake -S . -B build
cmake --build build -j

Binary: build/robot_app

Run

Chạy mặc định port 8080, phục vụ static từ www/, database tại data/RBS.db:

./build/robot_app

Hoặc chỉ định đủ tham số:

./build/robot_app <port> <www_dir> <db_path>
# ví dụ:
./build/robot_app 8080 ./www ./data/RBS.db

Mở trình duyệt: http://localhost:8080/

Tắt auth cho dev/test:

LM_AUTH_DISABLED=1 ./build/robot_app

Docker (giới hạn 2 CPU, 4 GB RAM)

Mô phỏng cấu hình controller tối thiểu (Dual-Core, 4 GB) trên máy dev:

Mục	Giá trị
Compose service	robot-app
Image	robot-app:RBS
Container	robot-app-limited
Port	8080

./scripts/lm.sh docker up
# hoặc:
sudo docker compose up --build -d

Sau khi đổi tên service/container, nếu port 8080 bị chiếm bởi container cũ:

sudo docker compose down --remove-orphans
sudo docker compose up --build -d

Kiểm tra / dừng:

./scripts/lm.sh docker stats
./scripts/lm.sh docker down

Dữ liệu lưu trên host qua volume ./data:/app/data.

./scripts/lm.sh docker shell   # shell trong container
./scripts/lm.sh docker htop

Biến môi trường

Biến	Mặc định	Mô tả
LM_AUTH_DISABLED	—	1 = tắt xác thực API (dev/test)
LM_URL	http://127.0.0.1:8080	URL khi test container
LM_CONTAINER	robot-app-limited	Tên container Docker
LM_TEST_PORT	18080	Port server tạm khi test run

API (tóm tắt)

Maps, sounds, dashboards

Method	Endpoint	Mô tả
GET/POST	/api/maps	Danh sách / tạo map
GET/PUT/DELETE	/api/maps/{id}	CRUD map
GET/POST	/api/maps/{id}/image	Ảnh map (data/maps/{id}/)
GET/POST	/api/sounds	Danh sách / tạo sound
GET/PUT/DELETE	/api/sounds/{id}	CRUD sound
GET/POST	/api/sounds/{id}/file	Upload/tải file âm thanh
POST	/api/sounds/{id}/play	Phát trên robot (volume 0–100)
GET/PUT	/api/dashboards	Dashboard server-side

Missions & queue

Method	Endpoint	Mô tả
GET/PUT	/api/missions	Danh sách / lưu missions
GET	/api/mission_queue	Queue + runner status
POST	/api/mission_queue	Enqueue mission
DELETE	/api/mission_queue	Xóa toàn bộ queue
DELETE	/api/mission_queue/{id}	Xóa một entry
PUT	/api/mission_queue/reorder	Sắp xếp lại queue
POST	/api/mission_queue/pause	Tạm dừng runner
POST	/api/mission_queue/continue	Tiếp tục runner
POST	/api/mission_queue/cancel	Hủy mission đang chạy

REST tương thích: GET/POST/DELETE /api/v2.0.0/mission_queue

Transitions, paths, I/O

Method	Endpoint	Mô tả
GET/POST	/api/transitions	CRUD transition (?site_id=)
GET/DELETE	/api/paths, /api/paths/{id}	Path cache (auto-create; xóa thủ công)
GET/POST/PUT/DELETE	/api/path_guides	Path guides
GET/POST/PUT/DELETE	/api/io_modules	I/O modules (Bluetooth / WISE)
POST	/api/io_modules/test	Kiểm tra kết nối TCP

Transitions: Setup → Transitions — cấu hình chuyển map (from/to map, start/goal position, mission liên kết). Khi mission chạy move_to_position hoặc adjust_localization tới position trên map khác active_map_id, runner tự chèn: đi tới start position → chạy transition mission → chuyển map → đi tới goal position → tiếp tục bước gốc.

Robot & tích hợp

Method	Endpoint	Mô tả
GET	/api/robot/status	Trạng thái robot (pin, pose, mission strip)
POST	/api/robot/start, /api/robot/pause	Start / pause
POST	/api/robot/errors/reset	Xóa lỗi
POST	/api/robot/active_map	Đặt map đang hoạt động
GET/POST/DELETE	/api/triggers	Modbus mission triggers (coil 1001–2000)
GET/POST/DELETE	/api/fleet/schedules	Lịch fleet (stub scheduler)
GET	/api/recordings	Stub — trả về []

Modbus TCP server: port 5502 (mission triggers + action coils 1–6).

Đăng nhập

Trang web bắt buộc đăng nhập (password hoặc PIN 4 số). Tài khoản mặc định:

User	Password	Nhóm
Admin	admin	Administrators (full quyền)
User	user	Users (dashboard write, còn lại read)
Distributor	distributor	Distributors (full quyền)

PIN chỉ dùng với nhóm Users sau khi admin gán (PUT /api/users/:id).

Chi tiết auth & permissions: docs/Reference_guide.md §2.

Test tự động

Chạy toàn bộ: unit C++ (GTest), API smoke (curl), pytest integration.

chmod +x scripts/lm.sh scripts/test/*.sh
./scripts/lm.sh test run

Chỉ unit test C++:

cmake -S . -B build -DBUILD_TESTING=ON
cmake --build build -j
./build/robot_app_tests
# hoặc: ctest --test-dir build --output-on-failure

Chỉ API smoke (server đang chạy, fixture tests/fixtures/data/):

./build/robot_app 18080 www tests/fixtures/data/state.json &
./scripts/lm.sh test smoke http://127.0.0.1:18080

Fixture mission id mặc định: testmission00001 (tests/fixtures/data/missions.json).

Benchmark trong container (cần docker compose up -d):

./scripts/lm.sh docker bench
# hoặc: ./scripts/lm.sh bench http

CI: GitHub Actions workflow .github/workflows/test.yml.