mirror of
https://github.com/mineracks/seedhammer-v1-companion.git
synced 2026-06-26 22:01:05 +10:00
3696dd6b34
A browser-based companion for SeedHammer v1 hardware. Three coordinated PWAs (composer, emulator, combined-sim) plus an optional Android wrapper, inspired by Gangleri42's SeedHammer II fork but retargeted to v1's Pi-Zero / WaveShare / MarkingWay hardware. What's in this commit: - LICENSE: Unlicense (matching upstream) - README.md: project overview + status + roadmap - CREDITS.md: upstream provenance + pinned baseline SHAs - docs/architecture/: five authoritative design docs (lifted from the prep work in mineracks-infrastructure): * BASELINES.md — pinned SHAs, license audit, path-mapping table * v1-engrave-spec.md — MarkingWay USB-serial wire protocol audit * v1-buttons-and-ui.md — GPIO map, UI screen flow, keyboard map * sh1e-spec.md — composer-to-Pi envelope format spec * seedsigner-reuse.md — Pyodide strategy + jumbo (SeedSigner+) support - Go package skeleton with doc.go contracts: backup, bezier, bspline, engrave, engrave/wire, engrave/wire/sh1e, font (+ comfortaa, poppins, constant), gui, input, internal/golden, platform/v1 - cmd/ entrypoints with stub main(): composer, emulator, combined-sim, seedsigner-sim - web/ static-shell skeleton - go.mod (module github.com/mineracks/seedhammer-v1-companion, Go 1.22) - go build ./... + go vet ./... both clean Next: lift universal packages (backup, font, bezier, bspline) from upstream seedhammer/seedhammer at v1.3.0 verbatim. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
91 lines
3.5 KiB
Markdown
91 lines
3.5 KiB
Markdown
# seedhammer-v1-companion
|
||
|
||
**Status:** early development. Phase 1 (composer port) in progress. See
|
||
[docs/architecture/](docs/architecture/) for the project plan and design
|
||
docs.
|
||
|
||
A browser-based companion for **SeedHammer v1** hardware (the original
|
||
Raspberry-Pi-Zero-based engraver), inspired by Gangleri42's SeedHammer II
|
||
fork. Ships three coordinated tools and one optional desktop wrapper.
|
||
|
||
## What this is
|
||
|
||
### 1. Plate composer (browser PWA)
|
||
|
||
Design a stainless steel seed-backup plate from your phone or desktop —
|
||
seed words, custom title text, optional logos — then transfer the design
|
||
to a real SeedHammer v1 controller via QR code.
|
||
|
||
The composer renders a pixel-faithful preview using the *same Go code the
|
||
Pi controller runs*. What you see in the browser is what the engraver
|
||
will physically punch.
|
||
|
||
The on-the-wire envelope is **SH1E** (a CBOR + CRC32 format documented at
|
||
[docs/architecture/sh1e-spec.md](docs/architecture/sh1e-spec.md)). Sized
|
||
to fit a 24-word multisig plate in a single QR frame, with BBQr fallback
|
||
for larger multi-plate manifests.
|
||
|
||
### 2. SeedHammer v1 emulator (browser PWA)
|
||
|
||
Run the real v1 controller firmware in your browser. The same `gui/`,
|
||
`input/`, and `engrave/` Go packages that drive the physical device,
|
||
compiled to WASM. Use it to:
|
||
|
||
- Test workflows end-to-end without a physical device
|
||
- Take screenshots / record screencasts of v1 flows
|
||
- Demo SeedHammer v1 to people without shipping hardware
|
||
|
||
Keyboard mapping: arrows = joystick, Enter = center/confirm, 1/2/3 = Button1/2/3.
|
||
|
||
### 3. Bundled SeedSigner emulator (browser PWA)
|
||
|
||
A faithful in-browser SeedSigner — both the classic 1.3" 240×240 model and
|
||
the newer 2.8" SeedSigner+ "jumbo" model. Generates seed-phrase QR codes
|
||
that you can hand off to the SeedHammer v1 emulator via a single button
|
||
press, end-to-end without leaving the page.
|
||
|
||
Built by hosting the upstream SeedSigner Python code via Pyodide so that
|
||
*the emulator IS the firmware* — when SeedSigner releases new versions
|
||
we bump the pinned commit and the sim updates.
|
||
|
||
### 4. Optional Android wrapper
|
||
|
||
Kotlin/Gradle shell hosting the composer WASM, for users who want a
|
||
plate-design app instead of a PWA. Mirrors the structure of Gangleri42's
|
||
SH2 Android companion.
|
||
|
||
## Hardware targeted
|
||
|
||
This codebase targets the **original SeedHammer v1** specifically — the
|
||
[Pi Zero v1.3 / WaveShare 1.3" 240×240 LCD HAT / MarkingWay engraver]
|
||
hardware. **Not** the newer SeedHammer II (RP2040 / TinyGo / SH2E NFC).
|
||
|
||
For an SH-II companion, use [Gangleri42's fork](https://github.com/Gangleri42/seedhammer)
|
||
directly. Most of the inspiration for this project comes from there.
|
||
|
||
## Status & roadmap
|
||
|
||
- ☐ **Phase 1** — composer port (Go-to-WASM, SH1E reference encoder, web UI)
|
||
- ☐ Phase 2 — v1 emulator (firmware-in-browser, Gangleri42-faithful UI shell)
|
||
- ☐ Phase 2.5 — SeedSigner emulator + QR handoff
|
||
- ☐ Phase 3 — combined three-pane sim
|
||
- ☐ Phase 4 — real-device validation on real v1 hardware
|
||
- ☐ Phase 5 (optional) — ColdCard emulator (port from Gangleri42's fork)
|
||
- ☐ Phase 6 (optional) — Android wrapper
|
||
|
||
## Building
|
||
|
||
(Will be documented as Phase 1 lands — `go build ./...` + a Vite build for
|
||
the web shells.)
|
||
|
||
## License
|
||
|
||
Released under the [Unlicense](LICENSE) (public domain dedication), matching
|
||
upstream SeedHammer's choice. SeedSigner-derived files segregated and
|
||
retain their MIT notice.
|
||
|
||
## Credits + provenance
|
||
|
||
Heavy lifting by three upstreams. See [CREDITS.md](CREDITS.md) for what
|
||
came from where and the pinned baseline commits.
|