@typecad/framework-arduino 0.1.0-alpha.1

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@typecad/framework-arduino",
+  "version": "0.1.0-alpha.1",
+  "description": "TypeCAD framework package for Arduino framework code generation",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./arduino": {
+      "types": "./dist/arduino/index.d.ts",
+      "default": "./dist/arduino/index.js"
+    },
+    "./graphics/ili9341": {
+      "types": "./dist/graphics/ili9341.d.ts",
+      "default": "./dist/graphics/ili9341.js"
+    },
+    "./displays/ili9341-spi": {
+      "types": "./dist/displays/ili9341-spi.d.ts",
+      "default": "./dist/displays/ili9341-spi.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test:hw": "npm exec -- cuttlefish-test",
+    "test:hw:basics": "npm exec -- cuttlefish-test tests/01-basics.test.ts"
+  },
+  "dependencies": {
+    "@typecad/hal": "0.1.0-alpha.1"
+  },
+  "devDependencies": {
+    "@typecad/expect": "0.1.0-alpha.1",
+    "@typecad/board-esp32-devkit": "0.1.0-alpha.1"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/justind000/typecode.git",
+    "directory": "packages/framework-arduino"
+  },
+  "homepage": "https://github.com/justind000/typecode/tree/main/packages/framework-arduino",
+  "bugs": {
+    "url": "https://github.com/justind000/typecode/issues"
+  },
+  "keywords": [
+    "arduino",
+    "cpp",
+    "cuttlefish",
+    "embedded",
+    "esp32",
+    "firmware",
+    "framework",
+    "microcontroller",
+    "typecad",
+    "typescript"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "typecad0",
+  "sideEffects": false
+}

package/src/arduino/i2c-arduino.ts

@@ -0,0 +1,72 @@
+// ---------------------------------------------------------------------------
+// @typecad/framework-arduino — I2C Arduino-compatible API interface
+//
+// Arduino Wire-compatible methods for I2C communication.
+// ---------------------------------------------------------------------------
+
+import type { I2CAddress } from '@typecad/hal';
+
+// ---------------------------------------------------------------------------
+// Arduino Wire-compatible Interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Arduino Wire-compatible I2C bus interface.
+ *
+ * Usage:
+ * ```typescript
+ * import { I2C0 } from '@typecad/framework-arduino/arduino';
+ *
+ * I2C0.begin();
+ * I2C0.setClock(400000);
+ * I2C0.beginTransmission(0x76);
+ * I2C0.write(0xFA);
+ * const status = I2C0.endTransmission();
+ * const bytesAvailable = I2C0.requestFrom(0x76, 2);
+ * const data = I2C0.read();
+ * ```
+ */
+export interface II2CArduino {
+  readonly busNumber: number;
+  readonly isInitialized: boolean;
+
+  // --- Initialization ---
+  /** Initialize as I2C master. */
+  begin(): void;
+  /** Initialize as I2C slave with given address. */
+  begin(address: I2CAddress): void;
+
+  // --- Transactional write API ---
+  /** Begin a transmission to the given address. */
+  beginTransmission(address: I2CAddress): void;
+  /** Write data to the transmission buffer. Returns number of bytes written. */
+  write(data: number | Uint8Array | string): number;
+  /** End the transmission and send data. Returns status code. */
+  endTransmission(stop?: boolean): number;
+
+  // --- Read API ---
+  /** Request bytes from a slave. Returns number of bytes available. */
+  requestFrom(address: I2CAddress, quantity: number, stop?: boolean): number;
+  /** Number of bytes available to read. */
+  available(): number;
+  /** Read a single byte from the buffer. Returns -1 if no data available. */
+  read(): number;
+
+  // --- Clock control ---
+  /** Set the I2C clock frequency in Hz. */
+  setClock(clock: number): void;
+
+  // --- Slave mode callbacks ---
+  /** Register a callback for when data is received as slave. */
+  onReceive(handler: (howMany: number) => void): void;
+  /** Register a callback for when data is requested from slave. */
+  onRequest(handler: () => void): void;
+
+  // --- Cleanup ---
+  /** Disable the Wire peripheral. */
+  end(): void;
+
+  // --- Bus recovery ---
+  /** Attempt to recover a stuck bus (toggles SCL to release stuck slaves). */
+  recover(): boolean;
+}

package/src/arduino/index.ts

@@ -0,0 +1,18 @@
+// ---------------------------------------------------------------------------
+// @typecad/framework-arduino/arduino — Arduino-compatible API types and stubs
+//
+// Import from '@typecad/framework-arduino/arduino' to use Arduino-style APIs
+// (Wire, SPI, Serial) with full TypeScript type checking.
+// ---------------------------------------------------------------------------
+
+// Interface definitions
+export type { II2CArduino } from './i2c-arduino.js';
+export type { ISPIArduino } from './spi-arduino.js';
+export type { ISerialArduino } from './uart-arduino.js';
+
+// Supporting types from core (re-exported for convenience)
+export type { I2CAddress } from '@typecad/hal';
+export type { SPIMode, SPIBitOrder, SPISettings } from '@typecad/hal';
+
+// Arduino Uno stubs
+export { I2C0, SPI0, UART0 } from './stubs-uno.js';

package/src/arduino/spi-arduino.ts

@@ -0,0 +1,63 @@
+// ---------------------------------------------------------------------------
+// @typecad/framework-arduino — SPI Arduino-compatible API interface
+//
+// Arduino SPI-compatible methods for SPI communication.
+// ---------------------------------------------------------------------------
+
+import type { SPIMode, SPIBitOrder, SPISettings } from '@typecad/hal';
+
+// ---------------------------------------------------------------------------
+// Arduino SPI-compatible Interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Arduino SPI-compatible bus interface.
+ *
+ * Usage:
+ * ```typescript
+ * import { SPI0 } from '@typecad/framework-arduino/arduino';
+ *
+ * SPI0.begin();
+ * SPI0.setMode(0);
+ * SPI0.setBitOrder('msb');
+ * SPI0.setFrequency(1_000_000);
+ *
+ * const response = SPI0.transfer(0xAA);
+ * SPI0.transferBuffer(buffer);
+ * ```
+ */
+export interface ISPIArduino {
+  readonly isInitialized: boolean;
+
+  // --- Initialization ---
+  /** Initialize the SPI bus. */
+  begin(): void;
+  /** Disable the SPI bus. */
+  end(): void;
+
+  // --- Transactions ---
+  /** Begin a transaction with specific settings. */
+  beginTransaction(settings: SPISettings): void;
+  /** End the current transaction. */
+  endTransaction(): void;
+
+  // --- Transfer ---
+  /** Transfer a single byte (full-duplex). Returns received byte. */
+  transfer(data: number): number;
+  /** Transfer a buffer (full-duplex). Returns received bytes. */
+  transferBuffer(buffer: Uint8Array): Uint8Array;
+
+  // --- Write (transfer ignoring return) ---
+  /** Write a single byte. */
+  write(data: number): void;
+  /** Write a 16-bit value. */
+  write16(data: number): void;
+
+  // --- Configuration ---
+  /** Set clock frequency in Hz. */
+  setFrequency(hz: number): void;
+  /** Set SPI mode (0-3). */
+  setMode(mode: SPIMode): void;
+  /** Set bit order. */
+  setBitOrder(order: SPIBitOrder): void;
+}

package/src/arduino/stubs-uno.ts

@@ -0,0 +1,80 @@
+// ---------------------------------------------------------------------------
+// Arduino Uno — Arduino-compatible API stub implementations
+//
+// Empty stubs for type checking. The transpiler replaces these with Arduino
+// C++ calls via framework-arduino handlers.
+// ---------------------------------------------------------------------------
+
+import type { II2CArduino } from './i2c-arduino.js';
+import type { I2CAddress } from '@typecad/hal';
+import type { ISPIArduino } from './spi-arduino.js';
+import type { SPIMode, SPIBitOrder, SPISettings } from '@typecad/hal';
+import type { ISerialArduino } from './uart-arduino.js';
+
+// ---------------------------------------------------------------------------
+// I2C — Wire (bus 0) - Arduino API
+// ---------------------------------------------------------------------------
+
+/** Arduino Uno I2C bus 0 (Wire library, pins A4=SDA / A5=SCL). */
+export const I2C0: II2CArduino = {
+  busNumber: 0,
+  isInitialized: false,
+
+  begin(_address?: I2CAddress) { /* transpiler: Wire.begin(); or Wire.begin(addr); */ },
+  beginTransmission(_address: I2CAddress) { /* transpiler: Wire.beginTransmission(addr); */ },
+  write(_data: number | Uint8Array | string): number { return 0; },
+  endTransmission(_stop?: boolean): number { return 0; },
+  requestFrom(_address: I2CAddress, _quantity: number, _stop?: boolean): number { return 0; },
+  available(): number { return 0; },
+  read(): number { return -1; },
+  setClock(_clock: number) { /* transpiler: Wire.setClock(hz); */ },
+  onReceive(_handler: (howMany: number) => void) {},
+  onRequest(_handler: () => void) {},
+  end() { /* transpiler: Wire.end(); */ },
+  recover(): boolean { return true; },
+} as II2CArduino;
+
+// ---------------------------------------------------------------------------
+// SPI — SPI (bus 0) - Arduino API
+// ---------------------------------------------------------------------------
+
+/** Arduino Uno SPI bus 0 (pins D11=MOSI, D12=MISO, D13=SCK, D10=SS). */
+export const SPI0: ISPIArduino = {
+  isInitialized: false,
+
+  begin() { /* transpiler: SPI.begin(); */ },
+  end() { /* transpiler: SPI.end(); */ },
+  beginTransaction(_settings: SPISettings) {
+    /* transpiler: SPI.beginTransaction(SPISettings(freq, bitOrder, mode)); */
+  },
+  endTransaction() { /* transpiler: SPI.endTransaction(); */ },
+  transfer(_data: number): number { return 0; },
+  transferBuffer(_buffer: Uint8Array): Uint8Array { return new Uint8Array(0); },
+  write(_data: number): void {},
+  write16(_data: number): void {},
+  setFrequency(_hz: number): void {},
+  setMode(_mode: SPIMode): void {},
+  setBitOrder(_order: SPIBitOrder): void {},
+} as ISPIArduino;
+
+// ---------------------------------------------------------------------------
+// UART0 — UART 0 (USB / pins D0=RX, D1=TX) - Arduino API
+// ---------------------------------------------------------------------------
+
+/** Arduino Uno hardware serial (UART 0, pins D0/RX, D1/TX, + USB). */
+export const UART0: ISerialArduino = {
+  uartNumber: 0,
+  baudRate: 9600,
+  isInitialized: false,
+
+  begin(_baud: number) { /* transpiler: Serial.begin(baud); */ },
+  end() { /* transpiler: Serial.end(); */ },
+  available(): number { return 0; },
+  peek(): number { return -1; },
+  read(): number { return -1; },
+  write(_data: number | Uint8Array | string): number { return 0; },
+  flush() {},
+  print(..._args: unknown[]) {},
+  println(..._args: unknown[]) {},
+  printf(_format: string, ..._args: unknown[]) {},
+} as ISerialArduino;

package/src/arduino/uart-arduino.ts

@@ -0,0 +1,59 @@
+// ---------------------------------------------------------------------------
+// @typecad/framework-arduino — UART/Serial Arduino-compatible API interface
+//
+// Arduino Serial-compatible methods for UART communication.
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Arduino Serial-compatible Interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Arduino Serial-compatible UART interface.
+ *
+ * Usage:
+ * ```typescript
+ * import { UART0 } from '@typecad/framework-arduino/arduino';
+ *
+ * UART0.begin(9600);
+ * UART0.println("Hello, World!");
+ *
+ * if (UART0.available() > 0) {
+ *   const data = UART0.read();
+ *   UART0.write(data);
+ * }
+ * ```
+ */
+export interface ISerialArduino {
+  readonly uartNumber: number;
+  readonly baudRate: number;
+  readonly isInitialized: boolean;
+
+  // --- Initialization ---
+  /** Initialize with baud rate. */
+  begin(baud: number): void;
+  /** Deinitialize the UART. */
+  end(): void;
+
+  // --- Read API ---
+  /** Number of bytes available to read. */
+  available(): number;
+  /** Peek at next byte without consuming. Returns -1 if no data. */
+  peek(): number;
+  /** Read a single byte. Returns -1 if no data available. */
+  read(): number;
+  /** Write a single byte or buffer. Returns number of bytes written. */
+  write(data: number | Uint8Array | string): number;
+
+  // --- Buffer control ---
+  /** Wait for transmission to complete. */
+  flush(): void;
+
+  // --- Print helpers ---
+  /** Print values without newline. */
+  print(...args: unknown[]): void;
+  /** Print values with newline. */
+  println(...args: unknown[]): void;
+  /** Printf-style formatted print. */
+  printf(format: string, ...args: unknown[]): void;
+}

package/src/arduino-class-map.ts

@@ -0,0 +1,32 @@
+import { getArduinoLibraryClassNames, isArduinoLibraryImport } from "./arduino-libs.js";
+
+// Module-level cache for Arduino library class name mappings.
+// Maps module specifier -> (simple class name -> fully qualified name)
+const arduinoClassNameCache = new Map<string, Map<string, string>>();
+
+export interface ArduinoImportLike {
+  moduleSpecifier: string;
+  namedImports: string[];
+}
+
+export function buildArduinoClassNameMap(imports: ArduinoImportLike[]): Map<string, string> {
+  const result = new Map<string, string>();
+
+  for (const importedModule of imports) {
+    if (!isArduinoLibraryImport(importedModule.moduleSpecifier)) {
+      continue;
+    }
+
+    let classMap = arduinoClassNameCache.get(importedModule.moduleSpecifier);
+    if (!classMap) {
+      classMap = getArduinoLibraryClassNames(importedModule.moduleSpecifier);
+      arduinoClassNameCache.set(importedModule.moduleSpecifier, classMap);
+    }
+
+    for (const [simpleName, fullName] of classMap) {
+      result.set(simpleName, fullName);
+    }
+  }
+
+  return result;
+}