Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 14 additions & 9 deletions LICENSING.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,23 @@

GPL-3.0-only (`LICENSE`), as Felucca, SLOOP and Dinghy. Whoever gets a firmware built from this gets its source too.

| What | Who |
| -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| What | Who |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `platform/hal/`, `platform/loader/`, `platform/src/`, `platform/crt0.S`, `platform/app.ld`, `tools/fm1pkg_make.py`, `tools/lz4blk.py`, `web/fm1ota.js`, `web/fm1pkg.js`, the FM-1 parts of `tools/build.py` | Copyright (C) 2026 Leo Kuroshita (@kurogedelic), Hügelton Instruments ([Felucca](https://github.com/hugelton/Felucca)), with the changes of [SLOOP](https://github.com/isod89/sloop-fm1) (isod89), as [Dinghy](https://github.com/zvenson/dinghy) (zvenson) and [X0X](https://github.com/charlesvestal/fm1-x0x) (Charles Vestal) carry them |
| `platform/fm1.c` | Dinghy's `platform.c` (zvenson), rewired to `fm1.h` |
| `platform/fm1.h`, `platform/common.c`, `platform/web.c`, `web/` (the page, the emulator), `fm1`, `Dockerfile`, `src/main.c` | foma |
| `platform/fm1.c` | Dinghy's `platform.c` (zvenson), rewired to `fm1.h` |
| `platform/fm1.h`, `platform/common.c`, `platform/clock.c`, `platform/web.c`, `web/` (the page, the emulator), `fm1`, `Dockerfile`, `src/main.c` | foma |

The USB audio from a computer in `platform/src/usb.c` (`FOMA_USB_AUDIO`) is ported from
[felucca-bsp](https://github.com/hugelton/felucca-bsp) (commit 5758857, MPL-2.0, by Leo Kuroshita), whose license lets
it be used under GPL-3.0; foma's version uses integer math. The TRS MIDI input (`platform/src/midi_uart.c`,
`platform/hal/fm1_uart.h`) is Felucca's.

## Third-party material

| What | Licence | Where |
| --------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------- |
| Terminus font (ter-u16n), rendered into `platform/gen/felucca_font.h` | SIL OFL 1.1 | `platform/gen/Terminus-LICENSE.txt` |
| `platform/sdk/uboot.boot`, `cfg_tool.bin`, `eq_cfg_hw.bin` from JieLi's AC79NN_SDK_V1.2.1 | Apache-2.0 | <https://gitee.com/Jieli-Tech/fw-AC79_AIoT_SDK> |
| JieLi's toolchain, downloaded into the Docker image | JieLi's | <https://pkgman.jieliapp.com/s/linux-toolchain> |
| What | Licence | Where |
| ----------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------- |
| Terminus font (ter-u16n), rendered into `platform/gen/felucca_font.h` | SIL OFL 1.1 | `platform/gen/Terminus-LICENSE.txt` |
| `platform/sdk/uboot.boot`, `cfg_tool.bin`, `eq_cfg_hw.bin` from JieLi's AC79NN_SDK_V1.2.1 | Apache-2.0 | <https://gitee.com/Jieli-Tech/fw-AC79_AIoT_SDK> |
| JieLi's toolchain, downloaded into the Docker image | JieLi's | <https://pkgman.jieliapp.com/s/linux-toolchain> |

"M-VAVE" and "FM-1" belong to their owners; "Felucca" and "Hügelton Instruments" to Hügelton Instruments. This project is not made or endorsed by them.
31 changes: 26 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ as you save, install it on the FM-1 from the same page.
That pulls the toolchain image ([konsumer/foma-toolchain](https://hub.docker.com/r/konsumer/foma-toolchain)) the first time, then builds your firmware and serves a page with:

- **Emulator**: your code, compiled to WebAssembly, on a virtual FM-1 panel: the screen, keys, buttons, knobs, LEDs,
sound, MIDI in/out (Web MIDI), settings, `print()` to a console. Save a file and it reloads; a compile error shows on
the page.
sound, MIDI in/out (Web MIDI), MIDI clock, settings, `print()` to a console. Save a file and it reloads; a compile
error shows on the page.
- **Install**: puts your build (or any FM-1 `.fwsc`) on the FM-1 over USB, from Chrome or Edge.
- **Rescue**: the USB rescue, finishing a cut-off install, going back to the official firmware.

Expand Down Expand Up @@ -55,7 +55,27 @@ Everything you can call is in [platform/fm1.h](platform/fm1.h): keys (`key_press
MIDI (`midi_read`, `midi_send`), `settings_load` / `settings_save`, `millis`, and sound helpers (`sine`, `note_inc`,
`random32`).

Name, version and package identity: [firmware.json](firmware.json).
Name, version, package identity and build options: [firmware.json](firmware.json).

### Build options

Some parts of the platform are optional. They're all on unless `"options"` in `firmware.json` turns them off, and
turning one off takes its code and memory out of the firmware:

| Option | What it adds | Costs |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `usb_audio` | A computer or tablet can pick the FM-1 as a 44.1 kHz stereo output. `audio_in()` gives `audio()` that sound: play it, process it, record it. | 10 KiB RAM |
| `trs_midi` | MIDI in on the 3.5 mm TRS jack (a TRS-to-DIN adapter for most gear), through `midi_read()`, which says where each message came from. | <1 KiB |
| `midi_clock` | One MIDI clock for `audio()`: its own tempo or the clock coming in, sent out over USB if you like. `clock_events()` gives each block's ticks, start and stop at the frame they fall on. | 1 KiB RAM |

```json
{ "name": "MY SYNTH", "version": "0.1", "identity": "FM-1_95", "options": { "usb_audio": false } }
```

In your code, `#if FOMA_USB_AUDIO` (and `FOMA_TRS_MIDI`, `FOMA_MIDI_CLOCK`) tells you what's in. The FM-1 has no MIDI out on the TRS jack, so that can't be an option. Bluetooth (audio and BLE MIDI) is possible in
principle: JieLi's AC79 SDK has a Bluetooth stack for this chip, but only as prebuilt libraries that need JieLi's OS
underneath, so it isn't here (yet). The emulator follows MIDI
clock from Web MIDI; it has no USB audio input (`audio_in()` gives 0).

## The rules of the chip

Expand All @@ -66,7 +86,7 @@ The FM-1 runs a JieLi AC791N. The emulator is forgiving, the chip is not; the bu
- **No 64-bit division**, no C library (`printf`, `malloc`, `sin`). 64-bit multiplication is fine.
- **A division by zero does not trap** on the FM-1 (it gives a wrong value); in the emulator it crashes. Test divisors.
- **`audio()` has 5.8 ms per 256 frames**, less in practice. No screen, no flash, no waiting in it. Share with `loop()`
through `volatile` variables, one writer each.
through `volatile` variables, one writer each. `midi_send` works from both.
- **`loop()` should return within a few ms**: the USB, the updater and the watchdog run between passes.
- **Draw only what changed**: sending a full screen takes ~80 ms.
- **Save settings when silent**: a flash erase stops the sound for ~50 ms. Never in a loop: flash wears out.
Expand Down Expand Up @@ -132,7 +152,8 @@ platform/fm1.h the API
platform/fm1.c the FM-1 side (boot, rescue, updater, USB, panel, screen, audio)
platform/web.c the emulator side (the same API, for WebAssembly)
platform/common.c shared: drawing, fonts, sound helpers
platform/hal, src, loader, gen, sdk the Felucca platform, vendored unchanged
platform/clock.c shared: the MIDI clock (midi_clock)
platform/hal, src, loader, gen, sdk the Felucca platform, vendored (src/usb.c trimmed to MIDI and usb_audio)
tools/build.py the build (in Docker), with the checks
web/ the page: emulator, installer, rescue
```
Expand Down
7 changes: 6 additions & 1 deletion firmware.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
{
"name": "FOMA",
"version": "0.1",
"identity": "FM-1_95"
"identity": "FM-1_95",
"options": {
"usb_audio": true,
"trs_midi": true,
"midi_clock": true
}
}
121 changes: 121 additions & 0 deletions platform/clock.c
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
/* foma: one MIDI clock for the app, 24 ticks a beat (FOMA_MIDI_CLOCK). It runs at the app's tempo, or follows the
* clock coming in over MIDI; either way audio() gets each block's ticks, start, continue and stop at the frame they
* fall on, and the clock can go out over USB MIDI.
*
* The platform defines CLOCK_MUL (its time stamps to frames: 44100 * 2^32 / their rate), passes clock_in() the
* clock and transport messages that come in with when they came, and calls clock_block() before each audio().
* Followed ticks are placed by when they came between the last block and this one: the sound is a block late, but
* steady. clock_in() runs where MIDI comes in (an ISR on the FM-1), clock_block() where audio() runs. */
#include "fm1.h"
#ifndef RING_PUBLISH
#define RING_PUBLISH() __asm__ volatile("" :: \
: "memory")
#endif

#define CK_Q 64u
static struct {
uint32_t t;
uint8_t st, src;
} ck_q[CK_Q];
static volatile uint32_t ck_w, ck_r;
static volatile uint8_t ck_from, ck_out, ck_req; /* the app's (loop) */
static volatile uint32_t ck_bpm100 = 12000, ck_measured;
static clock_event_t ck_ev[CLOCK_EVENTS];
static int ck_n;
static uint32_t ck_next_q8; /* its own tempo: frames to the next tick, Q8 */
static uint32_t ck_t, ck_frames, ck_last, ck_q4; /* followed: the last block's time; a tick's length (frames, Q4) */
static uint8_t ck_on; /* followed ticks are coming */

static int clock_in(uint32_t st, uint32_t src, uint32_t t) {
if (ck_w - ck_r < CK_Q) {
ck_q[ck_w % CK_Q].t = t;
ck_q[ck_w % CK_Q].st = (uint8_t)st;
ck_q[ck_w % CK_Q].src = (uint8_t)src;
RING_PUBLISH();
ck_w++;
}
return 1;
}

static void ck_add(uint32_t at, int what) {
static const uint8_t ST[5] = {0, 0xF8, 0xFA, 0xFB, 0xFC};
if (ck_n < CLOCK_EVENTS) {
ck_ev[ck_n].at = (uint16_t)at;
ck_ev[ck_n].what = (uint8_t)what;
ck_n++;
}
if (ck_out) {
midi_send(ST[what], 0, 0);
}
}

static void ck_tick(uint32_t at) { /* a followed tick: its length, smoothed (a pause is not one) */
uint32_t f = ck_frames + at, d = f - ck_last;
ck_last = f;
if (ck_on && d < 44100u && (!ck_q4 || d << 4 < ck_q4 * 3u)) {
ck_q4 = ck_q4 ? (uint32_t)((int32_t)ck_q4 + ((int32_t)(d << 4) - (int32_t)ck_q4) / 4) : d << 4;
}
ck_on = 1;
ck_add(at, CLOCK_TICK);
}

static void clock_block(uint32_t n, uint32_t t) {
uint32_t r = ck_r, from = ck_from, req = ck_req;
ck_n = 0;
ck_req = 0;
if (req) { /* the app's own start / continue / stop, first (following too) */
ck_add(0, (int)req);
if (req != CLOCK_STOP) {
ck_next_q8 = 0; /* (its own tempo: a tick on the start) */
}
}
if (from) {
while (r != ck_w) {
RING_PUBLISH();
uint32_t st = ck_q[r % CK_Q].st, src = ck_q[r % CK_Q].src;
int32_t dt = (int32_t)(ck_q[r % CK_Q].t - ck_t);
uint32_t at = dt <= 0 ? 0 : (uint32_t)(((uint64_t)(uint32_t)dt * CLOCK_MUL) >> 32);
r++;
if (!(src & from)) {
continue;
}
at = at >= n ? n - 1 : at;
if (st == 0xF8) {
ck_tick(at);
} else {
ck_add(at, st == 0xFA ? CLOCK_START : st == 0xFB ? CLOCK_CONTINUE
: CLOCK_STOP);
}
}
if (ck_frames + n - ck_last > 44100u) { /* none for 1 s */
ck_q4 = 0;
ck_on = 0;
}
ck_measured = ck_q4 ? 176400000u / ck_q4 : 0; /* 44100 * 60 / 24 * 100, Q4 */
} else {
uint32_t bpm = ck_bpm100 < 100u ? 100u : ck_bpm100, len = 2822400000u / bpm; /* 44100 * 60 / 24 * 100, Q8 */
r = ck_w; /* (what came in is not followed) */
ck_on = 0;
while ((ck_next_q8 >> 8) < n) {
ck_add(ck_next_q8 >> 8, CLOCK_TICK);
ck_next_q8 += len;
}
ck_next_q8 -= n << 8;
}
RING_PUBLISH();
ck_r = r;
ck_t = t;
ck_frames += n;
}

void clock_follow(int from) { ck_from = (uint8_t)(from & MIDI_ANY); }
void clock_send(int on) { ck_out = (uint8_t) !!on; }
void clock_tempo(uint32_t bpm100) { ck_bpm100 = bpm100; }
void clock_start(void) { ck_req = CLOCK_START; }
void clock_continue(void) { ck_req = CLOCK_CONTINUE; }
void clock_stop(void) { ck_req = CLOCK_STOP; }
int clock_events(const clock_event_t **ev) {
*ev = ck_ev;
return ck_n;
}
uint32_t clock_bpm(void) { return ck_from ? ck_measured : ck_bpm100; }
Loading
Loading