Tạo tài liệu

docs/Reference_guide.md

@@ -0,0 +1,352 @@
+# 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
+
+#### Luồng truy cập
+
+```
+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**.
+
+#### Thiết kế web tương tự MiR (gợi ý Test3)
+
+**UI trang Sign in**
+
+| Thành phần | Mô tả |
+|------------|--------|
+| Layout | Full-screen, logo, form giữa màn hình |
+| Tabs | `Username & password` \| `PIN code` |
+| Nút | **Sign in** (MiR dùng thuật ngữ này) |
+| Responsive | Input/nút lớn, dễ chạm trên tablet sàn |
+
+**Kiến trúc**
+
+```
+Sign-in (public) → POST /api/auth/login → session/JWT
+  → Shell app + route guard theo permissions
+  → API middleware (read/write từng module)
+```
+
+**API gợi ý**
+
+| Method | Endpoint | Mô tả |
+|--------|----------|--------|
+| POST | `/api/auth/login` | `{ username, password }` hoặc `{ pin }` |
+| POST | `/api/auth/logout` | Hủy session |
+| GET | `/api/auth/me` | User, group, permissions (ẩn menu) |
+| PUT | `/api/auth/password` | User tự đổi password |
+| CRUD | `/api/users`, `/api/user_groups` | Cần quyền admin |
+
+**Phân quyền UI sau login (ví dụ)**
+
+| Group | Truy cập |
+|-------|----------|
+| User / Operator | Dashboard (mission, queue, pause/cancel) |
+| Administrator | + Setup (Missions, Maps, Tích hợp, Cấu hình) |
+| Distributor | + Users / User groups |
+
+#### Test3 hiện tại
+
+| MiR §2.1 | Test3 |
+|----------|-------|
+| Sign in bắt buộc | Chưa có — mở thẳng UI |
+| User / User group | Chưa có |
+| PIN operator | Chưa có |
+| REST auth | API công khai (phù hợp dev) |
+
+### 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 | Test3 (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 Test3) |
+
+---
+
+## 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 Test3
+
+| Khái niệm MiR Reference Guide | Test3 |
+|------------------------------|--------|
+| 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 | **Chưa triển khai** (xem §2.1) |
+
+---
+
+## 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*.