Each ADR captures one significant decision: its context, the choice, and the consequences. They are immutable once accepted; a later ADR supersedes an earlier one rather than editing it.
| # | Decision | Status |
|---|---|---|
| 0001 | Build PyBLE as a separate project, not an extension of an existing closed-source product | Accepted |
| 0002 | Use a fresh, clean-room protocol (PBLE/1), not a reused one | Accepted |
| 0003 | License the project MIT, free, donation-supported (Thonny model) | Accepted |
| 0004 | Name the project PyBLE ("Python over BLE") | Accepted |
| 0005 | Use a standalone domain (pyble.dev/.org), not a subdomain of a commercial site |
Accepted |
| 0006 | Build the firmware agent as native C from day one (not frozen-Python first) | Accepted |
| 0007 | Use Riverpod as the app's single declarative state-management approach (closes App OI-2) | Accepted |
| 0008 | Adopt "Signal", the app's adaptive Material 3 design system (seed #2D5BFF, light+dark, offline-first) |
Accepted |
| 0009 | Hold the active Connection as a runtime session behind a neutral ConnectionManager in lib/pble (enables real scan/connect) |
Accepted |
| 0010 | Working-loop current document is a volatile in-memory provider; feature packages cross-import public providers; Drift persistence deferred to A-24 | Accepted |
| 0011 | Connection-gated shell: Connect is a full-screen pre-connection surface (no IDE chrome until a board is ready), not an IDE tab; Disconnect moves to the toolbar | Accepted |
| 0012 | Adopt flutter_code_editor behind an EditorSurface interface as the Python editor, with the plain field retained as a live fallback (closes App OI-1; bounds R1) |
Accepted |
| 0013 | Host pinned Blockly offline as a clean-room, one-way Blocks → Python surface over the shared file-backed editor actions | Accepted |
| 0014 | Make Blocks a first-class, canvas-first landscape destination with a conditional Python inspector and on-demand console | Accepted |
| 0015 | Add a clean-room, composable digital-GPIO block set that generates standard MicroPython machine.Pin code with no board profile |
Accepted |
| 0016 | Ship six offline, editable beginner Blocks examples with explicit GPIO selection, generated-source preview, and no automatic execution | Accepted |
| 0017 | Reopen Blocks exactly through a verified sidecar and convert an explicit beginner Python subset through an all-or-nothing offline importer | Accepted |
| 0018 | Freeze upstream MicroPython NeoPixel into every firmware target and expose its standard API through generic Blocks, examples, and bounded reverse conversion | Accepted |
| 0019 | Build the public site as a statically exported Next.js app under tools/web/ |
Accepted |
| 0020 | Package the static Next.js site for Sites with vinext | Accepted |
| 0021 | Define PyBLE's board scope by MicroPython + BLE capability, with ESP32 as the initial reference family | Accepted |
| 0022 | Host the canonical static site on a Cloudflare-fronted VPS | Accepted |
Decided 2026-06-30 (0001–0005); 0006 accepted 2026-07-01; 0007, 0008, 0009 and 0010 accepted 2026-07-02; 0011 accepted 2026-07-03; 0012 accepted 2026-07-25; 0013 accepted 2026-07-27; 0014, 0015, 0016, and 0017 accepted 2026-07-28; 0018–0022 accepted 2026-07-29.