Ceci est le manuel de Studio 1.0.2, une version antérieure. Le manuel de la dernière version

Documentation 1.0.2 / Référence

Formats de fichiers

_Brouillon (itération 14) : le texte est en cours de rédaction ; les sections peuvent encore s’allonger._

Programmes

Un programme est un fichier texte G-code dans le dialecte de Grbl 1.1, que parle le noyau propre à Twinwright. Studio lit n’importe quel fichier de ce genre. Les programmes que sa FAO écrit ressemblent à ceci :

(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

Les commentaires sont entre parenthèses. Les lignes ne sont pas numérotées.

Studio conserve chaque version d’un programme dans le dossier des programmes (Documents/Twinwright Studio/programs), dans un dossier portant le nom du programme :

Travaux et phases

Un travail est la description d’une pièce à partir de laquelle la FAO produit des programmes. C’est un objet JSON :

Une phase a ses propres features et indique comment la pièce y arrive depuis la phase précédente :

{"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}]}

Chaque version d’un travail est conservée à côté du programme qu’elle a produit, sous le nom job-v0001.json : sa version, l’heure (UTC), qui l’a créée (operator ou ai:<client>), une note, la version du programme qu’elle a produit et le travail lui-même. Un travail décrit en phases liste aussi, pour chaque phase, son programme, la version produite et son hachage.

Enregistrements (MCAP)

--mcap FILE enregistre une exécution dans un fichier MCAP (mcap.dev, format version 0) : un canal pour chaque type de données, des messages JSON, chaque canal avec son schéma JSON, sans découpage en blocs et sans compression, et un résumé à la fin avec les statistiques et un CRC. Les tests de Studio relisent les fichiers selon la spécification MCAP ; les outils qui lisent MCAP, comme PlotJuggler et Foxglove, sont censés les ouvrir, mais cela n’a pas encore été essayé.

• --rec-period MS règle la fréquence d’écriture des canaux échantillonnés (1 ms si l’option n’est pas donnée).
• Un enregistrement ne change rien à l’exécution : une exécution enregistrée et la même exécution non enregistrée sont identiques bit à bit.
• --play FILE.mcap relit un enregistrement dans Studio, avec une ligne de temps : lecture, pause, positionnement, de 0,25 à 10 fois la vitesse. Rien n’est simulé pendant la relecture.

Temps

L’horodatage d’enregistrement de chaque message est le temps virtuel du jumeau, en nanosecondes depuis la mise sous tension. La plupart des canaux portent aussi t, le même temps en secondes. Un canal échantillonné n’écrit un message que lorsque quelque chose y a changé.

L’en-tête

Un enregistrement de métadonnées nommé mc1sim décrit l’exécution :

Canaux

Traces de pins (VCD)

--vcd FILE écrit les pins du contrôleur dans un fichier VCD (IEEE 1364), que lisent GTKWave et PulseView : le scope mcu contient les pins du contrôleur, chaque changement au tick d’horloge où il se produit (les pins de pas sous forme d’impulsions de $0 microsecondes) ; le scope machine contient les lignes extérieures au contrôleur : les alimentations, KM1, le variateur de broche, la pompe, le bouton d’arrêt d’urgence, le capteur de longueur d’outil, les cinq capteurs. L’échelle de temps est de 1 ns.

Journaux de session

--record FILE écrit les entrées d’une session, chacune avec son temps virtuel : ce qu’ont envoyé les logiciels d’envoi, les commandes temps réel, les commandes des vues. --replay FILE rejoue la session, bit à bit, avec la même version de Studio et les mêmes fichiers machine. --replay FILE --branch S la rejoue jusqu’à S secondes, puis continue en direct à partir de là ; avec --record, la branche a un journal à elle, qui part de celui de son parent (# branch <parent> <ticks>). Un journal est un texte ; ses lignes sont propres à Studio et peuvent changer d’une version à l’autre.

L’archive du monde

Ce que le jumeau conserve entre deux sessions, comme le fait une machine réelle quand on l’éteint puis la rallume : la position des axes, le brut avec ses usinages, l’outil dans la broche, la mémoire du contrôleur et l’horloge de la carte, et la chaleur, qui retombe pendant que la machine est éteinte. Le contrôleur démarre à froid : la prise d’origine de la machine est à refaire.

La fenêtre conserve le monde de chaque machine dans le dossier d’état (sous Windows %LOCALAPPDATA%\Twinwright\Studio) : celui de la première machine dans world, celui des autres dans machines\<id>\world. --world DIR utilise un autre dossier ; --world-reset repart de l’état d’usine. Les exécutions par lots, les tests, les rejeux, les enregistrements relus et les machines d’arrière-plan de l’IA ne conservent aucun monde si --world n’est pas donné. Un seul processus à la fois ouvre un monde ; un deuxième repart de l’état d’usine et n’enregistre rien.

world.json :

Au démarrage suivant, les axes sont là où ils se trouvaient ; le même brut revient avec ses cellules, ainsi que l’outil et la table ; la chaleur a diminué pendant le temps où la machine était éteinte, chaque élément vers son repos selon sa propre constante de temps ; l’horloge de la carte a continué de tourner. --world-off S indique combien de temps la machine est restée éteinte (pour les tests ; sinon, le temps écoulé depuis l’enregistrement). --pos, --tool, --stock, --setup et --part donnés au démarrage l’emportent sur l’archive.

Fichiers de licence

Un fichier de licence (.twlic) est un objet JSON en UTF-8, signé avec Ed25519. Studio le vérifie sur l’ordinateur, sans le réseau. Où se trouvent les fichiers et comment ils sont utilisés : Licences, postes et activation.

Cet exemple provient des vecteurs de test partagés. Il est signé avec la clé de test (kid test), que les versions publiées n’acceptent pas :

{"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"}

Champs

Un champ que Studio ne connaît pas fait partie des octets signés, et Studio ignore ce qu’il signifie.

Les octets signés

La signature couvre le fichier sans sig, écrit sous une forme canonique :

• les clés dans l’ordre des points de code Unicode ;
• aucun espace blanc ;
• des chaînes avec les échappements les plus courts de JSON ;
• des entiers sans point décimal ; aucun autre nombre, et aucune clé en double.

Studio écrit le fichier sous cette forme avant de vérifier la signature. Les espaces, les sauts de ligne et l’ordre des clés dans le fichier n’ont donc pas d’importance. Une valeur modifiée fait échouer la vérification.

Le hachage de l’empreinte

Le hachage est formé des 32 premiers chiffres hexadécimaux du SHA-256 calculé sur les octets twinwright-fp-v1, un octet nul, et l’identifiant de l’ordinateur :

À défaut de l’un comme de l’autre, Studio crée un identifiant aléatoire et le conserve dans le dossier des licences (machine.id) ; le supprimer fait de l’ordinateur un autre ordinateur. L’identifiant lui-même ne quitte jamais l’ordinateur.

Par exemple, l’identifiant 8b1c3a0e-5f2d-4c7a-9e61-2d0f4b7a1c55 donne le hachage 0a2d31bb82176516415efa7b3a340562.

Le code de demande

Le code de demande pour l’activation hors ligne est le JSON canonique en UTF-8 {"fp": <the hash>, "version": <Studio's version>}, en base64url sans remplissage =. Par exemple, le hachage 0123456789abcdef0123456789abcdef et la version 1.0.0 donnent :

eyJmcCI6IjAxMjM0NTY3ODlhYmNkZWYwMTIzNDU2Nzg5YWJjZGVmIiwidmVyc2lvbiI6IjEuMC4wIn0

TwinwrightStudio.exe --licence-request affiche le code de demande de cet ordinateur.

Fichiers d’essai

Un essai est un fichier de licence comme les autres, signé par le serveur de licences de Twinwright : "kind": "trial", le hachage de cet ordinateur dans fp, et valid_until 30 jours après le début de l’essai. Il n’est jamais renouvelé. Un fichier d’essai modifié à la main n’est plus valable.

L’archive de la machine

Chaque clé de l’archive d’une machine, avec les valeurs de la MC-1 : Schéma du profil de machine.