add pudu robot control client; drop global.json SDK pin

2026-07-06 14:51:39 +02:00
parent b927f48260
commit f64d2c8f28
4 changed files with 285 additions and 6 deletions
--- a/EpsonPrintService/robot_control.md
+++ b/EpsonPrintService/robot_control.md
@@ -0,0 +1,138 @@
+# Robot Control — Send a Robot to a Table
+
+Step-by-step guide to authorize against the `PuduControl.DataSync.API` and dispatch a robot (by serial number) to a specific table (by table name).
+
+## Prerequisites
+
+- API running locally at `http://localhost:5022` (see `Properties/launchSettings.json`).
+- Credentials: `admin` / `admin`.
+- Robot serial number (`Sn`) and the exact table name configured as a destination point (`TargetPoint`) in the robot's shop.
+- A REST client (`curl`, Postman, HTTPie, etc.).
+
+All endpoints return a uniform envelope:
+
+```json
+{ "success": true, "data": { ... }, "errorMessage": null }
+```
+
+## Step 1 — Authorize (obtain a JWT)
+
+`POST /api/Auth/login`
+
+Request body:
+
+```json
+{ "username": "admin", "password": "admin" }
+```
+
+`curl` example:
+
+```bash
+curl -s -X POST http://localhost:5022/api/Auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"admin"}'
+```
+
+Sample response:
+
+```json
+{
+  "success": true,
+  "data": {
+    "message": "Login successful",
+    "username": "admin",
+    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "expiresIn": 86400
+  },
+  "errorMessage": null
+}
+```
+
+Copy `data.token` — every subsequent call must include it as:
+
+```
+Authorization: Bearer <token>
+```
+
+The token is valid for 24 hours.
+
+## Step 2 — Send the robot to a table
+
+`POST /api/Robots/add-command` (requires `Authorization` header)
+
+Request body:
+
+| Field         | Type   | Description                                      |
+|---------------|--------|--------------------------------------------------|
+| `Sn`          | string | Robot serial number                              |
+| `TargetPoint` | string | Table name (must exist in the robot's shop map)  |
+
+```json
+{ "Sn": "ROBOT_SERIAL_HERE", "TargetPoint": "TABLE_NAME_HERE" }
+```
+
+`curl` example:
+
+```bash
+TOKEN="eyJhbGciOi..."   # token from Step 1
+
+curl -s -X POST http://localhost:5022/api/Robots/add-command \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -d '{"Sn":"ROBOT_SERIAL_HERE","TargetPoint":"TABLE_NAME_HERE"}'
+```
+
+Success response:
+
+```json
+{
+  "success": true,
+  "data": { "message": "Command added successfully." },
+  "errorMessage": null
+}
+```
+
+The command is persisted and picked up by the `DataSyncHosted` background service, which forwards it to the robot through the Pudu API.
+
+## One-shot script
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+BASE_URL="http://localhost:5022"
+ROBOT_SN="$1"
+TABLE_NAME="$2"
+
+TOKEN=$(curl -s -X POST "$BASE_URL/api/Auth/login" \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"admin"}' \
+  | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')
+
+curl -s -X POST "$BASE_URL/api/Robots/add-command" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $TOKEN" \
+  -d "{\"Sn\":\"$ROBOT_SN\",\"TargetPoint\":\"$TABLE_NAME\"}"
+```
+
+Usage: `./send_robot.sh <ROBOT_SN> <TABLE_NAME>`
+
+## Troubleshooting
+
+- **401 Unauthorized** — token missing, expired, or malformed. Repeat Step 1.
+- **`You do not have permission to control this robot.`** — the logged-in user does not own the shop this robot belongs to. Assign the shop to the user via `POST /api/Robots/assign-shop` (admin only).
+- **Target point not reached / ignored** — verify `TargetPoint` matches a point name on the robot's map exactly (case-sensitive). Use `GET /api/Robots/shops/{shopId}` to list available points.
+- **Listing available robots** — `GET /api/Robots/shops/{shopId}/robots` returns robots (and their `Sn`) in a shop; `GET /api/Robots/shops` lists shops the user can access.
+
+## Helpful companion endpoints
+
+| Purpose                       | Method & Path                                     |
+|-------------------------------|---------------------------------------------------|
+| List accessible shops         | `GET  /api/Robots/shops`                          |
+| List robots in a shop         | `GET  /api/Robots/shops/{shopId}/robots`          |
+| Get shop layout / points      | `GET  /api/Robots/shops/{shopId}`                 |
+| Get robot status              | `GET  /api/Robots/shops/{shopId}/status`          |
+| List queued commands          | `POST /api/Robots/list-commands`                  |
+| Cancel a queued command       | `POST /api/Robots/delete-command`                 |
+
+All of the above require the `Authorization: Bearer <token>` header.