https://github.com/yoelf22/electrum
A structured, AI-assisted toolkit for defining hardware products that have software inside — from concept through engineering spec to presentation-ready materials in eight phases.
https://github.com/yoelf22/electrum
awesome-iot claude-code claude-skill embedded-systems firmware hardware hardware-software iot product-definition product-management
Last synced: 4 days ago
JSON representation
A structured, AI-assisted toolkit for defining hardware products that have software inside — from concept through engineering spec to presentation-ready materials in eight phases.
- Host: GitHub
- URL: https://github.com/yoelf22/electrum
- Owner: yoelf22
- License: mit
- Created: 2026-02-20T09:05:38.000Z (4 months ago)
- Default Branch: master
- Last Pushed: 2026-05-28T15:41:43.000Z (20 days ago)
- Last Synced: 2026-05-28T17:23:02.935Z (20 days ago)
- Topics: awesome-iot, claude-code, claude-skill, embedded-systems, firmware, hardware, hardware-software, iot, product-definition, product-management
- Language: Python
- Homepage: https://github.com/yoelf22/electrum/blob/master/examples/bubbler-automated-soap-bubble-maker/WALKTHROUGH.md
- Size: 27.7 MB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-iot - Electrum - A structured, AI-assisted toolkit for defining hardware products that have software inside — from concept through engineering spec to presentation-ready materials in eight phases. (Table of Contents / Software)
- awesome-iot - Electrum ★ 4 ⧗ 1 - A structured, AI-assisted toolkit for defining hardware products that have software inside — from concept through engineering spec to presentation-ready materials in eight phases. (Toolkits Include Non-OS / Android Things)
README
# Electrum — Product Definition Toolkit for Software-Augmented Hardware
*Status: v0.1 — exercised on 7 worked examples (see [`examples/`](examples/)), MIT-licensed.*
## The Problem
Software PMs have established tools — user stories, PRDs, sprint planning. Pure hardware PMs have theirs — datasheets, BOMs, DFM checklists. But when the product is *both* — firmware-driven hardware with sensors, actuators, maybe an app, maybe cloud — most PMs either use a software PRD template that ignores physics, or a hardware spec that ignores the software.
The boundary between HW and SW is where the expensive mistakes happen, and it's usually the least documented part.
## Quickstart for PMs and Product Strategists
You have a connected product idea and want to stress-test it before committing resources. Here's the fastest path:
```bash
# 1. Install Claude Code (https://docs.anthropic.com/en/docs/claude-code)
# 2. Clone this repo and open a terminal in it
git clone https://github.com/yoelf22/electrum.git && cd electrum
# 3. Start Claude Code and run the skill
claude
> /electrum
```
The process will walk you through a structured dialogue — mapping the HW/SW boundary, forcing specifics, and surfacing what you're still assuming. It pauses after every output for your review. Budget 60–90 minutes for a full run.
**Don't have Claude Code?** The templates work without AI. Copy `templates/system_description_template.md` into your project folder, fill it in by hand, then run through `templates/checklist.md`. That's 80% of the value.
**Want to see what a full run looks like?** Read the [Bubbler walkthrough](examples/bubbler-automated-soap-bubble-maker/WALKTHROUGH.md) — a soup-to-nuts example that turned "automated soap bubble machine" into a force-sensing feedback system with a 90-item gate review.
---
## What This Toolkit Does
A repeatable, AI-assisted process for defining hardware products that have software inside them — so the firmware team and the mechanical team aren't surprised by each other at EVT.
It takes a product idea from "I think this could work" through to a structured system description, product illustrations, and a presentation-ready carousel. Eight phases, driven by the `/electrum` Claude Code skill:
| Phase | Output | Description |
|-------|--------|-------------|
| 1. **Explore** | `explore_notes.md` | Map the HW/SW boundary, identify knowledge gaps, surface risks |
| 2. **High-Level Design** | `high_level_design.md` | Single-page system overview: blocks, interfaces, constraints, hardest problems |
| 3. **Component Arrangement** | `component_arrangement.md`, `arrangement_options.png` | Spatial layout alternatives — where boards, batteries, sensors, and actuators sit relative to each other and the enclosure |
| 4. **System Description** | `system_description.md` | Full engineering-grade spec with real components, power budgets, firmware architecture |
| 5. **Gate Checklist** | `gate_checklist.md` | Validate completeness across both domains (90 items, PASS/FAIL/N/A) |
| 6. **Product Visual** | `product_visual.png` | Pick an existing diagram from earlier phases (or a user-supplied image) as the carousel visual |
| 7. **PPTX Carousel** | `*_Carousel.pptx` | LinkedIn-format slide deck (4:5 portrait, dark theme, 8 pages) |
| 8. **PDF Carousel** | `*_Carousel.pdf` | Same carousel as multi-page PDF |
Phases 1-5 produce the engineering definition. Phases 6-8 turn it into visual presentation materials.
## Prerequisites
### Python dependencies
```bash
pip install -r requirements.txt
```
Required packages: `python-pptx`, `reportlab`, `playwright`, `matplotlib`, `numpy`.
### Playwright browser (for image generation)
```bash
pip install playwright
python -m playwright install chromium
```
### Claude Code (for the `/electrum` skill)
Install [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and open a terminal in this repo. The `/electrum` skill is automatically available:
```bash
claude
> /electrum smart posture-correcting office chair
```
## Repository Structure
```
├── scripts/ # Python reference implementations (carousel, diagrams, deck builders)
├── templates/ # Directive markdown files (workflow, checklists, templates)
├── examples/ # Worked examples with full output artifacts
│ ├── bubbler-automated-soap-bubble-maker/ ← start here (has WALKTHROUGH.md)
│ ├── pop-miniature-popcorn-machine/
│ ├── metronome/
│ ├── chair_balancing_act/
│ ├── consumable-electric-toothbrush/
│ ├── shusher/
│ └── smart_sensor_hub/
└── output/ # Raw output from recent runs
```
## What's in the Box
### Templates and Checklists
| File | What it does |
|------|-------------|
| `electrum/templates/hw_sw_product_initiation.md` | 8-phase workflow from concept to presentation |
| `electrum/templates/hw_sw_high_level.md` | Single-page system overview template |
| `electrum/templates/system_description_template.md` | Full system description template with HW↔SW boundary items |
| `electrum/templates/checklist.md` | Gate checklist — 90 items, each tagged if it targets the HW/SW boundary |
| `electrum/templates/skills_map.md` | 16 competency areas a PM should understand or staff for |
| `.claude/skills/electrum/SKILL.md` | Claude Code skill definition (drives the 8-phase workflow) |
### Reference Scripts
| File | What it does |
|------|-------------|
| `electrum/scripts/generate_illustration.py` | DALL-E image generation via Playwright browser automation |
| `electrum/scripts/build_carousel.py` | PPTX + PDF carousel builder (LinkedIn-format, 4:5 portrait) |
| `electrum/scripts/build_deck.py` | Executive product overview deck builder |
| `electrum/scripts/build_high_level_deck.py` | High-level design deck builder |
| `electrum/scripts/visualize.py` | Visualization utilities |
| `electrum/scripts/block_diagram.py` | Block diagram generator |
### Worked Examples
| Project | What it is | Phases covered |
|---------|-----------|----------------|
| [`bubbler-automated-soap-bubble-maker/`](examples/bubbler-automated-soap-bubble-maker/) | Force-sensing automated bubble machine with adaptive optimization — **[full walkthrough](examples/bubbler-automated-soap-bubble-maker/WALKTHROUGH.md)** | All 8 phases |
| `pop-miniature-popcorn-machine/` | Miniature countertop popcorn machine with heating and motor control | Explore, HLD, system description, gate checklist, carousel |
| `metronome/` | Wrist-worn haptic metronome bracelet for musicians — silent, precise beat pulses | All phases |
| `chair_balancing_act/` | Clip-on tilt sensor that plays an escalating tone when a chair leaves static balance | HLD, system description, gate checklist |
| `consumable-electric-toothbrush/` | Disposable electric toothbrush with wear tracking | Full |
| `shusher/` | Noise-aware mechanical mute device with sound detection | HLD, system description, gate checklist |
| `smart_sensor_hub/` | Wireless indoor environment monitor (CO2, temp, humidity, PM) with BLE mesh | HLD, system description |
The bubbler example includes a [step-by-step walkthrough](examples/bubbler-automated-soap-bubble-maker/WALKTHROUGH.md) showing what each phase surfaced and what the team would have missed without the process.
## How to Use
### With Claude Code (recommended)
1. Open a terminal in this repo
2. Run `claude` to start Claude Code
3. Type `/electrum `
4. Walk through all 8 phases interactively — Claude drafts, you review and refine at each step
5. Final output: a complete product definition + diagrams + presentation deck
### Without Claude Code
The core toolkit is markdown templates and checklists — no AI required:
1. **Understand the process** — Read `electrum/templates/hw_sw_product_initiation.md` for the workflow overview
2. **Assess your gaps** — Review `electrum/templates/skills_map.md` for team competency planning
3. **Create the high-level design** — Copy `electrum/templates/hw_sw_high_level.md` into your project folder and fill it in
4. **Write the system description** — Copy `electrum/templates/system_description_template.md` and work through each section
5. **Validate** — Run through `electrum/templates/checklist.md` to confirm nothing was missed
For image generation and carousel building, adapt the scripts in `electrum/scripts/` to your product.
## Who This is For
Hardware product managers and technical leads building products where physical hardware and software must be designed together. The toolkit is most useful when:
- Your product has firmware, and maybe a companion app or cloud backend
- Your team spans EE/ME and software disciplines
- You need documents that both an executive and an engineer can use
- You want presentation-ready materials alongside the engineering spec
- You've been burned before by HW/SW integration surprises at EVT
---
## Part of *Tangibles*
Electrum is the open-source companion to **[Tangibles](https://tangibles-book.com)** — a book on building connected hardware your competitors can't copy. The book's companion site hosts an overview of Electrum plus a set of free, no-signup tools for connected-hardware teams:
- **[Electrum overview](https://tangibles-book.com/tools/electrum)** — what this toolkit is, with worked examples
- **[IoT Security Scorecard](https://tangibles-book.com/tools/iot-security-scorecard)** — grade your device against ETSI EN 303 645 / EU CRA
- **[Security Requirements Generator](https://tangibles-book.com/tools/iot-security-requirements)** — a PRD-ready requirements list
- **[Regulatory Landscape](https://tangibles-book.com/tools/regulatory-landscape)** — which frameworks bind your product, by market and archetype
By [Yoel Frischoff](https://theroadtlv.com).