@typecad/board-esp32s3 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,44 @@
+# @typecad/board-esp32s3
+
+ESP32-S3 board definition package for TypeCAD.
+
+## Overview
+
+`@typecad/board-esp32s3` provides typed pins, peripherals, and board metadata for boards built on the ESP32-S3 (dual-core Xtensa LX7 @ 240 MHz, Wi-Fi 4 + BLE 5, native USB-OTG). It re-exports silicon-level pin definitions from [`@typecad/mcu-esp32s3`](../mcu-esp32s3) and HAL utilities from [`@typecad/hal`](../hal).
+
+## Quick start
+
+```ts
+import { GPIO2, delay } from '@typecad/board';
+
+const led = GPIO2.asOutput(false);
+
+while (true) {
+  led.toggle();
+  delay(1000);
+}
+```
+
+Reference this board in `cuttlefish.config.ts`:
+
+```ts
+board: '@typecad/board-esp32s3',
+```
+
+## What's inside
+
+- **GPIO pins**: `GPIO0`–`GPIO48` (silicon pins from `@typecad/mcu-esp32s3`)
+- **Peripheral instances**: `I2C0`, `SPI0`, `UART0`, `ADC`
+- **HAL utilities** (re-exported from `@typecad/hal`): `delay`, `millis`, `Pin`, `I2CBus`, `SPIBus`, etc.
+- **Board metadata**: `BoardDefinition` manifest with PWM/analog/interrupt pin capabilities and memory specs
+
+Direct imports from `@typecad/board-esp32s3` are also supported when you want explicit board package references.
+
+## Related packages
+
+- [`@typecad/mcu-esp32s3`](../mcu-esp32s3) — silicon-level pin definitions for the ESP32-S3 chip
+- [`@typecad/hal`](../hal) — hardware abstraction layer (GPIO, I2C, SPI, UART)
+
+## License
+
+MIT

package/dist/analog.d.ts

@@ -0,0 +1,4 @@
+/** Default reference (3.3V). */
+export declare const DEFAULT = 0;
+/** Internal 1.1V reference. */
+export declare const INTERNAL = 3;

package/dist/analog.js

@@ -0,0 +1,7 @@
+// ---------------------------------------------------------------------------
+// @typecad/board-esp32s3 — Analog constants
+// ---------------------------------------------------------------------------
+/** Default reference (3.3V). */
+export const DEFAULT = 0;
+/** Internal 1.1V reference. */
+export const INTERNAL = 3;

package/dist/board.d.ts

@@ -0,0 +1,80 @@
+import type { BoardDefinition } from '@typecad/cuttlefish/api/schema';
+import * as boardIndex from './index.js';
+export declare const Board: {
+    readonly definition: BoardDefinition;
+    D1: boardIndex.Pin;
+    D2: boardIndex.Pin;
+    D3: boardIndex.Pin;
+    D4: boardIndex.Pin;
+    D5: boardIndex.Pin;
+    D6: boardIndex.Pin;
+    D7: boardIndex.Pin;
+    D8: boardIndex.Pin;
+    D9: boardIndex.Pin;
+    D10: boardIndex.Pin;
+    D38: boardIndex.Pin;
+    D39: boardIndex.Pin;
+    D40: boardIndex.Pin;
+    D41: boardIndex.Pin;
+    D42: boardIndex.Pin;
+    D43: boardIndex.Pin;
+    D44: boardIndex.Pin;
+    D45: boardIndex.Pin;
+    D46: boardIndex.Pin;
+    D47: boardIndex.Pin;
+    D48: boardIndex.Pin;
+    A0: boardIndex.Pin;
+    A1: boardIndex.Pin;
+    A2: boardIndex.Pin;
+    A3: boardIndex.Pin;
+    A4: boardIndex.Pin;
+    A5: boardIndex.Pin;
+    A6: boardIndex.Pin;
+    A7: boardIndex.Pin;
+    A8: boardIndex.Pin;
+    A9: boardIndex.Pin;
+    LED: boardIndex.Pin;
+    I2C0: boardIndex.I2CBus;
+    I2C1: boardIndex.I2CBus;
+    SPI0: boardIndex.SPIBus;
+    SPI1: boardIndex.SPIBus;
+    UART0: boardIndex.SerialPort;
+    UART1: boardIndex.SerialPort;
+    UART2: boardIndex.SerialPort;
+    digital: {
+        D1: boardIndex.Pin;
+        D2: boardIndex.Pin;
+        D3: boardIndex.Pin;
+        D4: boardIndex.Pin;
+        D5: boardIndex.Pin;
+        D6: boardIndex.Pin;
+        D7: boardIndex.Pin;
+        D8: boardIndex.Pin;
+        D9: boardIndex.Pin;
+        D10: boardIndex.Pin;
+        D38: boardIndex.Pin;
+        D39: boardIndex.Pin;
+        D40: boardIndex.Pin;
+        D41: boardIndex.Pin;
+        D42: boardIndex.Pin;
+        D43: boardIndex.Pin;
+        D44: boardIndex.Pin;
+        D45: boardIndex.Pin;
+        D46: boardIndex.Pin;
+        D47: boardIndex.Pin;
+        D48: boardIndex.Pin;
+    };
+    analog: {
+        A0: boardIndex.Pin;
+        A1: boardIndex.Pin;
+        A2: boardIndex.Pin;
+        A3: boardIndex.Pin;
+        A4: boardIndex.Pin;
+        A5: boardIndex.Pin;
+        A6: boardIndex.Pin;
+        A7: boardIndex.Pin;
+        A8: boardIndex.Pin;
+        A9: boardIndex.Pin;
+    };
+};
+export default Board;

package/dist/board.js

@@ -0,0 +1,31 @@
+// ---------------------------------------------------------------------------
+// @typecad/board-esp32s3 — Board namespace
+//
+// Convenience namespace that exposes every board feature under one object.
+// For method calls on pins/peripherals, prefer direct imports:
+//
+//   import { D2, UART0 } from '@typecad/board-esp32s3';
+//   D2.high();
+//   UART0.begin(115200);
+//
+// The Board object is useful for pin iteration and metadata access.
+// ---------------------------------------------------------------------------
+import { D1, D2, D3, D4, D5, D6, D7, D8, D9, D10, D38, D39, D40, D41, D42, D43, D44, D45, D46, D47, D48, A0, A1, A2, A3, A4, A5, A6, A7, A8, A9, LED, } from './pins.js';
+import { I2C0, I2C1, SPI0, SPI1, UART0, UART1, UART2 } from '@typecad/mcu-esp32s3';
+import * as boardIndex from './index.js';
+export const Board = {
+    get definition() { return boardIndex.ESP32S3Board; },
+    // Common digital pins (strapping/flash/USB pins omitted from the convenience namespace)
+    D1, D2, D3, D4, D5, D6, D7, D8, D9, D10,
+    D38, D39, D40, D41, D42, D43, D44, D45, D46, D47, D48,
+    // Analog aliases
+    A0, A1, A2, A3, A4, A5, A6, A7, A8, A9,
+    // Convenience aliases
+    LED,
+    // Peripherals
+    I2C0, I2C1, SPI0, SPI1, UART0, UART1, UART2,
+    // Collections
+    digital: { D1, D2, D3, D4, D5, D6, D7, D8, D9, D10, D38, D39, D40, D41, D42, D43, D44, D45, D46, D47, D48 },
+    analog: { A0, A1, A2, A3, A4, A5, A6, A7, A8, A9 },
+};
+export default Board;

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+import type { BoardDefinition } from '@typecad/cuttlefish/api/schema';
+export declare const ESP32S3Board: BoardDefinition;
+export default ESP32S3Board;
+export * from '@typecad/mcu-esp32s3';
+export * from '@typecad/hal';
+/**
+ * Pin collections for runtime capability discovery.
+ */
+export declare const pins: {
+    /** PWM-capable pins (all output-capable GPIOs that are not flash/USB/strap). */
+    readonly pwm: readonly [import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin];
+    /** Analog input pins (ADC1 — usable while Wi-Fi active). */
+    readonly analog: readonly [import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin];
+    /** All GPIOs support interrupts on ESP32-S3. */
+    readonly interrupt: readonly [import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin];
+    /** All digital I/O pins. */
+    readonly digital: readonly [import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin, import("@typecad/hal").Pin];
+};
+/**
+ * Peripheral-to-pin mapping for the ESP32-S3.
+ */
+export declare const PeripheralPins: {
+    /** I2C bus 0 — default GPIO8 (SDA) / GPIO9 (SCL); remappable via GPIO matrix. */
+    readonly I2C0: {
+        readonly SDA: "GPIO8";
+        readonly SCL: "GPIO9";
+    };
+    /** I2C bus 1 — no fixed pins (remappable). */
+    readonly I2C1: {
+        readonly SDA: "remappable";
+        readonly SCL: "remappable";
+    };
+    /** SPI bus 0 / FSPI — GPIO12 (MOSI), GPIO13 (MISO), GPIO11 (SCK). GPIO10 is default CS. */
+    readonly SPI0: {
+        readonly MOSI: "GPIO12";
+        readonly MISO: "GPIO13";
+        readonly SCK: "GPIO11";
+        readonly CS: "GPIO10";
+    };
+    /** SPI bus 1 / GPSI — no fixed pins (remappable). */
+    readonly SPI1: {
+        readonly MOSI: "remappable";
+        readonly MISO: "remappable";
+        readonly SCK: "remappable";
+    };
+    /** UART 0 — GPIO43 (TX) / GPIO44 (RX). USB-CDC serial available too. */
+    readonly UART0: {
+        readonly TX: "GPIO43";
+        readonly RX: "GPIO44";
+    };
+    /** UART 1 — no fixed pins (remappable). */
+    readonly UART1: {
+        readonly TX: "remappable";
+        readonly RX: "remappable";
+    };
+};
+export * from './pins.js';
+export * from './analog.js';
+export { Board } from './board.js';

package/dist/index.js

@@ -0,0 +1,112 @@
+// ---------------------------------------------------------------------------
+// @typecad/board-esp32s3 — Board definition manifest
+// ---------------------------------------------------------------------------
+import { ESP32S3 } from '@typecad/mcu-esp32s3';
+/** Arduino core API version for this board's build defines. */
+const ARDUINO_CORE_VERSION = '10819';
+// ---------------------------------------------------------------------------
+// Board definition
+// ---------------------------------------------------------------------------
+export const ESP32S3Board = {
+    id: 'esp32s3',
+    name: 'ESP32-S3',
+    vendor: 'Espressif',
+    description: 'Generic ESP32-S3 (vendor-agnostic). Dual-core Xtensa LX7 @ 240 MHz ' +
+        'with Wi-Fi 4 + BLE 5 and native USB-OTG. Flash/PSRAM are module-dependent; ' +
+        'override via FQBN menu options, e.g. ' +
+        'esp32:esp32:esp32s3:FlashSize=16M,PSRAM=opi',
+    mcu: ESP32S3,
+    clockSpeed: 240_000_000, // 240 MHz
+    // ----- Memory (module-level defaults; silicon memory lives on the MCU) ---
+    memory: {
+        flash: 8 * 1024 * 1024, // 8 MB module flash (N8R2-class default)
+        externalRam: 2 * 1024 * 1024, // 2 MB octal PSRAM
+    },
+    // ----- Pins --------------------------------------------------------------
+    pins: {
+        ...ESP32S3.pins,
+        led: 'GPIO48',
+    },
+    // ----- Peripherals -------------------------------------------------------
+    peripherals: {
+        ...ESP32S3.peripherals,
+        aliases: {
+            UART0: 'Serial',
+            UART1: 'Serial1',
+            UART2: 'Serial2',
+            I2C0: 'Wire',
+            I2C1: 'Wire1',
+            SPI0: 'SPI',
+            SPI1: 'SPI1',
+        },
+    },
+    // ----- Build config ------------------------------------------------------
+    build: {
+        frameworks: {
+            platformio: 'esp32s3',
+            arduino: 'esp32:esp32:esp32s3',
+        },
+        defines: {
+            F_CPU: '240000000UL',
+            ARDUINO: ARDUINO_CORE_VERSION,
+            ARDUINO_ESP32S3_DEV: '1',
+        },
+    },
+};
+export default ESP32S3Board;
+// ---------------------------------------------------------------------------
+// Re-exports — convenience barrel
+// ---------------------------------------------------------------------------
+// Silicon-level (local MCU module)
+export * from '@typecad/mcu-esp32s3';
+// Generic HAL re-exports from @typecad/hal. Full re-export so this board package
+// is a superset of @typecad/hal — `import { ... } from '@typecad/hal'` resolves
+// here at transpile time and exposes every HAL symbol plus board-specific pins.
+export * from '@typecad/hal';
+// Board-level pin Discovery API (uses local silicon pins)
+import { GPIO0, GPIO1, GPIO2, GPIO3, GPIO4, GPIO5, GPIO6, GPIO7, GPIO8, GPIO9, GPIO10, GPIO11, GPIO12, GPIO13, GPIO14, GPIO15, GPIO16, GPIO17, GPIO18, GPIO19, GPIO20, GPIO21, GPIO38, GPIO39, GPIO40, GPIO41, GPIO42, GPIO43, GPIO44, GPIO45, GPIO46, GPIO47, GPIO48, } from '@typecad/mcu-esp32s3';
+/**
+ * Pin collections for runtime capability discovery.
+ */
+export const pins = {
+    /** PWM-capable pins (all output-capable GPIOs that are not flash/USB/strap). */
+    pwm: [GPIO0, GPIO1, GPIO2, GPIO3, GPIO4, GPIO5, GPIO6, GPIO7, GPIO8, GPIO9,
+        GPIO10, GPIO11, GPIO12, GPIO13, GPIO14, GPIO15, GPIO16, GPIO17, GPIO18,
+        GPIO19, GPIO20, GPIO21, GPIO38, GPIO39, GPIO40, GPIO41, GPIO42, GPIO43,
+        GPIO44, GPIO45, GPIO46, GPIO47, GPIO48],
+    /** Analog input pins (ADC1 — usable while Wi-Fi active). */
+    analog: [GPIO1, GPIO2, GPIO3, GPIO4, GPIO5, GPIO6, GPIO7, GPIO8, GPIO9, GPIO10],
+    /** All GPIOs support interrupts on ESP32-S3. */
+    interrupt: [GPIO0, GPIO1, GPIO2, GPIO3, GPIO4, GPIO5, GPIO6, GPIO7, GPIO8, GPIO9,
+        GPIO10, GPIO11, GPIO12, GPIO13, GPIO14, GPIO15, GPIO16, GPIO17, GPIO18,
+        GPIO19, GPIO20, GPIO21, GPIO38, GPIO39, GPIO40, GPIO41, GPIO42, GPIO43,
+        GPIO44, GPIO45, GPIO46, GPIO47, GPIO48],
+    /** All digital I/O pins. */
+    digital: [GPIO0, GPIO1, GPIO2, GPIO3, GPIO4, GPIO5, GPIO6, GPIO7, GPIO8, GPIO9,
+        GPIO10, GPIO11, GPIO12, GPIO13, GPIO14, GPIO15, GPIO16, GPIO17, GPIO18,
+        GPIO19, GPIO20, GPIO21, GPIO38, GPIO39, GPIO40, GPIO41, GPIO42, GPIO43,
+        GPIO44, GPIO45, GPIO46, GPIO47, GPIO48],
+};
+/**
+ * Peripheral-to-pin mapping for the ESP32-S3.
+ */
+export const PeripheralPins = {
+    /** I2C bus 0 — default GPIO8 (SDA) / GPIO9 (SCL); remappable via GPIO matrix. */
+    I2C0: { SDA: 'GPIO8', SCL: 'GPIO9' },
+    /** I2C bus 1 — no fixed pins (remappable). */
+    I2C1: { SDA: 'remappable', SCL: 'remappable' },
+    /** SPI bus 0 / FSPI — GPIO12 (MOSI), GPIO13 (MISO), GPIO11 (SCK). GPIO10 is default CS. */
+    SPI0: { MOSI: 'GPIO12', MISO: 'GPIO13', SCK: 'GPIO11', CS: 'GPIO10' },
+    /** SPI bus 1 / GPSI — no fixed pins (remappable). */
+    SPI1: { MOSI: 'remappable', MISO: 'remappable', SCK: 'remappable' },
+    /** UART 0 — GPIO43 (TX) / GPIO44 (RX). USB-CDC serial available too. */
+    UART0: { TX: 'GPIO43', RX: 'GPIO44' },
+    /** UART 1 — no fixed pins (remappable). */
+    UART1: { TX: 'remappable', RX: 'remappable' },
+};
+// Board-level typed pins (Arduino-style aliases D0, A0, etc.)
+export * from './pins.js';
+// Board-specific analog constants
+export * from './analog.js';
+// Board namespace (single-import convenience)
+export { Board } from './board.js';

package/dist/pins.d.ts

@@ -0,0 +1,46 @@
+export declare const D0: import("@typecad/hal").Pin;
+export declare const D1: import("@typecad/hal").Pin;
+export declare const D2: import("@typecad/hal").Pin;
+export declare const D3: import("@typecad/hal").Pin;
+export declare const D4: import("@typecad/hal").Pin;
+export declare const D5: import("@typecad/hal").Pin;
+export declare const D6: import("@typecad/hal").Pin;
+export declare const D7: import("@typecad/hal").Pin;
+export declare const D8: import("@typecad/hal").Pin;
+export declare const D9: import("@typecad/hal").Pin;
+export declare const D10: import("@typecad/hal").Pin;
+export declare const D11: import("@typecad/hal").Pin;
+export declare const D12: import("@typecad/hal").Pin;
+export declare const D13: import("@typecad/hal").Pin;
+export declare const D14: import("@typecad/hal").Pin;
+export declare const D15: import("@typecad/hal").Pin;
+export declare const D16: import("@typecad/hal").Pin;
+export declare const D17: import("@typecad/hal").Pin;
+export declare const D18: import("@typecad/hal").Pin;
+export declare const D19: import("@typecad/hal").Pin;
+export declare const D20: import("@typecad/hal").Pin;
+export declare const D21: import("@typecad/hal").Pin;
+export declare const D38: import("@typecad/hal").Pin;
+export declare const D39: import("@typecad/hal").Pin;
+export declare const D40: import("@typecad/hal").Pin;
+export declare const D41: import("@typecad/hal").Pin;
+export declare const D42: import("@typecad/hal").Pin;
+export declare const D43: import("@typecad/hal").Pin;
+export declare const D44: import("@typecad/hal").Pin;
+export declare const D45: import("@typecad/hal").Pin;
+export declare const D46: import("@typecad/hal").Pin;
+export declare const D47: import("@typecad/hal").Pin;
+export declare const D48: import("@typecad/hal").Pin;
+export declare const A0: import("@typecad/hal").Pin;
+export declare const A1: import("@typecad/hal").Pin;
+export declare const A2: import("@typecad/hal").Pin;
+export declare const A3: import("@typecad/hal").Pin;
+export declare const A4: import("@typecad/hal").Pin;
+export declare const A5: import("@typecad/hal").Pin;
+export declare const A6: import("@typecad/hal").Pin;
+export declare const A7: import("@typecad/hal").Pin;
+export declare const A8: import("@typecad/hal").Pin;
+export declare const A9: import("@typecad/hal").Pin;
+/** On-board LED (GPIO48 — addressable RGB on most S3 dev modules). */
+export declare const LED: import("@typecad/hal").Pin;
+export { I2C0, I2C1, SPI0, SPI1, UART0, UART1, UART2 } from '@typecad/mcu-esp32s3';

package/dist/pins.js

@@ -0,0 +1,62 @@
+// ---------------------------------------------------------------------------
+// @typecad/board-esp32s3 — Pin aliases
+// ---------------------------------------------------------------------------
+import { GPIO0, GPIO1, GPIO2, GPIO3, GPIO4, GPIO5, GPIO6, GPIO7, GPIO8, GPIO9, GPIO10, GPIO11, GPIO12, GPIO13, GPIO14, GPIO15, GPIO16, GPIO17, GPIO18, GPIO19, GPIO20, GPIO21, GPIO38, GPIO39, GPIO40, GPIO41, GPIO42, GPIO43, GPIO44, GPIO45, GPIO46, GPIO47, GPIO48, } from '@typecad/mcu-esp32s3';
+// ---------------------------------------------------------------------------
+// Arduino-style digital pin aliases (D-numbers match GPIO numbers on ESP32-S3)
+// ---------------------------------------------------------------------------
+export const D0 = GPIO0;
+export const D1 = GPIO1;
+export const D2 = GPIO2;
+export const D3 = GPIO3;
+export const D4 = GPIO4;
+export const D5 = GPIO5;
+export const D6 = GPIO6;
+export const D7 = GPIO7;
+export const D8 = GPIO8;
+export const D9 = GPIO9;
+export const D10 = GPIO10;
+export const D11 = GPIO11;
+export const D12 = GPIO12;
+export const D13 = GPIO13;
+export const D14 = GPIO14;
+export const D15 = GPIO15;
+export const D16 = GPIO16;
+export const D17 = GPIO17;
+export const D18 = GPIO18;
+export const D19 = GPIO19;
+export const D20 = GPIO20;
+export const D21 = GPIO21;
+export const D38 = GPIO38;
+export const D39 = GPIO39;
+export const D40 = GPIO40;
+export const D41 = GPIO41;
+export const D42 = GPIO42;
+export const D43 = GPIO43;
+export const D44 = GPIO44;
+export const D45 = GPIO45;
+export const D46 = GPIO46;
+export const D47 = GPIO47;
+export const D48 = GPIO48;
+// ---------------------------------------------------------------------------
+// Analog input aliases (ADC1 channels — usable while Wi-Fi is active).
+// ADC2 pins (GPIO11-GPIO20) are omitted from Ax aliases because they are
+// unusable while Wi-Fi is enabled.
+// ---------------------------------------------------------------------------
+export const A0 = GPIO1;
+export const A1 = GPIO2;
+export const A2 = GPIO3;
+export const A3 = GPIO4;
+export const A4 = GPIO5;
+export const A5 = GPIO6;
+export const A6 = GPIO7;
+export const A7 = GPIO8;
+export const A8 = GPIO9;
+export const A9 = GPIO10;
+// ---------------------------------------------------------------------------
+// Board-specific aliases
+// ---------------------------------------------------------------------------
+/** On-board LED (GPIO48 — addressable RGB on most S3 dev modules). */
+export const LED = GPIO48;
+// Bus aliases (default pins for I2C0 / SPI0 / UART0)
+export { I2C0, I2C1, SPI0, SPI1, UART0, UART1, UART2 } from '@typecad/mcu-esp32s3';

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@typecad/board-esp32s3",
+  "version": "0.1.0-alpha.1",
+  "description": "TypeCAD ESP32-S3 board definition with typed pins and peripherals",
+  "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",
+    "@typecad/mcu-esp32s3": "0.1.0-alpha.1"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/justind000/typecode.git",
+    "directory": "packages/board-esp32s3"
+  },
+  "homepage": "https://github.com/justind000/typecode/tree/main/packages/board-esp32s3",
+  "bugs": {
+    "url": "https://github.com/justind000/typecode/issues"
+  },
+  "keywords": [
+    "arduino",
+    "board",
+    "cpp",
+    "cuttlefish",
+    "devkit",
+    "embedded",
+    "esp32s3",
+    "firmware",
+    "microcontroller",
+    "pins",
+    "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/analog.ts

@@ -0,0 +1,8 @@
+// ---------------------------------------------------------------------------
+// @typecad/board-esp32s3 — Analog constants
+// ---------------------------------------------------------------------------
+
+/** Default reference (3.3V). */
+export const DEFAULT = 0;
+/** Internal 1.1V reference. */
+export const INTERNAL = 3;

package/src/board.ts

@@ -0,0 +1,47 @@
+// ---------------------------------------------------------------------------
+// @typecad/board-esp32s3 — Board namespace
+//
+// Convenience namespace that exposes every board feature under one object.
+// For method calls on pins/peripherals, prefer direct imports:
+//
+//   import { D2, UART0 } from '@typecad/board-esp32s3';
+//   D2.high();
+//   UART0.begin(115200);
+//
+// The Board object is useful for pin iteration and metadata access.
+// ---------------------------------------------------------------------------
+
+import type { BoardDefinition } from '@typecad/cuttlefish/api/schema';
+
+import {
+  D1, D2, D3, D4, D5, D6, D7, D8, D9, D10,
+  D38, D39, D40, D41, D42, D43, D44, D45, D46, D47, D48,
+  A0, A1, A2, A3, A4, A5, A6, A7, A8, A9,
+  LED,
+} from './pins.js';
+
+import { I2C0, I2C1, SPI0, SPI1, UART0, UART1, UART2 } from '@typecad/mcu-esp32s3';
+import * as boardIndex from './index.js';
+
+export const Board = {
+  get definition() { return boardIndex.ESP32S3Board; },
+
+  // Common digital pins (strapping/flash/USB pins omitted from the convenience namespace)
+  D1, D2, D3, D4, D5, D6, D7, D8, D9, D10,
+  D38, D39, D40, D41, D42, D43, D44, D45, D46, D47, D48,
+
+  // Analog aliases
+  A0, A1, A2, A3, A4, A5, A6, A7, A8, A9,
+
+  // Convenience aliases
+  LED,
+
+  // Peripherals
+  I2C0, I2C1, SPI0, SPI1, UART0, UART1, UART2,
+
+  // Collections
+  digital: { D1, D2, D3, D4, D5, D6, D7, D8, D9, D10, D38, D39, D40, D41, D42, D43, D44, D45, D46, D47, D48 },
+  analog:  { A0, A1, A2, A3, A4, A5, A6, A7, A8, A9 },
+};
+
+export default Board;

package/src/index.ts

@@ -0,0 +1,139 @@
+// ---------------------------------------------------------------------------
+// @typecad/board-esp32s3 — Board definition manifest
+// ---------------------------------------------------------------------------
+
+import type { BoardDefinition } from '@typecad/cuttlefish/api/schema';
+import { ESP32S3 } from '@typecad/mcu-esp32s3';
+
+/** Arduino core API version for this board's build defines. */
+const ARDUINO_CORE_VERSION = '10819';
+
+// ---------------------------------------------------------------------------
+// Board definition
+// ---------------------------------------------------------------------------
+
+export const ESP32S3Board: BoardDefinition = {
+  id: 'esp32s3',
+  name: 'ESP32-S3',
+  vendor: 'Espressif',
+  description:
+    'Generic ESP32-S3 (vendor-agnostic). Dual-core Xtensa LX7 @ 240 MHz ' +
+    'with Wi-Fi 4 + BLE 5 and native USB-OTG. Flash/PSRAM are module-dependent; ' +
+    'override via FQBN menu options, e.g. ' +
+    'esp32:esp32:esp32s3:FlashSize=16M,PSRAM=opi',
+
+  mcu: ESP32S3,
+  clockSpeed: 240_000_000, // 240 MHz
+
+  // ----- Memory (module-level defaults; silicon memory lives on the MCU) ---
+  memory: {
+    flash: 8 * 1024 * 1024,        // 8 MB module flash (N8R2-class default)
+    externalRam: 2 * 1024 * 1024,  // 2 MB octal PSRAM
+  },
+
+  // ----- Pins --------------------------------------------------------------
+  pins: {
+    ...ESP32S3.pins,
+    led: 'GPIO48',
+  },
+
+  // ----- Peripherals -------------------------------------------------------
+  peripherals: {
+    ...ESP32S3.peripherals,
+    aliases: {
+      UART0: 'Serial',
+      UART1: 'Serial1',
+      UART2: 'Serial2',
+      I2C0:  'Wire',
+      I2C1:  'Wire1',
+      SPI0:  'SPI',
+      SPI1:  'SPI1',
+    },
+  },
+
+  // ----- Build config ------------------------------------------------------
+  build: {
+    frameworks: {
+      platformio: 'esp32s3',
+      arduino: 'esp32:esp32:esp32s3',
+    },
+    defines: {
+      F_CPU:              '240000000UL',
+      ARDUINO:            ARDUINO_CORE_VERSION,
+      ARDUINO_ESP32S3_DEV: '1',
+    },
+  },
+};
+
+export default ESP32S3Board;
+
+// ---------------------------------------------------------------------------
+// Re-exports — convenience barrel
+// ---------------------------------------------------------------------------
+
+// Silicon-level (local MCU module)
+export * from '@typecad/mcu-esp32s3';
+
+// Generic HAL re-exports from @typecad/hal. Full re-export so this board package
+// is a superset of @typecad/hal — `import { ... } from '@typecad/hal'` resolves
+// here at transpile time and exposes every HAL symbol plus board-specific pins.
+export * from '@typecad/hal';
+
+// Board-level pin Discovery API (uses local silicon pins)
+import {
+  GPIO0, GPIO1, GPIO2, GPIO3, GPIO4, GPIO5, GPIO6, GPIO7,
+  GPIO8, GPIO9, GPIO10, GPIO11, GPIO12, GPIO13, GPIO14,
+  GPIO15, GPIO16, GPIO17, GPIO18, GPIO19, GPIO20, GPIO21,
+  GPIO38, GPIO39, GPIO40, GPIO41, GPIO42, GPIO43, GPIO44,
+  GPIO45, GPIO46, GPIO47, GPIO48,
+} from '@typecad/mcu-esp32s3';
+
+/**
+ * Pin collections for runtime capability discovery.
+ */
+export const pins = {
+  /** PWM-capable pins (all output-capable GPIOs that are not flash/USB/strap). */
+  pwm: [GPIO0, GPIO1, GPIO2, GPIO3, GPIO4, GPIO5, GPIO6, GPIO7, GPIO8, GPIO9,
+        GPIO10, GPIO11, GPIO12, GPIO13, GPIO14, GPIO15, GPIO16, GPIO17, GPIO18,
+        GPIO19, GPIO20, GPIO21, GPIO38, GPIO39, GPIO40, GPIO41, GPIO42, GPIO43,
+        GPIO44, GPIO45, GPIO46, GPIO47, GPIO48] as const,
+  /** Analog input pins (ADC1 — usable while Wi-Fi active). */
+  analog: [GPIO1, GPIO2, GPIO3, GPIO4, GPIO5, GPIO6, GPIO7, GPIO8, GPIO9, GPIO10] as const,
+  /** All GPIOs support interrupts on ESP32-S3. */
+  interrupt: [GPIO0, GPIO1, GPIO2, GPIO3, GPIO4, GPIO5, GPIO6, GPIO7, GPIO8, GPIO9,
+              GPIO10, GPIO11, GPIO12, GPIO13, GPIO14, GPIO15, GPIO16, GPIO17, GPIO18,
+              GPIO19, GPIO20, GPIO21, GPIO38, GPIO39, GPIO40, GPIO41, GPIO42, GPIO43,
+              GPIO44, GPIO45, GPIO46, GPIO47, GPIO48] as const,
+  /** All digital I/O pins. */
+  digital: [GPIO0, GPIO1, GPIO2, GPIO3, GPIO4, GPIO5, GPIO6, GPIO7, GPIO8, GPIO9,
+            GPIO10, GPIO11, GPIO12, GPIO13, GPIO14, GPIO15, GPIO16, GPIO17, GPIO18,
+            GPIO19, GPIO20, GPIO21, GPIO38, GPIO39, GPIO40, GPIO41, GPIO42, GPIO43,
+            GPIO44, GPIO45, GPIO46, GPIO47, GPIO48] as const,
+} as const;
+
+/**
+ * Peripheral-to-pin mapping for the ESP32-S3.
+ */
+export const PeripheralPins = {
+  /** I2C bus 0 — default GPIO8 (SDA) / GPIO9 (SCL); remappable via GPIO matrix. */
+  I2C0: { SDA: 'GPIO8',  SCL: 'GPIO9'  } as const,
+  /** I2C bus 1 — no fixed pins (remappable). */
+  I2C1: { SDA: 'remappable', SCL: 'remappable' } as const,
+  /** SPI bus 0 / FSPI — GPIO12 (MOSI), GPIO13 (MISO), GPIO11 (SCK). GPIO10 is default CS. */
+  SPI0: { MOSI: 'GPIO12', MISO: 'GPIO13', SCK: 'GPIO11', CS: 'GPIO10' } as const,
+  /** SPI bus 1 / GPSI — no fixed pins (remappable). */
+  SPI1: { MOSI: 'remappable', MISO: 'remappable', SCK: 'remappable' } as const,
+  /** UART 0 — GPIO43 (TX) / GPIO44 (RX). USB-CDC serial available too. */
+  UART0: { TX: 'GPIO43', RX: 'GPIO44' } as const,
+  /** UART 1 — no fixed pins (remappable). */
+  UART1: { TX: 'remappable', RX: 'remappable' } as const,
+} as const;
+
+// Board-level typed pins (Arduino-style aliases D0, A0, etc.)
+export * from './pins.js';
+
+// Board-specific analog constants
+export * from './analog.js';
+
+// Board namespace (single-import convenience)
+export { Board } from './board.js';

package/src/pins.ts

@@ -0,0 +1,55 @@
+// ---------------------------------------------------------------------------
+// @typecad/board-esp32s3 — Pin aliases
+// ---------------------------------------------------------------------------
+
+import {
+  GPIO0, GPIO1, GPIO2, GPIO3, GPIO4, GPIO5, GPIO6, GPIO7,
+  GPIO8, GPIO9, GPIO10, GPIO11, GPIO12, GPIO13, GPIO14,
+  GPIO15, GPIO16, GPIO17, GPIO18, GPIO19, GPIO20, GPIO21,
+  GPIO38, GPIO39, GPIO40, GPIO41, GPIO42, GPIO43, GPIO44,
+  GPIO45, GPIO46, GPIO47, GPIO48,
+} from '@typecad/mcu-esp32s3';
+
+// ---------------------------------------------------------------------------
+// Arduino-style digital pin aliases (D-numbers match GPIO numbers on ESP32-S3)
+// ---------------------------------------------------------------------------
+
+export const D0  = GPIO0;   export const D1  = GPIO1;   export const D2  = GPIO2;
+export const D3  = GPIO3;   export const D4  = GPIO4;   export const D5  = GPIO5;
+export const D6  = GPIO6;   export const D7  = GPIO7;   export const D8  = GPIO8;
+export const D9  = GPIO9;   export const D10 = GPIO10;  export const D11 = GPIO11;
+export const D12 = GPIO12;  export const D13 = GPIO13;  export const D14 = GPIO14;
+export const D15 = GPIO15;  export const D16 = GPIO16;  export const D17 = GPIO17;
+export const D18 = GPIO18;  export const D19 = GPIO19;  export const D20 = GPIO20;
+export const D21 = GPIO21;
+export const D38 = GPIO38;  export const D39 = GPIO39;  export const D40 = GPIO40;
+export const D41 = GPIO41;  export const D42 = GPIO42;  export const D43 = GPIO43;
+export const D44 = GPIO44;  export const D45 = GPIO45;  export const D46 = GPIO46;
+export const D47 = GPIO47;  export const D48 = GPIO48;
+
+// ---------------------------------------------------------------------------
+// Analog input aliases (ADC1 channels — usable while Wi-Fi is active).
+// ADC2 pins (GPIO11-GPIO20) are omitted from Ax aliases because they are
+// unusable while Wi-Fi is enabled.
+// ---------------------------------------------------------------------------
+
+export const A0 = GPIO1;
+export const A1 = GPIO2;
+export const A2 = GPIO3;
+export const A3 = GPIO4;
+export const A4 = GPIO5;
+export const A5 = GPIO6;
+export const A6 = GPIO7;
+export const A7 = GPIO8;
+export const A8 = GPIO9;
+export const A9 = GPIO10;
+
+// ---------------------------------------------------------------------------
+// Board-specific aliases
+// ---------------------------------------------------------------------------
+
+/** On-board LED (GPIO48 — addressable RGB on most S3 dev modules). */
+export const LED = GPIO48;
+
+// Bus aliases (default pins for I2C0 / SPI0 / UART0)
+export { I2C0, I2C1, SPI0, SPI1, UART0, UART1, UART2 } from '@typecad/mcu-esp32s3';