@typecad/hal

Hardware abstraction layer for TypeCAD — 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

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 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

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/ directory contains a hardware test suite that exercises every AVR-compilable HAL subsystem against real Arduino Uno hardware, using @typecad/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:

npm exec --workspace @typecad/hal -- cuttlefish-test

The suite is configured by cuttlefish.config.ts. Like the @typecad/framework-arduino 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 — the transpiler that resolves HAL calls to C++.
• @typecad/ui — HTML/CSS-driven display graphics.
• @typecad/mcu-* — silicon pin/port/peripheral definitions.
• @typecad/board-* — board-level pin mappings and bus aliases.

License

MIT