@typecad/mcu-atmega328p 0.1.0-alpha.1

package/src/mcu.ts

@@ -0,0 +1,164 @@
+// ---------------------------------------------------------------------------
+// @typecad/mcu-atmega328p — MCU hardware definition
+// ---------------------------------------------------------------------------
+
+import type { MCUDefinition } from '@typecad/cuttlefish/api/schema';
+import { MCU_PERIPHERALS } from './peripherals.js';
+
+// ---------------------------------------------------------------------------
+// Pin capability shorthands
+// ---------------------------------------------------------------------------
+
+const NO  = false as const;
+const YES = true  as const;
+
+/** Shorthand: digital I/O only, with internal pull-up. */
+const DIGITAL = {
+  digitalInput: YES, digitalOutput: YES,
+  analogInput: NO,   analogOutput: NO,
+  pwm: NO,           interrupt: NO,
+  pullUp: YES,       pullDown: NO,
+  touch: NO,         openDrain: NO,
+} as const;
+
+/** Shorthand: digital I/O + external-interrupt capable. */
+const DIGITAL_INT = { ...DIGITAL, interrupt: YES } as const;
+
+/** Shorthand: digital I/O + PWM. */
+const DIGITAL_PWM = { ...DIGITAL, pwm: YES } as const;
+
+/** Shorthand: digital I/O + PWM + interrupt. */
+const DIGITAL_PWM_INT = { ...DIGITAL, pwm: YES, interrupt: YES } as const;
+
+/** Shorthand: digital I/O + analog input. */
+const ANALOG_IN = { ...DIGITAL, analogInput: YES } as const;
+
+// ---------------------------------------------------------------------------
+// ATmega328P MCU Definition
+// ---------------------------------------------------------------------------
+
+export const ATmega328P: MCUDefinition = {
+  id: 'atmega328p',
+  name: 'ATmega328P',
+  architecture: 'avr',
+
+  // ----- Memory ------------------------------------------------------------
+  memory: {
+    flash:  32_768, // 32 KB
+    sram:    2_048, //  2 KB
+    eeprom:  1_024, //  1 KB
+  },
+
+  // ----- Pins --------------------------------------------------------------
+  pins: {
+    all: [
+      // Port D pins (PD0–PD7)
+      { number:  0, gpio:  0, name: 'PD0', aliases: ['RX'], capabilities: DIGITAL_INT,
+        functions: [{ type: 'uart', instance: 0, role: 'rx' }],
+        alternateFunctions: ['UART0 RX'],
+        warnings: ['Using PD0 as GPIO will interfere with UART0 receive'],
+        unsafe: true, notes: 'UART RX pin' },
+      { number:  1, gpio:  1, name: 'PD1', aliases: ['TX'], capabilities: DIGITAL_INT,
+        functions: [{ type: 'uart', instance: 0, role: 'tx' }],
+        alternateFunctions: ['UART0 TX'],
+        warnings: ['Using PD1 as GPIO will interfere with UART0 transmit'],
+        unsafe: true, notes: 'UART TX pin' },
+      { number:  2, gpio:  2, name: 'PD2', capabilities: DIGITAL_INT },
+      { number:  3, gpio:  3, name: 'PD3', capabilities: DIGITAL_PWM_INT,
+        functions: [{ type: 'pwm', instance: 0, role: 'OC2B', timer: 'timer2' }] },
+      { number:  4, gpio:  4, name: 'PD4', capabilities: DIGITAL },
+      { number:  5, gpio:  5, name: 'PD5', capabilities: DIGITAL_PWM,
+        functions: [{ type: 'pwm', instance: 0, role: 'OC0B', timer: 'timer0' }] },
+      { number:  6, gpio:  6, name: 'PD6', capabilities: DIGITAL_PWM,
+        functions: [{ type: 'pwm', instance: 0, role: 'OC0A', timer: 'timer0' }] },
+      { number:  7, gpio:  7, name: 'PD7', capabilities: DIGITAL },
+
+      // Port B pins (PB0–PB5)
+      { number:  8, gpio:  8, name: 'PB0', capabilities: DIGITAL },
+      { number:  9, gpio:  9, name: 'PB1', capabilities: DIGITAL_PWM,
+        functions: [{ type: 'pwm', instance: 0, role: 'OC1A', timer: 'timer1' }] },
+      { number: 10, gpio: 10, name: 'PB2', aliases: ['SS'], capabilities: DIGITAL_PWM,
+        functions: [
+          { type: 'pwm', instance: 0, role: 'OC1B', timer: 'timer1' },
+          { type: 'spi', instance: 0, role: 'cs'   },
+        ],
+        alternateFunctions: ['SPI0 CS'] },
+      { number: 11, gpio: 11, name: 'PB3', aliases: ['MOSI'], capabilities: DIGITAL_PWM,
+        functions: [
+          { type: 'pwm', instance: 0, role: 'OC2A', timer: 'timer2' },
+          { type: 'spi', instance: 0, role: 'mosi' },
+        ],
+        alternateFunctions: ['SPI0 MOSI'],
+        warnings: ['Using PB3 as GPIO will interfere with SPI0 MOSI'] },
+      { number: 12, gpio: 12, name: 'PB4', aliases: ['MISO'], capabilities: DIGITAL,
+        functions: [{ type: 'spi', instance: 0, role: 'miso' }],
+        alternateFunctions: ['SPI0 MISO'],
+        warnings: ['Using PB4 as GPIO will interfere with SPI0 MISO'] },
+      { number: 13, gpio: 13, name: 'PB5', aliases: ['SCK'], capabilities: DIGITAL,
+        functions: [{ type: 'spi', instance: 0, role: 'sck' }],
+        alternateFunctions: ['SPI0 SCK'],
+        warnings: ['PB5 is SPI0 SCK'] },
+
+      // Port C pins (PC0–PC5)
+      { number: 14, gpio: 14, name: 'PC0', capabilities: ANALOG_IN,
+        functions: [{ type: 'adc', instance: 0, role: 'ch0' }] },
+      { number: 15, gpio: 15, name: 'PC1', capabilities: ANALOG_IN,
+        functions: [{ type: 'adc', instance: 0, role: 'ch1' }] },
+      { number: 16, gpio: 16, name: 'PC2', capabilities: ANALOG_IN,
+        functions: [{ type: 'adc', instance: 0, role: 'ch2' }] },
+      { number: 17, gpio: 17, name: 'PC3', capabilities: ANALOG_IN,
+        functions: [{ type: 'adc', instance: 0, role: 'ch3' }] },
+      { number: 18, gpio: 18, name: 'PC4', aliases: ['SDA'], capabilities: ANALOG_IN,
+        functions: [
+          { type: 'adc', instance: 0, role: 'ch4' },
+          { type: 'i2c', instance: 0, role: 'sda' },
+        ],
+        alternateFunctions: ['I2C0 SDA', 'ADC ch4'],
+        warnings: ['Using PC4 as GPIO will interfere with I2C0 SDA'] },
+      { number: 19, gpio: 19, name: 'PC5', aliases: ['SCL'], capabilities: ANALOG_IN,
+        functions: [
+          { type: 'adc', instance: 0, role: 'ch5' },
+          { type: 'i2c', instance: 0, role: 'scl' },
+        ],
+        alternateFunctions: ['I2C0 SCL', 'ADC ch5'],
+        warnings: ['Using PC5 as GPIO will interfere with I2C0 SCL'] },
+    ],
+
+    digital: [
+      'PD0', 'PD1', 'PD2', 'PD3', 'PD4', 'PD5', 'PD6', 'PD7',
+      'PB0', 'PB1', 'PB2', 'PB3', 'PB4', 'PB5',
+      'PC0', 'PC1', 'PC2', 'PC3', 'PC4', 'PC5',
+    ],
+    analog: ['PC0', 'PC1', 'PC2', 'PC3', 'PC4', 'PC5'],
+    pwm:    ['PD3', 'PD5', 'PD6', 'PB1', 'PB2', 'PB3'],
+    unsafe: ['PD0', 'PD1'],
+
+    i2c:  { 0: { sda: 'PC4', scl: 'PC5' } },
+    spi:  { 0: { mosi: 'PB3', miso: 'PB4', sck: 'PB5', cs: 'PB2' } },
+    uart: { 
+      0: { tx: 'PD1', rx: 'PD0' },
+      1: { tx: 'PD2', rx: 'PD3' },
+    },
+  },
+
+  // ----- Peripherals -------------------------------------------------------
+  peripherals: MCU_PERIPHERALS,
+
+  // ----- Features ----------------------------------------------------------
+  features: {
+    multicore: false,
+    coreCount: 1,
+    deepSleep: false,
+    watchdog: true,
+    externalInterrupts: true,
+    hardwareRng: false,
+    fpu: false,
+  },
+
+  // ----- Build config ------------------------------------------------------
+  build: {
+    extraFlags: ['-mmcu=atmega328p'],
+  },
+};
+
+export default ATmega328P;

package/src/peripherals.ts

@@ -0,0 +1,216 @@
+// ---------------------------------------------------------------------------
+// @typecad/mcu-atmega328p — Hardware peripheral descriptions
+//
+// Describes the peripherals built into the ATmega328P silicon.
+// These are properties of the chip, not the board — every ATmega328P has
+// exactly the same peripheral count regardless of what board it's on.
+//
+// Source: ATmega328P datasheet, Section 2 — Block Diagram / Peripheral Summary
+// ---------------------------------------------------------------------------
+
+import type {
+  PeripheralInstance,
+  ADCDefinition,
+  PWMDefinition,
+  TimerDefinition,
+} from '@typecad/cuttlefish/api/schema';
+import {
+  I2CBus,
+  SPIBus,
+  SerialPort,
+  i2cName,
+  spiName,
+  serialName,
+  createHALInstances,
+} from '@typecad/hal';
+
+// ---------------------------------------------------------------------------
+// UART — 1 USART peripheral
+// ---------------------------------------------------------------------------
+
+/**
+ * USART peripherals on the ATmega328P.
+ * The ATmega328P has a single USART with full-duplex TX/RX.
+ */
+export const UART_INSTANCES: readonly PeripheralInstance[] = [
+  { instance: 0, defaultPins: { tx: 'PD1', rx: 'PD0' } },
+] as const;
+
+// ---------------------------------------------------------------------------
+// I2C (TWI) — 1 Two-Wire Interface
+// ---------------------------------------------------------------------------
+
+/**
+ * I2C/TWI peripherals on the ATmega328P.
+ * Single TWI peripheral with SDA/SCL on Port C.
+ */
+export const I2C_INSTANCES: readonly PeripheralInstance[] = [
+  { instance: 0, defaultPins: { sda: 'PC4', scl: 'PC5' } },
+] as const;
+
+// ---------------------------------------------------------------------------
+// SPI — 1 SPI peripheral
+// ---------------------------------------------------------------------------
+
+/**
+ * SPI peripherals on the ATmega328P.
+ * Single SPI peripheral in Master/Slave mode.
+ */
+export const SPI_INSTANCES: readonly PeripheralInstance[] = [
+  { instance: 0, defaultPins: { mosi: 'PB3', miso: 'PB4', sck: 'PB5', cs: 'PB2' } },
+] as const;
+
+// ---------------------------------------------------------------------------
+// ADC — 1 ADC with 6 (single-ended) channels on Port C
+// ---------------------------------------------------------------------------
+
+/**
+ * ADC peripheral on the ATmega328P.
+ * 10-bit successive approximation ADC with 6 single-ended channels on PC0–PC5,
+ * plus internal channels for temperature sensor and bandgap reference.
+ *
+ * Note: referenceVoltage and referenceVoltages are board-dependent (determined
+ * by the board's power supply voltage). They are provided as chip-typical
+ * defaults (5V) and should be overridden by the board package if the board
+ * runs at a different voltage (e.g. 3.3V Pro Mini).
+ */
+export const ADC_INSTANCES: readonly ADCDefinition[] = [
+  {
+    instance: 0,
+    channels: 6,
+    resolution: 10,
+    maxValue: 1023,  // (1 << 10) - 1
+    referenceVoltage: 5.0,  // chip-typical default; board may override
+    referenceVoltages: {
+      DEFAULT: 5.0,    // VCC — board-dependent
+      INTERNAL: 1.1,   // internal 1.1V bandgap reference
+    },
+  },
+] as const;
+
+// ---------------------------------------------------------------------------
+// PWM — 6 channels from 3 timers
+// ---------------------------------------------------------------------------
+
+/**
+ * PWM capabilities on the ATmega328P.
+ * 6 PWM channels derived from Timer0 (2 ch), Timer1 (2 ch), Timer2 (2 ch).
+ * 8-bit resolution on Timer0/Timer2, up to 16-bit on Timer1 (but framework
+ * defaults often use 8-bit for all).
+ */
+export const PWM_CAPABILITIES: PWMDefinition = {
+  channels: 6,
+  resolution: 8,
+  maxFrequency: 62_500,  // at 16 MHz with default prescaler
+} as const;
+
+/**
+ * PWM output pin assignments.
+ * Maps each PWM output compare channel to its physical pin.
+ */
+export const PWM_PIN_MAP = {
+  /** Timer0 Channel A — PD6 */
+  OC0A: 'PD6',
+  /** Timer0 Channel B — PD5 */
+  OC0B: 'PD5',
+  /** Timer1 Channel A — PB1 */
+  OC1A: 'PB1',
+  /** Timer1 Channel B — PB2 */
+  OC1B: 'PB2',
+  /** Timer2 Channel A — PB3 */
+  OC2A: 'PB3',
+  /** Timer2 Channel B — PD3 */
+  OC2B: 'PD3',
+} as const;
+
+// ---------------------------------------------------------------------------
+// Timers — 3 hardware timers
+// ---------------------------------------------------------------------------
+
+/**
+ * Hardware timers on the ATmega328P.
+ * Timer0 is typically reserved for system timing functions (millis/delay)
+ * (type: 'sys'). Timer1 and Timer2 are available for general application use.
+ */
+export const TIMER_INSTANCES: readonly TimerDefinition[] = [
+  {
+    instance: 0,
+    type: 'sys',
+    bits: 8,
+    frequency: 16_000_000,
+    features: ['pwm', 'interrupt'],
+  },
+  {
+    instance: 1,
+    type: 'general',
+    bits: 16,
+    frequency: 16_000_000,
+    features: ['pwm', 'interrupt', 'capture', 'compare'],
+  },
+  {
+    instance: 2,
+    type: 'general',
+    bits: 8,
+    frequency: 16_000_000,
+    features: ['pwm', 'interrupt'],
+  },
+] as const;
+
+// ---------------------------------------------------------------------------
+// External interrupts
+// ---------------------------------------------------------------------------
+
+/**
+ * External interrupt pins on the ATmega328P.
+ * Only PD2 (INT0) and PD3 (INT1) support hardware external interrupts.
+ * Pin-change interrupts are available on all pins but are handled separately.
+ */
+export const EXTERNAL_INTERRUPTS = [
+  { instance: 0, pin: 'PD2' },  // INT0
+  { instance: 1, pin: 'PD3' },  // INT1
+] as const;
+
+// ---------------------------------------------------------------------------
+// Aggregate MCU peripheral description
+// ---------------------------------------------------------------------------
+
+/**
+ * Complete hardware peripheral description for the ATmega328P.
+ * Board packages can import this and spread it into their BoardDefinition,
+ * overriding board-specific fields (aliases, reference voltages, etc.).
+ *
+ * @example
+ * ```typescript
+ * // In a board package:
+ * import { MCU_PERIPHERALS } from '@typecad/mcu-atmega328p';
+ *
+ * export const MyBoard: BoardDefinition = {
+ *   // ...
+ *   peripherals: {
+ *     ...MCU_PERIPHERALS,
+ *     aliases: { UART0: 'Serial', I2C0: 'Wire', SPI0: 'SPI' },
+ *   },
+ * };
+ * ```
+ */
+export const MCU_PERIPHERALS = {
+  i2c: [...I2C_INSTANCES],
+  spi: [...SPI_INSTANCES],
+  uart: [...UART_INSTANCES],
+  adc: [...ADC_INSTANCES],
+  pwm: PWM_CAPABILITIES,
+  timers: [...TIMER_INSTANCES],
+} 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] = createHALInstances(UART_INSTANCES, i => new SerialPort(serialName(i)));

package/src/pins.ts

@@ -0,0 +1,74 @@
+// ---------------------------------------------------------------------------
+// @typecad/mcu-atmega328p — Datasheet pin definitions
+//
+// Each pin is a Pin instance created via Pin.fromPort() using the MCU port
+// name from the ATmega328P datasheet. The port name is the canonical identity;
+// framework-specific pin numbers are resolved at
+// transpile time via the arduino-map.
+// ---------------------------------------------------------------------------
+
+import { Pin } from '@typecad/hal';
+
+// ---------------------------------------------------------------------------
+// Port D (PD0–PD7) — 8-bit bidirectional I/O port
+// DIP-28 pins 2–6, 9–11
+// ---------------------------------------------------------------------------
+
+export const PD0 = Pin.fromPort('PD0');
+export const PD1 = Pin.fromPort('PD1');
+export const PD2 = Pin.fromPort('PD2');
+export const PD3 = Pin.fromPort('PD3');
+export const PD4 = Pin.fromPort('PD4');
+export const PD5 = Pin.fromPort('PD5');
+export const PD6 = Pin.fromPort('PD6');
+export const PD7 = Pin.fromPort('PD7');
+
+// ---------------------------------------------------------------------------
+// Port B (PB0–PB7) — 8-bit bidirectional I/O port
+// DIP-28 pins 12–19 (PB6/PB7 are crystal oscillator, not GPIO)
+// ---------------------------------------------------------------------------
+
+export const PB0 = Pin.fromPort('PB0');
+export const PB1 = Pin.fromPort('PB1');
+export const PB2 = Pin.fromPort('PB2');
+export const PB3 = Pin.fromPort('PB3');
+export const PB4 = Pin.fromPort('PB4');
+export const PB5 = Pin.fromPort('PB5');
+export const PB6 = Pin.fromPort('PB6');
+export const PB7 = Pin.fromPort('PB7');
+
+// ---------------------------------------------------------------------------
+// Port C (PC0–PC6) — 7-bit bidirectional I/O port (PC6 is RESET on DIP-28)
+// DIP-28 pins 23–28
+// ---------------------------------------------------------------------------
+
+export const PC0 = Pin.fromPort('PC0');
+export const PC1 = Pin.fromPort('PC1');
+export const PC2 = Pin.fromPort('PC2');
+export const PC3 = Pin.fromPort('PC3');
+export const PC4 = Pin.fromPort('PC4');
+export const PC5 = Pin.fromPort('PC5');
+export const PC6 = Pin.fromPort('PC6');
+
+// ---------------------------------------------------------------------------
+// Convenience aliases (Silicon-level defaults)
+// ---------------------------------------------------------------------------
+
+/** I2C data line (PC4). */
+export const SDA  = PC4;
+/** I2C clock line (PC5). */
+export const SCL  = PC5;
+
+/** SPI master-out / slave-in (PB3). */
+export const MOSI = PB3;
+/** SPI master-in / slave-out (PB4). */
+export const MISO = PB4;
+/** SPI clock (PB5). */
+export const SCK  = PB5;
+/** SPI slave select (PB2). */
+export const SS   = PB2;
+
+/** UART transmit (PD1). */
+export const TX   = PD1;
+/** UART receive (PD0). */
+export const RX   = PD0;