@typecad/hal 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,127 @@
+# `@typecad/hal`
+
+Hardware abstraction layer for [TypeCAD](https://github.com/justind000/typecode) —
+GPIO, I2C, SPI, UART, timers, ADC/DAC, EEPROM, and more, written as regular
+TypeScript.
+
+`@typecad/hal` is what firmware code imports to talk to hardware. You write
+normal TypeScript (`pin.high()`, `i2c.write(...)`, `Serial0.print(...)`); the
+TypeCAD transpiler (`@typecad/cuttlefish`) resolves each HAL call against the
+active MCU/board packages and emits the equivalent C++ at build time.
+
+## Install
+
+```bash
+npm install @typecad/hal @typecad/cuttlefish
+```
+
+You'll also want an MCU package (e.g. `@typecad/mcu-esp32`) and a board package
+(e.g. `@typecad/board-esp32-devkit`) to pin and bus definitions for your target.
+
+## Overview
+
+The HAL is built on three compile-time directives that look like ordinary
+TypeScript but are intercepted by the transpiler:
+
+- **`emit(text)`** — appends a line of C++ to the output (with parameter/field substitution).
+- **`include(header)`** — adds a deduplicated `#include` to the output.
+- **`board(path)`** — looks up a board-specific constant (e.g. pin numbers) inside an `emit()` template.
+
+This means there are no runtime fallbacks: if the HAL doesn't `emit()` it, it
+doesn't appear in the firmware. See [`HAL-GUIDE.md`](./HAL-GUIDE.md) for how to
+add new HAL features.
+
+## What's included
+
+| Area | Exports |
+| --- | --- |
+| **Digital I/O** | `Pin`, `OutputPin`, `InputPin`, `PinMode`, `HIGH`, `LOW`, `INPUT`, `OUTPUT`, `INPUT_PULLUP` |
+| **Pin groups** | `createPinGroup`, `IPinGroup`, `PinCapabilityFlags` |
+| **Analog** | `ADC`, `ADCClass`, `DAC`, `DACClass`, `AnalogValue` |
+| **I2C** | `I2CBus`, `II2CBus`, `I2CStatus`, `i2cName` |
+| **SPI** | `SPIBus`, `ISPIBus`, `SPIStatus`, `SPISettings`, `spiName` |
+| **UART / Serial** | `SerialPort`, `IUARTBus`, `UARTStatus`, `serialName` |
+| **Timing** | `delay`, `millis`, `micros`, `delayMicroseconds`, `Timing`, `map`, `constrain` |
+| **Pulse / Shift** | `pulseIn`, `shiftIn`, `shiftOut` |
+| **Interrupts** | `attachInterrupt`, `detachInterrupt`, `noInterrupts`, `interrupts`, `InterruptMode` |
+| **Timers** | `HardwareTimer`, `Timer0`, `Timer1`, `Timer2` |
+| **Storage** | `EEPROM`, `Preferences` (NVFlash), `FS` |
+| **Power / Watchdog** | `Power`, `WDT` (`WDTO_1S`, …) |
+| **Math / Random** | `abs`, `min`, `max`, `Num`, `random`, `randomSeed` |
+| **Async** | `Async` (cooperative scheduling) |
+| **Directives** | `emit`, `include`, `board`, `callback` |
+
+## Example
+
+```ts
+import { OutputPin, HIGH, LOW, delay } from '@typecad/hal';
+
+const led = new OutputPin('LED_BUILTIN');
+
+export function setup() {
+  led.mode();
+}
+
+export function loop() {
+  led.write(HIGH);
+  delay(500);
+  led.write(LOW);
+  delay(500);
+}
+```
+
+For I2C/SPI/UART, instantiate the bus class with the board's pinned instance
+(see your `@typecad/board-*` package for available bus names).
+
+## Hardware tests
+
+The [`tests/`](./tests/) directory contains a hardware test suite that
+exercises every AVR-compilable HAL subsystem against real Arduino Uno hardware,
+using [`@typecad/expect`](https://github.com/justind000/typecode/tree/main/packages/expect)
+(`describe()` / `.it()` / `.expect()` / `done()`) over serial. Each file covers
+one subsystem: GPIO, timing, math, random, pulse, shift, interrupts, UART,
+I2C, SPI, ADC, EEPROM, WDT, Preferences, async, and constants.
+
+ESP32-only subsystems (DAC, `FS`, `Power`, `HardwareTimer`) are intentionally
+omitted — they require an ESP32 target.
+
+Run on a connected Uno:
+
+```bash
+npm exec --workspace @typecad/hal -- cuttlefish-test
+```
+
+The suite is configured by [`cuttlefish.config.ts`](./cuttlefish.config.ts).
+Like the [`@typecad/framework-arduino`](https://github.com/justind000/typecode/tree/main/packages/framework-arduino/tests)
+tests, it imports through `@typecad/board` (the board package) and ambient globals
+declared in `cuttlefish-env.d.ts`, never directly from `@typecad/board`, so the
+transpiler resolves each call against the active MCU/board packages.
+
+### Skipped on AVR
+
+One file is skipped on AVR by a `@typecad-skip-target` directive, for a
+genuine hardware reason (not a transpiler limitation):
+
+- **`08-uart`** — the Uno has a single hardware UART, which the test runner
+  itself uses as the `[TC:...]` protocol channel. Any `UART0` call disrupts
+  that channel. Runs on multi-UART targets (ESP32).
+
+The async test (`15-async`) **runs on AVR**: on heap-less targets the
+transpiler emits a fixed-capacity, allocation-free static timer/task runtime
+(`async-runtime-static.ts`) in place of the full `Promise<T>` runtime used on
+ESP32, so `Async.sleep`/`yield`/`sleepUntil`/`currentTask` link and run on the
+ATmega328P.
+
+ESP32-only subsystems (DAC, `FS`, `Power`, `HardwareTimer`) are omitted
+entirely — they require an ESP32 target.
+
+## Ecosystem
+
+- [`@typecad/cuttlefish`](https://github.com/justind000/typecode/tree/main/packages/cuttlefish) — the transpiler that resolves HAL calls to C++.
+- [`@typecad/ui`](https://github.com/justind000/typecode/tree/main/packages/ui) — HTML/CSS-driven display graphics.
+- `@typecad/mcu-*` — silicon pin/port/peripheral definitions.
+- `@typecad/board-*` — board-level pin mappings and bus aliases.
+
+## License
+
+MIT

package/dist/adc.d.ts

@@ -0,0 +1,13 @@
+export declare class ADCClass {
+    static readonly __instance_name = "ADC";
+    static readonly __default_fields: {
+        _reference: string;
+    };
+    _reference: string;
+    constructor();
+    getAnalogResolution(): number;
+    setAnalogReference(ref: string): void;
+    getAnalogReference(): number;
+    read(pin: number): number;
+}
+export declare const ADC: ADCClass;

package/dist/adc.js

@@ -0,0 +1,22 @@
+import { adcRead, adcSetReference, boardResolve } from './emit.js';
+export class ADCClass {
+    constructor() {
+        this._reference = "DEFAULT";
+    }
+    getAnalogResolution() {
+        return boardResolve("peripherals.adc.0.resolution");
+    }
+    setAnalogReference(ref) {
+        this._reference = ref;
+        adcSetReference(ref);
+    }
+    getAnalogReference() {
+        return boardResolve("peripherals.adc.0.referenceVoltages." + this._reference);
+    }
+    read(pin) {
+        return adcRead(pin);
+    }
+}
+ADCClass.__instance_name = "ADC";
+ADCClass.__default_fields = { _reference: "DEFAULT" };
+export const ADC = new ADCClass();

package/dist/async.d.ts

@@ -0,0 +1,30 @@
+export declare class AsyncClass {
+    static readonly __instance_name = "Async";
+    /**
+     * Non-blocking sleep for `ms` milliseconds.
+     * Returns a Promise<void> that resolves after the given delay.
+     * The underlying C++ implementation uses the platform's timer/microtask
+     * mechanism (e.g. millis-based polling on Arduino, std::this_thread::sleep_for
+     * on native, or a FreeRTOS vTaskDelay in the future).
+     */
+    sleep(ms: number): Promise<void>;
+    /**
+     * Cooperative yield — suspend the current task and allow other tasks
+     * (microtasks, timers) to run. Resumes on the next microtask pump cycle.
+     */
+    yield(): Promise<void>;
+    /**
+     * Await a polling condition.
+     * Repeatedly checks `condition()` every `pollIntervalMs` milliseconds
+     * until it returns true, then resolves.
+     * The underlying implementation uses the platform's timer mechanism.
+     */
+    sleepUntil(condition: () => boolean, pollIntervalMs?: number): Promise<void>;
+    /**
+     * Return a human-readable description of the currently executing async task.
+     * Useful for debugging / logging in cooperative multitasking environments.
+     */
+    currentTask(): string;
+}
+/** Singleton instance — consumers use `Async.sleep(...)` directly. */
+export declare const Async: AsyncClass;

package/dist/async.js

@@ -0,0 +1,56 @@
+// ---------------------------------------------------------------------------
+// Async — Top-level cooperative async / scheduling abstraction for TypeCAD
+//
+// Provides a platform-independent API for:
+//   - sleep(ms)      — non-blocking delay via Promise + microtask
+//   - yield()        — cooperative yield to other tasks
+//   - sleepUntil(condition) — await a condition (promise-based)
+//   - currentTask()  — return a description of the currently executing task
+//
+// Framework packages (Arduino, Native, etc.) provide the C++ runtime behind
+// the rawCpp() markers; the transpiler resolves these to the correct platform
+// implementation at compile time.
+// ---------------------------------------------------------------------------
+import { rawCpp } from './emit.js';
+export class AsyncClass {
+    /**
+     * Non-blocking sleep for `ms` milliseconds.
+     * Returns a Promise<void> that resolves after the given delay.
+     * The underlying C++ implementation uses the platform's timer/microtask
+     * mechanism (e.g. millis-based polling on Arduino, std::this_thread::sleep_for
+     * on native, or a FreeRTOS vTaskDelay in the future).
+     */
+    sleep(ms) {
+        rawCpp(`__cuttlefish_async_sleep(${ms});`);
+        return Promise.resolve();
+    }
+    /**
+     * Cooperative yield — suspend the current task and allow other tasks
+     * (microtasks, timers) to run. Resumes on the next microtask pump cycle.
+     */
+    yield() {
+        rawCpp(`__cuttlefish_async_yield();`);
+        return Promise.resolve();
+    }
+    /**
+     * Await a polling condition.
+     * Repeatedly checks `condition()` every `pollIntervalMs` milliseconds
+     * until it returns true, then resolves.
+     * The underlying implementation uses the platform's timer mechanism.
+     */
+    sleepUntil(condition, pollIntervalMs = 10) {
+        rawCpp(`__cuttlefish_async_sleep_until(${pollIntervalMs});`);
+        return Promise.resolve();
+    }
+    /**
+     * Return a human-readable description of the currently executing async task.
+     * Useful for debugging / logging in cooperative multitasking environments.
+     */
+    currentTask() {
+        rawCpp(`return __cuttlefish_async_current_task();`);
+        return "";
+    }
+}
+AsyncClass.__instance_name = "Async";
+/** Singleton instance — consumers use `Async.sleep(...)` directly. */
+export const Async = new AsyncClass();

package/dist/board.d.ts

@@ -0,0 +1,3 @@
+/** Compile-time function: resolves a board definition path to a literal value.
+ *  At runtime (tests, type-checking) this is a no-op that returns undefined. */
+export declare function board(_path: string): any;

package/dist/board.js

@@ -0,0 +1,5 @@
+/** Compile-time function: resolves a board definition path to a literal value.
+ *  At runtime (tests, type-checking) this is a no-op that returns undefined. */
+export function board(_path) {
+    return undefined;
+}

package/dist/callback.d.ts

@@ -0,0 +1,4 @@
+/** Compile-time function: registers a function argument as a standalone C++ callback.
+ *  Returns the generated function name for use in rawCpp() templates.
+ *  At runtime (tests, type-checking) this is a no-op. */
+export declare function callback<T extends (...args: any[]) => any>(_fn: T): string;

package/dist/callback.js

@@ -0,0 +1,6 @@
+/** Compile-time function: registers a function argument as a standalone C++ callback.
+ *  Returns the generated function name for use in rawCpp() templates.
+ *  At runtime (tests, type-checking) this is a no-op. */
+export function callback(_fn) {
+    return "";
+}

package/dist/constants.d.ts

@@ -0,0 +1,21 @@
+export declare const INPUT: number;
+export declare const OUTPUT: number;
+export declare const INPUT_PULLUP: number;
+export declare const INPUT_PULLDOWN: number;
+export declare const OUTPUT_OPEN_DRAIN: number;
+export declare const ANALOG: number;
+export declare const HIGH: number;
+export declare const LOW: number;
+export declare const LED_BUILTIN: number;
+export declare const LSBFIRST: number;
+export declare const MSBFIRST: number;
+export declare const WDTO_15MS: number;
+export declare const WDTO_30MS: number;
+export declare const WDTO_60MS: number;
+export declare const WDTO_120MS: number;
+export declare const WDTO_250MS: number;
+export declare const WDTO_500MS: number;
+export declare const WDTO_1S: number;
+export declare const WDTO_2S: number;
+export declare const WDTO_4S: number;
+export declare const WDTO_8S: number;

package/dist/constants.js

@@ -0,0 +1,23 @@
+// These constants are resolved from the board definition at compile time by the
+// transpiler. At runtime (tests, type-checking) they default to 0.
+export const INPUT = 0;
+export const OUTPUT = 0;
+export const INPUT_PULLUP = 0;
+export const INPUT_PULLDOWN = 0;
+export const OUTPUT_OPEN_DRAIN = 0;
+export const ANALOG = 0;
+export const HIGH = 0;
+export const LOW = 0;
+export const LED_BUILTIN = 0;
+export const LSBFIRST = 0;
+export const MSBFIRST = 0;
+export const WDTO_15MS = 0;
+export const WDTO_30MS = 0;
+export const WDTO_60MS = 0;
+export const WDTO_120MS = 0;
+export const WDTO_250MS = 0;
+export const WDTO_500MS = 0;
+export const WDTO_1S = 0;
+export const WDTO_2S = 0;
+export const WDTO_4S = 0;
+export const WDTO_8S = 0;

package/dist/dac.d.ts

@@ -0,0 +1,12 @@
+/**
+ * DACClass provides access to true digital-to-analog converters.
+ *
+ * Note: This is for true analog output (DAC), distinct from PWM-based
+ * analog simulation provided by Pin.pwm().
+ */
+export declare class DACClass {
+    static readonly __instance_name = "DAC";
+    write(pin: number, value: number): void;
+    getResolution(): number;
+}
+export declare const DAC: DACClass;

package/dist/dac.js

@@ -0,0 +1,17 @@
+import { dacWrite, boardResolve } from './emit.js';
+/**
+ * DACClass provides access to true digital-to-analog converters.
+ *
+ * Note: This is for true analog output (DAC), distinct from PWM-based
+ * analog simulation provided by Pin.pwm().
+ */
+export class DACClass {
+    write(pin, value) {
+        dacWrite(pin, value);
+    }
+    getResolution() {
+        return boardResolve("peripherals.dac.0.resolution");
+    }
+}
+DACClass.__instance_name = "DAC";
+export const DAC = new DACClass();

package/dist/eeprom.d.ts

@@ -0,0 +1,16 @@
+export declare class EEPROMClass {
+    static readonly __instance_name = "EEPROM";
+    static readonly __includes: string[];
+    static readonly __default_fields: {
+        _name: string;
+    };
+    private _name;
+    constructor(name: string);
+    read(address: number): number;
+    write(address: number, value: number): void;
+    update(address: number, value: number): void;
+    length(): number;
+    get<T>(address: number, ref: T): T;
+    put<T>(address: number, value: T): void;
+}
+export declare const EEPROM: EEPROMClass;

package/dist/eeprom.js

@@ -0,0 +1,21 @@
+import { rawCpp } from './emit.js';
+import { include } from './include.js';
+export class EEPROMClass {
+    constructor(name) {
+        include("<EEPROM.h>");
+        this._name = name;
+    }
+    read(address) { return 0; }
+    write(address, value) { rawCpp(`${this._name}.write(${address}, ${value});`); }
+    update(address, value) { rawCpp(`${this._name}.update(${address}, ${value});`); }
+    length() { return 0; }
+    get(address, ref) {
+        rawCpp(`${this._name}.get(${address}, ${ref});`);
+        return ref;
+    }
+    put(address, value) { rawCpp(`${this._name}.put(${address}, ${value});`); }
+}
+EEPROMClass.__instance_name = "EEPROM";
+EEPROMClass.__includes = ["<EEPROM.h>"];
+EEPROMClass.__default_fields = { _name: "EEPROM" };
+export const EEPROM = new EEPROMClass("EEPROM");

package/dist/emit.d.ts

@@ -0,0 +1,121 @@
+/** Set a digital pin HIGH or LOW. */
+export declare function gpioWrite(pin: number | string, value: number | boolean): void;
+/** Read a digital pin. Returns HIGH (1) or LOW (0). */
+export declare function gpioRead(pin: number | string): number;
+/** Toggle a digital pin. */
+export declare function gpioToggle(pin: number | string): void;
+/** Set pin mode: "output" | "input" | "input_pullup" | "input_pulldown". */
+export declare function gpioSetMode(pin: number | string, mode: string): void;
+/** Write PWM duty cycle to a pin. */
+export declare function pwmWrite(pin: number | string, duty: number): void;
+/** Read analog value from a pin. */
+export declare function adcRead(pin: number | string): number;
+/** Read analog voltage from a pin (ADC value converted to voltage). */
+export declare function adcReadVoltage(pin: number | string): number;
+/** Set the analog reference. */
+export declare function adcSetReference(ref: string | number): void;
+/** Attach an interrupt handler to a pin. */
+export declare function interruptAttach(pin: number | string, handler: string, mode: string): void;
+/** Detach an interrupt from a pin. */
+export declare function interruptDetach(pin: number | string): void;
+/** Play a tone on a pin at the given frequency, optionally for a duration. */
+export declare function tonePlay(pin: number | string, frequency: number, duration?: number): void;
+/** Stop tone playback on a pin. */
+export declare function toneStop(pin: number | string): void;
+/** Delay for the given number of milliseconds. */
+export declare function delayMs(ms: number): void;
+/** Delay for the given number of microseconds. */
+export declare function delayMicro(us: number): void;
+/** Get milliseconds since boot. */
+export declare function getMillis(): number;
+/** Get microseconds since boot. */
+export declare function getMicros(): number;
+/** Get free heap bytes. Architecture-aware: the strategy maps this to the right
+ *  symbol per target (ESP.getFreeHeap() on ESP32, __heap_start trick on AVR). */
+export declare function getFreeHeap(): number;
+/** Initialize I2C bus (master mode if no address, slave mode with address). */
+export declare function i2cBegin(bus: string, address?: number): void;
+/** Disable I2C bus. */
+export declare function i2cEnd(bus: string): void;
+/** Set I2C bus clock speed. */
+export declare function i2cSetClock(bus: string, hz: number): void;
+/** Begin I2C transmission to a slave address. */
+export declare function i2cBeginTx(bus: string, address: number): void;
+/** Write data to I2C bus. */
+export declare function i2cWrite(bus: string, data: string | number | number[] | Uint8Array): void;
+/** Write a byte buffer to I2C bus (expands array literals to per-byte writes). */
+export declare function i2cWriteBuffer(bus: string, data: number[] | Uint8Array): void;
+/** End I2C transmission. Returns status. */
+export declare function i2cEndTx(bus: string, stop: boolean): number;
+/** Request bytes from I2C slave. */
+export declare function i2cRequestFrom(bus: string, address: number, quantity: number, stop?: boolean): number;
+/** Check if bytes are available from I2C. */
+export declare function i2cAvailable(bus: string): number;
+/** Read a byte from I2C. */
+export declare function i2cRead(bus: string): number;
+/** Initialize SPI bus. */
+export declare function spiBegin(bus: string): void;
+/** Disable SPI bus. */
+export declare function spiEnd(bus: string): void;
+/** Transfer data on SPI bus. */
+export declare function spiTransfer(bus: string, data: string | number | Uint8Array): number;
+/** Begin SPI transaction with settings. */
+export declare function spiBeginTx(bus: string, settings: string | any): void;
+/** End SPI transaction. */
+export declare function spiEndTx(bus: string): void;
+/** Set SPI chip-select pin LOW. */
+export declare function spiCsLow(pin: number | string): void;
+/** Set SPI chip-select pin HIGH. */
+export declare function spiCsHigh(pin: number | string): void;
+/** Set SPI data mode. */
+export declare function spiSetMode(bus: string, mode: number): void;
+/** Set SPI bit order. */
+export declare function spiSetBitOrder(bus: string, order: string): void;
+/** Initialize serial port with baud rate. */
+export declare function uartBegin(port: string, baud: number): void;
+/** Disable serial port. */
+export declare function uartEnd(port: string): void;
+/** Print value to serial. */
+export declare function uartPrint(port: string, value: any): void;
+/** Print value with newline to serial. */
+export declare function uartPrintln(port: string, value: any): void;
+/** printf-style formatted print to serial. */
+export declare function uartPrintf(port: string, format: any, args: any[]): void;
+/** Write raw data to serial. */
+export declare function uartWrite(port: string, data: any): void;
+/** Read a byte from serial. */
+export declare function uartRead(port: string): number;
+/** Peek at next byte from serial without consuming. */
+export declare function uartPeek(port: string): number;
+/** Check if bytes are available from serial. */
+export declare function uartAvailable(port: string): number;
+/** Flush serial output. */
+export declare function uartFlush(port: string): void;
+/** Measure pulse duration on a pin. */
+export declare function pulseIn_(pin: number | string, value: number, timeout?: number): number;
+/** Measure long pulse using high-precision timer. */
+export declare function pulseInLong_(pin: number | string, value: number): number;
+/** Shift a byte out to a pin. */
+export declare function shiftOut_(dataPin: number | string, clockPin: number | string, bitOrder: number, value: number): void;
+/** Shift a byte in from a pin. */
+export declare function shiftIn_(dataPin: number | string, clockPin: number | string, bitOrder: number): number;
+/** Write a value to a DAC pin. */
+export declare function dacWrite(pin: number | string, value: number): void;
+/** Enable the watchdog timer with the given timeout (string preset or number). */
+export declare function wdtEnable(timeout: string | number): void;
+/** Reset (kick) the watchdog timer. */
+export declare function wdtReset(): void;
+/** Disable the watchdog timer. */
+export declare function wdtDisable(): void;
+/** Resolve a board definition path to a compile-time constant. */
+export declare function boardResolve(path: string): any;
+/** Enter deep sleep for the given duration (ms). Architecture-aware: the
+ *  strategy emits the right call per target (esp_deep_sleep on ESP32, a
+ *  not-supported comment elsewhere). */
+export declare function powerDeepSleep(ms: number): void;
+/** Enter light sleep. Architecture-aware. */
+export declare function powerLightSleep(): void;
+/** Set the CPU frequency (MHz). */
+export declare function powerSetCpuFrequency(mhz: number): void;
+/** Emit raw C++ code (escape hatch for unsupported operations). */
+export declare function rawCpp(code: string): void;