| option | what it does |
|---|
--machine FILE | machine archive (default: built in, or twin/machine/mc1.machine.json) |
--max-time S | stop after S seconds of virtual time (default 3600 in batch, none in real time) |
--fg-quantum US | longest foreground wait between resumes (default 50) |
--link KIND | the sender's line: usb_cdc (the Teensy's native USB), uart (through a USB-serial adapter) or telnet (Ethernet); default the board's (machine archive controller.board) |
--baud N | a UART at N baud (implies --link uart) |
--link-param K=V | change a number of the link, e.g. adapter_timer_ms=1 or host_in_latency_us=0; host_dtr=0: the twin itself does not hold DTR (the native USB answers only once a host raises it), connect_dtr=0: a TCP sender does not raise it either |
--fg-cost off\|L,P,S | the foreground's CPU time in us: a line parsed, a block planned, a step segment prepared (default the board's; off: none) |
--pos X,Y,Z | power-on position, machine mm (default from the archive) |
--sw-delay US | limit sensors' response time (default from the archive) |
--tool-offset MM | tool tip below the reference tool (default 0) |
--drive L0\|L1\|L2\|L3 feed drives: L0 ideal steps, L1 closed-loop steppers moving rigid axes, | L2 rotor, screw and table apart (coupling, torsion, Hertzian nut, play, ringing), L3 the motors' two phases and the drives' current loops on rigid axes |
--l3-dyno [V] | the L3 motor on a dynamometer: torque against speed, as JSON (V: another supply) |
--lobes SPEC | a side-milling cut's stability lobes by three methods (zero-order, linear time domain, semi-discretisation), JSON: "tool=flat 6 n3 L20;mat=6061-T6;ae=1;ap=1;dir=x; rpm=6000:24000:500;m=100;methods=zoa,td,sdm" |
--chatter-sim SPEC | the cut in time, nonlinear (each tooth out of the cut where its chip is gone): the vibration and whether it chatters, JSON: "...;ap=2;rpm=15000;fz=0.02;t=0.5" (default: the machine archive's drives.model) |
--geom on\|off | the G- and T-layer: geometric errors, lead error, backlash, thermal offsets (machine archive "accuracy"; default off) |
--fidelity batch\|live | what feeds back into the simulation (docs/06 section 8.3): batch - the full resolution, as tests and the AI's practice machines have it; live - what a virtual machine at 1x keeps up with (the cut's path merged to an eighth of a cell). Default live with the window, --ws or --tcp and no --lockstep, else batch; a replay or a branch takes its recording's |
--threads N | threads for the cut's sweep (the results are the same with any number): 1 this one alone; default the processors less one, at most 8 (or TWINWRIGHT_THREADS) |
--chatter-async on\|off | the chatter check on a thread of its own, below the simulation's: its answers taken in the order the cuts came - the same as at once, later (the summary waits for them; the views show the tool's last one meanwhile). Default on where the machine keeps the wall clock's pace (the window, --ws, --tcp; not --lockstep) |
--chatter-cache FILE\|off | the chatter check's time-domain depths kept in FILE - the same results, the second run faster. Default: the state folder's chatter-depths.bin for the window and the MCP's practice machines; off elsewhere (TWINWRIGHT_CHATTER_CACHE too) |
--set PATH=VALUE | change a machine archive entry as it is read, e.g. drives.motor.detent_nm=0.01 or drives.alm.wired=false (repeatable) |
--mpg N | the handwheel UART as if the firmware were built with MPG_ENABLE N (2: the handwheel's own 0x8B takes control; 0: none) - default as the archive's firmware options say (a replay: as its log says) |
--mpg-port PORT | an external handwheel on the handwheel UART's cable, over TCP (with --mpg 2): its bytes reach the controller at the handwheel's baud rate (logged), the controller's come back |
--panel SPEC | how the operator's buttons are wired: cycle_start=pin\|sender\|mpg, feed_hold=... (pin: the board's input, Pn: and its debounce; sender: '~' '!' from the sender; mpg: on the handwheel's stream) - default as the archive's controller.panel, else the sender's (a replay: as its log says) |
--fault WIRE=MODE | wiring fault from power-on: x_min x_max ... z_switch setter alm estop estop_km1 rs485 (the VFD's bus) vfd_relay (its fault relay in the ALM chain) = open\|short\|intermittent (wire names follow the machine archive) |
--seed N | sensors with their scatter (repeatability, response jitter) drawn from seed N; without: nominal sensors. Intermittent wires use it too |
--nvs FILE | load EEPROM image; --save-nvs FILE writes it at exit. Batch runs start blank; real-time and replay runs from the MC-1 settings image (built in, or build/mc1.nvs made by make) unless --nvs FILE or --nvs blank |
--world DIR | the persistent world (docs/06 8.5): the machine as the last session left it - where the axes stood, the workpiece clamped and cut, the tool, the EEPROM (written through to DIR/eeprom.bin), the temperatures and the board's clock moved on by the time it was off, the odometers; saved there at the end. The window keeps one in its state folder; batch runs and replays only with this |
--world-reset | start the world from the factory state (its files removed first) |
--world-off S | as if the machine had been off S seconds (else the wall clock's time since) |
--predict FILE | with --shadow: the program the operator streams; each run of it the real machine starts is predicted by a background twin set up like the machine (homed, the workpiece, tool and offsets), flat out - its own run time against the machine's |
--nvs-through FILE | the controller's EEPROM kept in FILE, as the board's flash keeps it: loaded from FILE if it exists (else from the image above, and FILE made), every write landing in FILE at once - settings, offsets and tools carry over to the next session. Not in replays (a recording has its start image beside it: LOG.nvs) |
--params-trace FILE the machine archive's values the run used (JSON): where each sits, its | provenance (source, uncertainty), what it feeds, whether --set changed it |
--steps FILE | write every step pulse (tick step_bits dir_pins) |
--spindle-trace FILE | each millisecond the spindle turns: seconds, its angle (revolutions) and where the steps put the axes (machine mm) - a thread's pitch and phase (src/spenc.h) |
--hil-log FILE | write what crosses between the controller and the machine as the HIL emulator's frames (src/hil.h): step groups, enables, coolant, RS-485, the machine's answers |
--hil-replay FILE | the machine driven by such a log, the controller off (HIL's follower) |
--wav FILE | the run's sound as the machine makes it (src/sound.h): 48 kHz stereo, 32-bit float; the same run gives the same file |
--sound-player FILE,FACTOR | the window's player of the sound at speed FACTOR, without a device: the live frames played in this thread into a WAV (tests: the pitch at any factor) |
--sound-analyse FILE[,DBFS_AT_94[,T0,T1]] | a WAV measured as a sound level meter reads it: LZeq, LAeq, 1/3-octave bands, the strongest lines (JSON; default -20: 94 dB SPL is -20 dBFS rms) |
--sound-listener X,Y,Z | where --wav and --sound-player listen: model mm at the GLB pose (the machine archive's "sound"), facing the tool; default the archive's operator in front |
--sound-room off\|small\|workshop | the room --wav and --sound-player hear it in (RT60 0.35 s, 0.7 s; default off: the dry sound) |
--events FILE | write inputs, output lines and markers with ticks |
--echo | print controller output with virtual time |
--factor F | real-time factor (default 1) |
--www DIR | serve the UI from DIR (default: built in, or micro_cnc/) |
--bind local\|any | listen on localhost only (the default) or on every interface (in shadow mode the sender port passes to the real machine: any lets the network move it; a twin in WSL reached from Windows needs any) |
--open | open the web UI in the default browser |
--gui | the native window (Windows; the default when started without arguments) |
--lang TAG | the language (en, zh-CN, a pack's tag; default: the settings, else the system's; qps-ploc: the pseudo-language that shows untranslated texts and tight layouts) |
--lang-dir DIR | one more folder with language packs (.po); see twin/lang/README.md |
--units U | metric \| imperial \| a units.json system; --region auto\|lang\|de-DE; --currency EUR |
--lang-list | the languages found; --lang-check FILE.po checks a pack; --lang-template FILE.pot writes the texts to translate |
--warp | draw the 3D view in software (WARP) even with a graphics card |
--selftest DIR | window self-test: off-screen, homes and runs the demo program at --factor 5, pictures and selftest.json into DIR, exit status 1 on failure |
--selftest-setup DIR | the same for setting up workpieces (panel, dragging, keys, clamps, vise) |
--record FILE | log real-time input for --replay |
--mcap FILE | record signals, events, serial lines and UI frames (PlotJuggler, Foxglove) |
--vcd FILE | record the controller's pins and the machine's lines (GTKWave, PulseView) |
--rec-period MS | sampling period of the recordings (default 1) |
--stock x0,x1,y0,y1,ztop,zbot[,res] | a block held as if bolted down (machine mm; cells default 0.02 mm) |
--setup JSON\|@FILE | the workpiece set up as on the machine: shape, size, material, fixture (clamps, vise, vblock, tape, none, fixed), position; e.g. '{"shape":"block","size":[60,40,20], "material":"6061-T6","fixture":"vise","at":[100,75]}' (see twin/core/README) |
--tool 'flat 6 n2' | the cutter: flat\|ball\|bull\|v\|drill D [Rc\|angle] [nN] (default from the archive) |
--part FILE.stl[@X,Y,Z] | the part the program should make, its origin at X,Y,Z machine mm (default 0,0,0) |
--stock-stl FILE[,RES[,FRAME]] | write the workpiece as a binary STL at the end (cells RES, default 0.1; FRAME machine (default), program: the program's zero, blank: its own corner) |
--stock-png FILE[,RES] | write its height map, or the deviation from --part, as a PNG |
--branch S | with --replay and a real-time option: replay the log to S seconds, then carry on live |
--mtconnect PORT | MTConnect adapter (SHDR) for an agent on PORT (7878 is usual) |
--lockstep PORT | a script drives the twin over localhost PORT (twin/py/mc1twin): virtual time moves only when it says, as fast as the host allows (api.h has the requests); 0: any free port, printed on standard output as lockstep-port N |
--api-token T | the lockstep client's first request must be hello with token T |
--exit-with-client | the session ends when its lockstep client goes (or none came within 30 s) |
--control PORT | the control port (AI access, as the window's AI switch opens it): the lockstep API's requests from several local clients while time runs as usual; 0 any port |
--control-file F | write its port and token to F as JSON (the MCP server reads it) |
--workdir DIR | programs' versions here (default Documents/Twinwright Studio/programs; TWINWRIGHT_WORKDIR) |
--control-token T | its token (default: a random one) |
--control-confirm yes\|no\|ask | how its confirmations are answered (default yes: no window to ask) |
--own-call JSON | {"tool":..., "args":{...}}: a tool called from the window's own interface (its own channel, the AI switch off or on), printed as "own-call N {...}" (tests; up to 12) |
--mcp | the MCP server for AI clients on standard input and output (they start it; see twin/docs/05 section 9): background twins, and the window when its AI switch is on |
--mcp-http PORT | the same over Streamable HTTP at http://127.0.0.1:PORT/mcp |
--ai | (Windows) the window with its AI switch on (it remembers the switch anyway) |
--mtconnect-devices FILE | write the matching MTConnect device model (Devices.xml; - for stdout) |
--fmi-model-description FILE | write the FMI 2.0 modelDescription.xml of the lockstep API's FMI-shaped interface (fmi_* requests; twin/py/mc1twin/fmi.py; - for stdout) |
--shadow HOST[:PORT]\|COMn\|/dev/ttyACM0 | shadow mode: the sender port relays to the real machine's controller (Telnet, port 23, or its USB serial port); the twin runs the same lines alongside and compares answers, path, settings and run times (use --factor 1, the default) |
--shadow-guard | with --shadow: each line of the sender's is looked at before it reaches the machine; a predicted crash holds it back and feed-holds the machine (the views release it) |
--version | the program's version and the kind of build (public, internal; a public build with the test key says so) |
--licence-status [DIR] [--json] \| --licence-request [DIR] \| --licence-import FILE [DIR] \| --licence-canon FILE \| --licence-keys | the licence files (docs/14): their state; this computer's request code for offline activation; a licence file into the folder (DIR: the machine's licence folder unless given); a file's signed bytes; the keys this build takes |
--licence-activate CODE [DIR] [--json] \| --licence-trial maker\|pro [DIR] [--json] \| --licence-renew [DIR] [--json] \| --licence-renew-due [DIR] \| --licence-code CODE \| --licence-server | online (product/23, product/30): activate this computer with an activation code; ask the licence server for this computer's 30-day trial of an edition; renew the licence that is due, now; whether the window's start would renew (a day since the last try); a typed code in its canonical form; the server this build talks to (the last two send nothing) |