@typecad/hal 0.1.0-alpha.1 → 1.0.0-alpha.10

package/dist/mqtt.js

@@ -0,0 +1,48 @@
+import { callback } from './callback.js';
+/**
+ * MqttClass — MQTT 3.1.1 pub/sub client (ESP-IDF esp_mqtt).
+ *
+ * Lowered to native MQTT HAL ops (mqtt.*): ESP-IDF's esp_mqtt_client_* API.
+ * Covers the common IoT pub/sub path: connect to a broker, publish, subscribe
+ * with an onMessage callback, and disconnect. The runtime shim owns the event
+ * loop translation (ESP-IDF's MQTT event handler → the user's TS callback).
+ *
+ * Requires a network connection (WiFi) before connect().
+ */
+export class MqttClass {
+    /** Connect to a broker URI (e.g. "mqtt://broker.local" or "mqtts://..."). */
+    connect(brokerUri, clientId) {
+        mqttConnect(brokerUri, clientId);
+        return true;
+    }
+    /** Set a handler invoked for every received PUBLISH on a subscribed topic.
+     *  The handler receives (topic, payload). */
+    onMessage(handler) {
+        mqttOnMessage(callback(handler));
+    }
+    /** Subscribe to a topic filter (e.g. "sensors/#"). */
+    subscribe(topic) {
+        mqttSubscribe(topic);
+    }
+    /** Publish a message to a topic. */
+    publish(topic, data) {
+        mqttPublish(topic, data);
+    }
+    /** True if the client is currently connected to the broker. */
+    connected() {
+        return mqttConnected();
+    }
+    /** Disconnect from the broker and free the client. */
+    disconnect() {
+        mqttDisconnect();
+    }
+}
+MqttClass.__instance_name = "MQTT";
+export const MQTT = new MqttClass();
+// ── Semantic primitives (resolved to mqtt.* HAL ops by the transpiler) ──
+export function mqttConnect(brokerUri, clientId) { }
+export function mqttOnMessage(handler) { }
+export function mqttSubscribe(topic) { }
+export function mqttPublish(topic, data) { }
+export function mqttConnected() { return false; }
+export function mqttDisconnect() { }

package/dist/ota.d.ts

@@ -0,0 +1,29 @@
+/**
+ * OtaClass — over-the-air firmware update (ESP-IDF esp_https_ota / esp_app_format).
+ *
+ * Lowered to native OTA HAL ops (ota.*): ESP-IDF's esp_https_ota downloads a
+ * firmware image over HTTPS and writes it to the OTA partition, then reboots
+ * into it. The runtime shim owns the session/progress/verification dance.
+ *
+ * Requires a network connection (WiFi) and that the partition table defines
+ * at least two OTA app slots (the framework's default partitions.csv does).
+ */
+export declare class OtaClass {
+    static readonly __instance_name = "OTA";
+    /** Download and apply a firmware image from an HTTPS URL, then reboot.
+     *  Blocks until the update is written and verified. Returns true on success
+     *  (the reboot happens inside the shim on success, so a true return means
+     *  the new firmware is about to boot). */
+    fromUrl(url: string): boolean;
+    /** Begin a manual update session (caller writes chunks via write()). */
+    begin(): boolean;
+    /** Write a chunk of firmware data to the OTA partition. */
+    write(chunk: string): void;
+    /** Finalize the update: verify, set the boot partition, and reboot. */
+    apply(): void;
+}
+export declare const OTA: OtaClass;
+export declare function otaFromUrl(url: string): boolean;
+export declare function otaBegin(): boolean;
+export declare function otaWrite(chunk: string): void;
+export declare function otaApply(): void;

package/dist/ota.js

@@ -0,0 +1,38 @@
+/**
+ * OtaClass — over-the-air firmware update (ESP-IDF esp_https_ota / esp_app_format).
+ *
+ * Lowered to native OTA HAL ops (ota.*): ESP-IDF's esp_https_ota downloads a
+ * firmware image over HTTPS and writes it to the OTA partition, then reboots
+ * into it. The runtime shim owns the session/progress/verification dance.
+ *
+ * Requires a network connection (WiFi) and that the partition table defines
+ * at least two OTA app slots (the framework's default partitions.csv does).
+ */
+export class OtaClass {
+    /** Download and apply a firmware image from an HTTPS URL, then reboot.
+     *  Blocks until the update is written and verified. Returns true on success
+     *  (the reboot happens inside the shim on success, so a true return means
+     *  the new firmware is about to boot). */
+    fromUrl(url) {
+        return otaFromUrl(url);
+    }
+    /** Begin a manual update session (caller writes chunks via write()). */
+    begin() {
+        return otaBegin();
+    }
+    /** Write a chunk of firmware data to the OTA partition. */
+    write(chunk) {
+        otaWrite(chunk);
+    }
+    /** Finalize the update: verify, set the boot partition, and reboot. */
+    apply() {
+        otaApply();
+    }
+}
+OtaClass.__instance_name = "OTA";
+export const OTA = new OtaClass();
+// ── Semantic primitives (resolved to ota.* HAL ops by the transpiler) ──
+export function otaFromUrl(url) { return false; }
+export function otaBegin() { return false; }
+export function otaWrite(chunk) { }
+export function otaApply() { }

package/dist/power.d.ts

@@ -8,6 +8,13 @@
 export declare class PowerClass {
     static readonly __instance_name = "Power";
     deepSleep(ms: number): void;
+    /** Enter deep sleep until `pin` reaches `level` (0 = low, 1 = high).
+     *
+     *  Lowers to ext0 wakeup (Xtensa ESP32/S3, RTC pins only) or the gpio-wakeup
+     *  variant (RISC-V C3/C6) depending on the target. `pin` must be RTC-capable;
+     *  the framework flags non-RTC pins at compile time. Wakeup resets the chip,
+     *  so this call never returns. */
+    deepSleepPin(pin: number, level: 0 | 1): void;
     lightSleep(): void;
     setCpuFrequency(mhz: number): void;
 }

package/dist/power.js

@@ -1,4 +1,4 @@
-import { powerDeepSleep, powerLightSleep, powerSetCpuFrequency } from './emit.js';
+import { powerDeepSleep, powerLightSleep, powerSetCpuFrequency, powerDeepSleepPin } from './emit.js';
 /**
  * PowerClass provides control over MCU power states and clock frequencies.
  *
@@ -10,6 +10,15 @@ export class PowerClass {
     deepSleep(ms) {
         powerDeepSleep(ms);
     }
+    /** Enter deep sleep until `pin` reaches `level` (0 = low, 1 = high).
+     *
+     *  Lowers to ext0 wakeup (Xtensa ESP32/S3, RTC pins only) or the gpio-wakeup
+     *  variant (RISC-V C3/C6) depending on the target. `pin` must be RTC-capable;
+     *  the framework flags non-RTC pins at compile time. Wakeup resets the chip,
+     *  so this call never returns. */
+    deepSleepPin(pin, level) {
+        powerDeepSleepPin(pin, level);
+    }
     lightSleep() {
         powerLightSleep();
     }

package/dist/preferences.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Preferences — a persistent key/value store, lowered to native NVS
+ * (nvs_flash / nvs_open / nvs_set_* / nvs_get_*) by framework-esp32.
+ *
+ * No include() calls here — NVS headers are framework-owned and added via
+ * forcedIncludes when the program uses preferences.* ops. Method bodies pass
+ * parameters directly into semantic calls so the resolver can statically track
+ * every argument (matching the WiFi/HTTP HAL pattern).
+ */
 export declare class PreferencesClass {
     static readonly __instance_name = "Preferences";
     begin(name: string, readOnly?: boolean): void;
@@ -8,10 +17,10 @@ export declare class PreferencesClass {
     getInt(key: string, defaultValue?: number): number;
     putUInt(key: string, value: number): void;
     getUInt(key: string, defaultValue?: number): number;
-    putFloat(key: string, value: number): void;
-    getFloat(key: string, defaultValue?: number): number;
     putBool(key: string, value: boolean): void;
     getBool(key: string, defaultValue?: boolean): boolean;
+    putFloat(key: string, value: number): void;
+    getFloat(key: string, defaultValue?: number): number;
     putString(key: string, value: string): void;
     getString(key: string, defaultValue?: string): string;
 }

package/dist/preferences.js

@@ -1,54 +1,55 @@
-import { rawCpp } from './emit.js';
+import { preferencesBegin, preferencesEnd, preferencesClear, preferencesRemove, preferencesPutInt, preferencesGetInt, preferencesPutUInt, preferencesGetUInt, preferencesPutBool, preferencesGetBool, preferencesPutFloat, preferencesGetFloat, preferencesPutString, preferencesGetString, } from './emit.js';
+/**
+ * Preferences — a persistent key/value store, lowered to native NVS
+ * (nvs_flash / nvs_open / nvs_set_* / nvs_get_*) by framework-esp32.
+ *
+ * No include() calls here — NVS headers are framework-owned and added via
+ * forcedIncludes when the program uses preferences.* ops. Method bodies pass
+ * parameters directly into semantic calls so the resolver can statically track
+ * every argument (matching the WiFi/HTTP HAL pattern).
+ */
 export class PreferencesClass {
-    // NOTE: no __includes here. The transpiler emits singleton __includes on
-    // every architecture with no filtering, and <Preferences.h> is ESP32-only —
-    // adding it would break AVR builds. The class is ESP32-only by convention.
     begin(name, readOnly = false) {
-        rawCpp(`Preferences.begin(${name}.c_str(), ${readOnly});`);
+        preferencesBegin(name, readOnly);
     }
     end() {
-        rawCpp(`Preferences.end();`);
+        preferencesEnd();
     }
     clear() {
-        rawCpp(`Preferences.clear();`);
+        preferencesClear();
     }
     remove(key) {
-        rawCpp(`Preferences.remove(${key}.c_str());`);
+        preferencesRemove(key);
     }
     putInt(key, value) {
-        rawCpp(`Preferences.putInt(${key}.c_str(), ${value});`);
+        preferencesPutInt(key, value);
     }
     getInt(key, defaultValue = 0) {
-        rawCpp(`return Preferences.getInt(${key}.c_str(), ${defaultValue});`);
-        return 0;
+        return preferencesGetInt(key, defaultValue);
     }
     putUInt(key, value) {
-        rawCpp(`Preferences.putUInt(${key}.c_str(), ${value});`);
+        preferencesPutUInt(key, value);
     }
     getUInt(key, defaultValue = 0) {
-        rawCpp(`return Preferences.getUInt(${key}.c_str(), ${defaultValue});`);
-        return 0;
-    }
-    putFloat(key, value) {
-        rawCpp(`Preferences.putFloat(${key}.c_str(), ${value});`);
-    }
-    getFloat(key, defaultValue = 0) {
-        rawCpp(`return Preferences.getFloat(${key}.c_str(), ${defaultValue});`);
-        return 0;
+        return preferencesGetUInt(key, defaultValue);
     }
     putBool(key, value) {
-        rawCpp(`Preferences.putBool(${key}.c_str(), ${value});`);
+        preferencesPutBool(key, value);
     }
     getBool(key, defaultValue = false) {
-        rawCpp(`return Preferences.getBool(${key}.c_str(), ${defaultValue});`);
-        return false;
+        return preferencesGetBool(key, defaultValue);
+    }
+    putFloat(key, value) {
+        preferencesPutFloat(key, value);
+    }
+    getFloat(key, defaultValue = 0) {
+        return preferencesGetFloat(key, defaultValue);
     }
     putString(key, value) {
-        rawCpp(`Preferences.putString(${key}.c_str(), ${value}.c_str());`);
+        preferencesPutString(key, value);
     }
     getString(key, defaultValue = "") {
-        rawCpp(`return Preferences.getString(${key}.c_str(), ${defaultValue}.c_str());`);
-        return "";
+        return preferencesGetString(key, defaultValue);
     }
 }
 PreferencesClass.__instance_name = "Preferences";

package/dist/register.d.ts

@@ -4,8 +4,16 @@ export type Bit = 0 | 1;
  *  the bit width for documentation only; the value is the raw field contents. */
 export type Bits<N extends number = number> = number;
 /** Class decorator marking a struct as a memory-mapped register at `address`.
- *  Erased at transpile time — the class becomes a `volatile uint32_t*`. */
-export declare function register(address: number): ClassDecorator;
+ *  Erased at transpile time — the class becomes a `volatile uint32_t*`.
+ *
+ *  These carry real (inert) runtime bodies rather than `declare`, so the
+ *  `export { register, bits }` re-export in index.ts resolves under Node's ESM
+ *  loader, which validates that re-exported bindings exist at runtime. They are
+ *  never invoked: the cuttlefish transpiler detects them by name and lowers the
+ *  decorated struct away, so these stubs are only reached when the decorator
+ *  source is imported without transpilation (e.g. host-side tests). */
+export declare function register(_address: number): ClassDecorator;
 /** Property decorator carrying the bit range [lo, hi] (inclusive) of a field
- *  within its register. Erased at transpile time. */
-export declare function bits(hi: number, lo: number): PropertyDecorator;
+ *  within its register. Erased at transpile time. See `register` for why these
+ *  have runtime bodies. */
+export declare function bits(_hi: number, _lo: number): PropertyDecorator;

package/dist/register.js

@@ -18,4 +18,21 @@
 //   USART1.UE = 1;              // (*USART1 & ~1UL) | ((1 & 1UL) << 0)
 //   const parity = USART1.PS;   // ((*USART1 >> 8) & ((1UL << 2) - 1))
 // ---------------------------------------------------------------------------
-export {};
+/** Class decorator marking a struct as a memory-mapped register at `address`.
+ *  Erased at transpile time — the class becomes a `volatile uint32_t*`.
+ *
+ *  These carry real (inert) runtime bodies rather than `declare`, so the
+ *  `export { register, bits }` re-export in index.ts resolves under Node's ESM
+ *  loader, which validates that re-exported bindings exist at runtime. They are
+ *  never invoked: the cuttlefish transpiler detects them by name and lowers the
+ *  decorated struct away, so these stubs are only reached when the decorator
+ *  source is imported without transpilation (e.g. host-side tests). */
+export function register(_address) {
+    return () => { };
+}
+/** Property decorator carrying the bit range [lo, hi] (inclusive) of a field
+ *  within its register. Erased at transpile time. See `register` for why these
+ *  have runtime bodies. */
+export function bits(_hi, _lo) {
+    return () => { };
+}

package/dist/rmt.d.ts

@@ -0,0 +1,48 @@
+import type { Pin } from './gpio.js';
+/** Pin identifier accepted by RmtChannel: a Pin object, raw GPIO number, or port name. */
+type RmtPin = Pin | number | string;
+/**
+ * RMT transceiver channel bound to a GPIO pin. One channel per pin; TX and RX
+ * are independent roles on the same channel object.
+ *
+ * ```ts
+ * const led = new RmtChannel(LED);
+ * led.txInit({ resolutionHz: 10_000_000, bit0: [4, 9], bit1: [9, 4] });
+ * led.txWriteBytes([0, 16, 0]);
+ * led.txWaitDone();
+ * ```
+ */
+export declare class RmtChannel {
+    private _pin;
+    constructor(pin: RmtPin);
+    /** Initialize the channel for TX. Idempotent per pin. Bit timings are fixed
+     *  at init — ESP-IDF bakes them into the bytes-encoder and exposes no public
+     *  mutation API. Tick units are 1/resolutionHz seconds.
+     *
+     *  Args are positional scalars (not an opts object) because the transpiler's
+     *  method-body renderer folds scalar params but not property accesses on an
+     *  object param (opts.resolutionHz would render as a collapsed object + dead
+     *  property access). Mirrors how I2CBus.begin(address) takes a scalar. */
+    txInit(resolutionHz: number, bit0Hi: number, bit0Lo: number, bit1Hi: number, bit1Lo: number, msbFirst?: boolean, queueDepth?: number): void;
+    /** Write bytes via the channel's bytes-encoder (timings fixed at txInit). */
+    txWriteBytes(bytes: number[] | Uint8Array): void;
+    /** Write raw RMT symbols — arbitrary [hiTicks, loTicks] pairs. */
+    txWriteSymbols(symbols: [number, number][]): void;
+    /** Block until the queued TX completes. */
+    txWaitDone(timeoutMs?: number): void;
+    /** Tear down the TX channel and release its slot. */
+    txDeinit(): void;
+    /** Initialize the channel for RX. Idempotent per pin. */
+    rxInit(resolutionHz: number): void;
+    /** Register a callback-by-name invoked when an RX burst completes. */
+    rxOnReceived(handler: string): void;
+    /** Start receiving. */
+    rxStart(): void;
+    /** Stop receiving. */
+    rxStop(): void;
+    /** Blocking read — returns flattened symbols [d0,l0,d1,l1,…] in ticks. */
+    rxRead(maxCount: number): number[];
+    /** Tear down the RX channel and release its slot. */
+    rxDeinit(): void;
+}
+export {};

package/dist/rmt.js

@@ -0,0 +1,81 @@
+// ---------------------------------------------------------------------------
+// @typecad/hal — RMT (Remote Control Transceiver) ergonomic API
+// ---------------------------------------------------------------------------
+// Exposes RMT via a RmtChannel class, mirroring the I2CBus/I2CDevice pattern.
+// The transpiler only resolves semantic calls made inside class-method bodies
+// (free top-level calls emit verbatim), so every peripheral exposes its API
+// through a class whose methods call the positional semantic primitives in
+// emit.ts. The resolver collapses object literals, so HALOpIR fields must be
+// scalars; these methods destructure `opts` at the call site before forwarding.
+//
+// Channel identity is the GPIO pin (like pwm.ts's LEDC channel-per-pin model).
+import { rmtTxInit, rmtRxInit, rmtTxWriteBytes, rmtTxWriteSymbols, rmtTxWaitDone, rmtTxDeinit, rmtRxOnReceived, rmtRxStart, rmtRxStop, rmtRxRead, rmtRxDeinit, } from './emit.js';
+/**
+ * RMT transceiver channel bound to a GPIO pin. One channel per pin; TX and RX
+ * are independent roles on the same channel object.
+ *
+ * ```ts
+ * const led = new RmtChannel(LED);
+ * led.txInit({ resolutionHz: 10_000_000, bit0: [4, 9], bit1: [9, 4] });
+ * led.txWriteBytes([0, 16, 0]);
+ * led.txWaitDone();
+ * ```
+ */
+export class RmtChannel {
+    constructor(pin) {
+        this._pin = pin;
+    }
+    // ── TX ─────────────────────────────────────────────────────────────────────
+    /** Initialize the channel for TX. Idempotent per pin. Bit timings are fixed
+     *  at init — ESP-IDF bakes them into the bytes-encoder and exposes no public
+     *  mutation API. Tick units are 1/resolutionHz seconds.
+     *
+     *  Args are positional scalars (not an opts object) because the transpiler's
+     *  method-body renderer folds scalar params but not property accesses on an
+     *  object param (opts.resolutionHz would render as a collapsed object + dead
+     *  property access). Mirrors how I2CBus.begin(address) takes a scalar. */
+    txInit(resolutionHz, bit0Hi, bit0Lo, bit1Hi, bit1Lo, msbFirst = false, queueDepth = 4) {
+        rmtTxInit(this._pin, resolutionHz, bit0Hi, bit0Lo, bit1Hi, bit1Lo, msbFirst, queueDepth);
+    }
+    /** Write bytes via the channel's bytes-encoder (timings fixed at txInit). */
+    txWriteBytes(bytes) {
+        rmtTxWriteBytes(this._pin, bytes);
+    }
+    /** Write raw RMT symbols — arbitrary [hiTicks, loTicks] pairs. */
+    txWriteSymbols(symbols) {
+        rmtTxWriteSymbols(this._pin, symbols);
+    }
+    /** Block until the queued TX completes. */
+    txWaitDone(timeoutMs) {
+        rmtTxWaitDone(this._pin, timeoutMs);
+    }
+    /** Tear down the TX channel and release its slot. */
+    txDeinit() {
+        rmtTxDeinit(this._pin);
+    }
+    // ── RX ─────────────────────────────────────────────────────────────────────
+    /** Initialize the channel for RX. Idempotent per pin. */
+    rxInit(resolutionHz) {
+        rmtRxInit(this._pin, resolutionHz);
+    }
+    /** Register a callback-by-name invoked when an RX burst completes. */
+    rxOnReceived(handler) {
+        rmtRxOnReceived(this._pin, handler);
+    }
+    /** Start receiving. */
+    rxStart() {
+        rmtRxStart(this._pin);
+    }
+    /** Stop receiving. */
+    rxStop() {
+        rmtRxStop(this._pin);
+    }
+    /** Blocking read — returns flattened symbols [d0,l0,d1,l1,…] in ticks. */
+    rxRead(maxCount) {
+        return rmtRxRead(this._pin, maxCount);
+    }
+    /** Tear down the RX channel and release its slot. */
+    rxDeinit() {
+        rmtRxDeinit(this._pin);
+    }
+}

package/dist/spi.js

@@ -1,4 +1,4 @@
-import { spiBegin, spiEnd, spiTransfer, spiBeginTx, spiEndTx, spiCsLow, spiCsHigh, spiSetMode, spiSetBitOrder, rawCpp } from './emit.js';
+import { spiBegin, spiEnd, spiTransfer, spiBeginTx, spiEndTx, spiCsLow, spiCsHigh, spiSetMode, spiSetBitOrder, spiReadBuffer, rawCpp } from './emit.js';
 import { include } from './include.js';
 export class SPIDevice {
     constructor(bus, chipSelect) {
@@ -21,12 +21,15 @@ export class SPIDevice {
     }
     readRegister(register, count) {
         include("<SPI.h>");
-        rawCpp(`digitalWrite(${this._cs}, LOW);`);
-        rawCpp(`${this._bus}.transfer(${register});`);
-        rawCpp(`static uint8_t __spi_buf[${count}];`);
-        rawCpp(`for (int i=0; i<${count}; i++) __spi_buf[i] = ${this._bus}.transfer(0x00);`);
-        rawCpp(`digitalWrite(${this._cs}, HIGH);`);
-        rawCpp(`return __spi_buf;`);
+        spiCsLow(this._cs);
+        spiTransfer(this._bus, register);
+        // Clock `count` dummy bytes and drain them into the caller's buffer
+        // (declared by the Uint8Array return marker as `uint8_t data[count]`).
+        // Using the semantic primitive — NOT rawCpp — keeps the buffer in user
+        // scope so it survives the return (no decayed pointer) and `data.length`
+        // / `data[i]` work, mirroring I2CDevice.readBytes.
+        spiReadBuffer(this._bus, count, new Uint8Array(count));
+        spiCsHigh(this._cs);
         return new Uint8Array(count);
     }
     writeRegister(register, value) {

package/dist/temperature.d.ts

@@ -0,0 +1,14 @@
+/**
+ * TemperatureClass — on-chip die temperature sensor.
+ *
+ * Lowered to the temp.* HAL op: ESP-IDF's temperature_sensor driver reads the
+ * internal die temperature in °C. Useful for thermal monitoring and
+ * compensation. No external components required.
+ */
+export declare class TemperatureClass {
+    static readonly __instance_name = "Temperature";
+    /** Read the on-chip die temperature in degrees Celsius. */
+    read(): number;
+}
+export declare const Temperature: TemperatureClass;
+export declare function tempRead(): number;

package/dist/temperature.js

@@ -0,0 +1,17 @@
+/**
+ * TemperatureClass — on-chip die temperature sensor.
+ *
+ * Lowered to the temp.* HAL op: ESP-IDF's temperature_sensor driver reads the
+ * internal die temperature in °C. Useful for thermal monitoring and
+ * compensation. No external components required.
+ */
+export class TemperatureClass {
+    /** Read the on-chip die temperature in degrees Celsius. */
+    read() {
+        return tempRead();
+    }
+}
+TemperatureClass.__instance_name = "Temperature";
+export const Temperature = new TemperatureClass();
+// ── Semantic primitive (resolved to temp.* HAL op by the transpiler) ──
+export function tempRead() { return 0; }

package/dist/timer.d.ts

@@ -3,33 +3,30 @@
  *
  * Hardware timers are distinct from the software-based setInterval/setTimeout
  * and are typically used for high-precision timing, PWM generation, or
- * interrupt-driven tasks.
+ * interrupt-driven tasks. Lowered to hwtimer.* HAL ops: ESP-IDF's GPTimer
+ * driver (driver/gptimer.h); Arduino's HardwareTimer (Timer0/1/2 on STM32).
+ *
+ * The instance index maps to the platform's timer numbering (ESP-IDF GPTimer
+ * unit 0..n, STM32 TIM0..n).
  */
 export declare class HardwareTimer {
     private _instance;
     constructor(instance: number);
-    /**
-     * Sets the timer frequency in Hertz.
-     * Note: The actual frequency may be limited by the hardware's clock dividers.
-     */
+    /** Sets the timer frequency in Hertz. */
     setFrequency(hz: number): void;
-    /**
-     * Attaches an interrupt handler that executes when the timer overflows.
-     */
+    /** Attaches an interrupt handler that executes when the timer overflows. */
     onOverflow(handler: () => void): void;
-    /**
-     * Starts the timer.
-     */
+    /** Starts the timer. */
     start(): void;
-    /**
-     * Stops the timer.
-     */
+    /** Stops the timer. */
     stop(): void;
-    /**
-     * Returns the bit resolution of the timer (e.g., 8, 16, 32).
-     */
+    /** Returns the bit resolution of the timer (e.g., 8, 16, 32). */
     getBits(): number;
 }
 export declare const Timer0: HardwareTimer;
 export declare const Timer1: HardwareTimer;
 export declare const Timer2: HardwareTimer;
+export declare function hwtimerSetFrequency(instance: number, hz: number): void;
+export declare function hwtimerOnOverflow(instance: number, handler: string): void;
+export declare function hwtimerStart(instance: number): void;
+export declare function hwtimerStop(instance: number): void;

package/dist/timer.js

@@ -1,44 +1,37 @@
-import { rawCpp, boardResolve } from './emit.js';
+import { boardResolve } from './emit.js';
 import { callback } from './callback.js';
 /**
  * HardwareTimer provides direct control over the board's hardware timers.
  *
  * Hardware timers are distinct from the software-based setInterval/setTimeout
  * and are typically used for high-precision timing, PWM generation, or
- * interrupt-driven tasks.
+ * interrupt-driven tasks. Lowered to hwtimer.* HAL ops: ESP-IDF's GPTimer
+ * driver (driver/gptimer.h); Arduino's HardwareTimer (Timer0/1/2 on STM32).
+ *
+ * The instance index maps to the platform's timer numbering (ESP-IDF GPTimer
+ * unit 0..n, STM32 TIM0..n).
  */
 export class HardwareTimer {
     constructor(instance) {
         this._instance = instance;
     }
-    /**
-     * Sets the timer frequency in Hertz.
-     * Note: The actual frequency may be limited by the hardware's clock dividers.
-     */
+    /** Sets the timer frequency in Hertz. */
     setFrequency(hz) {
-        rawCpp(`Timer${this._instance}.setFrequency(${hz});`);
+        hwtimerSetFrequency(this._instance, hz);
     }
-    /**
-     * Attaches an interrupt handler that executes when the timer overflows.
-     */
+    /** Attaches an interrupt handler that executes when the timer overflows. */
     onOverflow(handler) {
-        rawCpp(`Timer${this._instance}.onOverflow(${callback(handler)});`);
+        hwtimerOnOverflow(this._instance, callback(handler));
     }
-    /**
-     * Starts the timer.
-     */
+    /** Starts the timer. */
     start() {
-        rawCpp(`Timer${this._instance}.start();`);
+        hwtimerStart(this._instance);
     }
-    /**
-     * Stops the timer.
-     */
+    /** Stops the timer. */
     stop() {
-        rawCpp(`Timer${this._instance}.stop();`);
+        hwtimerStop(this._instance);
     }
-    /**
-     * Returns the bit resolution of the timer (e.g., 8, 16, 32).
-     */
+    /** Returns the bit resolution of the timer (e.g., 8, 16, 32). */
     getBits() {
         // "peripherals.timer" (singular) matches the board-resolver's array-key
         // derivation (TIMER_INSTANCES → peripherals.timer.<index>.*).
@@ -48,3 +41,8 @@ export class HardwareTimer {
 export const Timer0 = new HardwareTimer(0);
 export const Timer1 = new HardwareTimer(1);
 export const Timer2 = new HardwareTimer(2);
+// ── Semantic primitives (resolved to hwtimer.* HAL ops by the transpiler) ──
+export function hwtimerSetFrequency(instance, hz) { }
+export function hwtimerOnOverflow(instance, handler) { }
+export function hwtimerStart(instance) { }
+export function hwtimerStop(instance) { }

package/dist/types.d.ts

@@ -37,7 +37,7 @@ export interface IPinGroup<T extends PinGroupMember = PinGroupMember> {
     fill(value: DigitalValue): void;
 }
 export declare function createPinGroup<T extends PinGroupMember>(pins: T[]): IPinGroup<T>;
-export type ArchitectureIdentifier = 'avr' | 'esp32' | 'esp32s2' | 'esp32s3' | 'esp32c3' | 'esp32c6' | 'rp2040' | 'samd' | 'stm32' | 'nrf52' | (string & {});
+export type ArchitectureIdentifier = 'avr' | 'esp32' | 'esp32s2' | 'esp32s3' | 'esp32c3' | 'esp32c6' | 'rp2040' | 'rp2350' | 'samd' | 'stm32' | 'nrf52' | (string & {});
 export type I2CAddress = number;
 export type SPIBitOrder = 'msb' | 'lsb';
 export type SPIMode = 0 | 1 | 2 | 3;