Entscheidungen

Status: Architekturentscheidungen (ADRs) für Strido. Entscheidungsdatum 2026-10-31, sofern nicht anders angegeben.

ADR-001 — Yertle-Mechanik beibehalten, modularen Sensorkopf ergänzen

Kontext. Mini Pupper 4 ist ein Vorserienprodukt ohne veröffentlichtes CAD, Stückliste oder PCB-Design. Optionen. (A) Einen Mini-Pupper-4-Klon anhand von Fotos nachmodellieren. (B) Einen neuen Roboter entwerfen. (C) Die veröffentlichten, real gebauten Yertle-Beine und den Rahmen beibehalten und Sensorkopf, Elektronik und Software ergänzen. Entscheidung. C. Konsequenzen. Die Mechanik erbt eine reale Baugeschichte; jede Änderung ist eine CAD-Boolesche Operation auf den Upstream-STEP/STL-Dateien, verifiziert durch den Harness. Nur neu bewerten, wenn: MangDang das CAD des Mini Pupper 4 unter einer offenen Lizenz veröffentlicht.

ADR-002 — CAD als Code, Verifikation als Prüfungen

Kontext. Menschen drucken und montieren allein anhand dieses Repositorys; eine falsche Bohrung kostet einen Neudruck. Entscheidung. Alle neuen und geänderten Teile sind CadQuery/manifold-Boolesche Operationen in strido_cad; jede Prüfung (Durchdringung, Bewegungsbereich, Passungen, Freigang, Sensoren, Elektronik, Stücklisten-Abdeckung) ist eine ausführbare Prüfung mit nachverfolgtem Bericht. Toleranzbänder und Kontaktregeln liegen samt Begründung in hardware/verification/*.yaml. Konsequenzen. Physikalische Aussagen sind reproduzierbar; eine Prüfung darf nur durch eine festgehaltene Entscheidung gelockert werden. Nur neu bewerten, wenn: ein parametrisches CAD-System mit gleichwertiger Skriptfähigkeit CadQuery ersetzt.

ADR-003 — uv-Workspace mit geschichteten Paketen

Kontext. Die Roboter-Laufzeit muss schlank bleiben (Pi, ROS-2-Image), während die Werkzeuge CadQuery, MuJoCo, PyTorch und WeasyPrint benötigen. Optionen. (A) Ein Paket mit Extras. (B) Ein uv-Workspace: core, cad, verify, publish, sim, ntx, workspace. Entscheidung. B, mit import-linter-Verträgen (core importiert nichts; publish → verify → cad → core; sim und ntx importieren nie CAD). Konsequenzen. pip install packages/strido-core --no-deps ist alles, was der Roboter braucht. Nur neu bewerten, wenn: die Anzahl der Pakete ohne Nutzen bei den Abhängigkeiten zur Wartungslast wird.

ADR-004 — Upstream-Mängel als abgeleitete Teile beheben, nicht durch Bearbeiten der Upstream-Dateien

Kontext. Die Verifikation fand Upstream-Probleme: den vorderen Servohalterungen fehlt die Vorbohrung für den Hüftdrehpunkt auf der Seite, die die Vorderbeine nutzen; das Servohorn-Muster des Femurs am rechten Bein ist gegenüber dem STEP um 30° verdreht; die Ausrichtung des Verbinders um 22°. Entscheidung. upstream/yertle/ bleibt byte-identisch; Korrekturen werden als Daten (hardware/assembly/corrections.yaml) und abgeleitete Teile (left_servo_mount_fl, right_servo_mount_fr im Druckpaket) ausgedrückt. Konsequenzen. Das Druckpaket enthält zwei zusätzliche Teiletypen; Upstream-Aktualisierungen lassen sich sauber vergleichen. Nur neu bewerten, wenn: Upstream korrigierte Dateien veröffentlicht.

ADR-005 — Gelenkgrenzen berücksichtigen das gespiegelte Partnerbein und Freigang im Betrieb

Kontext. Grenzen pro Bein erlaubten, dass sich beide Vorderfüße unter dem Körper treffen, wenn beide Hüften nach innen schwenken. Entscheidung. Der Hüft-Sweep setzt den Achspartner auf den gespiegelten Winkel und verlangt ≥ 0,3 mm Freigang sowie keine Überlappung. Konsequenzen. Engere innere Hüftgrenzen (≈ −17,5°); Firmware, Gait, Simulation und NT-X teilen sie über Codegenerierung. Nur neu bewerten, wenn: ein Controller die Beine koordiniert, um Kontakt zwischen den Beinen zu vermeiden.

ADR-006 — Gelernter Controller ohne Rückmeldung

Kontext. Die Hobby-Servos SPT5435LV melden weder Position noch Drehmoment. Entscheidung. Die Policy beobachtet nur IMU, Kommando, vorherige Action und einen Gait-Takt; Anstiegsbegrenzung und Begrenzungen der Firmware werden im Training modelliert; die numpy-Laufzeit wird von Simulation und Roboter gemeinsam genutzt. Konsequenzen. Seitliches und rückwärtiges Folgen sind schwach; der Transfer hängt vom gemessenen Servoverhalten ab. Nur neu bewerten, wenn: Servos mit Rückmeldung (z. B. serielle Bus-Servos) die SPT5435LV ersetzen.

ADR-007 — NT-X-Integration über eine Erweiterung, nicht durch Änderungen am Kern

Kontext. NT-X leitet Hardware nur an Unitree SDK2 weiter. Entscheidung. Katalog-Assets und einen Registry-robot-Adapter in strido-ntx ausliefern; die eine Kernänderung dokumentieren, die NT-X braucht; das NT-X-Repository nie von hier aus bearbeiten. Konsequenzen. Simulation, Studio und Training funktionieren schon heute; Live-Hardware-Sitzungen warten auf die NT-X-Änderung. Nur neu bewerten, wenn: NT-X eine registry-basierte Hardware-Weiterleitung übernimmt (dann die Zieldatei ergänzen).

ADR-008 — VitePress-Seite und WeasyPrint-Buch

Kontext. Bauende brauchen einen durchsuchbaren Katalog, ein 3D-Modell und ein druckbares A4-Buch. Entscheidung. VitePress (wie in den anderen Workspace-Projekten) mit einer three.js-Ansicht eines aus dem CAD exportierten GLB; das Buch ist HTML + CSS, gerendert mit WeasyPrint, sodass Befestigungselemente in echten Millimetern gezeichnet werden können. Konsequenzen. Node 26 für die Seite; Pango für das PDF. Nur neu bewerten, wenn: die Seite ohne Build-Schritt ausgeliefert werden muss.

ADR-009 — Die M3-Vorbohrungen der Upstream-Servohalterungen akzeptieren, mit einer Slicer-Maßnahme

Kontext. Die Passungsprüfung bewertet eine gedruckte M3-Vorbohrung über 0,93 d (gedruckte Größe, CAD − 0,15 mm) als „kein Halt“. 29 Schrauben der Upstream-Servohalterungsfamilie (left_servo_mount, right_servo_mount, deren abgeleitete Varianten _fl/_fr) und servo_mount_top_bracket greifen in CAD-Vorbohrungen von 2,94–2,97 mm (0,93–0,94 d gedruckt) mit 4–12 mm Einschraubtiefe. Upstream-Yertle-Roboter werden mit genau diesen Bohrungen gedruckt und montiert; die meisten FDM-Drucker drucken kleine Bohrungen 0,2–0,3 mm zu klein, wodurch sie im Band mit schwachem Halt landen. Eine Neukonstruktion der vier Halterungsteile würde die Upstream-Geometrie für eine druckerabhängige Reserve ändern. Entscheidung. Das Band bleibt bei 0,93 d, und diese Teile werden in accepted_deviations von hardware/verification/tolerances.yaml mit einer Maßnahme für Bauende aufgeführt: Drucken Sie sie mit einer X-Y-Lochkompensation von −0,15 mm (Vorbohrung ≈ 2,65 mm) oder härten Sie bei einem unkompensierten Druck die Vorbohrung mit einem Tropfen dünnflüssigem CA-Kleber, bevor Sie die Schraube eindrehen, und prüfen Sie, dass sie greift, bevor das Gelenk belastet wird (anaerobe Schraubensicherung härtet auf Kunststoff nicht aus und kann bei PETG Spannungsrisse verursachen; Datenblatt Loctite 243). Der Passungsbericht zeigt sie als Warnungen mit dieser Maßnahme; jedes andere Teil über dem Band schlägt weiterhin fehl. Konsequenzen. Die Prüfung bleibt für neue Teile und jede weitere Aufweitung rot; die Liste der akzeptierten Abweichungen ist explizit und überprüfbar. Nur neu bewerten, wenn: eine gedruckte Halterung ein Gewinde ausreißt (dann Varianten mit Ø2,5-mm-Neuvorbohrung wie in ADR-004 ergänzen).

ADR-010 — Knicken der langen Koppel: eine bekannte Schwachstelle, nur akzeptiert, bis die lange Koppel von Strido sie ersetzt

Kontext. Die Festigkeitsprüfung (strido_verify.strength) fährt das Kniekoppelgetriebe durch jede Pose innerhalb der Gelenkgrenzen, mit dem Knieservo am Blockiermoment (3,43 N·m). Die Upstream-long_link ist ein Stab, 5 mm breit in der Beinebene und 8 mm quer dazu, 130 mm zwischen den Bolzen. In der Beinebene sind ihre Enden gelenkig gelagert (K = 1) und ihre Wände ergeben I ≈ 75 mm⁴, daher beträgt ihre Euler-Knicklast π² · 1500 · 75 / 130² ≈ 65 N. Die ungünstigste Pose belastet sie mit 192 N, also S ≈ 0,34. In der Referenzpose sind es 127 N (S ≈ 0,51); im Stand (0,70 N·m am Knie, MuJoCo) etwa 29 N (S ≈ 2,2). Quer zur Beinebene ist sie ausreichend (S ≈ 1,8 mit K = 0,7). Jede andere Prüfung besteht mit S ≥ 1,5. Upstream-Yertle-Roboter betreiben diese Koppel mit Servos derselben Drehmomentklasse, beim normalen Laufen hält sie also. Ein Knieservo, der am Blockiermoment gegen einen blockierten Fuß oder in einer extremen Pose drückt, biegt sie in der Beinebene seitlich aus. Entscheidung. Als bekannte Schwachstelle behandeln, nicht als akzeptable Reserve. Sie ist unter accepted in hardware/strength.yaml mit min_safety: 0.3 aufgeführt, sodass die Prüfung eine Warnung mit der Maßnahme für Bauende meldet (das Knie nie gegen einen blockierten Fuß oder einen harten Anschlag steuern; nach harten Landungen die langen Koppeln auf Verbiegung prüfen und eine verbogene ersetzen) und erneut fehlschlägt, wenn sich die Reserve verschlechtert. Konsequenzen. Eine lange Koppel von Strido mit einem etwa 9 mm breiten Schaft in der Beinebene (I ≈ 330 mm⁴ nur mit Wänden, S ≥ 1,5 in der ungünstigsten Pose) ist die geplante Lösung (TODO.md). Dafür müssen die Prüfungen für Freigang, Bewegungsbereich, Druckbarkeit und Festigkeit erneut laufen. Sobald sie existiert, wird der accepted-Eintrag entfernt.

Gelöst (2026-11-01). Die steife Strido-Koppel (strido_cad.long_link, Druckteil stiff_long_link) ersetzt die Upstream-Koppel an allen vier Beinen: gleiche Bolzen (131 mm Abstand), Buchsenaugen und Augendicke, ein Schaft von 10 × 10 mm statt 5 × 8 mm. Mittig auf der Bolzenlinie kam sie dem Femur bei gestrecktem Knie bis auf 0,25 mm nahe, und der Bewegungsbereich-Sweep schränkte den Kniebereich um 5° ein; ihre Mittellinie liegt daher 2 mm neben der Bolzenlinie, vom Femur weg, und jeder Nachbar behält mindestens 1 mm (die Gelenkgrenzen sind unverändert). Die Festigkeitsprüfung ergibt jetzt S = 2,53 für das Knicken, und keine Prüfung braucht mehr eine Ausnahme (accepted: {} in hardware/strength.yaml). Sie wird flach ohne Stützen gedruckt. Die Hinweise für Bauende oben sind nicht mehr nötig; eine verbogene Upstream-Koppel ersetzt man weiterhin durch die steife.

ADR-011 — Kabelbaum im CAD verlegt und geprüft

Kontext. Bis v0.2.11 existierte die Verkabelung nur als Liste mit geschätzten Längen; nichts modellierte ein Kabel. Die Verlegung durch die Baugruppe deckte Mängel auf, die die Liste nicht zeigen konnte: Der 25-A-Sicherungshalter auf der Deckleiste ließ 4 mm, damit seine 14-AWG-Leitung in Richtung des vorderen Hüftservos austreten kann; Dupont-Gehäuse passten weder auf die IMU-Stiftleiste (2,5 mm unter dem Pi) noch auf die XIAO-Pins (9 mm unter dem oberen Schulterrahmen); der LiDAR-USB-Adapter verdeckte den Kabelschlitz der Oberschale; die Drähte vom XIAO zum PCA9685 brauchen ~0,3 m, nicht 0,1 m; ein STEMMA-QT-Kabel fehlte; der 18-AWG-Vorrat war zu knapp; und ein 60-mm-Abgriff in 18 AWG hing allein hinter der 25-A-Sicherung. Optionen. (A) Die Liste behalten und die Mängel von Hand beheben. (B) Jedes Kabel modellieren: Ankerpunkte an den Steckverbindern, Kabelbinder-Knoten, ein Router durch den freien Raum (Teile plus alles, was die Beine überstreichen) und eine Prüfung. Entscheidung. B: hardware/wiring.yaml ist die einzige Quelle; strido_cad.wiring verlegt, strido_cad.wiring_geometry fügt Kabel, Schläuche, Kabelbinder und Kabelbinder-Sockel zur Baugruppe hinzu (Renderings, 3D-Ansicht, Anleitung, Modellmassen); strido_verify.wiring prüft Reichweite, Vorrat, Durchhang der Hüftschlaufen, Anschlüsse und Freigang in jeder Betriebspose. Servokabel laufen ohne Verlängerungen, auf Länge gekürzt (Signal neu gecrimpt). Die Hauptsicherung wandert in den hinteren Hohlraum (ihre Leitungen treten durch die Rahmenöffnungen aus), die Logiksicherung in die Rückschale mit der eigenen 14-AWG-Leitung des Halters als Abgriff, der Akkueingang in die Tasche neben dem Akku. Konsequenzen. W01 (Akkueingang zur Hauptsicherung, ≈ 0,15 m) ist ungesichert, wie die eigene Leitung des Akkupacks; sie verläuft im Spiralschlauch abseits beweglicher Teile. Bauende schneiden jeden Draht nach der generierten Zuschnittliste zu. Biegeradien und die Form einer hängenden Schlaufe werden nicht modelliert (Routenecken sind scharf; Schlaufen werden über die Länge geprüft). Jede CAD-Änderung verlegt und prüft den Kabelbaum neu. Nur neu bewerten, wenn: ein kompakter abgesicherter Akkueingang (Sicherung wenige Zentimeter vom XT60 entfernt) unter das Deck passt oder Kabelmasse/-steifigkeit an einem realen Aufbau so stark abweichen, dass es für die Schlaufen relevant ist.

ADR-012 — Deutsche Seite aus Übersetzungskatalogen; Assistenzdienst über Cortex Keyring

Kontext. Die Seite brauchte Deutsch, einen KI-Assistenten, der aus der Dokumentation antwortet (mit Bildern, Verlauf und anheftbarem Panel), und einen Weg, auf dem Sprachmodelle und Coding-Agenten dasselbe Wissen nutzen. Rund ein Drittel der 110 000 Wörter ist generiert (Montageanleitung, Stückliste, Verifikationsberichte) und ändert sich mit jedem make-Lauf; die Seite ist statisches nginx hinter Cortex SSO. Optionen. Deutsch: (A) eine übersetzte Kopie jeder Markdown-Datei; (B) deutsche Texte in jedem Python-Generator; (C) ein Katalog pro Seite, der jedes englische Segment (Absatz, Listenpunkt, Tabellenzeile, Überschrift, Diagramm) seiner Übersetzung zuordnet und beim Build gerendert wird. Assistent: (D) ein Modellaufruf aus dem Browser; (E) ein Dienst neben der Seite, der Unterhaltungen hält, die Seiten durchsucht und das Modell über Cortex Keyring aufruft. Entscheidung. (C) und (E). Ein geändertes englisches Segment fällt auf Englisch zurück (die Seite meldet, dass sie teilweise übersetzt ist), und make drift schlägt fehl, bis es übersetzt ist; Zahlen in einem übersetzten Segment werden übernommen, sodass neu generierte Berichte ihr Deutsch behalten; deutsche Überschriften behalten die englischen IDs, sodass jeder Anker in beiden Sprachen funktioniert. Der Assistent (assistant/, Node, keine Abhängigkeiten) speichert Unterhaltungen und Anhänge pro angemeldetem Nutzer in SQLite, antwortet mit Werkzeugen über dieselben Seiten (search_docs, read_page, list_pages, search_parts) und stellt sie Agenten mit einem Cortex-App-Token als MCP-Server bereit; /llms.txt und das Agent-Skill-Paket erzeugt der Doku-Sync. Die App bringt ihre eigene Gateway-Route mit: /api/* und /mcp gehen ohne Kompression (Server-Sent Events) an den Assistenten, alles andere an nginx. Folgen. Englische Änderungen brauchen einen Übersetzungsdurchgang (make i18n); die Kataloge sind versionierte Quellen. Der Keyring-subscriber ist der Betreiber, daher bekommt bis zu einem gemeinsamen Pool-Schlüssel nur das Konto des Betreibers Antworten (andere sehen den Grund). Das Gateway-Secret erreicht den Assistenten über die vom Gateway erzeugte Env-Datei (der Sign/Folio-Vertrag), die diesem Container auch die übrigen erzeugten Werte des Stacks zeigt; nur diesen Schlüssel in die .env des Hosts zu kopieren (der Canvas-Vertrag) ist der sicherere nächste Schritt (TODO). Das Support-Widget ist aus: Sein Proxy säße im Antwortstrom. Antworten sind generiert: Leiste und docs/ai.md weisen darauf hin, Zahlen auf der verlinkten Seite zu prüfen.