Skip to content
Closed
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
49 changes: 45 additions & 4 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -49,11 +49,24 @@ jobs:
strategy:
fail-fast: false
matrix:
# Every Plaits image carries the eMMC storage and drive mode (#49); they differ
# only in whether the image FORMATS the card. Adara, 2026-10-08:
# plaits -> wakes-sp1.bin never formats (no formatter linked at all)
# fresh -> wakes-sp1-fresh.bin formats the eMMC once per build (SP1_FRESH)
# fallback -> the test-tone recovery image: no Plaits, never touches the eMMC
include:
- config: plaits
plaits: y
extra: ""
bin: wakes-sp1
- config: fresh
plaits: y
extra: -DCONFIG_SP1_FRESH=y
bin: wakes-sp1-fresh
- config: fallback
plaits: n
extra: ""
bin: wakes-sp1
defaults:
run:
working-directory: ws
Expand All @@ -68,9 +81,9 @@ jobs:
run: |
python -m west build -p always -b stem_player wakes-sp1/firmware -d build \
-- -DBOARD_ROOT="$PWD/wakes-sp1" -DCONFIG_SP1_PLAITS=${{ matrix.plaits }} \
2>&1 | tee build.log
${{ matrix.extra }} 2>&1 | tee build.log

# Both configs build with 0 warnings; keep it that way. This also catches a
# Every config builds with 0 warnings; keep it that way. This also catches a
# Kconfig "assigned ... but got ..." warning, i.e. a -DCONFIG_ that did not take.
- name: No warnings
run: |
Expand All @@ -83,6 +96,24 @@ jobs:
- name: Check the image (0x20000, SAFETY.md constraints)
run: python wakes-sp1/tools/ci/check_image.py build | tee check.txt

# A formatting image must never ship under the plain name, and the others must be
# what their names say. Checked from the build's own .config, not from the matrix.
- name: The configuration is what the name says
run: |
cfg=build/zephyr/.config
on() { grep -qx "CONFIG_$1=y" "$cfg"; }
fail() { echo "::error::${{ matrix.config }}: $1"; exit 1; }
case "${{ matrix.config }}" in
plaits) { on SP1_STORAGE && on SP1_DRIVE; } || fail "storage or drive mode missing"
if on SP1_FRESH; then fail "a formatting image named wakes-sp1"; fi ;;
fresh) { on SP1_STORAGE && on SP1_DRIVE && on SP1_FRESH; } || fail "not a fresh image" ;;
fallback) if on SP1_STORAGE; then fail "the recovery image must not touch the eMMC"; fi ;;
esac
for d in SP1_STORAGE_TEST SP1_EMMC_VERIFY; do
if on $d; then fail "diagnostic $d is on"; fi
done
echo "${{ matrix.config }}: OK"

- name: Size
run: python wakes-sp1/tools/ci/size_report.py report build -o size-head.json

Expand All @@ -106,7 +137,7 @@ jobs:
run: |
if ! python -m west build -p always -b stem_player base/firmware -d build-base \
-- -DBOARD_ROOT="$PWD/base" -DCONFIG_SP1_PLAITS=${{ matrix.plaits }} \
> build-base.log 2>&1; then
${{ matrix.extra }} > build-base.log 2>&1; then
tail -n 40 build-base.log
exit 1
fi
Expand Down Expand Up @@ -136,6 +167,16 @@ jobs:
echo "</details>"
} | tee "size-${{ matrix.config }}.md" >> "$GITHUB_STEP_SUMMARY"

# The tools all expect wakes-sp1.bin (CONFIG_KERNEL_BIN_NAME); the fresh image is
# RENAMED, not copied, so its artifact holds no file a person could take for the
# one that does not format.
- name: Name the image (${{ matrix.bin }}.bin)
if: always() && matrix.bin != 'wakes-sp1'
run: |
if [ -f build/zephyr/wakes-sp1.bin ]; then
mv build/zephyr/wakes-sp1.bin "build/zephyr/${{ matrix.bin }}.bin"
fi

- uses: actions/upload-artifact@v7
if: always()
with:
Expand All @@ -144,7 +185,7 @@ jobs:
include-hidden-files: true
if-no-files-found: warn
path: |
ws/build/zephyr/wakes-sp1.bin
ws/build/zephyr/${{ matrix.bin }}.bin
ws/build/zephyr/wakes-sp1-midi.md
ws/build/zephyr/wakes-sp1-midi.csv
ws/build/zephyr/wakes-sp1.elf
Expand Down
9 changes: 5 additions & 4 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
# Every PR to main, and every push to main, that touches a build input: build both
# configs, run the host suites, gate on check_image.py, and put the size diff in the
# run's summary. Administrative changes (see `paths`) run nothing. Tags always build
# (release.yml), and workflow_dispatch builds on demand.
# Every PR to main, and every push to main, that touches a build input: build every
# image (wakes-sp1, wakes-sp1-fresh, fallback), run the host suites, gate on
# check_image.py, and put the size diff in the run's summary. Administrative changes
# (see `paths`) run nothing. Tags always build (release.yml), and workflow_dispatch
# builds on demand.
name: ci

on:
Expand Down
27 changes: 23 additions & 4 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,10 @@
#
# It is attached twice: versioned, and as plain `wakes-sp1.bin`, so that
# releases/latest/download/wakes-sp1.bin (the README's download link) always names
# the newest PUBLISHED release. GitHub's "latest" skips drafts and pre-releases, so
# that link moves only when a person publishes a full release.
# the newest PUBLISHED release. `wakes-sp1-fresh.bin`, the image that FORMATS the eMMC
# (#49), is attached the same two ways; the fallback is attached versioned only.
# GitHub's "latest" skips drafts and pre-releases, so that link moves only when a
# person publishes a full release.
name: release

on:
Expand Down Expand Up @@ -85,6 +87,8 @@ jobs:
mkdir dist
cp in/wakes-sp1-plaits/build/zephyr/wakes-sp1.bin "dist/wakes-sp1-$t.bin"
cp in/wakes-sp1-plaits/build/zephyr/wakes-sp1.bin dist/wakes-sp1.bin
cp in/wakes-sp1-fresh/build/zephyr/wakes-sp1-fresh.bin "dist/wakes-sp1-$t-fresh.bin"
cp in/wakes-sp1-fresh/build/zephyr/wakes-sp1-fresh.bin dist/wakes-sp1-fresh.bin
cp in/wakes-sp1-fallback/build/zephyr/wakes-sp1.bin "dist/wakes-sp1-$t-fallback.bin"
# The MIDI CC chart for exactly this build's script (M5a, tools/gen_midi.py).
cp in/wakes-sp1-plaits/build/zephyr/wakes-sp1-midi.md "dist/wakes-sp1-$t-midi.md"
Expand All @@ -105,13 +109,28 @@ jobs:
echo
echo "\`wakes-sp1.bin\` is the same file under a fixed name, for the README's download link."
echo "Check the file against \`SHA256SUMS\` before flashing."
echo "\`wakes-sp1-$t-fallback.bin\` is the test-tone build without Plaits or Marbles,"
echo "for diagnosing hardware only. It is not the instrument."
echo
echo "### Storage: \`wakes-sp1\` vs \`wakes-sp1-fresh\`"
echo
echo "- **\`wakes-sp1-$t.bin\` never formats the SP-1's internal storage (the eMMC).** Flash"
echo " it to update: your presets and files stay where they are."
echo "- **\`wakes-sp1-$t-fresh.bin\` FORMATS the eMMC** the first time it turns ON, and"
echo " **erases everything on it**, including whatever another firmware left there (stock"
echo " stems, tape-looper recordings). Flash it once to set the storage up, or to start"
echo " over; a progress bar shows on T1-T4 while it formats. Flashing the same fresh file"
echo " again does not format a second time. \`wakes-sp1-fresh.bin\` is the same file under"
echo " a fixed name."
echo "- Without a formatted card Wakes still plays; the storage features stay off."
echo
echo "\`wakes-sp1-$t-fallback.bin\` is the test-tone recovery build without Plaits or Marbles."
echo "It never touches the eMMC, and is for diagnosing hardware only. It is not the instrument."
echo
echo "## Size${PREV:+ vs $PREV}"
echo
cat in/wakes-sp1-plaits/size-plaits.md
echo
cat in/wakes-sp1-fresh/size-fresh.md
echo
cat in/wakes-sp1-fallback/size-fallback.md
echo
echo "## SHA-256"
Expand Down
14 changes: 14 additions & 0 deletions LICENSES/FatFs.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
FatFs - Generic FAT Filesystem Module R0.16
Copyright (C) 2025, ChaN, all right reserved.

FatFs module is an open source software. Redistribution and use of FatFs in
source and binary forms, with or without modification, are permitted provided
that the following condition is met:

1. Redistributions of source code must retain the above copyright notice,
this condition and the following disclaimer.

This software is provided by the copyright holder and contributors "AS IS"
and any warranties related to this software are DISCLAIMED.
The copyright owner or contributors be NOT LIABLE for any damages caused
by use of this software.
1 change: 1 addition & 0 deletions LICENSES/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ what was changed.
| `MIT-feldd.txt` | Benjamin Reece | `third_party/feldd/` (the USB-MIDI 1.0 class and its packet parser) and the build-time patched copy of `usb_midi1.c` |
| `MIT-sp1-tape-looper.txt` | chattock | the board definition, power-off and watchdog sequence, and codec bring-up adapted from chattock/sp1-tape-looper |
| `MIT-SP-1-dev.txt` | Tim Knapen | the SP-1 pin map and hardware documentation from timknapen/SP-1-dev |
| `FatFs.txt` | ChaN | FatFs, the FAT filesystem on the eMMC (Zephyr's `fatfs` module, `modules/fs/fatfs`), compiled into images built with `CONFIG_SP1_STORAGE` |
| `MIT-sp1-midi.txt` | Eric Lewis | the original `stem_player` Zephyr board that the board definition descends from |
| `Apache-2.0.txt` | the Zephyr Project contributors; Ryan Gilmore | `third_party/sp1-usb-audio/` (USB audio out; it also carries its own `LICENSE` and `NOTICE`), `firmware/src/sp1_uac.{c,h}` and `tools/host-tests/uactest.c` (derived from it), `boards/teenageengineering/stem_player/Kconfig.defconfig`, `Kconfig.stem_player` and `stem_player_defconfig` (inherited from Zephyr's board template), `zephyr-patches/`, `firmware/src/sp1_usbd.c` (derived from Zephyr's USB sample helper), and the Zephyr RTOS compiled into every firmware image |

Expand Down
18 changes: 15 additions & 3 deletions NOTICE
Original file line number Diff line number Diff line change
Expand Up @@ -22,19 +22,31 @@ SP-1 board definition and power/watchdog sequence
48 kHz clock topology, the bring-up order, the I2S stream configuration,
and the TAS2505 and CS42L42 register sequences, ported verbatim; and
(M3) the headphone auto-mute: CS42L42 jack sense (reg 0x1B77 bit 7),
3-read debounce, TAS2505 speaker driver on/off (page 1 reg 0x2D).
3-read debounce, TAS2505 speaker driver on/off (page 1 reg 0x2D); and
(M6) the 1-bit eMMC protocol in firmware/src/sp1_emmc.c: the eMMC pin map,
the power/reset/init sequence, the command framing and the response and
data sampling points (reduced, read-only and bit-banged here).

SP-1 hardware documentation and pin map
timknapen/SP-1-dev — Copyright (c) 2026 Tim Knapen — MIT
https://github.com/timknapen/SP-1-dev
Licence text: LICENSES/MIT-SP-1-dev.txt
Source of: the SP-1 pinout in firmware/src/sp1_board.h, and the CS42L42
headphone-codec init sequence (via sp1-tape-looper) in sp1_audio.c.
Source of: the SP-1 pinout in firmware/src/sp1_board.h, the CS42L42
headphone-codec init sequence (via sp1-tape-looper) in sp1_audio.c, and the
eMMC driver (emmc.c, via sp1-tape-looper) behind firmware/src/sp1_emmc.c.

TAS2505 speaker amplifier configuration
Texas Instruments, TAS2505 Application Reference Guide (SLAU472C), sec. 5.1
The register sequence in sp1_audio.c follows it, via sp1-tape-looper.

FAT filesystem on the eMMC (M6, images built with CONFIG_SP1_STORAGE)
FatFs R0.16 — Copyright (C) 2025, ChaN — FatFs licence (one condition:
keep the notice in source redistributions)
https://elm-chan.org/fsw/ff/
Licence text: LICENSES/FatFs.txt
Used unmodified through Zephyr's fatfs module (zephyrproject-rtos/fatfs,
pinned by the Zephyr revision in west.yml) and Zephyr's fs layer.

Zephyr BSP precedent
ericlewis/sp1-midi — Copyright (c) 2026 Eric Lewis — MIT
https://github.com/ericlewis/sp1-midi
Expand Down
26 changes: 14 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,34 +3,36 @@
alt="Wakes: a love letter to Mutable Instruments, by Worldwave">
</p>

Wakes is a semimodular synthesizer, built as a custom firmware for the Teenage Engineering SP-1, Teenage Engineering's unreleased stem player.
It runs two Mutable Instruments modules combined:
Wakes is a semimodular synthesizer, built as a custom firmware for the SP-1, an unreleased Teenage Engineering stem player that was turned into a dev board by its community.

Wakes combines two Mutable Instruments modules:

- **Plaits**: A macro-synthesizer voice, featuring multiple sound engines
- **Marbles**: A playful random sequencer

The development of Wakes is unaffiliated with Teenage Engineering or Mutable Instruments.
IMPORTANT: Flashing custom firmware on the SP-1 is at your own risk. SP-1s are abandonware, they do not have manufacturer support.
REMEMBER: There is no way to go back to the base firmware once you've flashed it away.
**IMPORTANT:** Flash custom firmware on the SP-1 at your own risk. SP-1s are abandonware, they do not have manufacturer support. There is no way to go back to the base firmware once you've flashed it away.

## 📖 Manual

**[Wakes – Manual (PDF)](docs/Wakes%20-%20Manual.pdf)**: The manual details the layout of each page, with every control and how how to use them, in an aesthetically pleasing and readable format. Once you've installed Wakes on your SP-1, start there.
**[Wakes – Manual (PDF)](docs/Wakes%20-%20Manual.pdf)**: The manual details the layout of each page, with every control and how how to use them, in an aesthetically pleasing and readable format. Once you've installed Wakes on your SP-1 using the Flashing section below, start here.

## Status

**v0.7.2, pre-release for beta testing.** Report problems with the bug form under [Issues](https://github.com/Worldwave/Wakes/issues).
**v0.8.0, pre-release for beta testing.** Report problems with the bug form under [Issues](https://github.com/Worldwave/Wakes/issues).

## Flashing

1. **Download the latest [`wakes-sp1.bin`](https://github.com/Worldwave/Wakes/releases/latest/download/wakes-sp1.bin)**.
Older versions and release notes are on the [releases page](https://github.com/Worldwave/Wakes/releases).
2. Open <https://solderless.engineering>. Hold down **T1+T4** while connecting the SP-1 over USB-C.
3. Follow solderless.engineering's instructions on how to connect to your SP-1 to flash it.
1. Wakes features new storage protocols for the SP-1. If you've never used Wakes before, you need to format your storage partition.
To do that, **Download the latest Fresh bin [`wakes-sp1-fresh.bin`](https://github.com/Worldwave/Wakes/releases/latest/download/wakes-sp1-fresh.bin)**.
2. If you've used Wakes before, and want to avoid touching your storage, **Download the latest regular bin [`wakes-sp1.bin`](https://github.com/Worldwave/Wakes/releases/latest/download/wakes-sp1.bin)**.
3. Older Wakes versions and release notes are available through the repo's [releases page](https://github.com/Worldwave/Wakes/releases).
4. Open <https://solderless.engineering>. Hold down **T1+T4**. Keep them held while connecting the SP-1 over USB-C.
5. Follow solderless.engineering's instructions on how to connect to your SP-1 to flash it.
3. Select the `.bin` in Solderless Engineering's "firmware utility" page, flash it, and once done, you can unplug.

The T1+T4 recovery trigger in step 2 lives in Teenage Engineering's bootloader, not in Wakes, so it
works with whatever firmware is installed. Wakes never writes below `0x20000` (and neither should your CFW's),
The T1+T4 recovery trigger in step 4 lives in Teenage Engineering's bootloader, not in Wakes, so it
works with whatever firmware is installed. Wakes never writes below the flash memory's `0x20000` (and neither should your CFW's),
because that's where the bootloader lives.

## Building
Expand Down
17 changes: 16 additions & 1 deletion docs/BUILD.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,20 @@ Artifact: **`build\zephyr\wakes-sp1.bin`**. (`CONFIG_KERNEL_BIN_NAME="wakes-sp1"
`firmware/prj.conf` renames the outputs from Zephyr's default `zephyr.*`. The
`build\zephyr\` directory name itself comes from the CMake target and is unaffected.)

### The three images

| Image | Build | eMMC |
|---|---|---|
| `wakes-sp1.bin` | as above | storage + drive mode; **never formats** (no formatter is linked) |
| `wakes-sp1-fresh.bin` | add `-DCONFIG_SP1_FRESH=y` after the `--` | **formats the eMMC** on its first ON, once per build |
| fallback | add `-DCONFIG_SP1_PLAITS=n` | test tone, recovery only; never touches the eMMC |

The fresh build still writes `build\zephyr\wakes-sp1.bin`: **rename it to
`wakes-sp1-fresh.bin` straight away**, so it is never flashed by mistake as the image that
does not format. CI does the same, and checks each image's `.config` against its name.
Storage diagnostics, off in every shipped image: `-DCONFIG_SP1_STORAGE_TEST=y` (eMMC report
+ a 512 KB pattern test on each ON) and `-DCONFIG_SP1_EMMC_VERIFY=y` (every write read back).

### Three things that are not optional

**Quote `BOARD_ROOT` and use forward slashes.** Unquoted, the argument splits at the
Expand Down Expand Up @@ -83,7 +97,7 @@ The failure modes that recur on this board:
| a `pwm*`/`adc` node not found | the DTS label, and that the matching `CONFIG_*` driver is enabled |
| `zephyr,deferred-init` unknown property, or `device_init()` undeclared | see **Deferred PWM init** below — there is a fallback |
| pinctrl error on a `PSEL` | spelling in `stem_player-pinctrl.dtsi` |
| missing module | `west.yml`'s allowlist — `cmsis`, `cmsis_6`, `hal_nordic` are all required |
| missing module | `west.yml`'s allowlist — `cmsis`, `cmsis_6`, `fatfs`, `hal_nordic` are all required |
| **LEDs work but wrong ones, or wrong order** | **not a build error.** pinctrl channel order vs LED index — see the comment block in `sp1_board.h` |
| **ADC reads nonsense** | **not a build error.** Channel `reg` vs `io-channels` index vs the index used in C |

Expand Down Expand Up @@ -261,6 +275,7 @@ git config --global --add safe.directory C:/sp1-ws/zephyr
git config --global --add safe.directory C:/sp1-ws/modules/hal/cmsis
git config --global --add safe.directory C:/sp1-ws/modules/hal/cmsis_6
git config --global --add safe.directory C:/sp1-ws/modules/hal/nordic
git config --global --add safe.directory C:/sp1-ws/modules/fs/fatfs
git config --global --add safe.directory C:/sp1-ws/wakes-sp1
```

Expand Down
Binary file modified docs/Wakes - Manual.pdf
Binary file not shown.
8 changes: 8 additions & 0 deletions firmware/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,14 @@ target_sources(app PRIVATE
src/sp1_plaits_ui.c
)

# ---- M6 (#43): the eMMC and the FAT volume on it (src/sp1_store.h) ----
if(CONFIG_SP1_STORAGE)
target_sources(app PRIVATE src/sp1_emmc.c src/sp1_store.c)
target_sources_ifdef(CONFIG_SP1_STORAGE_TEST app PRIVATE src/sp1_emmc_report.c)
# ff.h, for FATFS and MKFS_PARM (Zephyr's fatfs module, ELMFAT interface).
target_link_libraries(app PRIVATE ELMFAT)
endif()

# ---- M3: the Plaits voice (third_party/eurorack, vendored unmodified) ----
# Built as its own Zephyr library so it gets its OWN optimisation flags. The rest of
# the firmware is built -Os (CONFIG_SIZE_OPTIMIZATIONS); the DSP is the one place where
Expand Down
Loading
Loading