bom-generator

BOM 生成器

为创客项目创建包含供应商链接和兼容性检查的详尽物料清单。

资源

• scripts/generate_bom.py - 用于生成 xlsx/csv/markdown 物料清单的 Python 脚本（需要 openpyxl）
• references/example-bom.md - 完整的物料清单示例
• assets/example-project.json - 脚本的示例项目配置

快速入门

交互式生成物料清单：

uv run --no-project scripts/generate_bom.py --interactive

根据 JSON 配置生成：

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

列出组件数据库：

uv run --no-project scripts/generate_bom.py --list

导出格式：xlsx（默认）、csv、md、json

适用场景

• 用户描述了一个项目，需要零件清单
• 用户询问“做 X 需要哪些组件”
• 用户想为某个设计订购零件
• 用户需要估算成本

工作流

步骤 1：收集项目需求

询问用户：

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)

步骤 2：生成物料清单

运行 scripts/generate_bom.py --interactive 进行引导式生成，或使用以下模板格式：

# 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]

组件数据库

微控制器

开发板	电压	GPIO	闪存	价格范围	最适合
Arduino UNO R3	5V	14	32KB	$12-25	初学者、大多数教程
Arduino Nano	5V	14	32KB	$3-20	紧凑型项目
Arduino Mega	5V	54	256KB	$15-40	需要大量 I/O、程序较大的项目
ESP32 DevKit	3.3V	34	4MB	$5-15	WiFi、Bluetooth、IoT
ESP32-C3	3.3V	22	4MB	$4-10	低成本 WiFi
RP2040 Pico	3.3V	26	2MB	$4-6	双核、PIO
RP2040 Pico W	3.3V	26	2MB	$6-8	Pico + WiFi

常见传感器

传感器	接口	电压	价格	用途
DHT22/AM2302	1-Wire	3.3-5V	$3-8	温度 + 湿度
BME280	I2C/SPI	3.3V	$5-15	温度 + 湿度 + 气压
BMP280	I2C/SPI	3.3V	$2-8	温度 + 气压（无湿度）
DS18B20	1-Wire	3-5.5V	$2-5	防水温度测量
HC-SR04	GPIO	5V	$1-3	超声波测距
VL53L0X	I2C	3.3V	$5-12	激光测距（精度高）
MPU6050	I2C	3.3V	$2-8	加速度计 + 陀螺仪
BNO055	I2C	3.3V	$25-35	9-DOF IMU（精度最高）
VEML7700	I2C	3.3V	$4-8	环境光（lux）
MAX30102	I2C	3.3V	$5-12	心率 + SpO2

显示屏

显示屏	接口	分辨率	价格	备注
16x2 LCD	I2C	16 字符	$3-8	需要 I2C 背板
20x4 LCD	I2C	20 字符	$5-12	更大的文本显示屏
SSD1306 OLED	I2C	128x64	$3-8	显示清晰，无需背光
SSD1306 OLED	I2C	128x32	$3-6	紧凑型 OLED
ST7735 TFT	SPI	128x160	$5-10	彩色，刷新速度快
ILI9341 TFT	SPI	240x320	$8-15	更大的彩色显示屏
E-Paper	SPI	各种	$15-40	低功耗，无需刷新

电机与执行器

类型	所需驱动器	价格	备注
SG90 舵机	无（PWM）	$2-5	180°，扭矩较弱
MG996R 舵机	无（PWM）	$5-10	扭矩大，金属齿轮
28BYJ-48 步进电机	ULN2003	$3-6	便宜、速度慢、扭矩弱
NEMA17 步进电机	A4988/DRV8825	$8-15	扭矩大、精度高
直流电机 + 减速箱	L298N/TB6612	$5-15	可提供高转速
线性执行器	L298N	$15-40	推拉运动

电机驱动器

驱动器	通道数	最大电流	电压	价格
L298N	2	2A/ch	5-35V	$3-8
TB6612FNG	2	1.2A/ch	4.5-13.5V	$3-8
A4988	1 个步进电机	2A	8-35V	$2-5
DRV8825	1 个步进电机	2.5A	8.2-45V	$3-6
TMC2209	1 个步进电机	2A	4.75-28V	$8-15

电源元件

元件	规格	价格	用途
LM7805	5V 1A 线性稳压	$0.50	简单的 5V 稳压
AMS1117-3.3	3.3V 1A 线性稳压	$0.30	将 5V 转为 3.3V
LM2596 Module	可调 3A 降压	$2-4	高效降压
MT3608 Module	可调 2A 升压	$1-3	升高电压
TP4056 Module	LiPo 充电器	$1-2	电池充电
18650 Holder	1-4 节电池	$1-5	安装电池
JST Connectors	2 针	$2-5/10pk	电池连接

无源元件（购买套件！）

套件类型	典型内容	价格	建议
电阻套件	600+ 个，1/4W	$8-15	买一次，用一辈子
电容套件	陶瓷电容 + 电解电容	$10-20	必备
LED 套件	多种颜色的 5mm LED	$5-10	满足常见需求
按钮套件	轻触开关	$5-8	多种尺寸
二极管套件	1N4148、1N4007 等	$5-8	保护电路

供应商指南

速度与成本的权衡

供应商	配送时间	价格	最适合
DigiKey	1-3 天	$$$	规格精准、提供数据手册、急需时
Mouser	1-3 天	$$$	选择丰富、品质可靠
Amazon	1-2 天	$$	快速配送、退货方便
Adafruit	3-5 天	$$$	品质、教程、支持
SparkFun	3-5 天	$$$	扩展板、学习
AliExpress	2-6 周	$	批量采购、预算有限、兼容品
LCSC	1-2 周	$$	中国元件、品质良好

零件编号模式

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

兼容性检查

电压电平矩阵

                     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

电流预算检查

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 地址冲突

需要留意的常见 I2C 地址：

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

输出格式选项

Markdown 表格（默认）

最适合文档和 GitHub README。

CSV 导出

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

购物车链接

尽可能提供直接的“加入购物车”链接。

BOM 输出示例

完整示例请参阅 references/example-bom.md。

共享输出约定

使用共享 Arduino 技能约定： 说明假设、所需工具及版本、实现步骤、 各证明阶段的测试/证据、已知限制，以及恢复/安全注意事项。