Gee
2196633ed5
Some checks failed
check / check (push) Has been cancelled
First commit of the repo. Contents beyond the v0.1 simulator and layout: - Full Pico 2 W firmware (firmware/app, drivers, engine port, host test). - BANK page and 404 mode A/B removed; learned pads play exactly what was learned. - 404/MiniFreak renamed to KIT/SYNTH throughout (jacks, code, sim, docs, layout labels; wiring rebuilt). - ROLL returns to page select after a re-roll; a freshly learned track turns on. - LCD contrast 66. - ROOT and SCALE pages: 21 scales, AUTO = the seed picks; global and sticky. Intended music change: the scale table grew from 8 to 21 and AUTO picks from all of them, so every seed's scale changed. Vectors regenerated with npm run vectors, plus new key-override cases. Flash record is now version 2. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
50 lines
2.7 KiB
Markdown
50 lines
2.7 KiB
Markdown
# CLAUDE.md
|
||
|
||
Seedbox: a generative MIDI rhythm and melody machine for the Raspberry Pi Pico 2 W. v0.1 is a browser simulator with a finished engine, and a checked stripboard layout. The next job is the C firmware.
|
||
|
||
Read first: `README.md`, `docs/concept.md`, `firmware/README.md`, `docs/decisions.md`.
|
||
|
||
## Ground rules
|
||
|
||
- **`sim/engine.js` is the musical reference.** The C engine must reproduce `test/vectors/` exactly. Don't "fix" the C to sound better: change the JS, listen, regenerate, commit both.
|
||
- **Never regenerate the vectors to make a failing port pass.** `npm run vectors` is only for intended changes to the music. Say so in the commit message.
|
||
- **Keep the engine integer-only and deterministic.**
|
||
- No `Math.random`, no floats in decisions, no wall-clock time.
|
||
- Use floor division through `fdiv`/`mod`.
|
||
- **`hardware/layout.js` is the only source for the stripboard.**
|
||
- After any change, run `node hardware/check-layout.js`; it must print `layout clean`.
|
||
- Then run `node tools/build-wiring.js`.
|
||
- Don't hand-edit `tools/wiring.html`.
|
||
- **Hardware facts that can't be checked here** (lug order on the user's TRS jacks, Nokia BL polarity): flag them; don't guess.
|
||
- **RP2350**:
|
||
- Inputs use pull-ups (erratum E9).
|
||
- Set GP0/GP4 drive strength to 8–12 mA.
|
||
- The pin map in `docs/hardware/pinout.md` is fixed by the board that's being built; don't move pins without updating `layout.js` and re-running the checker.
|
||
|
||
## Commands
|
||
|
||
```sh
|
||
npm test # vectors + layout, must pass before every commit
|
||
npm run vectors # regenerate vectors (intended music changes only)
|
||
node hardware/check-layout.js --nets
|
||
node tools/build-wiring.js
|
||
npx serve . → http://localhost:3000/sim/ # simulator (Web MIDI needs localhost/https)
|
||
```
|
||
|
||
No npm dependencies. Node 18+.
|
||
|
||
## Layout
|
||
|
||
- `sim/` simulator: `engine.js` (portable; also `require`-able from Node), `app.js` (browser UI, Web MIDI, scheduler, screen renderer), `index.html`.
|
||
- `test/` `cases.js` (the case list), `render.js`, `gen-vectors.js`, `check-vectors.js`, `vectors/*.json`.
|
||
- `hardware/` `layout.js`, `check-layout.js`.
|
||
- `tools/` single-file bench pages: `wiring.html` (built), `bom.html`, `panel.html`; `wiring-src/` holds the parts `wiring.html` is built from.
|
||
- `docs/` user-facing docs; `docs/hardware/svg` and the CSVs are exports from the tools.
|
||
- `firmware/` empty except the plan. Suggested structure is in its README.
|
||
|
||
## Conventions
|
||
|
||
- The user (Gee) builds by hand: stripboard, hookup wire, panel-mount parts. Write instructions as strip letter + hole number, with colour roles from `docs/hardware/wiring.md`.
|
||
- Docs are plain and short. Tables over prose for anything you'd look up.
|
||
- Commit vectors and engine changes together. Commit layout and rebuilt wiring together.
|