DoomBox for the M-VAVE FM-1: how to build and flash it

Independent, not affiliated with M-VAVE.

Quick path: use the prebuilt file

doombox-0.1.fwsc (609,657 bytes), built from AMB-1 at upstream commit 60dfbec4602497616d6a196be78e9288dc7c615a plus doombox-0.1.diff.

SHA-256: e0c7399cc0220c7eea75167eefa089542fef331d3e3462061a8de38705d4b531

To install it you still need the upstream repo's tools/fm1_install.py (see section 4). Clone charlesvestal/fm1-amb, then run python3 tools/fm1_install.py /path/to/doombox-0.1.fwsc.

This is a .fwsc package, not a raw .bin. The build did produce amb.bin inside it, but the installer takes the .fwsc.

Easiest install: no repo, no build

Do not use the web installer's "Return to official V15" box for this. That box only accepts M-VAVE's own FM-1 V15 file (it checks a hash and rejects anything else, including DoomBox). The upstream web installer has no field for your own firmware files, so DoomBox installs with the command-line script instead.

Install Python 3 (python.org).
In a terminal or command prompt:
```
pip install mido python-rtmidi
```
Put these two files in one folder: fm1_install.py (unchanged from upstream, GPL-3.0) and doombox-0.1.fwsc.
Plug in the FM-1 by USB, open a terminal in that folder and check it is found:
```
python fm1_install.py --info
```
Install:
```
python fm1_install.py doombox-0.1.fwsc
```
Answer the prompt, and do not unplug until it says it is done.

Tested here only on macOS with the upstream test suite; the Windows route is untested. Keep M-VAVE's official FM-1 V15 file so you can go back.

1. What DoomBox is

DoomBox is the AMB-1 generative ambient firmware (github.com/charlesvestal/fm1-amb, GPL-3.0) with a dark red screen, a pentagram sigil behind the garden, and tape-style saturation on the output.

It is firmware for the M-VAVE FM-1 (JieLi chip).

2. Why the AI Studio instructions fail

The AI Studio DoomBox page's Makefile targets an ARM Cortex-M4 with arm-none-eabi-gcc and flashes with dfu-util. The FM-1 is a JieLi chip, built with JieLi's pi32v2 clang toolchain and installed over MIDI as a .fwsc package.

That page also says the browser cannot produce a real .bin.

Python is only used by the build/install helper scripts. You do not write Python.

3. Build it yourself on macOS

First get the source: git clone https://github.com/charlesvestal/fm1-amb.git && cd fm1-amb && git checkout 60dfbec && git apply /path/to/doombox-0.1.diff. Run every command below from inside that folder.

Prerequisites: Python 3 with Pillow, and Docker Desktop. The JieLi toolchain is Linux x86-64 only; the build runs each tool in a linux/amd64 debian:bookworm-slim container (Rosetta on Apple silicon). Keep the source tree in a folder Docker can share, e.g. under /Users.

Install Pillow:
```
pip3 install Pillow
```
Install the JieLi Linux toolchain (clang 4.0.1 for pi32v2):
```
tools/get_toolchain.sh
```
Installs to ~/.jieli/toolchain.
Clone the JieLi AC79 SDK (Apache-2.0) from gitee, branch 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
```
The package uses three of its files: cpu/wl82/tools/uboot.boot, cfg_tool.bin, cfg/eq_cfg_hw.bin.
Build:
```
./build.sh
```

The build makes three files in build/: amb.bin (the firmware app), loader/ota.bin (the update loader), and amb.fwsc (the installable package: app + loader).

On Linux x86-64 the toolchain runs natively and Docker is not needed.

Windows is not covered by BUILDING.md. WSL2 Ubuntu may work, but it is untested.

4. Install over MIDI

Install the Python helper dependencies:

pip3 install mido python-rtmidi

Install the package:

python3 tools/fm1_install.py build/amb.fwsc

To check the connected FM-1 identity:

python3 tools/fm1_install.py --info

Hold OCT− and OCT+ for 5 seconds for Felucca's update mode.

5. Safety

At your own risk. Back up or keep the stock firmware first (M-VAVE's site).

If the FM-1 no longer starts but reaches the chip's update mode (4C4A:8057 on USB), tools/fm1_rescue.sh restores stock firmware from a Mac; otherwise recovery needs FM-1-transporter.

DoomBox 0.1 is compiled, passes the upstream test suite and simulator scenarios (one test, update-loader, was skipped because it needs the SDK path exported), but has NOT been tested on real hardware. Nobody has flashed it on a real FM-1 yet. Treat the first flash as an experiment.

6. Source and licence

DoomBox is GPL-3.0-only. Source: upstream github.com/charlesvestal/fm1-amb at commit 60dfbec plus the patch doombox-0.1.diff (palette, sigil and saturation changes only).

Derived firmware must ship source.