Serial Port Guide

Returns the firmware version string.

Development builds include the commit count and hash:

Returns the board’s unique hardware ID as a hex string.

Returns product, version, build type, the number of programs in the current author index, and the loaded program.

current_program is none when no program is loaded. LZX Connect reads product to tell Videomancer from other LZX devices.

Lists the available commands, pipe-delimited.

Reboots Videomancer into USB mass-storage (BOOTSEL) mode for a firmware update. The LCD shows Updating…​ Firmware. The CDC connection drops right after the reply — copy the new .uf2 file to the RPI-RP2 drive, and reconnect once Videomancer restarts. LZX Connect’s firmware update uses this command.

Firmware 1.0.1 and later. Lists the author folders found on the SD card.

Firmware 1.0.1 and later. Rebuilds the program index for one author, the same as choosing that author in the program picker. If that author is already indexed, the scan is skipped unless you add force.

Lists the programs in the current author index as paginated JSON.

To retrieve every program, page through until more is absent:

To list another author’s programs, run programs enumerate <author> first.

Loads a program by name. Matching is case-insensitive and accepts the display name (Roll Shutter), the display name with underscores for spaces (Roll_Shutter), or the file name without .vmprog (rollshut).

If the program is not in the current author index, Videomancer searches the other authors' folders, switches the picker to the author that has it, and loads it (firmware 1.0.1 and later). A name found nowhere returns file_not_found.

@program:ok means the load has started. It then runs the full workflow: video sync suspension, loading screen, FPGA bitstream load, factory preset application, and video output resume.

Returns the loaded program’s name, ID and parameter labels with their display ranges.

Returns service_unavailable when no program is loaded.

Returns the live modulator state for all 12 parameter channels: manual position (m), time (t), space (sp), slope (sl) and modulation source (sr).

Source numbers are the operator IDs in Modulation Operators.

Streams a .vmprog package into the FPGA without the SD card. <size> is the file size in bytes; [name] is shown on the LCD while the program runs (default Sideload).

Videomancer buffers the package header and metadata, then streams the bitstream for the current video configuration (the variant fpga preferred-variant reports) directly into the FPGA. If no bytes arrive for 5 seconds the stream is abandoned with an io_error.

A stream cannot be rewound, so Videomancer configures the FPGA once per transfer. If the FPGA does not configure, the load fails with code 738197512 (fpga_config_timeout) and the next program stream programs the FPGA at a lower SPI speed. Send the file again, up to two more times. LZX Connect does this for you.

A streamed program is not saved. It stops running if the video timing crosses between SD and HD, and Videomancer sends @program:invalidated:variant_mismatch.

The older SD-staged sideload, kept for scripts written against early firmware. It writes the bytes to sd:/tmp/sideload.vmprog and then loads that file through the normal program-load workflow. It needs an SD card and accepts files up to 512 KiB. The handshake is the same as program stream: @program:ready, the raw bytes, then @program:ok once the program has loaded. A 2-second gap in the data aborts the upload.

Returns the bitstream variant the current video routing and timing need.

Variants: sd_analog, sd_hdmi, sd_dual, sd_standalone, hd_analog, hd_hdmi, hd_dual, hd_standalone (generic means none is resolved).

Lists preset indices and names, plus free flash space.

Returns full preset data. Type is factory or user.

Factory presets carry manual positions (m) only. User presets also carry t (time), sp (space), sl (slope) and sr (source), in the same layout as program state.

Applies a preset by numeric index and type.

Applies a preset by name (case-insensitive). Factory presets are searched first, then user presets.

Saves a user preset at slot <index>. Without data, it captures the current state.

To save explicit values, append all five arrays in this order, 12 comma-separated values each:

Rules:

Deletes a user preset. Returns the updated preset list, in the same format as program presets list.

Renames a user preset. The same naming rules apply.

Returns one setting with its type.

Changes one setting. A value starting with a digit is stored as a number; anything else is stored as text. The change takes effect the same way as a front-panel edit — for example, changing a video setting reconfigures the video chain.

Resets every setting to its factory default.

Writes all settings to sd:/tmp/lzx-settings-export.json on the SD card and returns the file path and the number of settings. Read the file back with fs read. Requires an SD card.

The file holds a format version and one entry per setting: k is the key, t the value type (1 unsigned, 2 signed, 3 float, 4 boolean, 5 string), and v the value.

Imports settings from a JSON file on the SD card (the format settings export writes) and saves them. Copy the file to the card first with fs put.

LZX Connect’s Export Settings and Import Settings use these two commands with fs read and fs put.

Preferred Timing codes (key 8). The code is the FPGA’s 4-bit timing value, not a list position:

Returns the video chain’s state: the active source, resolved timing, input lock, and output state. Diagnostic register snapshots from the video encoder (enc) and HDMI transmitter (hdmi_tx), and the HDMI receiver’s raw timing measurement (hdmi_rx, firmware 1.0.2 and later), follow when available.

Switches the active video input.

Sets the video timing by name: NTSC, PAL, 480p, 576p, 720p60, 720p5994, 720p50, 1080i60, 1080i5994, 1080i50, 1080p30, 1080p2997, 1080p25, 1080p24, 1080p2398.

In Standalone routing this sets Preferred Timing (setting key 8), the same as the SYSTEM menu. In the input routing modes it is a temporary bench override of the timing taken from the input; it is not saved.

Returns one page of the video event trace — timestamped events from the video chain, for diagnosing lock and reload problems — and removes it from the trace. Repeat until left is 0.

Without a channel: the selected channel, the MIDI channel filter, and source (s), manual (m) and output (o) for each channel.

With a channel: every parameter of that channel.

Sets a channel’s modulation operator.

Sets a channel’s manual position and, optionally, its time, space and slope. Omitted values keep their current setting.

Resets every channel’s modulation.

Latches all physical controls, so each knob and switch must be moved to its stored value before it takes over again. Has no effect unless Soft Pickup is enabled (setting key 13).

Returns the MIDI CC assignment for each channel (null when unassigned).

Timing counters for the audio and per-line modulation paths. A diagnostic for LZX support.

Returns transport state and timing counters as JSON.

state is one of stopped, playing, or paused. bpm_x100 is BPM × 100 (e.g. 12000 = 120.0 BPM).

Sets the internal BPM. Valid range: 1000–40000 (10.0–400.0 BPM).

Starts transport playback (the same as a front-panel Play or MIDI Start).

Stops transport playback (the same as a front-panel Stop or MIDI Stop).

Switches the control mode to remote (register writes from the serial port are accepted) or back to local (front-panel controls and modulation only).

Modes: local, remote, hybrid, passthrough.

Writes one register. Refused with invalid_state while the mode is local.

Returns the FPGA service state and the loaded program.

state is one of uninitialized, idle, loading, configuring, running, or error.

Writes one register regardless of the control mode — a bench command. Ranges as above.

Without a code, returns the interface language. With a code, changes it.

Codes, in setting-key order 0–17: en_US, de_DE, fr_FR, es_ES, da_DK, sv_SE, fi_FI, it_IT, pt_BR, id_ID, nl_NL, nb_NO, tr_TR, ca_ES, pl_PL, hr_HR, ro_RO, cs_CZ.

Switches the LCD to an internal screen number (0–255). A bench command.

Developer Mode only. Returns the 32 character cells of the 2 × 16 LCD as byte values.

Developer Mode only. Simulates front-panel input, for automated testing.

Each answers @ui:ok.

Prints incoming MIDI messages as log lines. Clock and Active Sensing are filtered out.

Like on, but also prints MIDI Clock and Active Sensing.

Stops the monitor.

midi monitor on its own reports the current state.

Returns settings usage, the program index size, and an RP2040 heap snapshot.

Returns per-core CPU usage, one @cpu: line per core. A core without data reports {"available":false}.

Without an argument, returns the current log level. With one, sets how much diagnostic logging appears on the serial stream, and returns the new level.

Release firmware compiles most log lines out, so raising the level shows little there. Development builds print mount and stall messages between responses.

Unmounts the SD card and presents it to the computer as a drive. Needs a card in the slot; otherwise the LCD shows NO SD CARD.

Ejects the drive from the computer, remounts the card, and rescans the program library. Eject the drive on your computer first.

Returns SD card presence, mount status and capacity in bytes. fs on its own does the same.

Without a mounted card: {"mounted":false,"present":false}.

Returns the filesystem protocol version and limits, so a host tool can choose the fastest transfer method. LZX Connect calls this before a program library install.

Lists a directory. Defaults to sd:/.

A long listing is split into pages. The page then comes wrapped in an object; pass next as the offset to continue:

Returns a file’s or directory’s type and size.

Creates a directory, including any missing parent directories. An existing directory is not an error.

Removes a file or an empty directory.

Renames or moves a file or directory.

Reads up to 256 bytes from <offset>. The data is base64-encoded; read is the number of bytes returned, and 0 means the end of the file.

Writes base64-encoded data at <offset>. A write at offset 0 truncates the file first; an empty write at offset 0 creates an empty file. Because the whole command must fit in one 511-byte line, each write carries a few hundred bytes at most — use fs put for anything larger.

Writes a whole file as raw bytes — much faster than fs write, with no base64. Missing parent directories are created, and an existing file is replaced. Files can be up to 8 MiB.

A zero-byte file skips the handshake and answers {"put":"ok","written":0} at once.

If a write fails partway (firmware 1.0.1 and later), Videomancer deletes the partial file, discards the rest of the announced bytes so none are read as commands, and then sends a single ! io_error line. Wait for that line before retrying. If the data stops arriving for 120 seconds, the transfer is abandoned the same way.

Returns the BLAKE2b-256 hash of a file as 64 hex digits, with its size. A missing file is not an error.

Hashing a large file takes a few seconds; allow a 15-second timeout.

Firmware 1.0.1 and later. Erases the SD card and creates a new, empty filesystem. Without --apply the command only prints its usage. The card must be mounted.