# MCU Database Schema Reference ## Schema Definition ```python MCU_DB: dict[str, dict[str, dict]] = { "": { "": { "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": { "": { "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 "": { "": { "description": "", "core": "", "voltage_profiles": [ {"id": "3v3_only", "vcore": 3.3, "vio": 3.3, "vbat_supported": False}, ], "packages": { "": { "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.5V–5.5V)