Loading files
This file is pinned to the selected release. Download the original to open it in your design tool.
# bundles/
> **New here? Read [`docs/EDITIONS.md`](../../docs/EDITIONS.md) first** — what
> an edition is, why they exist, and what one has to promise. This file is the
> mechanics: the two files, and when cutting one is worth it.
Named firmwares, built from this repository.
Everything Patternflow does lives in `patternflow/` — the panel, the pattern
loader, Wi-Fi, sleep, OSC, MQTT, the show player, weather, audio. **A bundle
does not add code.** It is two files saying which of that gets compiled in,
and which settings differ.
```
bundles/audio/
features_local.h which features this firmware has, and in what order
overrides.h what it calls itself, and any setting it changes
env (optional) the PlatformIO env to build in — only when
the difference is a build flag, not a setting
```
That is the whole of it. The default build needs no bundle at all — and it
is the opposite of everything: the device and nothing else. Every feature
lives in an edition built from these two files.
```bash
./firmware/bundles/build.sh # the default: no features
./firmware/bundles/build.sh audio # the audio bundle
./firmware/bundles/build.sh midi # the MIDI edition, in its own env (bundles/midi/env)
./firmware/bundles/build.sh audio flash patternflow.local
./firmware/bundles/build.sh all # every composition + the marker scan
# proving each binary carries exactly
# its features
./firmware/bundles/shelf.sh audio v0.5.0 # a publishable image: secrets
# moved aside, scanner proven against a
# control build, four files staged for
# the shelf
```
## When a bundle is worth making
Not for "everything minus a few things". That was tried and it is pointless:
dropping three features saved 278,528 bytes of flash on a board using 45 % of it, and
left the ceiling on loadable patterns *exactly where it was* — 73,716 bytes
either way. Nobody would switch, and they would be right not to.
A bundle earns its place when it carries something the default **cannot**:
| | why not in the default |
|---|---|
| **audio** | an on-board microphone that needs four wires soldered to the DevKit, a Wi-Fi transmit power that is not the conformance-tested one, and MIDI over the network |
| **performance** | the show player, MQTT in every role, weather — Simone Majocchi's performance-director firmware, pinned so a show behaves the same at the next gig |
| **clock** | the time cut out of the running pattern, in a choice of faces — a panel on a shelf that tells the time, with nothing else attached. **Not on the shelf since 2026-09-15:** the clock is a feature; this bundle is the composition CI keeps compiling |
| **midi** | the DevKit's USB port as a MIDI device, beside RTP-MIDI — a wire into a DAW with no driver and no session. It needs the port on the S3's USB-OTG stack, a build flag the other images cannot carry (that flag is what makes the port their serial console), so this one builds in its own PlatformIO env. Data only; the panel is still powered from `J4`. **Not on the shelf:** the composition that proves the OTG build |
Three shapes of reason, and they are not the same:
- **Not ready.** Experimental, or needs hardware the board does not have.
- **Not universal.** Correct for a situation, wrong as a default — a radio
setting for a hostile venue, say.
- **Deliberately still.** Somebody building a show around a firmware and
needing it to behave identically at the next gig, pinned to a core version
and not moving.
The card on [patternflow.work/editions](https://patternflow.work/editions)
says which of the three each bundle is, because a person choosing needs to
know whether they are picking up something unfinished or something frozen.
A bundle can also be in the tree and not on the shelf at all — `clock` and
`midi` are. Then it is a composition CI keeps compiling so a core change
cannot break it silently, and there is no card and nothing to cut. It can
still be tried: the features page carries a frozen image of it, staged with
`shelf.sh <name> vA.B.C` like a shelf image but named from
`web/src/app/features/features-data.ts`, and nobody bumps it when the core
moves. The shelf is what its maintainer stands behind, and it is short on
purpose.
## Graduating
A bundle is not a permanent home. When the microphone works and the board has
a footprint for it, that feature joins the default list and the audio bundle
either dissolves or picks up whatever is next. Nothing here is meant to
accumulate.
## Owning one
A bundle can be somebody else's. The two files are small, they conflict with
nothing, and the person who owns a bundle decides what goes in it and when it
cuts a version — without owning a fork, and without the code leaving this
repository where the compiler keeps it honest against every core change.
See [`../patternflow/features/README.md`](../patternflow/features/README.md) for
what a feature is and the hooks it can answer.
07e931b46This file is pinned to the selected release. Download the original to open it in your design tool.