initial: add all custom Claude.ai skills

This commit is contained in:
unavlab
2026-03-21 19:36:11 +03:00
commit 643e9b68b3
22 changed files with 2307 additions and 0 deletions
+214
View File
@@ -0,0 +1,214 @@
# MCU Database Schema Reference
## Schema Definition
```python
MCU_DB: dict[str, dict[str, dict]] = {
"<vendor>": {
"<family_id>": {
"description": str, # Human-readable family description
"core": str, # CPU core (e.g. "Cortex-M4F", "Xtensa LX7")
"voltage_profiles": [
{
"id": str, # e.g. "3v3_only", "1v8_core_3v3_io"
"vcore": float, # Core supply voltage
"vio": float, # I/O supply voltage
"vbat_supported": bool,
},
],
"packages": {
"<package_id>": {
"description": str, # e.g. "LQFP64, 10x10mm, 0.5mm pitch"
"pin_count": int,
"thermal_pad": bool, # QFN/DFN exposed pad
"pinmap": {
# int pin_number or str pin_name → pin definition
1: {
"signal": str, # Primary signal name
"roles": list[str], # ["power", "ground", "reset", "boot", "gpio", "analog"]
"af": list[str], # Alternate functions (optional)
},
},
"capabilities": {
"has_usb_fs": bool,
"has_usb_hs": bool,
"has_eth_mac": bool,
"has_can": bool,
"has_sdio": bool,
"uart_count": int,
"i2c_count": int,
"spi_count": int,
"adc_channels": int,
"dac_channels": int,
"timer_count": int,
"dma_channels": int,
# extensible — add any capability flags needed
},
},
},
},
},
}
```
## Key Design Decisions
- **Vendor as top-level key**: Allows unambiguous lookup when family names overlap.
- **Roles list, not single role**: A pin can be both "gpio" and "analog" (e.g. PA0 on STM32).
- **Alternate functions (af)**: Matches STM32 AF model; for ESP32, use GPIO matrix mapping.
- **thermal_pad flag**: Reminds the generator to add GND connection for QFN/DFN pads.
- **Capabilities are flat**: Easier to query than nested structures. Add custom keys freely.
## Example: ST / STM32F4 / LQFP64
```python
MCU_DB = {
"ST": {
"STM32F4": {
"description": "High-performance Cortex-M4F, up to 180 MHz, FPU, DSP",
"core": "Cortex-M4F",
"voltage_profiles": [
{"id": "3v3_only", "vcore": 3.3, "vio": 3.3, "vbat_supported": True},
{"id": "1v8_core_3v3_io", "vcore": 1.8, "vio": 3.3, "vbat_supported": True},
],
"packages": {
"LQFP64": {
"description": "LQFP64, 10x10mm, 0.5mm pitch",
"pin_count": 64,
"thermal_pad": False,
"pinmap": {
1: {"signal": "VBAT", "roles": ["power"]},
2: {"signal": "PC13", "roles": ["gpio"], "af": ["RTC_AF1"]},
7: {"signal": "NRST", "roles": ["reset"]},
60: {"signal": "BOOT0", "roles": ["boot"]},
14: {"signal": "PA0", "roles": ["gpio", "analog"],
"af": ["ADC1_IN0", "TIM2_CH1", "USART2_CTS"]},
15: {"signal": "PA1", "roles": ["gpio", "analog"],
"af": ["ADC1_IN1", "TIM2_CH2", "USART2_RTS"]},
16: {"signal": "PA2", "roles": ["gpio", "analog"],
"af": ["ADC1_IN2", "TIM2_CH3", "USART2_TX"]},
17: {"signal": "PA3", "roles": ["gpio", "analog"],
"af": ["ADC1_IN3", "TIM2_CH4", "USART2_RX"]},
# ... fill from datasheet DS9716 Table 8
19: {"signal": "VSS", "roles": ["ground"]},
20: {"signal": "VDD", "roles": ["power"]},
},
"capabilities": {
"has_usb_fs": True,
"has_usb_hs": False,
"has_eth_mac": False,
"has_can": True,
"has_sdio": True,
"uart_count": 4,
"i2c_count": 3,
"spi_count": 3,
"adc_channels": 16,
"dac_channels": 2,
"timer_count": 14,
"dma_channels": 16,
},
},
},
},
},
"Espressif": {
"ESP32-S3": {
"description": "Dual-core Xtensa LX7, WiFi + BLE 5, AI acceleration",
"core": "Xtensa LX7 (dual)",
"voltage_profiles": [
{"id": "3v3_only", "vcore": 3.3, "vio": 3.3, "vbat_supported": False},
],
"packages": {
"ESP32-S3-MINI-1": {
"description": "Module, 15.4x20.5mm, castellated pads",
"pin_count": 55,
"thermal_pad": True,
"pinmap": {
1: {"signal": "GND", "roles": ["ground"]},
2: {"signal": "3V3", "roles": ["power"]},
3: {"signal": "EN", "roles": ["reset"]},
4: {"signal": "IO4", "roles": ["gpio", "analog"],
"af": ["ADC1_CH3", "TOUCH4"]},
5: {"signal": "IO5", "roles": ["gpio", "analog"],
"af": ["ADC1_CH4", "TOUCH5"]},
6: {"signal": "IO6", "roles": ["gpio", "analog"],
"af": ["ADC1_CH5", "TOUCH6"]},
7: {"signal": "IO7", "roles": ["gpio", "analog"],
"af": ["ADC1_CH6", "TOUCH7"]},
# ESP32 uses GPIO matrix — any GPIO can map to any peripheral
# af list shows default/recommended assignments
# ... fill from ESP32-S3-MINI-1 datasheet
},
"capabilities": {
"has_usb_fs": True, # USB-OTG
"has_usb_hs": False,
"has_eth_mac": False,
"has_can": True, # TWAI (CAN 2.0)
"has_sdio": True,
"has_wifi": True,
"has_ble": True,
"uart_count": 3,
"i2c_count": 2,
"spi_count": 3, # SPI0/SPI1 for flash; SPI2/SPI3 general
"adc_channels": 20,
"dac_channels": 0, # S3 has no DAC (S2 did)
"timer_count": 4, # General-purpose timers
"dma_channels": 5, # GDMA channels
"gpio_matrix": True, # Any GPIO → any peripheral
},
},
},
},
},
}
```
## Blank Template
Copy this to add a new MCU family:
```python
"<Vendor>": {
"<FAMILY>": {
"description": "",
"core": "",
"voltage_profiles": [
{"id": "3v3_only", "vcore": 3.3, "vio": 3.3, "vbat_supported": False},
],
"packages": {
"<PACKAGE_ID>": {
"description": "",
"pin_count": 0,
"thermal_pad": False,
"pinmap": {
# Fill from datasheet pinout table
},
"capabilities": {
"has_usb_fs": False,
"has_usb_hs": False,
"has_eth_mac": False,
"has_can": False,
"has_sdio": False,
"uart_count": 0,
"i2c_count": 0,
"spi_count": 0,
"adc_channels": 0,
"dac_channels": 0,
"timer_count": 0,
"dma_channels": 0,
},
},
},
},
},
```
## Validation
Run `scripts/validate_mcu_db.py` to check:
- All required keys present
- Pin numbers are unique within a package
- Every package has at least one "power" and one "ground" pin
- Capability counts are non-negative integers
- Voltage profiles have valid voltage ranges (0.5V5.5V)
+150
View File
@@ -0,0 +1,150 @@
# Power Supply Design Guide
## Topology Selection
| Topology | When to Use | Efficiency | Noise | Cost |
|----------|-------------|------------|-------|------|
| **LDO** | Vdrop < 1V, Iout < 500mA, noise-sensitive | Low (η ≈ Vout/Vin) | Very low | Low |
| **Buck** | Vdrop > 1V, Iout > 200mA, efficiency matters | High (85-95%) | Medium | Medium |
| **Buck + LDO chain** | High Vin, multiple rails, mixed noise needs | Good overall | Low on LDO rails | Medium |
| **Boost** | Vout > Vin (battery → 5V, etc.) | Medium (80-90%) | Medium-High | Medium |
| **Buck-Boost** | Vin can be above or below Vout | Medium | High | High |
| **Charge Pump** | Small current (<100mA), voltage doubling/inversion | Medium | High | Low |
### Decision Tree
```
Is Vin always > Vout?
├─ Yes → Is (Vin - Vout) < 1V AND Iout < 500mA?
│ ├─ Yes → LDO
│ └─ No → Is noise critical on this rail?
│ ├─ Yes → Buck + LDO (buck for bulk, LDO for clean rail)
│ └─ No → Buck
└─ No → Is Vin sometimes < Vout?
├─ Yes → Buck-Boost (or SEPIC)
└─ No → Boost
```
## Input Protection
Every power input should have:
1. **Reverse polarity protection**: P-MOSFET (preferred) or Schottky diode (simpler, lossy)
2. **Overvoltage / transient protection**: TVS diode rated above max operating voltage
3. **Inrush current limiting**: NTC thermistor or soft-start IC for high-capacitance designs
4. **Fuse**: Resettable PTC or standard fuse, rated for max expected current × 1.5
```python
# circuit-synth pattern: input protection block
@circuit(name="input_protection")
def input_protection(vin_raw, vin_protected, gnd):
fuse = Component(symbol="Device:Fuse_Small", ref="F", value="2A",
footprint="Fuse:Fuse_1206_3216Metric")
tvs = Component(symbol="Diode:TVS", ref="D_TVS", value="SMBJ15A",
footprint="Diode_SMD:D_SMA")
cin = Component(symbol="Device:C", ref="C_IN", value="10uF",
footprint="Capacitor_SMD:C_1206_3216Metric")
vin_raw += fuse[1]
fuse[2] += tvs["A"] # TVS anode to fused input
tvs["K"] += gnd # TVS cathode to ground (unidirectional)
vin_protected += fuse[2], cin[1]
gnd += cin[2]
```
## Decoupling Strategy
### Per-IC decoupling (mandatory)
- **100nF ceramic (X7R/X5R, 0402 or 0603)** on every VDD pin, placed as close as possible.
- For MCUs with VDDA (analog supply): separate 100nF + 1µF, with ferrite bead isolation.
- For MCUs with VCAP (internal regulator output): capacitor per datasheet (typically 2.2µF).
### Per-rail bulk capacitors
- **10µF ceramic** per power rail (at the regulator output).
- **100µF electrolytic/tantalum** for high-current rails (>500mA).
### High-frequency bypass
- **100nF + 10nF** pair for noise-sensitive analog circuits.
- Place smaller cap closest to IC pin.
### Layout rules
- Capacitor → IC pin via is shorter than capacitor → pour via.
- Ground vias under decoupling caps (direct path to ground plane).
- Never route high-speed signals under/near switching regulators.
## Common Regulator Reference Circuits
### LDO: AMS1117-3.3 (SOT-223)
```python
@circuit(name="ldo_3v3")
def ldo_3v3(vin, vout_3v3, gnd):
reg = Component(symbol="Regulator_Linear:AMS1117-3.3", ref="U_LDO",
footprint="Package_TO_SOT_SMD:SOT-223-3_TabPin2")
cin = Component(symbol="Device:C", ref="C_LDO_IN", value="10uF",
footprint="Capacitor_SMD:C_0805_2012Metric")
cout = Component(symbol="Device:C", ref="C_LDO_OUT", value="22uF",
footprint="Capacitor_SMD:C_0805_2012Metric")
vin += reg["VI"], cin[1]
vout_3v3 += reg["VO"], cout[1]
gnd += reg["GND"], cin[2], cout[2]
```
### Buck: TPS54331 (SOIC-8) — 3A, 3.5-28V input
```python
@circuit(name="buck_5v")
def buck_5v(vin, vout_5v, gnd):
buck = Component(symbol="Regulator_Switching:TPS54331", ref="U_BUCK",
footprint="Package_SO:SOIC-8_3.9x4.9mm_P1.27mm")
inductor = Component(symbol="Device:L", ref="L_BUCK", value="15uH",
footprint="Inductor_SMD:L_1210_3225Metric")
diode = Component(symbol="Diode:SS34", ref="D_BUCK",
footprint="Diode_SMD:D_SMA")
# Feedback resistors, bootstrap cap, input/output caps...
# (Complete circuit depends on exact target voltage)
vin += buck["VIN"]
buck["GND"] += gnd
buck["PH"] += inductor[1], diode["K"]
inductor[2] += vout_5v
diode["A"] += gnd
```
## Multi-Rail Design Patterns
### Pattern: 12V → 5V (Buck) → 3.3V (LDO) → 1.8V (LDO)
Good for: general-purpose MCU boards, moderate current.
```
VIN_12V ──→ [Buck] ──→ 5V rail (1A)
├──→ [LDO] ──→ 3.3V rail (500mA)
│ └──→ MCU VDD, peripherals
└──→ [LDO] ──→ 1.8V rail (200mA)
└──→ MCU VCORE (if separate)
```
### Pattern: USB 5V → 3.3V (LDO)
Good for: simple USB-powered devices.
```
USB_VBUS ──→ [Fuse 500mA] ──→ [LDO] ──→ 3.3V
```
### Pattern: Battery (3.0-4.2V) → 3.3V (Buck-Boost or LDO)
Good for: battery-powered IoT. LDO if battery always > 3.5V; buck-boost otherwise.
## Thermal Considerations
- Calculate power dissipation: `P = (Vin - Vout) × Iout` for LDO
- Check junction temperature: `Tj = Ta + P × θja`
- SOT-223 θja ≈ 65°C/W; SOIC-8 ≈ 125°C/W; QFN exposed pad ≈ 35°C/W
- If Tj > 125°C at max load → need larger package or switch to buck
@@ -0,0 +1,115 @@
# Review Checklists
## 1. Schematic Review Checklist
Walk through every item. Mark each as PASS / FAIL / N/A.
### Power
- [ ] Every VDD/AVDD/VDDIO pin has a dedicated 100nF decoupling cap (placed close)
- [ ] Bulk capacitor (10µF+) present on each power rail at regulator output
- [ ] VDDA isolated with ferrite bead + dedicated caps (if MCU has analog supply)
- [ ] VCAP pin has capacitor per datasheet value (STM32 specific)
- [ ] All GND pins connected (including exposed thermal pad on QFN/DFN)
- [ ] Power sequencing considered for multi-rail designs
- [ ] Regulator input/output caps meet datasheet ESR requirements
- [ ] Input protection present (TVS, fuse, reverse polarity) if external power
- [ ] USB VBUS has resettable fuse (500mA for device, per USB spec)
- [ ] Battery circuit has undervoltage lockout if applicable
### Reset & Boot
- [ ] NRST has 100nF cap to GND (RC filter for noise rejection)
- [ ] NRST has external pull-up (10kΩ typical) if not using reset IC
- [ ] BOOT0 pin pulled to defined state (typically GND via 10kΩ)
- [ ] BOOT1/other boot config pins at correct state for normal operation
- [ ] ESP32 EN pin: 10kΩ pull-up + 1µF cap (slow rise for reliable boot)
- [ ] ESP32 GPIO0: pull-up for normal boot, button to GND for programming
### Clock
- [ ] Crystal load capacitors calculated from datasheet formula:
`CL = (C1 × C2) / (C1 + C2) + Cstray`, where Cstray ≈ 3-5pF
- [ ] Crystal placed close to MCU oscillator pins (< 10mm trace length)
- [ ] Ground guard ring / pour around crystal area (EMI reduction)
- [ ] 32.768 kHz RTC crystal present if RTC needed (with its own load caps)
### Signal Integrity
- [ ] USB D+/D- have ESD protection diodes (TPD2E001, PRTR5V0U2X, or similar)
- [ ] USB D+/D- traces are 90Ω differential impedance (controlled, matched length)
- [ ] I2C bus has external pull-up resistors (4.7kΩ default; 2.2kΩ for fast-mode+)
- [ ] SPI chip-select lines have pull-ups (prevent floating during boot)
- [ ] UART TX/RX: series resistor (22-100Ω) if crossing board boundaries
- [ ] High-speed signals (>10 MHz) have series termination resistors
- [ ] CAN bus: 120Ω termination resistor at each end of bus
- [ ] Analog inputs: RC low-pass filter if reading noisy signals
### GPIO & Unused Pins
- [ ] No floating input pins (all unused GPIO tied high/low or set as output)
- [ ] LED current-limiting resistors present and correctly calculated
- [ ] Button/switch inputs have debounce circuit (RC or software)
- [ ] Test points on critical signals (power rails, I2C, SPI, UART)
### Connectors
- [ ] Programming/debug header present (SWD for ARM, JTAG if needed)
- [ ] USB connector shield connected to GND (directly or via 1MΩ + 4.7nF)
- [ ] All connector pins assigned and documented
- [ ] Mechanical mounting holes present (M3 at corners, connected to GND or float)
## 2. DRC/ERC Checklist (pre-KiCad)
These should be verified in the Python code before generating KiCad files:
- [ ] Every `Component` has `symbol`, `ref`, and `footprint` defined
- [ ] No duplicate reference designators (R1, R1 conflict)
- [ ] Every net has at least two connections (no dangling nets)
- [ ] Power nets (VCC, GND) are explicitly named and consistent
- [ ] No unconnected component pins that should be connected
- [ ] Component values are specified where needed (resistors, capacitors)
Post-KiCad-generation (in KiCad ERC):
- [ ] Run ERC in KiCad schematic editor — zero errors
- [ ] Run DRC in KiCad PCB editor — zero errors
- [ ] Check for unconnected pads in PCB
- [ ] Verify copper pour connectivity (GND plane continuous)
## 3. BOM Review Checklist
- [ ] All components have manufacturer part number (MPN) or generic value
- [ ] All components have valid KiCad footprint assigned
- [ ] No DNP (Do Not Place) components without documented reason
- [ ] Passive component values are standard E-series (E12/E24/E96)
- [ ] Capacitor dielectric specified (X7R/X5R for decoupling, C0G for precision)
- [ ] Capacitor voltage rating ≥ 2× operating voltage (derating)
- [ ] Resistor power rating adequate for application
- [ ] Check JLCPCB basic parts availability (cost optimization)
- [ ] Second-source alternatives identified for critical components
- [ ] Total unique part count minimized (fewer unique values = cheaper assembly)
## 4. Manufacturing Review (pre-Gerber)
- [ ] Board outline defined with correct dimensions
- [ ] Minimum trace width / spacing meets fab capability (typically 0.15mm/0.15mm)
- [ ] Via size meets fab capability (typically 0.3mm drill, 0.6mm annular ring)
- [ ] Silkscreen text readable (min 0.8mm height, 0.15mm line width)
- [ ] Component courtyard clearances respected (no overlaps)
- [ ] Fiducial marks present if using pick-and-place assembly
- [ ] Panel design considered if small board (add mouse bites / V-score lines)
## How to Use These Checklists
When generating or reviewing a circuit:
1. Complete the **Schematic Review** after writing all Python circuit files.
2. Run **DRC/ERC** checks both in Python (structural) and in KiCad (electrical).
3. Do **BOM Review** after `generate_bom()`.
4. Do **Manufacturing Review** after PCB layout, before generating Gerber files.
Report findings as:
- 🔴 **CRITICAL**: Must fix before fabrication (missing decoupling, floating pins, wrong voltage)
- 🟡 **WARNING**: Should fix, risk of intermittent issues (marginal thermal, no test points)
- 🟢 **SUGGESTION**: Nice to have, improves robustness (second-source parts, extra test points)