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