180 lines
7.7 KiB
Markdown
180 lines
7.7 KiB
Markdown
# Roadmap 12 — Austauschbare Kinematik
|
||
|
||
## Ziel
|
||
|
||
Der `appRobotDriver` soll als generischer G-Code-Treiber für beliebige Roboterarme
|
||
funktionieren. Die Kinematik ist der einzige arm-spezifische Teil — alles andere
|
||
(G-Code, WebSocket, Sender, Konfiguration) ist roboter-unabhängig.
|
||
|
||
## Konventionen (festgelegt)
|
||
|
||
- **Workspace-Koordinaten:** `x, y, z, phi, theta, psi` + `e` (Greifer) — gilt für alle
|
||
6-DOF-Arme mit Greifer. Das ist der implizite Vertrag dieses Frameworks.
|
||
- **Motoranzahl:** 7 Slots (`x, y, z, a, b, c, e` in `RobotMotorPosition`) bleiben fest.
|
||
Das Framework ist für 6-DOF + Greifer ausgelegt.
|
||
- **Ordner:** `robot/kinematics/` (nicht `inverseKinematics/` — enthält beide Richtungen)
|
||
- **Klassenname:** beschreibend für die physikalische Struktur, z. B. `Arm3SegmentLinearX`
|
||
|
||
---
|
||
|
||
## Dateistruktur (Zielzustand)
|
||
|
||
```
|
||
robot/
|
||
├── RobotBase.js ← Interface + generische Infrastruktur
|
||
├── KinematicsFactory.js ← lädt Kinematik-Klasse anhand Env-Variable
|
||
└── kinematics/
|
||
├── Arm3SegmentLinearX.js ← aktuelle Implementierung
|
||
└── <NextRobot>.js ← zukünftige Implementierungen
|
||
```
|
||
|
||
> **Update (umgesetzt):** Der ursprünglich geplante dauerhafte Kompatibilitäts-Alias
|
||
> `robot/Robot.js` wurde **nicht** beibehalten, sondern nach Abschluss von Phase 0–2
|
||
> **entfernt**. Tests importieren direkt `kinematics/Arm3SegmentLinearX` bzw.
|
||
> `RobotBase`; Produktivcode geht über `KinematicsFactory`. Die folgenden Abschnitte
|
||
> zur Transition über `Robot.js` sind daher historisch.
|
||
|
||
## Wo ist das Interface?
|
||
|
||
**`RobotBase` ist das Interface** — als abstrakte Basisklasse (JavaScript-Idiom).
|
||
Es definiert zwei Dinge:
|
||
1. Die **Infrastruktur**, die jede Implementierung erbt (State, `sendCommand`, ...)
|
||
2. Den **Vertrag**: zwei Methoden, die jede Implementierung überschreiben *muss*
|
||
|
||
`RobotBase` ist die einzige Klasse, die alle anderen Module (`GCode.js`, `InputWS.js`,
|
||
Sender, ...) kennen müssen. Sie importieren nie eine konkrete Kinematik.
|
||
|
||
## Wie greift der restliche Code auf den Roboter zu?
|
||
|
||
**Heute und während der Transition:**
|
||
```
|
||
startRobot.js → require('./robot/Robot') → Robot.js (Alias) → Arm3SegmentLinearX
|
||
GCode.js → bekommt robot als Parameter → sieht nur RobotBase-Methoden
|
||
InputWS.js → bekommt robot als Parameter → sieht nur RobotBase-Methoden
|
||
```
|
||
|
||
`GCode.js`, `InputWS.js` und alle Sender erhalten `robot` bereits als Parameter —
|
||
sie importieren `Robot.js` gar nicht. **Für sie ändert sich nichts.**
|
||
|
||
**Langfristig (nach Abschluss Phase 2):**
|
||
```
|
||
startRobot.js → KinematicsFactory → instantiiert Arm3SegmentLinearX (oder anderen)
|
||
robot/Robot.js → dauerhafter Alias für RobotBase (nicht mehr für eine Implementierung)
|
||
```
|
||
|
||
`robot/Robot.js` bleibt erhalten, zeigt aber auf `RobotBase`:
|
||
```js
|
||
// robot/Robot.js — dauerhaft
|
||
module.exports = require('./RobotBase');
|
||
```
|
||
|
||
Damit kann externer Code weiterhin `require('./robot/Robot')` schreiben und bekommt
|
||
die Basisklasse — z. B. für `instanceof`-Checks oder zum Ableiten in Tests.
|
||
|
||
---
|
||
|
||
## Phase 0 — `RobotBase` und Interface-Vertrag
|
||
|
||
`Robot.js` enthält heute zwei Dinge: generische Infrastruktur und arm-spezifische Kinematik.
|
||
Der Schnitt:
|
||
|
||
**`RobotBase` (generisch, nie überschreiben):**
|
||
- Zustandsvariablen: `x, y, z, phi, theta, psi, e, feedrate, moveRelative`
|
||
- Motor-Zustand: `xMotor, alpha, beta, a, b, c, eMotor` + Changed-Flags
|
||
- `sendCommand()`, `createMotorPosition()`, `calculateSpeeds()`
|
||
- `cmdReceivers`, `savedPoints`
|
||
|
||
**Interface-Vertrag (abstrakt, muss überschrieben werden):**
|
||
```js
|
||
calculateAngles3D() // Workspace → Motorwinkel (schreibt auf this.*)
|
||
calculatePositionFromMotorAngles() // Motorwinkel → Workspace (schreibt auf this.*)
|
||
```
|
||
|
||
- [x] `robot/RobotBase.js` anlegen — generische Infrastruktur aus `Robot.js`
|
||
- [x] Beide Kinematik-Methoden in `RobotBase` als Stub mit `throw new Error('not implemented')`
|
||
- [x] JSDoc: Interface-Vertrag dokumentieren
|
||
- [x] `rotateAroundAxis()` wandert in `RobotBase` als geschützte Hilfsmethode
|
||
|
||
---
|
||
|
||
## Phase 1 — `Arm3SegmentLinearX` als erste Implementierung
|
||
|
||
```
|
||
robot/
|
||
├── RobotBase.js
|
||
└── kinematics/
|
||
└── Arm3SegmentLinearX.js ← bisheriger Robot.js-Kinematik-Teil
|
||
```
|
||
|
||
- [x] `robot/kinematics/Arm3SegmentLinearX.js` anlegen
|
||
- `class Arm3SegmentLinearX extends RobotBase`
|
||
- Konstruktor: `constructor(l1, l2, l3)` → `super()` + Längen
|
||
- `calculateAngles3D()` — unverändert übernommen
|
||
- `calculatePositionFromMotorAngles()` — unverändert übernommen
|
||
- [x] `robot/Robot.js` wurde zunächst Kompatibilitäts-Alias und anschließend
|
||
**entfernt** (siehe Update-Hinweis oben). Tests importieren direkt
|
||
`./kinematics/Arm3SegmentLinearX`.
|
||
- [x] Alle bestehenden Tests müssen grün bleiben — kein Verhalten ändert sich
|
||
(`Robot.Kinematics.RoundTrip.test.js` ist das primäre Sicherheitsnetz)
|
||
|
||
---
|
||
|
||
## Phase 2 — Konfiguration über Umgebungsvariable
|
||
|
||
```yaml
|
||
# docker-compose.yml
|
||
environment:
|
||
ROBOT_KINEMATICS: arm3segmentlinearx
|
||
ROBOT_KINEMATICS_PARAMS: '{"l1": 250, "l2": 264, "l3": 100}'
|
||
```
|
||
|
||
- [x] `ROBOT_KINEMATICS` — Bezeichner der Kinematik-Klasse (Default: `arm3segmentlinearx`)
|
||
- [x] `ROBOT_KINEMATICS_PARAMS` — JSON mit Konstruktor-Parametern
|
||
- [x] `KinematicsFactory.js` (`createRobotFromEnv`), eingebunden in `startRobot.js`:
|
||
```js
|
||
const robot = createRobotFromEnv(processEnv, { l1: 250, l2: 264, l3: 100 });
|
||
```
|
||
- [x] Unbekannte Kinematik → klare Fehlermeldung beim Start, kein silent fail
|
||
- [ ] Neue Variablen ins zentrale Config-Modul aufnehmen (koordinieren mit `ToDo_3_Config`)
|
||
→ **offen:** `ToDo_3_Config` ist noch nicht umgesetzt. Die Factory liest `process.env`
|
||
vorerst direkt (gleicher Stil wie `ROBOT_DEFAULT_FEEDRATE`); das zentrale Config-Modul
|
||
kann die beiden Variablen später übernehmen. In `docker-compose.yaml` bereits dokumentiert.
|
||
|
||
---
|
||
|
||
## Phase 3 — Zweite Kinematik-Implementierung
|
||
|
||
Erst wenn ein konkreter zweiter Roboter definiert ist.
|
||
|
||
**Umgesetzt: Joy-IT „Grab-It" (Robot02)** als `Arm3SegmentRotaryBase`.
|
||
|
||
- [x] Physikalische Spezifikation dokumentieren (DOF, Achsen, Gelenkreihenfolge)
|
||
→ im JSDoc von `robot/kinematics/Arm3SegmentRotaryBase.js`. 5 Achsen + Greifer:
|
||
Basis-Yaw, Schulter, Ellbogen, Handgelenk-Pitch, Handgelenk-Roll, Greifer.
|
||
- [x] `robot/kinematics/Arm3SegmentRotaryBase.js` anlegen — nur die zwei Kinematik-Methoden
|
||
- [x] RoundTrip-Tests für die neue Implementierung schreiben
|
||
(`test/Robot.GrabIt.RoundTrip.test.js`)
|
||
- [x] Prüfen ob die 7 Motor-Slots ausreichen → **ja**: 6 Slots belegt
|
||
(`xMotor, alpha, beta, a, b, eMotor`), `c` bleibt frei. `RobotMotorPosition`
|
||
unverändert.
|
||
- [x] In `KinematicsFactory` registriert (Bezeichner `arm3segmentrotarybase`,
|
||
Aliase `grabit` / `robot02`). Factory reicht jetzt das vollständige
|
||
`params`-Objekt als 4. Konstruktor-Argument durch (für `baseHeight`).
|
||
|
||
**Offene Punkte / Annahmen (kein Blocker, aber vor Echtbetrieb zu klären):**
|
||
- ⚠️ **5-DOF-Constraint:** `phi` (Hand-Azimut) ist an die Position gekoppelt
|
||
(= Basis-Drehung) und nicht frei. In der Inversen aus `atan2(y,x)` abgeleitet.
|
||
- ⚠️ **Segmentlängen sind Schätzwerte** (l1=105, l2=98, l3=100, baseHeight=110 mm),
|
||
abgeleitet aus Reichweite (300 mm) / Höhe (420 mm). Vor Echtbetrieb am Arm
|
||
messen und per `ROBOT_KINEMATICS_PARAMS` setzen.
|
||
- ⚠️ **Gelenkmodell** (Pitch/Roll am Handgelenk) folgt der Standardkonfiguration
|
||
dieser Arm-Klasse; gegen das physische Gerät / die Kalibrieranleitung prüfen.
|
||
|
||
---
|
||
|
||
## Abhängigkeiten
|
||
|
||
- Phase 1 ist unabhängig von allen anderen ToDos — kann sofort angegangen werden
|
||
- Phase 2 koordiniert mit `ToDo_3_Config`
|
||
- Phase 3 hat keine zeitliche Vorgabe — wird bei Bedarf aufgenommen
|