@typecad/mcu-esp32c3 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 typecad0
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# @typecad/mcu-esp32c3
+
+MCU definition package for the **ESP32-C3** (single-core 32-bit RISC-V @ 160 MHz, Wi-Fi 4 + BLE 5). Provides datasheet-level pin definitions, hardware peripheral descriptions, and HAL instances used by the TypeCAD transpiler and board packages.
+
+## Purpose
+
+MCU packages are the silicon layer — they define what pins exist on the chip and what peripherals are built into the silicon, independent of any board or framework. Board packages (e.g. [`@typecad/board-esp32c3`](../board-esp32c3)) import from here and add board-specific aliases.
+
+## What's inside
+
+- **`src/pins.ts`** — One `Pin.fromPort()` export per GPIO: `GPIO0`–`GPIO21`
+- **`src/peripherals.ts`** — Hardware peripheral descriptions (I2C, SPI, UART, ADC, timers, PWM) and auto-generated HAL instances (`I2C0`, `SPI0`, `UART0`, `ADC`)
+- **`src/mcu.ts`** — `MCU_PERIPHERALS` manifest consumed by board packages
+
+## ESP32-C3 peripheral summary
+
+| Peripheral | Count | Notes |
+|---|---|---|
+| **UART** | 2 | USART0–1 |
+| **I2C** | 1 | I2C0 (GPIO matrix) |
+| **SPI** | 3 | SPI0–2 (SPI0/1 for flash, SPI2 general-purpose) |
+| **ADC** | 2 | ADC1 (5 channels), ADC2 (1 channel), 12-bit |
+| **Timers** | 4 | 52-bit general-purpose timers |
+| **PWM (LEDC)** | 6 channels | 4 low-speed + 2 high-speed |
+
+## How board packages use this
+
+```typescript
+// In @typecad/board-esp32c3
+export * from '@typecad/mcu-esp32c3';   // silicon pins + peripherals
+export * from '@typecad/hal';           // HAL utilities (delay, Pin, etc.)
+```
+
+## Related packages
+
+- [`@typecad/board-esp32c3`](../board-esp32c3) — board package using this MCU
+- [`@typecad/hal`](../hal) — hardware abstraction layer
+- [`@typecad/mcu-atmega328p`](../mcu-atmega328p) — example of a fully-documented MCU package
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import type { MCUDefinition } from '@typecad/cuttlefish/api/schema';
+export declare const ESP32C3: MCUDefinition;
+export default ESP32C3;
+export * from './pins.js';
+export * from './peripherals.js';
+/**
+ * Structured manifest consumed by the TypeCAD CLI for contract-based
+ * board generation. Provides pin names and peripheral instance names
+ * without requiring the CLI to text-scrape compiled output.
+ */
+export declare const TypeCADManifest: {
+    /** All MCU port-level pin names (e.g. 'GPIO0', 'GPIO1'). */
+    readonly pinNames: readonly ["GPIO0", "GPIO1", "GPIO2", "GPIO3", "GPIO4", "GPIO5", "GPIO6", "GPIO7", "GPIO8", "GPIO9", "GPIO10", "GPIO12", "GPIO13", "GPIO14", "GPIO15", "GPIO16", "GPIO17", "GPIO18", "GPIO19", "GPIO20", "GPIO21"];
+    /** All HAL peripheral instance names exported from this package. */
+    readonly peripheralNames: readonly ["I2C0", "SPI0", "UART0", "UART1"];
+};

package/dist/index.js

@@ -0,0 +1,193 @@
+// ---------------------------------------------------------------------------
+// @typecad/mcu-esp32c3 — MCU definition manifest
+//
+// ESP32-C3 is a single-core RISC-V (RV32IMC) @ 160 MHz with Wi-Fi 4 + BLE 5
+// (long range) and native USB Serial/JTAG. It has 22 GPIO (0-10, 12-21);
+// GPIO 11 is consumed by internal flash Vpp and is not broken out. All GPIOs
+// are bidirectional. No DAC. No PSRAM support.
+// ---------------------------------------------------------------------------
+import { MCU_PERIPHERALS } from './peripherals.js';
+// ---------------------------------------------------------------------------
+// Default capability flags for ESP32-C3
+// ---------------------------------------------------------------------------
+const NO = false;
+const YES = true;
+/** Full GPIO: digital I/O + pull-up + pull-down + PWM + interrupt. */
+const FULL_GPIO = {
+    digitalInput: YES, digitalOutput: YES,
+    analogInput: NO, analogOutput: NO,
+    pwm: YES, interrupt: YES,
+    pullUp: YES, pullDown: YES,
+    touch: NO, openDrain: NO,
+};
+/** Full GPIO + analog input (ADC). */
+const FULL_GPIO_ANALOG = { ...FULL_GPIO, analogInput: YES };
+/** Full GPIO + analog input + touch. */
+const FULL_GPIO_ANALOG_TOUCH = { ...FULL_GPIO, analogInput: YES, touch: YES };
+// ---------------------------------------------------------------------------
+// Helper: build ADC/touch peripheral-function references.
+//
+// ADC1 channels: GPIO0..GPIO4 -> ch0..ch4 (always usable).
+// ADC2 channels: GPIO5 -> ch0 (NOT usable while Wi-Fi is on).
+// Touch channels: GPIO0..GPIO5 -> T0..T5.
+// ---------------------------------------------------------------------------
+function adc(n, ch) {
+    return { type: 'adc', instance: n, role: `ch${ch}` };
+}
+function touch(ch) {
+    return { type: 'touch', instance: 0, role: `touch${ch}` };
+}
+// ---------------------------------------------------------------------------
+// MCU definition
+// ---------------------------------------------------------------------------
+export const ESP32C3 = {
+    id: 'esp32-c3',
+    name: 'ESP32-C3',
+    architecture: 'esp32c3',
+    memory: {
+        flash: 384 * 1024, // usable app flash; remainder reserved by bootloader/OTADATA
+        sram: 400 * 1024, // 400 KB
+        eeprom: 0,
+        rtcMemory: 16 * 1024, // 16 KB RTC slow memory
+    },
+    pins: {
+        all: [
+            // ---- ADC1 + touch pins (GPIO0-GPIO4) ---------------------------------
+            { number: 0, gpio: 0, name: 'GPIO0', capabilities: FULL_GPIO_ANALOG_TOUCH,
+                functions: [adc(1, 0), touch(0)],
+                alternateFunctions: ['ADC1_CH0', 'Touch0'] },
+            { number: 1, gpio: 1, name: 'GPIO1', capabilities: FULL_GPIO_ANALOG_TOUCH,
+                functions: [adc(1, 1), touch(1)],
+                alternateFunctions: ['ADC1_CH1', 'Touch1'] },
+            { number: 2, gpio: 2, name: 'GPIO2', capabilities: FULL_GPIO_ANALOG_TOUCH,
+                functions: [adc(1, 2), touch(2)],
+                alternateFunctions: ['ADC1_CH2', 'Touch2'],
+                warnings: ['GPIO2 is a strapping pin — boot mode select at boot'],
+                unsafe: true, notes: 'Boot strapping pin' },
+            { number: 3, gpio: 3, name: 'GPIO3', capabilities: FULL_GPIO_ANALOG_TOUCH,
+                functions: [adc(1, 3), touch(3)],
+                alternateFunctions: ['ADC1_CH3', 'Touch3'] },
+            { number: 4, gpio: 4, name: 'GPIO4', capabilities: FULL_GPIO_ANALOG_TOUCH,
+                functions: [adc(1, 4), touch(4), { type: 'spi', instance: 0, role: 'sck' }],
+                alternateFunctions: ['ADC1_CH4', 'Touch4', 'SPI0 SCK'] },
+            // ---- ADC2 pin (GPIO5) — Wi-Fi conflicted ------------------------------
+            { number: 5, gpio: 5, name: 'GPIO5', capabilities: FULL_GPIO_ANALOG_TOUCH,
+                functions: [adc(2, 0), touch(5), { type: 'spi', instance: 0, role: 'miso' }],
+                alternateFunctions: ['ADC2_CH0', 'Touch5', 'SPI0 MISO'],
+                warnings: ['GPIO5 is ADC2 — ADC2 is unusable while Wi-Fi is enabled'] },
+            { number: 6, gpio: 6, name: 'GPIO6', capabilities: FULL_GPIO,
+                functions: [{ type: 'spi', instance: 0, role: 'mosi' }],
+                alternateFunctions: ['SPI0 MOSI'] },
+            { number: 7, gpio: 7, name: 'GPIO7', capabilities: FULL_GPIO,
+                functions: [{ type: 'spi', instance: 0, role: 'cs' }],
+                alternateFunctions: ['SPI0 CS'] },
+            { number: 8, gpio: 8, name: 'GPIO8', capabilities: FULL_GPIO,
+                functions: [{ type: 'i2c', instance: 0, role: 'sda' }],
+                alternateFunctions: ['I2C0 SDA'],
+                warnings: ['GPIO8 is a strapping pin — controls VDD_SPI voltage at boot'],
+                unsafe: true, notes: 'Boot strapping pin' },
+            { number: 9, gpio: 9, name: 'GPIO9', capabilities: FULL_GPIO,
+                functions: [{ type: 'i2c', instance: 0, role: 'scl' }],
+                alternateFunctions: ['I2C0 SCL'],
+                warnings: ['GPIO9 is a strapping pin — must be HIGH at boot (reset source)'],
+                unsafe: true, notes: 'Boot strapping pin' },
+            { number: 10, gpio: 10, name: 'GPIO10', capabilities: FULL_GPIO,
+                alternateFunctions: ['FSPICS0'] },
+            // ---- GPIO 11 — internal flash Vpp, not broken out on the C3 ----------
+            { number: 12, gpio: 12, name: 'GPIO12', capabilities: FULL_GPIO,
+                functions: [{ type: 'spi', instance: 1, role: 'sck' }],
+                alternateFunctions: ['FSPICLK'] },
+            { number: 13, gpio: 13, name: 'GPIO13', capabilities: FULL_GPIO,
+                functions: [{ type: 'spi', instance: 1, role: 'mosi' }],
+                alternateFunctions: ['FSPID'] },
+            { number: 14, gpio: 14, name: 'GPIO14', capabilities: FULL_GPIO,
+                functions: [{ type: 'spi', instance: 1, role: 'miso' }],
+                alternateFunctions: ['FSPIQ'] },
+            { number: 15, gpio: 15, name: 'GPIO15', capabilities: FULL_GPIO,
+                functions: [{ type: 'spi', instance: 1, role: 'cs' }],
+                alternateFunctions: ['FSPICS1'] },
+            { number: 16, gpio: 16, name: 'GPIO16', capabilities: FULL_GPIO,
+                alternateFunctions: [] },
+            { number: 17, gpio: 17, name: 'GPIO17', capabilities: FULL_GPIO,
+                alternateFunctions: [] },
+            // ---- USB Serial/JTAG pins (unsafe) -----------------------------------
+            { number: 18, gpio: 18, name: 'GPIO18', capabilities: FULL_GPIO,
+                functions: [{ type: 'usb', instance: 0, role: 'dm' }],
+                alternateFunctions: ['USB D-'],
+                warnings: ['GPIO18 is USB D- — using it as GPIO disables native USB Serial/JTAG'],
+                unsafe: true, notes: 'USB D- pin' },
+            { number: 19, gpio: 19, name: 'GPIO19', capabilities: FULL_GPIO,
+                functions: [{ type: 'usb', instance: 0, role: 'dp' }],
+                alternateFunctions: ['USB D+'],
+                warnings: ['GPIO19 is USB D+ — using it as GPIO disables native USB Serial/JTAG'],
+                unsafe: true, notes: 'USB D+ pin' },
+            // ---- UART0 default pins ----------------------------------------------
+            { number: 20, gpio: 20, name: 'GPIO20', capabilities: FULL_GPIO,
+                functions: [{ type: 'uart', instance: 0, role: 'rx' }],
+                alternateFunctions: ['UART0 RX'],
+                warnings: ['Using GPIO20 as GPIO will interfere with UART0 receive'] },
+            { number: 21, gpio: 21, name: 'GPIO21', capabilities: FULL_GPIO,
+                functions: [{ type: 'uart', instance: 0, role: 'tx' }],
+                alternateFunctions: ['UART0 TX'],
+                warnings: ['Using GPIO21 as GPIO will interfere with UART0 transmit'] },
+        ],
+        digital: [
+            'GPIO0', 'GPIO1', 'GPIO2', 'GPIO3', 'GPIO4', 'GPIO5', 'GPIO6', 'GPIO7',
+            'GPIO8', 'GPIO9', 'GPIO10',
+            'GPIO12', 'GPIO13', 'GPIO14', 'GPIO15', 'GPIO16', 'GPIO17',
+            'GPIO18', 'GPIO19', 'GPIO20', 'GPIO21',
+        ],
+        analog: [
+            'GPIO0', 'GPIO1', 'GPIO2', 'GPIO3', 'GPIO4', // ADC1
+            'GPIO5', // ADC2
+        ],
+        pwm: [
+            'GPIO0', 'GPIO1', 'GPIO2', 'GPIO3', 'GPIO4', 'GPIO5', 'GPIO6', 'GPIO7',
+            'GPIO8', 'GPIO9', 'GPIO10',
+            'GPIO12', 'GPIO13', 'GPIO14', 'GPIO15', 'GPIO16', 'GPIO17',
+            'GPIO18', 'GPIO19', 'GPIO20', 'GPIO21',
+        ],
+        unsafe: ['GPIO2', 'GPIO8', 'GPIO9', 'GPIO18', 'GPIO19'],
+        i2c: { 0: { sda: 'GPIO8', scl: 'GPIO9' } },
+        spi: {
+            0: { mosi: 'GPIO6', miso: 'GPIO5', sck: 'GPIO4', cs: 'GPIO7' }, // GPSPI2 / VSPI
+        },
+        uart: {
+            0: { tx: 'GPIO21', rx: 'GPIO20' },
+        },
+    },
+    // ----- Peripherals -------------------------------------------------------
+    peripherals: MCU_PERIPHERALS,
+    features: {
+        multicore: false,
+        coreCount: 1,
+        deepSleep: true,
+        watchdog: true,
+        externalInterrupts: true,
+        hardwareRng: true,
+        fpu: false,
+    },
+    build: {
+        extraFlags: [],
+    },
+};
+export default ESP32C3;
+// Re-exports
+export * from './pins.js';
+export * from './peripherals.js';
+/**
+ * Structured manifest consumed by the TypeCAD CLI for contract-based
+ * board generation. Provides pin names and peripheral instance names
+ * without requiring the CLI to text-scrape compiled output.
+ */
+export const TypeCADManifest = {
+    /** All MCU port-level pin names (e.g. 'GPIO0', 'GPIO1'). */
+    pinNames: [
+        'GPIO0', 'GPIO1', 'GPIO2', 'GPIO3', 'GPIO4', 'GPIO5', 'GPIO6', 'GPIO7',
+        'GPIO8', 'GPIO9', 'GPIO10',
+        'GPIO12', 'GPIO13', 'GPIO14', 'GPIO15', 'GPIO16', 'GPIO17',
+        'GPIO18', 'GPIO19', 'GPIO20', 'GPIO21',
+    ],
+    /** All HAL peripheral instance names exported from this package. */
+    peripheralNames: ['I2C0', 'SPI0', 'UART0', 'UART1'],
+};

package/dist/peripherals.d.ts

@@ -0,0 +1,58 @@
+import type { PeripheralInstance, ADCDefinition, PWMDefinition, TimerDefinition } from '@typecad/cuttlefish/api/schema';
+import { I2CBus, SPIBus, SerialPort } from '@typecad/hal';
+export declare const I2C_INSTANCES: readonly PeripheralInstance[];
+export declare const SPI_INSTANCES: readonly PeripheralInstance[];
+export declare const UART_INSTANCES: readonly PeripheralInstance[];
+export declare const ADC_INSTANCES: readonly ADCDefinition[];
+export declare const PWM_CAPABILITIES: PWMDefinition;
+export declare const TOUCH_CAPABILITIES: {
+    channels: number;
+    pins: string[];
+};
+export declare const TIMER_INSTANCES: readonly TimerDefinition[];
+export declare const WIFI_CAPABILITIES: {
+    readonly type: "wifi";
+    readonly supportsStation: true;
+    readonly supportsAp: true;
+};
+export declare const BLUETOOTH_CAPABILITIES: {
+    readonly type: "ble";
+    readonly version: "5.0";
+};
+export declare const USB_CAPABILITIES: {
+    readonly type: "otg";
+    readonly vid: "0x303A";
+    readonly pid: "0x0001";
+};
+export declare const MCU_PERIPHERALS: {
+    readonly i2c: readonly PeripheralInstance[];
+    readonly spi: readonly PeripheralInstance[];
+    readonly uart: readonly PeripheralInstance[];
+    readonly adc: readonly ADCDefinition[];
+    readonly pwm: PWMDefinition;
+    readonly touch: {
+        channels: number;
+        pins: string[];
+    };
+    readonly timers: readonly TimerDefinition[];
+    readonly wifi: {
+        readonly type: "wifi";
+        readonly supportsStation: true;
+        readonly supportsAp: true;
+    };
+    readonly bluetooth: {
+        readonly type: "ble";
+        readonly version: "5.0";
+    };
+    readonly usb: {
+        readonly type: "otg";
+        readonly vid: "0x303A";
+        readonly pid: "0x0001";
+    };
+};
+/** I2C bus instances */
+export declare const I2C0: I2CBus;
+/** SPI bus instances */
+export declare const SPI0: SPIBus;
+/** UART/Serial instances */
+export declare const UART0: SerialPort, UART1: SerialPort;

package/dist/peripherals.js

@@ -0,0 +1,69 @@
+// ---------------------------------------------------------------------------
+// @typecad/mcu-esp32c3 — Hardware peripheral descriptions
+//
+// ESP32-C3 peripherals: 1× I2C, 1× SPI (GPSPI2), 2× UART, 2× ADC (12-bit),
+// 6× capacitive-touch, 4× general-purpose timers, Wi-Fi 4, BLE 5 (long range),
+// native USB Serial/JTAG (CDC). No DAC.
+// ---------------------------------------------------------------------------
+import { I2CBus, SPIBus, SerialPort, i2cName, spiName, serialName, createHALInstances, } from '@typecad/hal';
+// ---------------------------------------------------------------------------
+// Peripheral definitions
+// ---------------------------------------------------------------------------
+export const I2C_INSTANCES = [
+    { instance: 0, defaultPins: { sda: 'GPIO8', scl: 'GPIO9' } },
+];
+export const SPI_INSTANCES = [
+    { instance: 0, defaultPins: { mosi: 'GPIO6', miso: 'GPIO5', sck: 'GPIO4', cs: 'GPIO7' } }, // GPSPI2
+];
+export const UART_INSTANCES = [
+    { instance: 0, defaultPins: { tx: 'GPIO21', rx: 'GPIO20' } },
+    { instance: 1, defaultPins: { tx: 'GPIO21', rx: 'GPIO20' } },
+];
+export const ADC_INSTANCES = [
+    { instance: 0, channels: 5, resolution: 12, referenceVoltage: 3.3, maxValue: 4095,
+        referenceVoltages: { DEFAULT: 3.3, INTERNAL: 1.1 } }, // ADC1 — usable with Wi-Fi active
+    { instance: 1, channels: 1, resolution: 12, referenceVoltage: 3.3, maxValue: 4095,
+        referenceVoltages: { DEFAULT: 3.3, INTERNAL: 1.1 } }, // ADC2 — NOT usable with Wi-Fi active
+];
+export const PWM_CAPABILITIES = {
+    channels: 6,
+    resolution: 14,
+    maxFrequency: 40_000_000,
+};
+export const TOUCH_CAPABILITIES = {
+    channels: 6,
+    pins: ['GPIO0', 'GPIO1', 'GPIO2', 'GPIO3', 'GPIO4', 'GPIO5'],
+};
+export const TIMER_INSTANCES = [
+    { instance: 0, type: 'general', bits: 64, features: ['interrupt'] },
+    { instance: 1, type: 'general', bits: 64, features: ['interrupt'] },
+    { instance: 2, type: 'general', bits: 64, features: ['interrupt'] },
+    { instance: 3, type: 'general', bits: 64, features: ['interrupt'] },
+];
+export const WIFI_CAPABILITIES = { type: 'wifi', supportsStation: true, supportsAp: true };
+export const BLUETOOTH_CAPABILITIES = { type: 'ble', version: '5.0' };
+export const USB_CAPABILITIES = { type: 'otg', vid: '0x303A', pid: '0x0001' };
+// ---------------------------------------------------------------------------
+// Aggregate MCU peripheral description
+// ---------------------------------------------------------------------------
+export const MCU_PERIPHERALS = {
+    i2c: [...I2C_INSTANCES],
+    spi: [...SPI_INSTANCES],
+    uart: [...UART_INSTANCES],
+    adc: [...ADC_INSTANCES],
+    pwm: PWM_CAPABILITIES,
+    touch: TOUCH_CAPABILITIES,
+    timers: [...TIMER_INSTANCES],
+    wifi: WIFI_CAPABILITIES,
+    bluetooth: BLUETOOTH_CAPABILITIES,
+    usb: USB_CAPABILITIES,
+};
+// ---------------------------------------------------------------------------
+// HAL object instances — auto-generated from peripheral definitions
+// ---------------------------------------------------------------------------
+/** I2C bus instances */
+export const [I2C0] = createHALInstances(I2C_INSTANCES, i => new I2CBus(i2cName(i)));
+/** SPI bus instances */
+export const [SPI0] = createHALInstances(SPI_INSTANCES, i => new SPIBus(spiName(i)));
+/** UART/Serial instances */
+export const [UART0, UART1] = createHALInstances(UART_INSTANCES, i => new SerialPort(serialName(i)));

package/dist/pins.d.ts

@@ -0,0 +1,38 @@
+import { Pin } from '@typecad/hal';
+export declare const GPIO0: Pin;
+export declare const GPIO1: Pin;
+export declare const GPIO2: Pin;
+export declare const GPIO3: Pin;
+export declare const GPIO4: Pin;
+export declare const GPIO5: Pin;
+export declare const GPIO6: Pin;
+export declare const GPIO7: Pin;
+export declare const GPIO8: Pin;
+export declare const GPIO9: Pin;
+export declare const GPIO10: Pin;
+export declare const GPIO12: Pin;
+export declare const GPIO13: Pin;
+export declare const GPIO14: Pin;
+export declare const GPIO15: Pin;
+export declare const GPIO16: Pin;
+export declare const GPIO17: Pin;
+export declare const GPIO18: Pin;
+export declare const GPIO19: Pin;
+export declare const GPIO20: Pin;
+export declare const GPIO21: Pin;
+/** I2C0 data line (GPIO8). */
+export declare const SDA: Pin;
+/** I2C0 clock line (GPIO9). */
+export declare const SCL: Pin;
+/** SPI0 MOSI (GPIO6). */
+export declare const MOSI: Pin;
+/** SPI0 MISO (GPIO5). */
+export declare const MISO: Pin;
+/** SPI0 clock (GPIO4). */
+export declare const SCK: Pin;
+/** SPI0 slave select (GPIO7). */
+export declare const SS: Pin;
+/** UART0 transmit (GPIO21). */
+export declare const TX: Pin;
+/** UART0 receive (GPIO20). */
+export declare const RX: Pin;

package/dist/pins.js

@@ -0,0 +1,52 @@
+// ---------------------------------------------------------------------------
+// @typecad/mcu-esp32c3 — Datasheet pin definitions
+//
+// Each pin is a Pin instance from @typecad/hal. The ESP32-C3 has 22 GPIO
+// (0-10, 12-21); GPIO 11 is consumed by internal flash Vpp and is not broken
+// out. All GPIOs are bidirectional (no input-only pins). DAC is not present.
+// ---------------------------------------------------------------------------
+import { Pin } from '@typecad/hal';
+// ---------------------------------------------------------------------------
+// Named GPIO constants (Pin instances)
+// ---------------------------------------------------------------------------
+export const GPIO0 = new Pin(0);
+export const GPIO1 = new Pin(1);
+export const GPIO2 = new Pin(2);
+export const GPIO3 = new Pin(3);
+export const GPIO4 = new Pin(4);
+export const GPIO5 = new Pin(5);
+export const GPIO6 = new Pin(6);
+export const GPIO7 = new Pin(7);
+export const GPIO8 = new Pin(8);
+export const GPIO9 = new Pin(9);
+export const GPIO10 = new Pin(10);
+// GPIO 11 — internal flash Vpp, not broken out on the C3 package.
+export const GPIO12 = new Pin(12);
+export const GPIO13 = new Pin(13);
+export const GPIO14 = new Pin(14);
+export const GPIO15 = new Pin(15);
+export const GPIO16 = new Pin(16);
+export const GPIO17 = new Pin(17);
+export const GPIO18 = new Pin(18);
+export const GPIO19 = new Pin(19);
+export const GPIO20 = new Pin(20);
+export const GPIO21 = new Pin(21);
+// ---------------------------------------------------------------------------
+// Convenience aliases (Silicon-level defaults — match Arduino-ESP32 core)
+// ---------------------------------------------------------------------------
+/** I2C0 data line (GPIO8). */
+export const SDA = GPIO8;
+/** I2C0 clock line (GPIO9). */
+export const SCL = GPIO9;
+/** SPI0 MOSI (GPIO6). */
+export const MOSI = GPIO6;
+/** SPI0 MISO (GPIO5). */
+export const MISO = GPIO5;
+/** SPI0 clock (GPIO4). */
+export const SCK = GPIO4;
+/** SPI0 slave select (GPIO7). */
+export const SS = GPIO7;
+/** UART0 transmit (GPIO21). */
+export const TX = GPIO21;
+/** UART0 receive (GPIO20). */
+export const RX = GPIO20;

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@typecad/mcu-esp32c3",
+  "version": "0.1.0-alpha.1",
+  "description": "TypeCAD MCU definition for ESP32-C3 — datasheet pins, peripheral capabilities, and HAL instances",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@typecad/cuttlefish": "0.1.0-alpha.1",
+    "@typecad/hal": "0.1.0-alpha.1"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/justind000/typecode.git",
+    "directory": "packages/mcu-esp32c3"
+  },
+  "homepage": "https://github.com/justind000/typecode/tree/main/packages/mcu-esp32c3",
+  "bugs": {
+    "url": "https://github.com/justind000/typecode/issues"
+  },
+  "keywords": [
+    "arduino",
+    "cpp",
+    "cuttlefish",
+    "embedded",
+    "esp32c3",
+    "firmware",
+    "mcu",
+    "microcontroller",
+    "peripherals",
+    "pins",
+    "silicon",
+    "typecad",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "typecad0",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  }
+}

package/src/index.ts

@@ -0,0 +1,226 @@
+// ---------------------------------------------------------------------------
+// @typecad/mcu-esp32c3 — MCU definition manifest
+//
+// ESP32-C3 is a single-core RISC-V (RV32IMC) @ 160 MHz with Wi-Fi 4 + BLE 5
+// (long range) and native USB Serial/JTAG. It has 22 GPIO (0-10, 12-21);
+// GPIO 11 is consumed by internal flash Vpp and is not broken out. All GPIOs
+// are bidirectional. No DAC. No PSRAM support.
+// ---------------------------------------------------------------------------
+
+import type { MCUDefinition } from '@typecad/cuttlefish/api/schema';
+import { MCU_PERIPHERALS } from './peripherals.js';
+
+// ---------------------------------------------------------------------------
+// Default capability flags for ESP32-C3
+// ---------------------------------------------------------------------------
+
+const NO  = false as const;
+const YES = true  as const;
+
+/** Full GPIO: digital I/O + pull-up + pull-down + PWM + interrupt. */
+const FULL_GPIO = {
+  digitalInput: YES, digitalOutput: YES,
+  analogInput: NO,   analogOutput: NO,
+  pwm: YES,          interrupt: YES,
+  pullUp: YES,       pullDown: YES,
+  touch: NO,         openDrain: NO,
+} as const;
+
+/** Full GPIO + analog input (ADC). */
+const FULL_GPIO_ANALOG = { ...FULL_GPIO, analogInput: YES } as const;
+
+/** Full GPIO + analog input + touch. */
+const FULL_GPIO_ANALOG_TOUCH = { ...FULL_GPIO, analogInput: YES, touch: YES } as const;
+
+// ---------------------------------------------------------------------------
+// Helper: build ADC/touch peripheral-function references.
+//
+// ADC1 channels: GPIO0..GPIO4 -> ch0..ch4 (always usable).
+// ADC2 channels: GPIO5 -> ch0 (NOT usable while Wi-Fi is on).
+// Touch channels: GPIO0..GPIO5 -> T0..T5.
+// ---------------------------------------------------------------------------
+
+function adc(n: number, ch: number) {
+  return { type: 'adc' as const, instance: n, role: `ch${ch}` };
+}
+function touch(ch: number) {
+  return { type: 'touch' as const, instance: 0, role: `touch${ch}` };
+}
+
+// ---------------------------------------------------------------------------
+// MCU definition
+// ---------------------------------------------------------------------------
+
+export const ESP32C3: MCUDefinition = {
+  id: 'esp32-c3',
+  name: 'ESP32-C3',
+  architecture: 'esp32c3',
+  memory: {
+    flash:    384 * 1024, // usable app flash; remainder reserved by bootloader/OTADATA
+    sram:     400 * 1024, // 400 KB
+    eeprom:   0,
+    rtcMemory: 16 * 1024, // 16 KB RTC slow memory
+  },
+  pins: {
+    all: [
+      // ---- ADC1 + touch pins (GPIO0-GPIO4) ---------------------------------
+      { number:  0, gpio:  0, name: 'GPIO0', capabilities: FULL_GPIO_ANALOG_TOUCH,
+        functions: [adc(1, 0), touch(0)],
+        alternateFunctions: ['ADC1_CH0', 'Touch0'] },
+
+      { number:  1, gpio:  1, name: 'GPIO1', capabilities: FULL_GPIO_ANALOG_TOUCH,
+        functions: [adc(1, 1), touch(1)],
+        alternateFunctions: ['ADC1_CH1', 'Touch1'] },
+
+      { number:  2, gpio:  2, name: 'GPIO2', capabilities: FULL_GPIO_ANALOG_TOUCH,
+        functions: [adc(1, 2), touch(2)],
+        alternateFunctions: ['ADC1_CH2', 'Touch2'],
+        warnings: ['GPIO2 is a strapping pin — boot mode select at boot'],
+        unsafe: true, notes: 'Boot strapping pin' },
+
+      { number:  3, gpio:  3, name: 'GPIO3', capabilities: FULL_GPIO_ANALOG_TOUCH,
+        functions: [adc(1, 3), touch(3)],
+        alternateFunctions: ['ADC1_CH3', 'Touch3'] },
+
+      { number:  4, gpio:  4, name: 'GPIO4', capabilities: FULL_GPIO_ANALOG_TOUCH,
+        functions: [adc(1, 4), touch(4), { type: 'spi', instance: 0, role: 'sck' }],
+        alternateFunctions: ['ADC1_CH4', 'Touch4', 'SPI0 SCK'] },
+
+      // ---- ADC2 pin (GPIO5) — Wi-Fi conflicted ------------------------------
+      { number:  5, gpio:  5, name: 'GPIO5', capabilities: FULL_GPIO_ANALOG_TOUCH,
+        functions: [adc(2, 0), touch(5), { type: 'spi', instance: 0, role: 'miso' }],
+        alternateFunctions: ['ADC2_CH0', 'Touch5', 'SPI0 MISO'],
+        warnings: ['GPIO5 is ADC2 — ADC2 is unusable while Wi-Fi is enabled'] },
+
+      { number:  6, gpio:  6, name: 'GPIO6', capabilities: FULL_GPIO,
+        functions: [{ type: 'spi', instance: 0, role: 'mosi' }],
+        alternateFunctions: ['SPI0 MOSI'] },
+
+      { number:  7, gpio:  7, name: 'GPIO7', capabilities: FULL_GPIO,
+        functions: [{ type: 'spi', instance: 0, role: 'cs' }],
+        alternateFunctions: ['SPI0 CS'] },
+
+      { number:  8, gpio:  8, name: 'GPIO8', capabilities: FULL_GPIO,
+        functions: [{ type: 'i2c', instance: 0, role: 'sda' }],
+        alternateFunctions: ['I2C0 SDA'],
+        warnings: ['GPIO8 is a strapping pin — controls VDD_SPI voltage at boot'],
+        unsafe: true, notes: 'Boot strapping pin' },
+
+      { number:  9, gpio:  9, name: 'GPIO9', capabilities: FULL_GPIO,
+        functions: [{ type: 'i2c', instance: 0, role: 'scl' }],
+        alternateFunctions: ['I2C0 SCL'],
+        warnings: ['GPIO9 is a strapping pin — must be HIGH at boot (reset source)'],
+        unsafe: true, notes: 'Boot strapping pin' },
+
+      { number: 10, gpio: 10, name: 'GPIO10', capabilities: FULL_GPIO,
+        alternateFunctions: ['FSPICS0'] },
+
+      // ---- GPIO 11 — internal flash Vpp, not broken out on the C3 ----------
+
+      { number: 12, gpio: 12, name: 'GPIO12', capabilities: FULL_GPIO,
+        functions: [{ type: 'spi', instance: 1, role: 'sck' }],
+        alternateFunctions: ['FSPICLK'] },
+      { number: 13, gpio: 13, name: 'GPIO13', capabilities: FULL_GPIO,
+        functions: [{ type: 'spi', instance: 1, role: 'mosi' }],
+        alternateFunctions: ['FSPID'] },
+      { number: 14, gpio: 14, name: 'GPIO14', capabilities: FULL_GPIO,
+        functions: [{ type: 'spi', instance: 1, role: 'miso' }],
+        alternateFunctions: ['FSPIQ'] },
+      { number: 15, gpio: 15, name: 'GPIO15', capabilities: FULL_GPIO,
+        functions: [{ type: 'spi', instance: 1, role: 'cs' }],
+        alternateFunctions: ['FSPICS1'] },
+      { number: 16, gpio: 16, name: 'GPIO16', capabilities: FULL_GPIO,
+        alternateFunctions: [] },
+      { number: 17, gpio: 17, name: 'GPIO17', capabilities: FULL_GPIO,
+        alternateFunctions: [] },
+
+      // ---- USB Serial/JTAG pins (unsafe) -----------------------------------
+      { number: 18, gpio: 18, name: 'GPIO18', capabilities: FULL_GPIO,
+        functions: [{ type: 'usb', instance: 0, role: 'dm' }],
+        alternateFunctions: ['USB D-'],
+        warnings: ['GPIO18 is USB D- — using it as GPIO disables native USB Serial/JTAG'],
+        unsafe: true, notes: 'USB D- pin' },
+      { number: 19, gpio: 19, name: 'GPIO19', capabilities: FULL_GPIO,
+        functions: [{ type: 'usb', instance: 0, role: 'dp' }],
+        alternateFunctions: ['USB D+'],
+        warnings: ['GPIO19 is USB D+ — using it as GPIO disables native USB Serial/JTAG'],
+        unsafe: true, notes: 'USB D+ pin' },
+
+      // ---- UART0 default pins ----------------------------------------------
+      { number: 20, gpio: 20, name: 'GPIO20', capabilities: FULL_GPIO,
+        functions: [{ type: 'uart', instance: 0, role: 'rx' }],
+        alternateFunctions: ['UART0 RX'],
+        warnings: ['Using GPIO20 as GPIO will interfere with UART0 receive'] },
+      { number: 21, gpio: 21, name: 'GPIO21', capabilities: FULL_GPIO,
+        functions: [{ type: 'uart', instance: 0, role: 'tx' }],
+        alternateFunctions: ['UART0 TX'],
+        warnings: ['Using GPIO21 as GPIO will interfere with UART0 transmit'] },
+    ],
+
+    digital: [
+      'GPIO0', 'GPIO1', 'GPIO2', 'GPIO3', 'GPIO4', 'GPIO5', 'GPIO6', 'GPIO7',
+      'GPIO8', 'GPIO9', 'GPIO10',
+      'GPIO12', 'GPIO13', 'GPIO14', 'GPIO15', 'GPIO16', 'GPIO17',
+      'GPIO18', 'GPIO19', 'GPIO20', 'GPIO21',
+    ],
+    analog: [
+      'GPIO0', 'GPIO1', 'GPIO2', 'GPIO3', 'GPIO4',  // ADC1
+      'GPIO5',                                       // ADC2
+    ],
+    pwm: [
+      'GPIO0', 'GPIO1', 'GPIO2', 'GPIO3', 'GPIO4', 'GPIO5', 'GPIO6', 'GPIO7',
+      'GPIO8', 'GPIO9', 'GPIO10',
+      'GPIO12', 'GPIO13', 'GPIO14', 'GPIO15', 'GPIO16', 'GPIO17',
+      'GPIO18', 'GPIO19', 'GPIO20', 'GPIO21',
+    ],
+    unsafe: ['GPIO2', 'GPIO8', 'GPIO9', 'GPIO18', 'GPIO19'],
+
+    i2c:  { 0: { sda: 'GPIO8',  scl: 'GPIO9'  } },
+    spi:  {
+      0: { mosi: 'GPIO6', miso: 'GPIO5', sck: 'GPIO4', cs: 'GPIO7' },  // GPSPI2 / VSPI
+    },
+    uart: {
+      0: { tx: 'GPIO21', rx: 'GPIO20' },
+    },
+  },
+
+  // ----- Peripherals -------------------------------------------------------
+  peripherals: MCU_PERIPHERALS,
+
+  features: {
+    multicore: false,
+    coreCount: 1,
+    deepSleep: true,
+    watchdog: true,
+    externalInterrupts: true,
+    hardwareRng: true,
+    fpu: false,
+  },
+  build: {
+    extraFlags: [],
+  },
+};
+
+export default ESP32C3;
+
+// Re-exports
+export * from './pins.js';
+export * from './peripherals.js';
+
+/**
+ * Structured manifest consumed by the TypeCAD CLI for contract-based
+ * board generation. Provides pin names and peripheral instance names
+ * without requiring the CLI to text-scrape compiled output.
+ */
+export const TypeCADManifest = {
+  /** All MCU port-level pin names (e.g. 'GPIO0', 'GPIO1'). */
+  pinNames: [
+    'GPIO0', 'GPIO1', 'GPIO2', 'GPIO3', 'GPIO4', 'GPIO5', 'GPIO6', 'GPIO7',
+    'GPIO8', 'GPIO9', 'GPIO10',
+    'GPIO12', 'GPIO13', 'GPIO14', 'GPIO15', 'GPIO16', 'GPIO17',
+    'GPIO18', 'GPIO19', 'GPIO20', 'GPIO21',
+  ] as const,
+
+  /** All HAL peripheral instance names exported from this package. */
+  peripheralNames: ['I2C0', 'SPI0', 'UART0', 'UART1'] as const,
+} as const;

package/src/peripherals.ts

@@ -0,0 +1,99 @@
+// ---------------------------------------------------------------------------
+// @typecad/mcu-esp32c3 — Hardware peripheral descriptions
+//
+// ESP32-C3 peripherals: 1× I2C, 1× SPI (GPSPI2), 2× UART, 2× ADC (12-bit),
+// 6× capacitive-touch, 4× general-purpose timers, Wi-Fi 4, BLE 5 (long range),
+// native USB Serial/JTAG (CDC). No DAC.
+// ---------------------------------------------------------------------------
+
+import type {
+  PeripheralInstance,
+  ADCDefinition,
+  PWMDefinition,
+  TimerDefinition,
+} from '@typecad/cuttlefish/api/schema';
+import {
+  I2CBus,
+  SPIBus,
+  SerialPort,
+  i2cName,
+  spiName,
+  serialName,
+  createHALInstances,
+} from '@typecad/hal';
+
+// ---------------------------------------------------------------------------
+// Peripheral definitions
+// ---------------------------------------------------------------------------
+
+export const I2C_INSTANCES: readonly PeripheralInstance[] = [
+  { instance: 0, defaultPins: { sda: 'GPIO8', scl: 'GPIO9' } },
+] as const;
+
+export const SPI_INSTANCES: readonly PeripheralInstance[] = [
+  { instance: 0, defaultPins: { mosi: 'GPIO6', miso: 'GPIO5', sck: 'GPIO4', cs: 'GPIO7' } },  // GPSPI2
+] as const;
+
+export const UART_INSTANCES: readonly PeripheralInstance[] = [
+  { instance: 0, defaultPins: { tx: 'GPIO21', rx: 'GPIO20' } },
+  { instance: 1, defaultPins: { tx: 'GPIO21', rx: 'GPIO20' } },
+] as const;
+
+export const ADC_INSTANCES: readonly ADCDefinition[] = [
+  { instance: 0, channels: 5, resolution: 12, referenceVoltage: 3.3, maxValue: 4095,
+    referenceVoltages: { DEFAULT: 3.3, INTERNAL: 1.1 } },  // ADC1 — usable with Wi-Fi active
+  { instance: 1, channels: 1, resolution: 12, referenceVoltage: 3.3, maxValue: 4095,
+    referenceVoltages: { DEFAULT: 3.3, INTERNAL: 1.1 } },  // ADC2 — NOT usable with Wi-Fi active
+] as const;
+
+export const PWM_CAPABILITIES: PWMDefinition = {
+  channels: 6,
+  resolution: 14,
+  maxFrequency: 40_000_000,
+} as const;
+
+export const TOUCH_CAPABILITIES = {
+  channels: 6,
+  pins: ['GPIO0', 'GPIO1', 'GPIO2', 'GPIO3', 'GPIO4', 'GPIO5'],
+};
+
+export const TIMER_INSTANCES: readonly TimerDefinition[] = [
+  { instance: 0, type: 'general', bits: 64, features: ['interrupt'] },
+  { instance: 1, type: 'general', bits: 64, features: ['interrupt'] },
+  { instance: 2, type: 'general', bits: 64, features: ['interrupt'] },
+  { instance: 3, type: 'general', bits: 64, features: ['interrupt'] },
+] as const;
+
+export const WIFI_CAPABILITIES = { type: 'wifi', supportsStation: true, supportsAp: true } as const;
+export const BLUETOOTH_CAPABILITIES = { type: 'ble', version: '5.0' } as const;
+export const USB_CAPABILITIES = { type: 'otg', vid: '0x303A', pid: '0x0001' } as const;
+
+// ---------------------------------------------------------------------------
+// Aggregate MCU peripheral description
+// ---------------------------------------------------------------------------
+
+export const MCU_PERIPHERALS = {
+  i2c: [...I2C_INSTANCES],
+  spi: [...SPI_INSTANCES],
+  uart: [...UART_INSTANCES],
+  adc: [...ADC_INSTANCES],
+  pwm: PWM_CAPABILITIES,
+  touch: TOUCH_CAPABILITIES,
+  timers: [...TIMER_INSTANCES],
+  wifi: WIFI_CAPABILITIES,
+  bluetooth: BLUETOOTH_CAPABILITIES,
+  usb: USB_CAPABILITIES,
+} as const;
+
+// ---------------------------------------------------------------------------
+// HAL object instances — auto-generated from peripheral definitions
+// ---------------------------------------------------------------------------
+
+/** I2C bus instances */
+export const [I2C0] = createHALInstances(I2C_INSTANCES, i => new I2CBus(i2cName(i)));
+
+/** SPI bus instances */
+export const [SPI0] = createHALInstances(SPI_INSTANCES, i => new SPIBus(spiName(i)));
+
+/** UART/Serial instances */
+export const [UART0, UART1] = createHALInstances(UART_INSTANCES, i => new SerialPort(serialName(i)));

package/src/pins.ts

@@ -0,0 +1,59 @@
+// ---------------------------------------------------------------------------
+// @typecad/mcu-esp32c3 — Datasheet pin definitions
+//
+// Each pin is a Pin instance from @typecad/hal. The ESP32-C3 has 22 GPIO
+// (0-10, 12-21); GPIO 11 is consumed by internal flash Vpp and is not broken
+// out. All GPIOs are bidirectional (no input-only pins). DAC is not present.
+// ---------------------------------------------------------------------------
+
+import { Pin } from '@typecad/hal';
+
+// ---------------------------------------------------------------------------
+// Named GPIO constants (Pin instances)
+// ---------------------------------------------------------------------------
+
+export const GPIO0  = new Pin(0);
+export const GPIO1  = new Pin(1);
+export const GPIO2  = new Pin(2);
+export const GPIO3  = new Pin(3);
+export const GPIO4  = new Pin(4);
+export const GPIO5  = new Pin(5);
+export const GPIO6  = new Pin(6);
+export const GPIO7  = new Pin(7);
+export const GPIO8  = new Pin(8);
+export const GPIO9  = new Pin(9);
+export const GPIO10 = new Pin(10);
+// GPIO 11 — internal flash Vpp, not broken out on the C3 package.
+export const GPIO12 = new Pin(12);
+export const GPIO13 = new Pin(13);
+export const GPIO14 = new Pin(14);
+export const GPIO15 = new Pin(15);
+export const GPIO16 = new Pin(16);
+export const GPIO17 = new Pin(17);
+export const GPIO18 = new Pin(18);
+export const GPIO19 = new Pin(19);
+export const GPIO20 = new Pin(20);
+export const GPIO21 = new Pin(21);
+
+// ---------------------------------------------------------------------------
+// Convenience aliases (Silicon-level defaults — match Arduino-ESP32 core)
+// ---------------------------------------------------------------------------
+
+/** I2C0 data line (GPIO8). */
+export const SDA = GPIO8;
+/** I2C0 clock line (GPIO9). */
+export const SCL = GPIO9;
+
+/** SPI0 MOSI (GPIO6). */
+export const MOSI = GPIO6;
+/** SPI0 MISO (GPIO5). */
+export const MISO = GPIO5;
+/** SPI0 clock (GPIO4). */
+export const SCK = GPIO4;
+/** SPI0 slave select (GPIO7). */
+export const SS = GPIO7;
+
+/** UART0 transmit (GPIO21). */
+export const TX = GPIO21;
+/** UART0 receive (GPIO20). */
+export const RX = GPIO20;