Getting Started

From nothing to your own firmware running on an FM-1. This page follows the Felucca-family toolchain, which most open firmwares use. M-VAVE’s own open kit (FM1 Open) uses a different, Windows-only build; see Choosing a Base.

Before your first install, read Recovery and make a full flash backup with M-Flasher. It takes a minute and it is your way back.

1. What you need

Thing Why Where
JieLi’s toolchain (clang 4.0.1 for the pi32v2 CPU) compiles and links for the FM-1’s CPU JieLi’s package server (below). Linux x86-64 and Windows builds exist.
Three files from JieLi’s AC79 SDK (Apache-2.0) the package needs JieLi’s first-stage loader and two config blobs fw-AC79_AIoT_SDK on Gitee
Python 3 the build scripts, packaging, installing your system
On macOS or Windows: Docker, or a Linux VM the Linux toolchain runs only on x86-64 Linux Docker Desktop, podman, WSL2
A USB data cable installing over USB-MIDI  

[CODE] The JieLi Linux toolchain is fetched like this in Felucca-derived trees (tools/get_toolchain.sh):

curl -fL https://pkgman.jieliapp.com/s/linux-toolchain | tar -xJ -C ~/.jieli

m-bootloader pins an exact toolchain release, jieli-linux-toolchains-20250324.1, and checks its SHA-256 (m-bootloader README). Pinning a version and a hash is a good habit.

[CODE] The SDK files a Felucca-style package uses are cpu/wl82/tools/uboot.boot, cfg_tool.bin and cfg/eq_cfg_hw.bin. Felucca-family trees build against the tag AC79NN_SDK_V1.2.1_2023-12-13:

git clone --depth 1 --branch AC79NN_SDK_V1.2.1_2023-12-13 \
    https://gitee.com/Jieli-Tech/fw-AC79_AIoT_SDK.git ~/fw-AC79_AIoT_SDK

Some build scripts check these three files by SHA-256, so a package made from another SDK version is noticed.

[CODE] The hashes pinned by mvave-fm1’s build container (docker/vendor/README.md, which says they are the Optimist project’s); Dinghy’s tools/build.py checks the same three SDK hashes:

File SHA-256
jieli-linux-toolchains-20250324.1.tar.xz f686586bcfb45e0f0bb27fd2b39c7a7f313cb4f0e88a66a14da621ffa8225958
uboot.boot 4e3b4c220dc96641cb5a723f41e68ce41d5261ae9434bb33fbd7f2c59976ded4
cfg_tool.bin 276579954f076886a6a7694f65dc71c034a63a2c204b76749065c0ac7b010d1b
cfg/eq_cfg_hw.bin 41167491bffed4651750719c973d2758adeb9021a5670d02d6a53c85ed80ea7d

The same toolchain archive is also served from https://jl-update.oss-cn-shenzhen.aliyuncs.com/jieli-linux-toolchains-20250324.1.tar.xz. JieLi’s hosts geo-block some regions: from one developer’s network pkgman.jieliapp.com answered “Connection denied by Geolocation” and Gitee and Aliyun failed (mvave-fm1, 2026-10-22). Download the files on another machine, check the hashes, and copy them over. Don’t turn off certificate checks to get round it.

Building in a container

If you don’t want JieLi’s toolchain on your computer, or you are on macOS or Windows, mvave-fm1 (MIT) has a podman image (Debian bookworm, the toolchain, the three SDK files, Python with Pillow) and a script, mvave-build.sh, that builds Felucca-family firmwares unchanged:

./mvave-build.sh fetch-vendor        # toolchain + SDK files into docker/vendor/, hash-checked
./mvave-build.sh image
./mvave-build.sh clone dinghy
./mvave-build.sh run dinghy tests/run_host.sh    # host run: WAV + PNG screens
./mvave-build.sh build dinghy                    # -> out/dinghy/dinghy.fwsc

[CODE] Its CI built Dinghy, Felucca and ORBIT this way (2026-10-22); no container-built package had been flashed then. Install from the host, never from inside the container. Its notes say JieLi’s licence does not allow passing the toolchain on, so keep the image local (don’t push it to a registry) [?]. Felucca’s font generation needs Pillow with Raqm (libraqm0, libfribidi0, libharfbuzz0b on Debian).

An open toolchain is coming. pi32v2-isa and its LLVM fork build m-bootloader, fm1-base, Felucca and SLOOP with nothing of JieLi’s, and the results run on hardware (its README, October 2026). Watch that project if you need a toolchain you can audit.

2. Pick a starting point

Don’t start from an empty file. The hard parts (start-up, the audio interrupt, USB-MIDI, the update path, a crash screen) are done and tested in several bases. Choosing a Base compares them.

The smallest documented starting points:

  • Dinghy (GPL-3.0): “the plumbing done and documented”, with a four-voice sine.
  • fm1-base (MPL-2.0, beta): a template app on felucca-bsp, with a host simulator and a browser emulator.

3. First build

Each base has its own build command; read its BUILDING or README. What a good build does, whichever base:

  • compiles with the FPU on: -mcpu=r3 -mfprev1 (see Performance);
  • links at the address the boot chain jumps to, 0x02000120 [CODE];
  • checks the image: its size against the app slot, that no double crept in (the FPU is single precision), that code which runs with the flash off calls nothing in flash;
  • wraps the app and an update loader into a .fwsc package (Firmware Package Format).

If your build prints a check as failed, do not install the package it leaves behind. Some scripts leave the previous package in place when a check fails. Compare the package’s hash or a build stamp before installing.

4. First install

Most open firmwares install over USB-MIDI with the same protocol M-VAVE’s updater uses (Update Protocol and Installers):

  • from a browser (Chrome or Edge, Web MIDI with SysEx), on the project’s install page; or
  • from the command line, e.g. python3 tools/fm1_install.py build/app.fwsc in Felucca-family trees.

If the unit runs M-VAVE’s FM1 Open firmware, many installers refuse or fail: put M-VAVE’s stock firmware (V15) back first (Update Protocol and Installers).

5. When something goes wrong

  • The unit shows a crash screen: read the PC address on it, then Debugging.
  • The unit doesn’t start: Recovery.
  • The sound clicks or drops out: Performance.

Next

Hardware Overview · Programming Guide · Simulators and Emulators

Sources


Unofficial community wiki. Not affiliated with M-VAVE or JieLi. Text under CC BY-SA 4.0; code excerpts keep their own licences (License). Facts are tagged [HW] [SDK] [RE] [CODE] [?]: see Home. Found an error? See Contributing. Home