Dokumentation / Referenz

Dateiformate

_Entwurf (Runde 14): Der Text wird noch geschrieben; die Abschnitte können noch wachsen._

Programme

Ein Programm ist eine G-Code-Textdatei im Dialekt von Grbl 1.1, den Twinwrights eigener Kernel spricht. Studio liest jede solche Datei. Die Programme, die das CAM von Studio schreibt, sehen so aus:

(Sensor bracket)
(tool T1 flat 6 n3 L20, 6061-T6: S13263, F836, plunge F279, depth of cut 1.20 mm, stepover 2.40 mm)
(program zero: on the blank's top; the machine's top first; T1 is the length reference)
G21 G90 G17 G94 G54
G53 G0 Z0
T1 M6
G53 G0 Z0
M3 S13263
G4 P3 (up to speed)
(face X-2..62 Y-2..42, 0.3 mm deep: 1 layer of 12 passes)
...
M5
M9
G53 G0 Z0
M30

Kommentare stehen in Klammern. Die Sätze haben keine Nummern.

Studio bewahrt jede Version eines Programms im Programmordner (Dokumente/Twinwright Studio/programs) auf, in einem Ordner mit dem Namen des Programms:

Aufträge und Aufspannungen

Ein Auftrag ist die Beschreibung eines Teils, aus der das CAM Programme erstellt. Er ist ein JSON-Objekt:

Eine Aufspannung hat eigene features und gibt an, wie das Teil aus der vorhergehenden Aufspannung zu ihr gelangt:

{"name": "bracket.nc", "title": "Sensor bracket", "material": "6061-T6",
 "tools": {"1": "flat 6 n3 L20", "2": "drill 3.4 118 n2 L20"},
 "features": [
  {"op": "face", "x0": -2, "y0": -2, "x1": 62, "y1": 42, "depth": 0.3, "tool": 1},
  {"op": "pocket", "shape": "rect", "x0": 6, "y0": 6, "x1": 28, "y1": 34, "r": 3, "depth": 4, "tool": 1},
  {"op": "pocket", "shape": "circle", "cx": 44, "cy": 20, "d": "Ø12 H7", "depth": 6, "tool": 1},
  {"op": "drill", "points": [[44, 6], [44, 34]], "depth": 8, "tool": 2}]}

Jede Version eines Auftrags wird neben dem Programm aufbewahrt, das sie erzeugt hat, als job-v0001.json: mit ihrer Version, der Zeit (UTC), wer sie erstellt hat (operator oder ai:<client>), einer Notiz, der Programmversion, die sie erzeugt hat, und dem Auftrag selbst. Ein Auftrag in Aufspannungen führt außerdem für jede Aufspannung das Programm, die erzeugte Version und deren Hash auf.

Aufzeichnungen (MCAP)

--mcap FILE zeichnet einen Lauf in eine MCAP-Datei auf (mcap.dev, Formatversion 0): ein Kanal für jede Art von Daten, JSON-Nachrichten, jeder Kanal mit seinem JSON-Schema, nicht in Chunks aufgeteilt und nicht komprimiert, und am Ende eine Zusammenfassung mit den Statistiken und einer CRC. Die Tests von Studio lesen die Dateien wieder ein und prüfen sie gegen die MCAP-Spezifikation; Anwendungen, die MCAP lesen, wie PlotJuggler und Foxglove, sollen sie öffnen können, aber das wurde noch nicht ausprobiert.

• --rec-period MS legt fest, wie oft die abgetasteten Kanäle geschrieben werden (1 ms, wenn nichts angegeben ist).
• Eine Aufzeichnung ändert nichts am Lauf: Ein aufgezeichneter Lauf und derselbe Lauf ohne Aufzeichnung sind Bit für Bit gleich.
• --play FILE.mcap spielt eine Aufzeichnung in Studio ab, mit einer Zeitleiste: Abspielen, Pausieren, Springen, 0,25- bis 10-fache Geschwindigkeit. Während des Abspielens wird nichts simuliert.

Zeit

Die Log-Zeit jeder Nachricht ist die virtuelle Zeit des Zwillings, in Nanosekunden ab dem Einschalten. Die meisten Kanäle tragen außerdem t, dieselbe Zeit in Sekunden. Ein abgetasteter Kanal schreibt nur dann eine Nachricht, wenn sich etwas darin geändert hat.

Der Dateikopf

Ein Metadatensatz mit dem Namen mc1sim sagt, was der Lauf war:

Kanäle

Pin-Verläufe (VCD)

--vcd FILE schreibt die Pins der Steuerung als VCD-Datei (IEEE 1364), die GTKWave und PulseView lesen: Der Scope mcu enthält die Pins der Steuerung, jede Änderung zu dem Taktschritt, in dem sie geschieht (die Schritt-Pins als Impulse von $0 Mikrosekunden); der Scope machine enthält die Leitungen außerhalb der Steuerung: die Versorgungen, KM1, den Spindelantrieb, die Pumpe, den Not-Halt-Taster, den Werkzeuglängensensor, die fünf Schalter. Die Zeitskala beträgt 1 ns.

Sitzungsprotokolle

--record FILE schreibt die Eingaben einer Sitzung, jede mit ihrer virtuellen Zeit: was die Sender-Programme gesendet haben, die Echtzeitbefehle, die Befehle der Ansichten. --replay FILE führt die Sitzung Bit für Bit noch einmal aus, mit derselben Version von Studio und denselben Maschinendateien. --replay FILE --branch S spielt sie bis S Sekunden ab und läuft von dort live weiter; mit --record hat der Zweig ein eigenes Protokoll, das vom übergeordneten Protokoll ausgeht (# branch <parent> <ticks>). Ein Protokoll ist Text; seine Zeilen sind Studios eigenes Format und können sich von Version zu Version ändern.

Das Weltarchiv

Was der Zwilling zwischen den Sitzungen behält, so wie es eine reale Maschine tut, wenn sie aus- und wieder eingeschaltet wird: wo die Achsen stehen, das Rohteil mit seinen Schnitten, das Werkzeug in der Spindel, der Speicher der Steuerung und die Uhr der Platine sowie die Wärme, die abkühlt, während die Maschine aus ist. Die Steuerung startet kalt: Die Maschine wird erneut referenziert.

Das Fenster bewahrt die Welt jeder Maschine im Zustandsordner auf (unter Windows %LOCALAPPDATA%\Twinwright\Studio): die der ersten Maschine in world, die der anderen in machines\<id>\world. --world DIR verwendet einen anderen Ordner; --world-reset beginnt mit dem Werkszustand. Stapelläufe, Tests, Wiederholungen, abgespielte Aufzeichnungen und die Hintergrundmaschinen der KI behalten keine Welt, es sei denn, --world ist angegeben. Eine Instanz zur Zeit öffnet eine Welt; eine zweite beginnt mit dem Werkszustand und speichert nichts.

world.json:

Beim nächsten Start stehen die Achsen dort, wo sie standen; dasselbe Rohteil kommt mit seinen Zellen zurück, ebenso das Werkzeug und die Tabelle; die Wärme hat sich so lange abgekühlt, wie die Maschine aus war, jedes Teil mit seiner eigenen Zeitkonstante seinem Ruhewert entgegen; die Uhr der Platine ist weitergelaufen. --world-off S gibt an, wie lange die Maschine aus war (für Tests; sonst die Zeit seit dem Speichern). Beim Start angegebene --pos, --tool, --stock, --setup und --part haben Vorrang vor dem Archiv.

Lizenzdateien

Eine Lizenzdatei (.twlic) ist ein JSON-Objekt in UTF-8, signiert mit Ed25519. Studio prüft sie auf dem Computer, ohne Netzwerk. Wo die Dateien liegen und wie sie verwendet werden: Lizenzen, Arbeitsplätze und Aktivierung.

Dieses Beispiel stammt aus den gemeinsamen Testvektoren. Es ist mit dem Testschlüssel signiert (kid test), den Release-Builds nicht akzeptieren:

{"v": 1, "kid": "test", "id": "TWL-TEST000001", "edition": "pro", "kind": "subscription", "seats": 1,
 "holder": "Weber Lab, TU Example", "issued": "2026-11-02T10:00:00Z", "valid_until": "2027-11-02T10:00:00Z",
 "renew_after": "2027-10-28T10:00:00Z", "updates_until": null, "fp": ["0123456789abcdef0123456789abcdef"],
 "mc1_serial": null,
 "sig": "h3FTqZnDYtq8Q7_0ZuELLeDrTfyZnkTPgvDWSywTyl7BCJJxGIyhrBQUjYHJiE1_WOWaFarqbveFiMLrEfUyCA"}

Felder

Ein Feld, das Studio nicht kennt, ist Teil der signierten Bytes, und Studio ignoriert seine Bedeutung.

Die signierten Bytes

Die Signatur deckt die Datei ohne sig ab, geschrieben in einer kanonischen Form:

• Schlüssel in der Reihenfolge der Unicode-Codepoints;
• kein Leerraum;
• Zeichenketten mit den kürzesten Escape-Folgen von JSON;
• Ganzzahlen ohne Dezimalpunkt; keine anderen Zahlen, und kein Schlüssel doppelt.

Studio schreibt die Datei in dieser Form, bevor es die Signatur prüft. Leerzeichen, Zeilenumbrüche und die Reihenfolge der Schlüssel in der Datei spielen deshalb keine Rolle. Ein geänderter Wert lässt die Prüfung fehlschlagen.

Der Hash des Fingerabdrucks

Der Hash besteht aus den ersten 32 Hexadezimalziffern von SHA-256 über die Bytes twinwright-fp-v1, ein Nullbyte und die ID des Computers:

Ohne beides erzeugt Studio eine zufällige ID und legt sie im Lizenzordner ab (machine.id); sie zu löschen macht den Computer zu einem anderen. Die ID selbst verlässt den Computer nie.

Zum Beispiel ergibt die ID 8b1c3a0e-5f2d-4c7a-9e61-2d0f4b7a1c55 den Hash 0a2d31bb82176516415efa7b3a340562.

Der Anforderungscode

Der Anforderungscode für die Offline-Aktivierung ist das kanonische UTF-8-JSON {"fp": <the hash>, "version": <Studio's version>} in base64url ohne =-Padding. Zum Beispiel ergeben der Hash 0123456789abcdef0123456789abcdef und die Version 1.0.0:

eyJmcCI6IjAxMjM0NTY3ODlhYmNkZWYwMTIzNDU2Nzg5YWJjZGVmIiwidmVyc2lvbiI6IjEuMC4wIn0

TwinwrightStudio.exe --licence-request gibt den Anforderungscode dieses Computers aus.

Testdateien

Eine Testphase ist eine Lizenzdatei wie die anderen, vom Lizenzserver von Twinwright signiert: "kind": "trial", der Hash dieses Computers in fp und valid_until 30 Tage nach Beginn der Testphase. Sie wird nie verlängert. Eine von Hand geänderte Testdatei gilt nicht mehr.

Das Maschinenarchiv

Jeder Schlüssel des Archivs einer Maschine, mit den Werten der MC-1: Schema des Maschinenprofils.