App/docs/Reference_guide.md

MiR Robot Reference Guide — Tóm tắt

Nguồn: docs/Reference guide.pdf
MiR robot Reference guide (en), rev. 1.9, 03/2019
Mô tả giao diện web trên robot MiR (không phải User Guide phần cứng MiR250).

---

1. Giới thiệu

Tài liệu dành cho administrator và người cấu hình hệ thống: tạo mission, map, user, dashboard, Modbus trigger.

Tài liệu liên quan khác (Distributor site / Support Portal):

Loại	Nội dung
Quick Start	Vận hành nhanh (in trong hộp robot)
User Guide	Vận hành & bảo trì robot (MiR250 có bản riêng)
Commissioning / Risk Analysis	Đưa robot vào sản xuất an toàn
REST API Reference	Robot, Hook, Fleet
Network & WiFi Guide	Yêu cầu mạng

• Fleet (scheduler, robot groups): tài liệu riêng MiR Fleet Reference Guide.

---

2. MiR robot interface (ch. 2)

Giao diện web trên robot: responsive (PC, tablet, portrait/landscape). Truy cập qua WiFi AP robot hoặc LAN (http://<robot_ip> / mir.com).

2.1 Signing in

RBS: tính năng đã triển khai — xem RBS — Signing in.

Luồng truy cập (MiR)

Thiết bị → kết nối mạng robot → trình duyệt → trang Sign in → shell app (Dashboard / Setup / …)

Toàn bộ UI bị chặn cho đến khi đăng nhập thành công.

Hai cách đăng nhập

Cách	Đối tượng	Giao diện
Username + password	Distributor, Administrator, kỹ sư	Tab form username + password
PIN 4 chữ số	Operator sàn (quyền thấp)	Tab PIN; không có PIN mặc định

Ba cấp truy cập mặc định

Role	Username	Password mặc định	Vai trò
Distributor	Distributor	Liên hệ MiR Support	Đại lý; full quyền; quản lý quyền Admin/User
Administrator	Admin	admin	Kỹ sư khách hàng; full read/write
User	User	user	Operator hàng ngày

MiR250 Quick Start: đổi password mặc định ngay; mỗi người một tài khoản; chỉ operator cấp thấp dùng PIN; Admin/Distributor dùng password mạnh.

Tách credentials và permissions

Lớp	Gắn với	Nội dung
Credentials	User (cá nhân)	username, password, PIN
Permissions	User group (nhóm)	module nào được xem / sửa

Mỗi user thuộc một user group. Mục không có quyền write: vẫn hiển thị nhưng không chỉnh sửa được.

User groups mặc định (mục 4.6)

Nhóm	Quyền mặc định
Distributors	Full R/W; quản lý quyền Administrators và Users
Administrators	Full R/W; quản lý quyền Users
Users	Xem toàn UI; tạo/sửa dashboard

Admin có thể tạo thêm user group (ví dụ Operators) và gán quyền từng module (Maps, Missions, System…).

Sau khi đăng nhập

• Góc phải trên: tên user → đổi password, Sign out.
• Admin tạo user tại Setup → Users; nhóm tại Setup → User groups (tạo group trước user).
• Dashboard gán quyền theo group qua nút Permissions khi tạo/sửa dashboard.
• Widget Log-out button trên dashboard (hữu ích trên tablet).

Bảo mật (Quick Start + SW mới)

• MiR không ép password policy phức tạp trên robot đơn lẻ.
• Không nên nhiều người dùng chung một account.
• SW mới (~2023): auto sign-out theo user group; MiR Fleet hỗ trợ OAuth 2.0 / OpenID Connect.

RBS — Signing in (đã triển khai)

Tính năng đăng nhập theo MiR §2.1 đã tích hợp vào lidar_manager_web. Toàn bộ API (trừ health/login/logout) yêu cầu session; UI bị chặn cho đến khi đăng nhập thành công.

Luồng người dùng

Trình duyệt → / (trang Sign in)
  → POST /api/auth/login (password hoặc PIN)
  → Cookie lm_session + shell app (Dashboard / Cấu hình / Missions / Tích hợp)
  → Menu user (góc phải): đổi mật khẩu, đăng xuất

• Static (www/) phục vụ công khai để tải trang login.
• auth.js gọi GET /api/auth/me khi mở trang; session hợp lệ thì vào app ngay.
• app.js, missions.js, dashboard.js, integrations.js chỉ khởi động sau sự kiện lm:auth-ready.
• API mission queue và các endpoint khác không được gọi trước khi đăng nhập.

Giao diện web (MiR-style)

Thành phần	Mô tả
Nền	Xanh #3d6cb3, full-screen
Header	Tên robot (RobotApp) + «Chọn cách đăng nhập» + 2 tab
Tab Tên đăng nhập và mật khẩu	2 cột: hướng dẫn trái, form phải; nút xanh «Đăng nhập»
Tab Mã PIN	Trái: hướng dẫn + 4 ô vuông (•); phải: keypad 1–9, 0, ✕
PIN	Tự đăng nhập khi đủ 4 số; hỗ trợ bàn phím vật lý
Sau login	Menu user topbar; ẩn/vô hiệu menu theo quyền read-only

File: www/index.html, www/auth.js, www/style.css.

Tài khoản mặc định

Tự tạo lần đầu trong data/auth.json (cùng thư mục state.json):

Username	Password	User group	Ghi chú
Admin	admin	Administrators	Full quyền
User	user	Users	Dashboard write; phần còn lại read
Distributor	distributor	Distributors	Full quyền

• Username đăng nhập không phân biệt hoa thường (admin = Admin).
• PIN: không có mã mặc định (giống MiR). Chỉ nhóm Users (allow_pin: true); admin gán qua API.

User groups và permissions

Credentials → user; quyền → group. Module: dashboard, config, missions, integrations, users — giá trị none | read | write.

Group	PIN	dashboard	config	missions	integrations	users
Distributors	Không	write	write	write	write	write
Administrators	Không	write	write	write	write	write
Users	Sau khi gán	write	read	read	read	none

Group	Menu UI
Users	Dashboard + xem Cấu hình/Missions/Tích hợp (nút ghi read-only)
Administrators / Distributors	Toàn bộ menu; quản lý user qua API

Session và middleware

Cơ chế	Chi tiết
Session	Server-side; mất khi restart process
Cookie	lm_session=<token>; HttpOnly; SameSite=Lax
Header	Authorization: Bearer <token>
Middleware	AuthService::preRoute trên /api/*
Public	GET /api/health, POST /api/auth/login, POST /api/auth/logout, OPTIONS
Dev	LM_AUTH_DISABLED=1 tắt auth

API → module (kiểm tra read/write):

Module	Prefix
config	/api/lidars, /api/imus, /api/layouts, /api/state, …
missions	/api/missions, /api/mission_queue
integrations	/api/triggers, /api/schedules, /api/fleet, /api/modbus, /api/v2.0.0/
users	/api/users, /api/user_groups

REST API

Method	Endpoint	Auth	Mô tả
POST	/api/auth/login	Public	{ username, password } hoặc { pin }
POST	/api/auth/logout	Public	Xóa session + cookie
GET	/api/auth/me	Session	User, group, permissions
PUT	/api/auth/password	Session	Đổi mật khẩu
GET	/api/user_groups	users read	Danh sách nhóm
GET	/api/users	users read	Danh sách user
POST	/api/users	users write	Tạo user
PUT	/api/users/:id	users write	Sửa user / gán PIN (pin: null = xóa)
DELETE	/api/users/:id	users write	Xóa user

Ví dụ login + gán PIN

curl -c c.txt -X POST http://localhost:8080/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"Admin","password":"admin"}'

curl -b c.txt -X PUT http://localhost:8080/api/users/user_operator \
  -H 'Content-Type: application/json' \
  -d '{"pin":"1234"}'

Lưu trữ và mã nguồn

Thành phần	Vị trí
Dữ liệu	data/auth.json — groups, users (hash + salt)
Backend	src/auth/auth_service.cpp, src/util/crypto_util.cpp, src/app/lidar_manager_app.cpp
Frontend	www/auth.js, www/index.html, www/style.css
Test	scripts/test/smoke.sh, tests/test_api_integration.py

Hash: SHA-256 + salt (sha256(salt:password) / sha256(salt:pin:pin)).

Kiểm thử và vận hành

./scripts/lm.sh test run   # smoke tự login Admin; pytest test_auth_*

• Docker: www/ copy lúc build → docker compose up --build -d sau sửa UI.
• Hard refresh (Ctrl+Shift+R) nếu cache JS/CSS.

So sánh MiR ↔ RBS

MiR §2.1	RBS
Sign in bắt buộc	Có
Tab password | PIN + keypad	Có
3 role mặc định	Admin / User / Distributor
PIN không mặc định	Có — admin gán API
User menu, đổi password, sign out	Có
Credentials / permissions tách biệt	Có
Setup → Users (UI)	Chưa — chỉ API
Auto sign-out / OAuth Fleet	Chưa

2.2 Navigating the MiR robot interface

• Menu chính → tối đa một submenu rồi vào section (ví dụ Setup → Sounds).
• Top bar: trạng thái robot, nút start/pause.

2.3 Getting started

Thiết lập user trước vận hành:

1. Users (Setup → Users)
2. User groups (Setup → User groups)
3. Dashboards theo vai trò (Dashboards → Create)

Thiết lập hệ thống: map → chỉnh map (positions, zones) → missions.

---

3. Mục lục đầy đủ

1. About this document

• 1.1. Where to find more information
• 1.2. Document history

2. MiR robot interface

• 2.1. Signing in
• 2.2. Navigating the MiR robot interface
• 2.3. Getting started

3. Dashboards

• 3.1. Dashboards — Create / designer / edit / delete
• 3.2. Widgets
  • 3.2.1. Maps — Locked map, Map
  • 3.2.2. Missions — Mission button, Pause/Continue, Mission queue, Mission action log, Mission group
  • 3.2.3. PLC registers — PLC button/display
  • 3.2.4. I/O module — Connect, configuration, status
  • 3.2.5. Hook — Cart actions (Pick up / Place cart)
  • 3.2.6. Miscellaneous — Joystick, Robot summary, Distributor, Log-out button

4. Setup

• 4.1. Missions — Start, Create, Editor, Actions (xem §4 bên dưới)
• 4.2. Maps — Site, mapping, object types (walls, zones…), delete
• 4.3. Sounds — Edit sound
• 4.4. Transitions — Chuyển map tự động
• 4.5. Users — CRUD user
• 4.6. User groups — CRUD nhóm
• 4.7. Shelf types
• 4.8. I/O modules — Kết nối Modbus/TCP I/O
• 4.9. Paths
• 4.10. Path guides

5. Monitoring

• Analytics, System log, Error logs, Hardware health, Safety system
• Mission log / Mission action log

6. System

• Settings (WiFi, date/time), Processes, PLC registers, Software versions, Backups
• Robot setup — bật Modbus, cấu hình robot
• Triggers — gắn coil Modbus → mission_id

7. Help

• Robot & Hook info, API documentation, Remote access, Service book, Manual

8. Hook

• Manual control, Carts (type, calibration), Settings, Setup

9. Modbus register reference

• 9.1. Status messages (registers 4001+)
• 9.2. PLC triggers (int/float)
• 9.3. Mission triggers (coil 1001–2000)
• 9.4. Action commands (coil 1–6)

---

4. Ba cách chạy Mission (mục 4.1.1)

Cách	Mô tả
Dashboard	Widget Mission button — một mission cố định
Setup → Missions	Bấm icon queue → thêm vào mission queue
Tích hợp ngoài	Modbus trigger (coil), REST API (xem Help → API)

Mission queue: robot chạy tuần tự từ trên xuống; operator có thể sắp xếp lại.

Biến (variables): nếu mission có tham số biến (ví dụ position), operator chọn giá trị khi enqueue — hiển thị màu xanh trong queue.

---

5. Mission editor

• Mission = chuỗi actions (Move, Logic, Battery, I/O, Cart…).
• Action có thể dùng giá trị cố định hoặc biến (hỏi operator mỗi lần enqueue).
• Kéo thả ↕ để sắp xếp; thực thi từ trên xuống dưới.
• Có thể embed mission con (icon ◎) trong mission lớn.
• Save / Save as / đổi tên & nhóm qua ⚙.

4.1.4. Mission actions — các nhóm

Variables (4.1.4.1–2)

• Khai báo biến dùng chung trong mission.

Move (4.1.4.3)

Action	Mục đích
Adjust localization	Hiệu chỉnh vị trí trên map
Check position status	Kiểm tra position free/occupied (timeout)
Docking	Dock vào marker / trạm sạc
Move	Đi tới position (retries, distance threshold)
Move to entry position	Đi tới entry position trước khi dock/pick
Move to coordinate	X, Y, orientation tuyệt đối trên map
Planner settings	Desired speed, path deviation, path timeout
Relative Move	Dịch chuyển tương đối X/Y/yaw
Set footprint	Đổi footprint (top module, cart)
Switch Map	Chuyển map trong mission (cần overlap vật lý)

Battery (4.1.4.4)

• Charging — đi dock + sạc theo thời gian tối thiểu hoặc % pin; có thể giữ sạc đến khi có mission mới.

Logic (4.1.4.5)

Action	Mục đích
Break	Thoát vòng Loop
Continue	Bỏ phần còn lại của vòng loop, sang vòng tiếp theo
If	Điều kiện: pin %, pending missions, PLC register, I/O input → nhánh True/False
Loop	Lặp N lần hoặc endlessly (đến khi operator dừng); kéo action vào body loop
Pause	Dừng mission đến khi operator bấm Continue
Prompt User	Hỏi Yes/No/Timeout
Return	Abort mission (thường trong Try/Catch)
Wait	Chờ N giây
While	Lặp action khi điều kiện còn đúng

Error handling (4.1.4.6)

• Try/Catch — Try thất bại → chạy Catch (ví dụ Return).

Sound/Light, PLC, Email, I/O module, Cart, Shelf, UR

• Set/wait I/O, PLC register, pick/drop cart, shelf, tích hợp UR cobot, v.v.

---

6. Maps

• Site — nhóm nhiều map (tầng/khu vực); robot chuyển map qua Transition hoặc Switch Map action.
• Object types: Walls, Floors, Positions, Markers, Directional zones, Preferred/Unpreferred/Forbidden/Critical zones, Speed zones, Sound/light zones, Planner zones, I/O zones, Limit-robots (Fleet), Evacuation zones (Fleet).

---

7. Dashboard widgets

Widget MiR	RBS (Cách B)
Mission button	dashboard.js — mission_button
Mission group	mission_group
Mission queue	mission_queue
Pause/Continue	pause_continue (+ Hủy mission bổ sung trong RBS)

---

8. Modbus

Robot là Modbus TCP server. Bật tại System → Robot setup, cấu hình trigger tại System → Triggers.

Mission triggers (coil 1001–2000)

Rising edge coil → enqueue mission đã gắn mission_id.

Action commands (coil 1–6)

Coil	Chức năng
1	Continue robot
2	Pause robot
3	Cancel current mission
4	Clear mission queue
5	Clear error
6	Continue robot

Status registers (ví dụ)

Software version, mode, state, error code, battery %, uptime… (registers 4001+).

---

9. REST API

Tài liệu API đầy đủ: Help → API documentation → Launch trên giao diện robot.

Base URL: http://<robot_ip>/api/v2.0.0/

Endpoint	Mô tả
GET /status	Trạng thái robot
GET /missions	Danh sách mission
GET /mission_queue	Queue hiện tại
POST /mission_queue	Enqueue (mission_id)
DELETE /mission_queue	Xóa queue

Xác thực: HTTP Basic (user/password robot).

---

10. Mapping sang dự án RBS

Khái niệm MiR Reference Guide	RBS
Setup → Missions → queue	Cách A — www/missions.js
Dashboard widgets	Cách B — www/dashboard.js
Modbus triggers 1001–2000	Cách C — :5502, integrations.js
REST v2 mission_queue	POST /api/v2.0.0/mission_queue
MiR Fleet schedule	/api/fleet/schedules
Loop / Break / Continue	www/missions.js + mission_queue.cpp
Pause / Continue	/api/mission_queue/pause, /continue
Cancel (Modbus coil 3)	/api/mission_queue/cancel
Sign in / User groups	Đã triển khai — §2.1 (AuthService, UI MiR, data/auth.json)

---

11. Ghi chú

• Rev. 1.9 (2019) — firmware mới có thể khác; đối chiếu bản API trên robot thực tế.
• Phần cứng MiR250: xem docs/mir250_user_guide_11_en.pdf.
• Fleet (scheduler, robot groups): tài liệu riêng MiR Fleet Reference Guide.