139 lines
4.3 KiB
Markdown
139 lines
4.3 KiB
Markdown
# 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.
|