name: bom-generator description: Generates Bill of Materials (BOM) from project descriptions for Arduino/ESP32/RP2040 projects. Use when user needs component lists, parts shopping lists, cost estimates, or asks "what parts do I need". Outputs formatted BOMs with part numbers, quantities, suppliers (DigiKey, Mouser, Amazon, AliExpress), and compatibility warnings. Run scripts/generate_bom.py for xlsx/csv export.

BOM Generator

Creates comprehensive Bill of Materials for maker projects with supplier links and compatibility checks.

Resources

scripts/generate_bom.py - Python script for xlsx/csv/markdown BOM generation (requires openpyxl)
references/example-bom.md - Complete example BOM
assets/example-project.json - Sample project configuration for script

Quick Start

Generate BOM interactively:

uv run scripts/generate_bom.py --interactive

Generate from JSON configuration:

uv run scripts/generate_bom.py --json assets/example-project.json --output bom.xlsx

List component database:

uv run scripts/generate_bom.py --list

Export formats: xlsx (default), csv, md, json

When to Use

User describes a project and needs parts list
User asks "what components do I need for X"
User wants to order parts for a design
User needs cost estimates

Workflow

Step 1: Gather Project Requirements

Ask user for:

1. Project description (what does it do?)
2. Target microcontroller (Arduino UNO/Nano/Mega, ESP32, RP2040)
3. Power source (USB, batteries, wall adapter)
4. Quantity (how many units to build?)
5. Budget constraints (optional)
6. Supplier preference (optional)

Step 2: Generate BOM

Run scripts/generate_bom.py --interactive for guided generation, or use this template format:

# Bill of Materials: [Project Name]

**Generated:** [Date]
**Target Board:** [MCU]
**Quantity:** [N] unit(s)
**Estimated Total:** $[X.XX] - $[Y.YY] (per unit)

## Core Components

| Qty | Component | Specifications | Est. Price | Supplier Links |
|-----|-----------|----------------|------------|----------------|
| 1 | [MCU Board] | [specs] | $X.XX | [DigiKey](#) / [Amazon](#) |
| ... | ... | ... | ... | ... |

## Sensors & Input

| Qty | Component | Specifications | Est. Price | Supplier Links |
|-----|-----------|----------------|------------|----------------|
| ... | ... | ... | ... | ... |

## Output Devices

| Qty | Component | Specifications | Est. Price | Supplier Links |
|-----|-----------|----------------|------------|----------------|
| ... | ... | ... | ... | ... |

## Power Components

| Qty | Component | Specifications | Est. Price | Supplier Links |
|-----|-----------|----------------|------------|----------------|
| ... | ... | ... | ... | ... |

## Passive Components

| Qty | Component | Specifications | Est. Price | Supplier Links |
|-----|-----------|----------------|------------|----------------|
| ... | ... | ... | ... | ... |

## Mechanical & Connectors

| Qty | Component | Specifications | Est. Price | Supplier Links |
|-----|-----------|----------------|------------|----------------|
| ... | ... | ... | ... | ... |

## Tools Required (if not owned)
- [ ] Tool 1
- [ ] Tool 2

## Compatibility Warnings
⚠️ [Any voltage/current/timing concerns]

## Substitution Notes
💡 [Alternative components if primary unavailable]

Component Database

Microcontrollers

Board	Voltage	GPIO	Flash	Price Range	Best For
Arduino UNO R3	5V	14	32KB	$12-25	Beginners, most tutorials
Arduino Nano	5V	14	32KB	$3-20	Compact projects
Arduino Mega	5V	54	256KB	$15-40	Many I/O, large programs
ESP32 DevKit	3.3V	34	4MB	$5-15	WiFi, Bluetooth, IoT
ESP32-C3	3.3V	22	4MB	$4-10	Low-cost WiFi
RP2040 Pico	3.3V	26	2MB	$4-6	Dual-core, PIO
RP2040 Pico W	3.3V	26	2MB	$6-8	Pico + WiFi

Common Sensors

Sensor	Interface	Voltage	Price	Use Case
DHT22/AM2302	1-Wire	3.3-5V	$3-8	Temperature + humidity
BME280	I2C/SPI	3.3V	$5-15	Temp + humidity + pressure
BMP280	I2C/SPI	3.3V	$2-8	Temp + pressure (no humidity)
DS18B20	1-Wire	3-5.5V	$2-5	Waterproof temperature
HC-SR04	GPIO	5V	$1-3	Ultrasonic distance
VL53L0X	I2C	3.3V	$5-12	Laser distance (accurate)
MPU6050	I2C	3.3V	$2-8	Accelerometer + gyroscope
BNO055	I2C	3.3V	$25-35	9-DOF IMU (best accuracy)
VEML7700	I2C	3.3V	$4-8	Ambient light (lux)
MAX30102	I2C	3.3V	$5-12	Heart rate + SpO2

Displays

Display	Interface	Resolution	Price	Notes
16x2 LCD	I2C	16 chars	$3-8	Need I2C backpack
20x4 LCD	I2C	20 chars	$5-12	Larger text display
SSD1306 OLED	I2C	128x64	$3-8	Sharp, no backlight needed
SSD1306 OLED	I2C	128x32	$3-6	Compact OLED
ST7735 TFT	SPI	128x160	$5-10	Color, fast refresh
ILI9341 TFT	SPI	240x320	$8-15	Larger color display
E-Paper	SPI	Various	$15-40	Low power, no refresh

Motors & Actuators

Type	Driver Needed	Price	Notes
SG90 Servo	None (PWM)	$2-5	180°, weak torque
MG996R Servo	None (PWM)	$5-10	Strong, metal gears
28BYJ-48 Stepper	ULN2003	$3-6	Cheap, slow, weak
NEMA17 Stepper	A4988/DRV8825	$8-15	Strong, precise
DC Motor + Gearbox	L298N/TB6612	$5-15	High speed available
Linear Actuator	L298N	$15-40	Push/pull motion

Motor Drivers

Driver	Channels	Max Current	Voltage	Price
L298N	2	2A/ch	5-35V	$3-8
TB6612FNG	2	1.2A/ch	4.5-13.5V	$3-8
A4988	1 stepper	2A	8-35V	$2-5
DRV8825	1 stepper	2.5A	8.2-45V	$3-6
TMC2209	1 stepper	2A	4.75-28V	$8-15

Power Components

Component	Specs	Price	Use Case
LM7805	5V 1A linear	$0.50	Simple 5V reg
AMS1117-3.3	3.3V 1A linear	$0.30	3.3V from 5V
LM2596 Module	Adj. 3A buck	$2-4	Efficient step-down
MT3608 Module	Adj. 2A boost	$1-3	Step-up voltage
TP4056 Module	LiPo charger	$1-2	Battery charging
18650 Holder	1-4 cells	$1-5	Battery mounting
JST Connectors	2-pin	$2-5/10pk	Battery connections

Passive Components (Buy Kits!)

Kit Type	Typical Contents	Price	Recommendation
Resistor Kit	600+ pcs, 1/4W	$8-15	Get once, use forever
Capacitor Kit	Ceramic + electrolytic	$10-20	Essential
LED Kit	5mm various colors	$5-10	Common needs
Button Kit	Tactile switches	$5-8	Various sizes
Diode Kit	1N4148, 1N4007, etc	$5-8	Protection circuits

Supplier Guide

Speed vs Cost Trade-offs

Supplier	Shipping	Price	Best For
DigiKey	1-3 days	$$$	Precise specs, datasheets, urgent
Mouser	1-3 days	$$$	Wide selection, quality
Amazon	1-2 days	$$	Quick delivery, returns easy
Adafruit	3-5 days	$$$	Quality, tutorials, support
SparkFun	3-5 days	$$$	Breakout boards, learning
AliExpress	2-6 weeks	$	Bulk, budget, clones
LCSC	1-2 weeks	$$	Chinese components, good quality

Part Number Patterns

DigiKey: Descriptive codes
  - 1N4007-TP → 1N4007 diode
  - SER0006 → Servo motor

Mouser: Manufacturer part numbers
  - Search by exact MPN

Amazon: ASIN codes
  - Search by product name + specs

AliExpress: Store + product ID
  - Check reviews, sold count

Compatibility Checks

Voltage Level Matrix

                     Can Connect To:
From:        3.3V Logic    5V Logic
─────────────────────────────────────
3.3V MCU     ✅ Direct     ⚠️ Level shifter
5V MCU       ⚠️ Divider    ✅ Direct
3.3V Sensor  ✅ Direct     ⚠️ May work*
5V Sensor    ❌ Damage!    ✅ Direct

* Some 3.3V sensors are 5V tolerant - check datasheet

Current Budget Check

Source Limits:
- Arduino 5V pin: 500mA max (from USB)
- Arduino GPIO: 40mA max per pin
- ESP32 3.3V: 500mA max
- ESP32 GPIO: 40mA max
- RP2040 GPIO: 16mA max

Always calculate:
Total current = Σ(component currents)
If total > source limit → external power needed

I2C Address Conflicts

Common I2C addresses to watch:

0x3C - SSD1306 OLED
0x27 - PCF8574 LCD backpack  
0x3F - PCF8574A LCD backpack
0x68 - MPU6050, DS3231 RTC
0x76 - BME280 (default)
0x77 - BME280 (alternate), BMP280
0x48 - ADS1115 ADC
0x50 - AT24C32 EEPROM

Output Format Options

Markdown Table (Default)

Best for documentation, GitHub READMEs.

CSV Export

Qty,Component,Specifications,Unit Price,Total,Supplier,Link
1,Arduino UNO R3,ATmega328P,15.00,15.00,Amazon,https://...

Shopping Cart Links

Provide direct "Add to Cart" links where possible.

Example BOM Output

See references/example-bom.md for complete example.

bom-generator

$ 설치