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](#RBS--signing-in-đã-triển-khai).

#### 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**

```bash
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

```bash
./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*.