• Cheat Sheet

Cheat Sheet

This page is the command entry point for every project in the repository: the common workflows first (multi-step, meant to be pasted and run in order), then the individual commands per project, followed by the firmware sections, the impact of each kind of change, where to start on a failure symptom, and what the checks do not cover.

Only commands and constraints are recorded here. Why things are this way, and the measured numbers, are in the pages linked at the end.

Contents

• Conventions: argument forwarding, caching, and the boundary of the task list
• Common workflows: 12 multi-step sequences, each with prerequisites, commands, and a success marker
• Command reference: server, server-ui, server-ui-e2e, app, iot, docs
• Release and maintenance
• Firmware: Boards and ports, Build-time variables, Logging, Before flashing, Handy commands
• Impact of a change
• Symptoms and where to start
• What the checks do not cover
• Full details

Conventions

• Run every command from the repository root; moon run <project>:<task> also works from any subdirectory.
• Pass arguments to a task after --: moon run <project>:<task> -- <arguments>. They are appended to the end of the task's command, not inserted anywhere inside it.
• A task that hits the cache is not executed; moon run --force <project>:<task> re-runs it.
• The complete task list is whatever moon query tasks --project <project> reports. This page omits tasks that exist only as dependencies of another task; moon runs those on its own.

Common workflows

1. Start the server for the first time

Prerequisite: a fresh clone has no application.toml, and data/ holds no model assets. Run these three in order.

moon run server-ui:build
moon run server:downloader-install
moon run server:run

Success: the terminal prints listening on 0.0.0.0:3000, and http://127.0.0.1:3000/login accepts the default account root / Change_Me.

• server-ui:build installs dependencies through ensure-deps; no manual pnpm install is required.
• Without model assets the server stops during TTS initialisation with Matcha acoustic model file (.onnx) not found in ….
• Both application.toml and application-dev.toml are gitignored, and a missing file is skipped silently by figment: the server starts on defaults without asking and without reporting anything.

2. Develop the frontend and backend together

# Terminal A
moon run server:dev
# Terminal B
moon run server-ui:dev

Success: terminal A prints listening on 0.0.0.0:3000; terminal B prints http://localhost:4200 and the page loads data.

• The frontend uses no Vite proxy; its API address comes from VITE_BASE_URL=http://localhost:3000 in apps/server-ui/.env.development. With the backend down the page stays blank — there is no cross-origin error to read.
• server-ui:dev does not depend on ensure-deps, so pnpm i is required once.
• server:dev reads application-dev.toml; a missing file means defaults.

3. Start without model assets

moon run server:dev-minimal

VAD and ASR are set to void, TTS to mute, and the LLM to local_echo, so no model asset is needed; the voice path is unavailable while the rest of the API and the pages work as usual. The success marker is the same as in workflow 1.

moon run server:dev-lite keeps VAD, ASR, and TTS and only swaps the LLM for local_echo; it still needs model assets.

4. Change only the frontend and verify the embedded build

moon run server-ui:build
moon run server:run

Success: http://127.0.0.1:3000/ shows the new interface.

apps/server/web/dist is a symbolic link to apps/server-ui/dist/, and the backend embeds the build product on disk; running server-ui:dev alone does not change the page served on port 3000.

5. End-to-end test

moon run server-ui-e2e:e2e

Prerequisite: nothing has to be started by hand. The task depends on server-ui:build and install-playwright, and Playwright runs vite preview on port 4300 itself.

Success: the cases pass and the HTML report is written to apps/server-ui-e2e/playwright-report.

• To target another address, set BASE_URL: BASE_URL=http://127.0.0.1:3000 moon run server-ui-e2e:e2e.
• If something already listens on 4300, Playwright reuses it (reuseExistingServer, disabled under CI).

6. Check the firmware after a change

moon run iot:check-s3
moon run iot:check-c6
moon run iot:check-host

None of the three replaces another: S3 goes through the Xtensa toolchain, C6 through riscv32imac, and check-host covers the host-smoke binary. The third may be skipped when only host-side code changed.

7. Flash the product image

espflash list-ports -n
IOT_PORT=<port> moon run iot:flash-s3

Success: the monitor shows [IOT] log level INFO (IOT_LOG_LEVEL) first, then [IOT] boot complete.

• IOT_PORT is mandatory when both boards are plugged in; otherwise espflash picks a port itself and may write the C6.
• The task's script passes --monitor, so it keeps the terminal after flashing.

8. Run a single-peripheral probe

IOT_PORT=<port> moon run iot:flash-probe-audio-s3

Each probe image enables one peripheral only, so a fault belongs to a single path. flash-probe-* already builds; there is no need to run the matching probe-* first, which only builds and serves the no-flash case.

• The full set of subjects: aec, audio, camera, clock, demand, echo, multicore, wifi-s3, wifi-c6.
• Probe flash tasks pass no partition table, so the device receives espflash's default table; reflash the product image to restore product behaviour.

9. Without hardware

moon run iot:smoke-host
moon run iot:emu-smoke

smoke-host runs host-smoke on the host and hits the cache, so a replay needs --force; emu-smoke boots the merged C6 image through esp-emu and asserts [IOT] boot complete, and is not cached — it rebuilds and boots on every run.

10. Before committing

lefthook run pre-commit --force
moon run server:test
moon run docs:check-translation

pre-commit carries formatting and static analysis only: cargo fmt --check, cargo clippy (once for the server, three times for the firmware), dart format, and flutter analyze. It runs no tests and checks no translation, so the last two commands are separate obligations.

• With no changed files the hooks skip themselves; --force runs them anyway.
• server:test depends on test-download-resources (cache: false), which installs any missing model assets for real.

11. Match CI

moon ci --base=origin/dev
moon run docs:check-translation

CI's ci job runs moon ci (affected tasks only) and its docs-check job runs docs:check-translation on its own. Both must pass to equal CI.

12. CUDA

moon cannot forward --features to server:run: that task's command already contains --, so an appended argument reaches the binary's own command line. Call cargo directly:

cd apps/server && cargo run -p vanling-server --features cuda -- \
  -O 'address=0.0.0.0' -O 'data_dir=../../data' --config=application.toml

Command reference

server

apps/server, listening on 3000. dev reads application-dev.toml, run reads application.toml; both are gitignored and both fail silently when missing.

server-ui

apps/server-ui, dev server on 4200, preview on 4300.

server-ui-e2e

app

apps/app, the Flutter client. Build tasks take their version from scripts/version.sh.

iot

apps/iot. check-s3 and build-s3 are dispatched by scripts/iot-xtensa.sh: a complete espup toolchain is used directly, otherwise the image built by iot:xtensa-image is used.

docs

docs, the Zola site.

Release and maintenance

Rare tasks, run on demand.

Firmware

Boards and ports

Two boards sit on the bench permanently and are not interchangeable. The port name changes on every replug; it is not an identifier.

espflash list-ports -n                                # List attached ports, names only
espflash board-info --port <port>                      # Chip type / flash size / MAC address
IOT_PORT=<port> moon run iot:flash-s3                  # Mandatory when both boards are plugged in

Build-time variables

The following are read at build time; a change requires a rebuild.

IOT_PORT is not one of these: it only tells espflash which port to use and never enters the firmware.

IOT_DEMAND is parsed per term and leniently: a term it does not recognise costs only that term, and the build still succeeds; when the whole string names no plane at all, the firmware prints [IOT] IOT_DEMAND named no plane this firmware recognises: ignored. An IOT_BOOT_PAGE that is not a page name falls back to ambient and prints [IOT] IOT_BOOT_PAGE=… is not a page, booting on Ambient.

Logging

The product defaults to info: the boot inventory, each state transition, and each user action are one line, and a steady state may print nothing for a long time — a quiet port is normal, not a hang. Periodic telemetry (frame cost and stack peak, feed cadence, link phase and address, scan lists) is all debug:

IOT_LOG_LEVEL=debug IOT_PORT=<port> moon run iot:flash-s3

The [DISPLAY] stack peak …, [PLAY] … feeds …, and [WIFI] … address … lines a record quotes appear per window in a debug image only; rebuild with the line above to reproduce one. warn is reserved for a bound actually crossed (a single executor hold over 30 ms, a frame write over 20 ms or 25% duty, a late feed or under 95% of the nominal rate), so any warn line is worth reading. The first line, [IOT] log level …, is the level this image really carries; check it first when a log seems to be missing.

Before flashing

• A failed build leaves the previous binary in place, and its timestamp proves nothing. Add a log line, then run strings <elf> | grep <literal>; only a match shows the artifact is new.
• iot:flash runs --monitor in its script and keeps the terminal after flashing. Without a tty it ends with Failed to initialize input reader; the image is already written.
• S3 builds go through Docker; a docker.sock/_ping 500 means the daemon is down, not a compile error.
• moon does not re-run a cached task; moon run --force <task> re-runs it.

Handy commands

# Live log: read the port directly, not through the flash stub
timeout 5 cat <port>

# Full boot log: monitor needs a pty, and CTRL+R (0x12) only counts once it has connected.
# The full recipe is in flashing.md.
({ sleep 6; printf '\x12'; sleep 10; } | script -q -t 1 /tmp/boot.log \
  espflash monitor --chip esp32s3 --port <port> -a no-reset) >/dev/null 2>&1

# Forget the saved network without reflashing; espflash does not read the device's table, so pass the csv
espflash erase-parts --chip esp32s3 --port <port> \
  --partition-table partitions/lckfb-szpi-esp32s3.csv creds

# Any cargo subcommand on the S3 target has to go through this dispatcher
bash ../../scripts/iot-xtensa.sh tree -p iot-app --target xtensa-esp32s3-none-elf \
  --no-default-features --features lckfb-szpi-esp32s3,console-auto

# One test, with its println output
cargo test -p iot-core <test-name> -- --nocapture

# Total main-task stack = the difference between these two symbols (the same arithmetic esp-rtos uses)
nm <elf> | grep -E '_stack_(start|end)_cpu0'

Impact of a change

Symptoms and where to start

What the checks do not cover

• check-s3 only type-checks and never links: running out of memory shows up at build-s3 or iot:image.
• Build-time variables are not part of moon's cache key; build-s3 sets cache: false, the other tasks have no such protection.
• Whether each feature compiles on its own is answered by check-features alone.
• The log level is a build-time constant (configured_level in chip-esp/src/logging.rs): changing IOT_LOG_LEVEL without a rebuild has no effect.
• There is no gdb and no openocd: debugging means logs, and each peripheral added means one more probe (flash-probe-*-s3).
• server:lint is cargo clippy --workspace, and the root workspace excludes apps/iot; the firmware is not checked.
• server-ui:typecheck covers the include of tsconfig.app.json (src/**) only; vite.config.ts and vitest.config.ts belong to tsconfig.spec.json and are not included.
• pre-commit runs no tests and checks no translation.
• apps/iot/target grows into the tens of GB; cd apps/iot && cargo clean costs a rebuild, and the S3 half costs the most.

Full details

• Layering and composition, feature criteria
• Firmware installation — artifacts, partition tables, bench images, the full boot-log recipe
• Hardware-free emulation
• Motion, audio metering, playback
• Implementation records — why it is this way and the measured numbers (AI output, not human-reviewed)