1 Welcome and safety

Thank you for trying Lunar Modulator. It is open firmware being written for the M-VAVE FM-1, the pocket six-operator FM synthesizer with 27 keys, eight knobs and a 240 × 240 colour screen. It is designed to give the FM-1 a choice of synthesis engines, up to four sounds at once with effects of their own, a rack of modulation and a sequencer with parameter locks, and every line of its own code is open under the MIT licence.

Lunar Modulator runs today in a web browser and on computers. It does not run on the FM-1 yet. This manual describes what it does, how to play it, and where each part of it stands. Please read this chapter before anything else: it explains what you can use now, and why nothing is offered for the FM-1 itself yet.

1.1 What you can use today

Lunar Modulator is built and tested on computers first, and each function in this manual carries a status that says where it works today:

• The browser simulator is a virtual FM-1. The firmware’s engines and effects run in your browser, behind a to-scale drawing of the front panel with the firmware’s own 240 × 240 screen. Play it with the mouse, a touch screen, the computer keyboard or a MIDI keyboard. It is the front page of the project’s website, ip2k.github.io/lunar-modulator, and chapter 2 shows how to use it.
• The desktop tools play the same engines, effects, modulation and sequencer into audio files from the command line. They are how the firmware is tested, and the only place a few of the sequencer’s functions (clips, scenes and songs) run so far.
• The FM-1 itself runs none of it yet. Everything marked Planned for the device is designed and documented, and waits for the rule described below.

1.2 Features at a glance

1.3 The one rule

Nothing is installed on, or written to, an FM-1 until two things have been shown on that very unit: a complete copy of its memory has been read out, and that copy has been written back so that the unit is byte for byte as it was.

The reason is that an FM-1 has no safety net. Its firmware lives in a single bank of memory, and the board has no recovery button and no test connector. The FM-1’s own update method runs inside the firmware that is already installed: it can replace a working firmware, but it cannot rescue one that no longer starts. Owners of other FM-1s have reported reading out and writing their units’ memory with a small USB dongle, but this project has not yet done so itself. Until a way back has been shown to work on the unit in question, a failed install could leave the instrument permanently unusable.

The one rule also limits what this project sends to an FM-1 while the work goes on: a read-only query that asks the unit which version of its firmware it runs, and passive listening, nothing else. Chapter 11 describes the recovery work under way and what will change once it succeeds.

1.4 Safety and care

Lunar Modulator does not change how the FM-1 is built or powered. M-VAVE’s instructions for the battery, charging and care of the instrument still apply; follow M-VAVE’s manual for them.

1.5 About this manual

• Controls are written as the panel prints them: SELECT, KNOB1, PLAY/STOP. Sequencer functions that are still to be given a key are drawn with a dashed outline, such as LOOP.
• Statuses. The status line under a heading says where the function described below it works today, using the three labels above.
• Notes add detail and tips suggest a way of working. Cautions protect your hearing and your data; warnings protect your instrument.
• Note names. Middle C, MIDI note 60, is C4. The FM-1’s lowest key, F3, is MIDI note 53.
• Generated reference. The parameter tables, value lists and sequencer tables are generated from the firmware’s code each time the manual is built, so they always match the build named below.
• Online and in print. The newest edition is on the project’s website, with a PDF of the whole manual beside it. Corrections are welcome as issues on the project’s repository.