153 lines
5.8 KiB
Markdown
Executable File
153 lines
5.8 KiB
Markdown
Executable File
# appRobotHoming
|
||
|
||
Browserbasierte Bedienoberfläche für das kameragestützte **Homing** und die
|
||
**Kalibrierung** eines Roboterarms. Das Frontend kommuniziert mit einem Node.js-Backend
|
||
(BFF-Proxy), das Kamera-Bilder, ArUco-Erkennung und Gelenk-Winkel-Schätzung
|
||
über Python-Skripte orchestriert.
|
||
|
||
## Architektur
|
||
|
||
```
|
||
Browser ──HTTPS──▶ Reverse-Proxy ──HTTPS──▶ appRobotHoming-Backend (Port 2093)
|
||
│ server/server.js
|
||
intern (HTTP): │
|
||
├──▶ WebCam-Service (Bilder, NPZ)
|
||
└──▶ Robot-Driver (POST /api/state)
|
||
```
|
||
|
||
**Frontend (`public/`):** statische Seiten — Homing, Kalibrierung, Board-Viewer,
|
||
Scene-Viewer. Kein direkter Zugriff auf interne Services.
|
||
|
||
**Backend (`server/server.js`):** HTTPS-BFF auf Port 2093. Liefert Frontend aus,
|
||
orchestriert Python-Skripte (SSE-Stream) und liest/schreibt `robot.json`.
|
||
|
||
## Funktionen
|
||
|
||
| Seite | Pfad | Beschreibung |
|
||
|-------|------|--------------|
|
||
| Homing | `/` (`index.html`) | Homing-Run starten, Status, GCode-Ausgabe |
|
||
| Kalibrierung | `/calibration.html` | Tabs: Camera NPZ · Board · X-Achse · Arm1-Y · **Marker** |
|
||
| Board-Viewer | `/boardViewer.html` | 3D-Viewer: Board-Marker, Skeleton FK, Arm-Marker mit Spin |
|
||
| Scene-Viewer | `/sceneViewer.html` | Standalone-Viewer (Datei-Upload, keine Server-Abhängigkeit) |
|
||
| Homing-Detail | `/homing.html` | Detail-Ansicht eines Homing-Laufs |
|
||
|
||
## Homing-Ablauf
|
||
|
||
```
|
||
Foto alle Kameras
|
||
→ 1_detect_aruco_observations.py (ArUco-Erkennung, pro Kamera)
|
||
→ 2_estimate_camera_from_observations.py (Kamera-Pose)
|
||
→ 3b_corner_marker_poses.py (Marker-Triangulierung)
|
||
→ X-Position schätzen (JS: server/homingXEstimate.cjs)
|
||
→ 4b_revolute_angle.py Arm1 / Ellbow / Arm2 / Hand (Gelenk-Winkel)
|
||
→ POST ROBOT_URL/api/state
|
||
```
|
||
|
||
SSE-Events (`log` / `step` / `analysis` / `done`) streamen den Fortschritt live
|
||
ins Frontend. Der Board-Viewer zeigt das Skeleton progressiv nach jedem erkannten Gelenk.
|
||
|
||
Details: [`doc/Homing_ROADMAP.md`](doc/Homing_ROADMAP.md)
|
||
|
||
## Kalibrierung
|
||
|
||
Einmaliger Vorgang nach mechanischen Änderungen:
|
||
|
||
| Schritt | Tab | Ergebnis |
|
||
|---------|-----|---------|
|
||
| 1 Camera NPZ | Camera NPZ | Kamera-Intrinsics als `.npz` |
|
||
| 2 Board | Board | `links.Board.markers` in `robot.json` |
|
||
| 3 X-Achse | Robot X Axis | alle Marker-Positionen rotiert |
|
||
| 4 Arm1-Y | Arm1 – Y | `links.Arm1.jointToParent.origin[1,2]` |
|
||
| 5 Arm-Marker | Marker | Spin-Korrektur, Orientierungs-Verifikation |
|
||
|
||
Details: [`doc/Kalibrierung.md`](doc/Kalibrierung.md) ·
|
||
[`doc/Kalibrierung_Marker.md`](doc/Kalibrierung_Marker.md) ·
|
||
[`doc/accessRobotAPI.md`](doc/accessRobotAPI.md) (robot.json via Driver)
|
||
|
||
## robot.json
|
||
|
||
Zentrale Konfiguration aller Gelenke, Marker und Kinematik-Parameter.
|
||
|
||
```
|
||
ROBOT_JSON = process.env.ROBOT_JSON || 'scripts/robot_1781069752019.json'
|
||
```
|
||
|
||
Enthält: `links.{Link}.markers[].{id, position, normal, size, spin}`,
|
||
`links.{Link}.jointToParent`, `defaultPosition`, `robot_test_poses`.
|
||
|
||
## API-Übersicht
|
||
|
||
| Endpoint | Methode | Zweck |
|
||
|----------|---------|-------|
|
||
| `/api/robot` | GET | robot.json lesen |
|
||
| `/api/robot/set-arm-marker-spin` | POST | Spin eines Arm-Markers setzen |
|
||
| `/api/robot/set-joint-origin` | POST | Joint-Origin Y/Z setzen |
|
||
| `/api/robot/assign-by-z` | POST | Marker nach Z-Bereich zuordnen |
|
||
| `/api/robot/adopt-x-axis` | POST | X-Achse übernehmen |
|
||
| `/api/board/run` | POST | Board-Pipeline starten (SSE) |
|
||
| `/api/board/latest` | GET | Letzter Board-Run (Marker + Robot) |
|
||
| `/api/homing/run` | POST | Homing-Lauf starten (SSE) |
|
||
| `/api/homing/send-state` | POST | State an Robot-Driver senden |
|
||
| `/api/homing/run-data` | GET | Debug-Daten eines Runs |
|
||
| `/api/calibration/*` | POST/GET | Kalibrierungs-Session verwalten |
|
||
|
||
## Konfiguration
|
||
|
||
| Variable | Bedeutung |
|
||
|----------|-----------|
|
||
| `HTTPS_PORT` | Port (Default `2093`) |
|
||
| `WEBCAM_URL` | Interner WebCam-Service |
|
||
| `ROBOT_URL` | Interner Robot-Driver |
|
||
| `ROBOT_JSON` | Pfad zu robot.json (Default `scripts/robot_1781069752019.json`) |
|
||
| `HTTPS_KEY_PATH` / `HTTPS_CERT_PATH` / `HTTPS_PASSPHRASE` | self-signed Cert |
|
||
|
||
## Dateien & Struktur
|
||
|
||
```
|
||
public/ Frontend (HTML, JS, CSS)
|
||
boardViewer.html 3D-Viewer mit Three.js FK, Arm-Markern, Spin-Rendering
|
||
sceneViewer.html Standalone-Viewer (nur Datei-Upload)
|
||
calibration*.html Kalibrierungs-Tabs (lazy-geladen)
|
||
client.js Homing-Frontend-Logik
|
||
calibration.js Kalibrierungs-Frontend-Logik
|
||
|
||
server/
|
||
server.js Express-Backend, alle API-Routes
|
||
editRobot.js robot.json lesen/schreiben
|
||
homingOrchestrator.js Homing-Ablauf (SSE-Stream)
|
||
homingXEstimate.cjs X-Schätzung (reine Geometrie, unit-getestet)
|
||
spinNormalize.cjs Spin-Normalisierung [0,360) (unit-getestet)
|
||
|
||
scripts/
|
||
robot_1781069752019.json Haupt-Konfiguration (robot.json)
|
||
1_detect_aruco_observations.py
|
||
2_estimate_camera_from_observations.py
|
||
3b_corner_marker_poses.py
|
||
4b_revolute_angle.py
|
||
|
||
test/
|
||
homingXEstimate.test.js X-Schätzungs-Geometrie (9 Tests, inkl. Regression)
|
||
spinNormalize.test.js Spin-Normalisierung (5 Tests)
|
||
yAxisComputeJs.test.js Y-Achsen-Berechnung
|
||
yAxisRotation.test.js Rotations-Mathe
|
||
|
||
doc/
|
||
Homing_ROADMAP.md Homing-Ablauf und Implementierungs-Status
|
||
Kalibrierung.md Kalibrierungs-Schritte 1–4
|
||
Kalibrierung_Marker.md Arm-Marker: Datenmodell, Spin-Verifikation, Roadmap P1–P5
|
||
ToDo.md Offene Punkte
|
||
```
|
||
|
||
## Nutzung
|
||
|
||
```bash
|
||
npm install
|
||
npm test # Jest-Tests (14+ Tests)
|
||
npm start # HTTPS-Backend auf Port 2093
|
||
```
|
||
|
||
Danach: `https://<host>:2093/`
|
||
|
||
> self-signed Zertifikat → einmalige Browser-Warnung bestätigen.
|
||
> Frontend benötigt laufendes Backend (API-Calls beim Laden).
|