Documentation / Reference

File formats

_Draft (round 14): the text is being written; the sections may still grow._

Programs

A program is a G-code text file in the dialect of Grbl 1.1, which the Twinwright controller speaks. Studio reads any such file. The programs its CAM writes look like this:

(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

Comments are in parentheses. Lines have no numbers.

Studio keeps each version of a program in the programs folder (Documents/Twinwright Studio/programs), in a folder of the program's name:

Jobs and setups

A job is the description of a part that the CAM makes programs from. It is a JSON object:

A setup has its own features, and says how the part comes to it from the setup before:

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

Each version of a job is kept beside the program it made, as job-v0001.json: its version, the time (UTC), who made it (operator or ai:<client>), a note, the program version it made, and the job itself. A job in setups also lists each setup's program, the version made and its hash.

Recordings (MCAP)

--mcap FILE records a run into an MCAP file (mcap.dev, format version 0): a channel for each kind of data, JSON messages, each channel with its JSON schema, not chunked and not compressed, and a summary at the end with the statistics and a CRC. Studio's tests read the files back against the MCAP specification; tools that read MCAP, such as PlotJuggler and Foxglove, are meant to open them, but that has not been tried yet.

• --rec-period MS sets how often the sampled channels are written (1 ms unless given).
• A recording changes nothing in the run: a run recorded and the same run not recorded are the same bit for bit.
• --play FILE.mcap plays a recording back in Studio, with a timeline: play, pause, seek, 0.25–10 times the speed. Nothing is simulated while it plays.

Time

Each message's log time is the twin's virtual time, in nanoseconds from power-on. Most channels also carry t, the same time in seconds. A sampled channel writes a message only when something in it changed.

The header

A metadata record named mc1sim says what the run was:

Channels

Pin traces (VCD)

--vcd FILE writes the controller's pins as a VCD file (IEEE 1364), which GTKWave and PulseView read: the scope mcu has the controller's pins, each change at the clock tick it happens (the step pins as pulses of $0 microseconds); the scope machine has the lines outside the controller: the supplies, KM1, the spindle drive, the pump, the E-stop button, the tool setter, the five switches. The timescale is 1 ns.

Session logs

--record FILE writes a session's inputs, each with its virtual time: what the senders sent, the real-time commands, the views' commands. --replay FILE runs the session again, bit for bit, with the same version of Studio and the same machine files. --replay FILE --branch S replays it to S seconds and goes on live from there; with --record the branch has a log of its own, which starts from its parent's (# branch <parent> <ticks>). A log is text; its lines are Studio's own and may change from version to version.

The world archive

What the twin keeps between sessions, as a real machine does when it is switched off and on again: where the axes stand, the blank with its cuts, the tool in the spindle, the controller's memory and the board's clock, and the heat, which cools down while the machine is off. The controller starts cold: the machine is homed again.

The window keeps each machine's world in the state folder (on Windows %LOCALAPPDATA%\Twinwright\Studio): the first machine's in world, the others' in machines\<id>\world. --world DIR uses another folder; --world-reset starts from the factory state. Batch runs, tests, replays, recordings played back and the AI's background machines keep no world unless given --world. One program at a time opens a world; a second one starts from the factory state and saves nothing.

world.json:

At the next start the axes are where they stood; the same blank comes back with its cells, and the tool and the table; the heat has cooled for the time the machine was off, each part towards its rest by its own time constant; the board clock has run on. --world-off S says how long the machine was off (for tests; otherwise the time since it was saved). --pos, --tool, --stock, --setup and --part given at the start win over the archive.

Licence files

A licence file (.twlic) is a JSON object in UTF-8, signed with Ed25519. Studio checks it on the computer, without the network. Where the files live and how they are used: Licences, seats and activation.

This example is from the shared test vectors. It is signed with the test key (kid test), which release builds do not accept:

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

Fields

A field Studio does not know is part of the signed bytes, and Studio ignores what it means.

The signed bytes

The signature covers the file without sig, written in a canonical form:

• keys in Unicode code point order;
• no whitespace;
• strings with JSON's shortest escapes;
• integers without a decimal point; no other numbers, and no key twice.

Studio writes the file in this form before it checks the signature. Spaces, line breaks and the order of keys in the file therefore do not matter. A changed value makes the check fail.

The fingerprint's hash

The hash is the first 32 hexadecimal digits of SHA-256 over the bytes twinwright-fp-v1, a zero byte, and the computer's ID:

Without either, Studio makes a random ID and keeps it in the licence folder (machine.id); deleting it makes the computer a different one. The ID itself never leaves the computer.

For example, the ID 8b1c3a0e-5f2d-4c7a-9e61-2d0f4b7a1c55 gives the hash 0a2d31bb82176516415efa7b3a340562.

The request code

The request code for offline activation is the canonical UTF-8 JSON {"fp": <the hash>, "version": <Studio's version>}, in base64url without = padding. For example, the hash 0123456789abcdef0123456789abcdef and version 1.0.0 give:

eyJmcCI6IjAxMjM0NTY3ODlhYmNkZWYwMTIzNDU2Nzg5YWJjZGVmIiwidmVyc2lvbiI6IjEuMC4wIn0

TwinwrightStudio.exe --licence-request prints this computer's request code.

Trial files

A trial is a licence file like the others, signed by Twinwright's licence server: "kind": "trial", this computer's hash in fp, and valid_until 30 days after the trial began. It is never renewed. A trial file changed by hand no longer holds.

The machine archive

Every key of a machine's archive, with the MC-1's values: Machine profile schema.