@typecad/framework-arduino 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,192 @@
+# @typecad/framework-arduino
+
+Arduino framework strategy for TypeCAD code generation.
+
+## Overview
+
+`@typecad/framework-arduino` implements the Arduino-compatible code generation strategy used by TypeCAD. It emits Arduino-style C++ calls such as `pinMode()`, `digitalWrite()`, and `Serial` operations, and provides helper utilities for Arduino CLI metadata, library discovery, and runtime polyfills.
+
+## Quick start
+
+Add the package to your `cuttlefish.config.ts`:
+
+```ts
+import type { CuttlefishConfig } from '@typecad/cuttlefish/api';
+
+const config: CuttlefishConfig = {
+  entry: './src/main.ts',
+  target: 'avr',
+  mcu: '@typecad/mcu-atmega328p',
+  board: '@typecad/board-arduino-uno',
+  framework: '@typecad/framework-arduino',
+  output: { framework: 'arduino', optimize: 'size' },
+};
+
+export default config;
+```
+
+Then run the CLI:
+
+```bash
+npx cuttlefish src/main.ts --compile --upload --port COM4
+```
+
+## How to use
+
+### Framework strategy
+
+When `framework` is set to `@typecad/framework-arduino`, TypeCAD generates code compatible with the Arduino runtime and Arduino CLI toolchain.
+
+### Key exports
+
+This package exposes the main Arduino strategy and helpers for advanced workflows:
+
+- `ArduinoStrategy`
+- `FrameworkStrategy` (alias for `ArduinoStrategy`)
+- `compileArduinoSketch`
+- `uploadArduinoSketch`
+- `monitorArduinoSketch`
+- `loadArduinoCliMetadata`
+- `getInstalledLibraries`
+- `generateArduinoLibDecl`
+- `buildArduinoClassNameMap`
+- `arduinoAsyncPolyfill`
+- `generateStdStringPolyfill`
+
+### Arduino library support
+
+The package can discover installed Arduino libraries and generate TypeScript declaration stubs for library imports. This is useful when using third-party Arduino libraries from TypeScript firmware.
+
+### Serial and console polyfills
+
+`@typecad/framework-arduino` includes helpers for detecting `Serial.begin()` usage and injecting Arduino console support automatically when needed.
+
+---
+
+## AVR safety features
+
+The following features are automatically applied when targeting AVR (Arduino Uno, Mega, etc.) or ESP32.
+
+### Panic handler — `cuttlefish_halt`
+
+TypeScript `throw` statements compile to a `cuttlefish_halt("PANIC")` macro call instead of a bare `for(;;){}` loop. The macro prints the message over Serial (using `F()` for flash storage) then halts:
+
+```cpp
+#ifndef cuttlefish_halt
+#define cuttlefish_halt(msg) do { Serial.println(F(msg)); for (;;) {} } while (0)
+#endif
+```
+
+### Flash-storage string literals — `F()`
+
+Bare string literals passed to `console.log` / `console.error` / `console.warn` are automatically wrapped in the Arduino `F()` macro so they reside in program flash rather than precious SRAM:
+
+```ts
+// TypeScript
+console.log("Hello AVR");
+console.error("bad state");
+```
+
+```cpp
+// Generated C++
+Serial.println(F("Hello AVR"));
+Serial.print(F("[ERROR] ")); Serial.println(F("bad state"));
+```
+
+Variable expressions are passed through without wrapping.
+
+### C-stdlib string predicates (no `String` heap allocation)
+
+`.includes()`, `.startsWith()`, and `.endsWith()` on `const char*` values are lowered to C standard-library calls instead of constructing Arduino `String` objects:
+
+| TypeScript               | Generated C++                             |
+|--------------------------|-------------------------------------------|
+| `s.includes(sub)`        | `(strstr(s, sub) != NULL)`                |
+| `s.startsWith(prefix)`   | `(strncmp(s, prefix, strlen(prefix)) == 0)` |
+| `s.endsWith(suffix)`     | `__tc_endsWith(s, suffix)`                |
+
+### Configurable string buffer size — `CUTTLEFISH_STR_BUF_SIZE`
+
+String-method polyfills (`.toUpperCase()`, `.toLowerCase()`, `.trim()`, `.replace()`, etc.) use a stack-allocated buffer whose size is controlled by a compile-time macro. Override it in your sketch or build flags:
+
+```cpp
+#define CUTTLEFISH_STR_BUF_SIZE 128  // default is 64
+```
+
+### Heap-allocation validator
+
+On AVR targets, `new ClassName(args)` in variable declarations produces a compile-time `heap-allocation-avr` error diagnostic. AVR has only 2 KB of SRAM and no heap manager — use stack or global objects instead:
+
+```ts
+// ❌ Error on AVR:
+const sensor = new BME280(0x76);
+
+// ✅ Correct — stack/global allocation:
+let sensor: BME280;   // emits: BME280 sensor;
+```
+
+### `IRAM_ATTR` for ESP32 ISR functions
+
+On ESP32 targets, functions registered as interrupt service routines (ISR callbacks) are automatically prefixed with `IRAM_ATTR` to ensure they run from fast internal RAM:
+
+```cpp
+// Generated on ESP32:
+IRAM_ATTR void myButton_isr_0();
+IRAM_ATTR void myButton_isr_0() { ... }
+```
+
+---
+
+## New namespaces
+
+### `Timing` — timing utilities
+
+| TypeCAD                      | Generated C++                  |
+|-------------------------------|--------------------------------|
+| `Timing.millis()`             | `millis()`                     |
+| `Timing.micros()`             | `micros()`                     |
+| `Timing.delay(ms)`            | `delay(ms)`                    |
+| `Timing.delayMicroseconds(us)`| `delayMicroseconds(us)`        |
+
+```ts
+const t0 = Timing.millis();
+Timing.delay(500);
+const elapsed = Timing.millis() - t0;
+```
+
+### `EEPROM` — non-volatile storage
+
+Requires `<EEPROM.h>` (included automatically by the board framework).
+
+| TypeCAD                      | Generated C++                  |
+|-------------------------------|--------------------------------|
+| `EEPROM.read(addr)`           | `EEPROM.read(addr)`            |
+| `EEPROM.write(addr, val)`     | `EEPROM.write(addr, val)`      |
+| `EEPROM.update(addr, val)`    | `EEPROM.update(addr, val)`     |
+| `EEPROM.length()`             | `EEPROM.length()`              |
+| `EEPROM.get(addr, ref)`       | `EEPROM.get(addr, ref)`        |
+| `EEPROM.put(addr, ref)`       | `EEPROM.put(addr, ref)`        |
+
+`EEPROM.update()` is preferred over `EEPROM.write()` when the value may not have changed — it skips the write cycle and extends EEPROM lifetime.
+
+### `WDT` — watchdog timer
+
+Controls the AVR hardware watchdog. Requires `<avr/wdt.h>`.
+
+| TypeCAD                      | Generated C++                    |
+|-------------------------------|----------------------------------|
+| `WDT.enable('2s')`            | `wdt_enable(WDTO_2S)`            |
+| `WDT.reset()`                 | `wdt_reset()`                    |
+| `WDT.disable()`               | `wdt_disable()`                  |
+
+Supported timeout strings: `'15ms'`, `'30ms'`, `'60ms'`, `'120ms'`, `'250ms'`, `'500ms'`, `'1s'`, `'2s'`, `'4s'`, `'8s'`. Calling `WDT.enable()` without an argument defaults to `WDTO_2S`.
+
+```ts
+WDT.enable('1s');   // reset within 1 second or the board reboots
+
+function loop(): void {
+  WDT.reset();      // pet the watchdog each loop iteration
+  doWork();
+}
+```
+

package/dist/arduino/i2c-arduino.d.ts

@@ -0,0 +1,47 @@
+import type { I2CAddress } from '@typecad/hal';
+/**
+ * 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;
+    /** Initialize as I2C master. */
+    begin(): void;
+    /** Initialize as I2C slave with given address. */
+    begin(address: I2CAddress): void;
+    /** 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;
+    /** 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;
+    /** Set the I2C clock frequency in Hz. */
+    setClock(clock: number): void;
+    /** 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;
+    /** Disable the Wire peripheral. */
+    end(): void;
+    /** Attempt to recover a stuck bus (toggles SCL to release stuck slaves). */
+    recover(): boolean;
+}

package/dist/arduino/i2c-arduino.js

@@ -0,0 +1,6 @@
+// ---------------------------------------------------------------------------
+// @typecad/framework-arduino — I2C Arduino-compatible API interface
+//
+// Arduino Wire-compatible methods for I2C communication.
+// ---------------------------------------------------------------------------
+export {};

package/dist/arduino/index.d.ts

@@ -0,0 +1,6 @@
+export type { II2CArduino } from './i2c-arduino.js';
+export type { ISPIArduino } from './spi-arduino.js';
+export type { ISerialArduino } from './uart-arduino.js';
+export type { I2CAddress } from '@typecad/hal';
+export type { SPIMode, SPIBitOrder, SPISettings } from '@typecad/hal';
+export { I2C0, SPI0, UART0 } from './stubs-uno.js';

package/dist/arduino/index.js

@@ -0,0 +1,8 @@
+// ---------------------------------------------------------------------------
+// @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.
+// ---------------------------------------------------------------------------
+// Arduino Uno stubs
+export { I2C0, SPI0, UART0 } from './stubs-uno.js';

package/dist/arduino/spi-arduino.d.ts

@@ -0,0 +1,42 @@
+import type { SPIMode, SPIBitOrder, SPISettings } from '@typecad/hal';
+/**
+ * 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;
+    /** Initialize the SPI bus. */
+    begin(): void;
+    /** Disable the SPI bus. */
+    end(): void;
+    /** Begin a transaction with specific settings. */
+    beginTransaction(settings: SPISettings): void;
+    /** End the current transaction. */
+    endTransaction(): void;
+    /** 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 a single byte. */
+    write(data: number): void;
+    /** Write a 16-bit value. */
+    write16(data: number): void;
+    /** 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/dist/arduino/spi-arduino.js

@@ -0,0 +1,6 @@
+// ---------------------------------------------------------------------------
+// @typecad/framework-arduino — SPI Arduino-compatible API interface
+//
+// Arduino SPI-compatible methods for SPI communication.
+// ---------------------------------------------------------------------------
+export {};

package/dist/arduino/stubs-uno.d.ts

@@ -0,0 +1,9 @@
+import type { II2CArduino } from './i2c-arduino.js';
+import type { ISPIArduino } from './spi-arduino.js';
+import type { ISerialArduino } from './uart-arduino.js';
+/** Arduino Uno I2C bus 0 (Wire library, pins A4=SDA / A5=SCL). */
+export declare const I2C0: II2CArduino;
+/** Arduino Uno SPI bus 0 (pins D11=MOSI, D12=MISO, D13=SCK, D10=SS). */
+export declare const SPI0: ISPIArduino;
+/** Arduino Uno hardware serial (UART 0, pins D0/RX, D1/TX, + USB). */
+export declare const UART0: ISerialArduino;

package/dist/arduino/stubs-uno.js

@@ -0,0 +1,65 @@
+// ---------------------------------------------------------------------------
+// Arduino Uno — Arduino-compatible API stub implementations
+//
+// Empty stubs for type checking. The transpiler replaces these with Arduino
+// C++ calls via framework-arduino handlers.
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// I2C — Wire (bus 0) - Arduino API
+// ---------------------------------------------------------------------------
+/** Arduino Uno I2C bus 0 (Wire library, pins A4=SDA / A5=SCL). */
+export const I2C0 = {
+    busNumber: 0,
+    isInitialized: false,
+    begin(_address) { },
+    beginTransmission(_address) { },
+    write(_data) { return 0; },
+    endTransmission(_stop) { return 0; },
+    requestFrom(_address, _quantity, _stop) { return 0; },
+    available() { return 0; },
+    read() { return -1; },
+    setClock(_clock) { },
+    onReceive(_handler) { },
+    onRequest(_handler) { },
+    end() { },
+    recover() { return true; },
+};
+// ---------------------------------------------------------------------------
+// SPI — SPI (bus 0) - Arduino API
+// ---------------------------------------------------------------------------
+/** Arduino Uno SPI bus 0 (pins D11=MOSI, D12=MISO, D13=SCK, D10=SS). */
+export const SPI0 = {
+    isInitialized: false,
+    begin() { },
+    end() { },
+    beginTransaction(_settings) {
+        /* transpiler: SPI.beginTransaction(SPISettings(freq, bitOrder, mode)); */
+    },
+    endTransaction() { },
+    transfer(_data) { return 0; },
+    transferBuffer(_buffer) { return new Uint8Array(0); },
+    write(_data) { },
+    write16(_data) { },
+    setFrequency(_hz) { },
+    setMode(_mode) { },
+    setBitOrder(_order) { },
+};
+// ---------------------------------------------------------------------------
+// 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 = {
+    uartNumber: 0,
+    baudRate: 9600,
+    isInitialized: false,
+    begin(_baud) { },
+    end() { },
+    available() { return 0; },
+    peek() { return -1; },
+    read() { return -1; },
+    write(_data) { return 0; },
+    flush() { },
+    print(..._args) { },
+    println(..._args) { },
+    printf(_format, ..._args) { },
+};

package/dist/arduino/uart-arduino.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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;
+    /** Initialize with baud rate. */
+    begin(baud: number): void;
+    /** Deinitialize the UART. */
+    end(): void;
+    /** 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;
+    /** Wait for transmission to complete. */
+    flush(): void;
+    /** 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/dist/arduino/uart-arduino.js

@@ -0,0 +1,6 @@
+// ---------------------------------------------------------------------------
+// @typecad/framework-arduino — UART/Serial Arduino-compatible API interface
+//
+// Arduino Serial-compatible methods for UART communication.
+// ---------------------------------------------------------------------------
+export {};

package/dist/arduino-class-map.d.ts

@@ -0,0 +1,5 @@
+export interface ArduinoImportLike {
+    moduleSpecifier: string;
+    namedImports: string[];
+}
+export declare function buildArduinoClassNameMap(imports: ArduinoImportLike[]): Map<string, string>;

package/dist/arduino-class-map.js

@@ -0,0 +1,21 @@
+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();
+export function buildArduinoClassNameMap(imports) {
+    const result = new Map();
+    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;
+}

package/dist/arduino-compile.d.ts

@@ -0,0 +1,24 @@
+import type { CompileResult, UploadResult } from "@typecad/cuttlefish/api/shared";
+export type ArduinoCompileResult = CompileResult;
+export type ArduinoUploadResult = UploadResult;
+/**
+ * Parse memory usage from arduino-cli output.
+ */
+export declare function parseArduinoMemoryUsage(output: string): {
+    flashUsed?: number;
+    flashTotal?: number;
+    ramUsed?: number;
+    ramTotal?: number;
+};
+/**
+ * Extract architecture from FQBN string.
+ * FQBN format: vendor:arch:board[:config]
+ */
+export declare function toArchitectureFromFqbn(buildTarget?: string): string | undefined;
+export declare function flattenGeneratedModulesIntoSketch(sketchDir: string, sketchPath: string): void;
+export declare function compileArduinoSketch(sketchFilePath: string, buildTarget: string, options?: {
+    extraFlags?: string[];
+    defines?: Record<string, string>;
+}): ArduinoCompileResult;
+export declare function uploadArduinoSketch(sketchDir: string, buildTarget: string, port: string): ArduinoUploadResult;
+export declare function monitorArduinoSketch(port: string, baud: number): void;