@typecad/hal 1.0.0-alpha.6 → 1.0.0-alpha.8

package/src/http.ts

@@ -0,0 +1,144 @@
+import {
+  httpBegin,
+  httpReset,
+  httpSetHeader,
+  httpSetTimeout,
+  httpSetMaxBody,
+  httpSetBody,
+  httpSetInsecure,
+  httpSetCaCert,
+  httpSend,
+  httpStatus,
+  httpOk,
+  httpBody,
+  httpContentLength,
+  httpResponseHeader,
+} from './emit.js';
+
+export enum HttpMethod {
+  GET = 0,
+  POST = 1,
+  PUT = 2,
+  DELETE = 3,
+  HEAD = 4,
+  PATCH = 5,
+}
+
+/**
+ * Fluent HTTP/S request builder, lowered to native ESP-IDF
+ * `esp_http_client` by framework-esp32 (TLS via esp-tls / mbedTLS bundle).
+ * Response fields are read from this object after send() — mirrors
+ * `await WiFi.connect(); WiFi.localIP()`.
+ *
+ * No `include()` calls here — ESP-IDF headers are framework-owned and added
+ * via forcedIncludes when the program uses http.* ops.
+ */
+export class HttpRequest {
+  private _method: string;
+  private _url: string;
+
+  constructor(method: string, url: string) {
+    this._method = method;
+    this._url = url;
+  }
+
+  header(name: string, value: string): this {
+    httpSetHeader(name, value);
+    return this;
+  }
+
+  timeout(ms: number): this {
+    httpSetTimeout(ms);
+    return this;
+  }
+
+  maxBody(bytes: number): this {
+    httpSetMaxBody(bytes);
+    return this;
+  }
+
+  body(data: string): this {
+    httpSetBody(data, false);
+    return this;
+  }
+
+  jsonBody(json: string): this {
+    httpSetBody(json, true);
+    return this;
+  }
+
+  /** Skip TLS certificate verification (development only). */
+  insecure(): this {
+    httpSetInsecure();
+    return this;
+  }
+
+  caCert(pem: string): this {
+    httpSetCaCert(pem);
+    return this;
+  }
+
+  /** Blocking at top level; cooperatively awaitable inside async functions. */
+  send(): Promise<boolean> {
+    httpBegin(this._method, this._url);
+    httpSend();
+    return Promise.resolve(false);
+  }
+
+  status(): number {
+    return httpStatus();
+  }
+
+  ok(): boolean {
+    return httpOk();
+  }
+
+  /** Response body as a C string (valid until the next request). */
+  text(): string {
+    return httpBody();
+  }
+
+  contentLength(): number {
+    return httpContentLength();
+  }
+
+  responseHeader(name: string): string {
+    return httpResponseHeader(name);
+  }
+}
+
+export class HttpClass {
+  static readonly __instance_name = "Http";
+
+  get(url: string): HttpRequest {
+    httpReset();
+    return new HttpRequest("GET", url);
+  }
+
+  post(url: string): HttpRequest {
+    httpReset();
+    return new HttpRequest("POST", url);
+  }
+
+  put(url: string): HttpRequest {
+    httpReset();
+    return new HttpRequest("PUT", url);
+  }
+
+  del(url: string): HttpRequest {
+    httpReset();
+    return new HttpRequest("DELETE", url);
+  }
+
+  head(url: string): HttpRequest {
+    httpReset();
+    return new HttpRequest("HEAD", url);
+  }
+
+  patch(url: string): HttpRequest {
+    httpReset();
+    return new HttpRequest("PATCH", url);
+  }
+}
+
+export const Http = new HttpClass();

package/src/index.ts

@@ -19,7 +19,7 @@ export type { SPIBitOrder, SPIMode, SPISettings } from './types.js';
 export { include } from './include.js';
 export { board } from './board.js';
 export { callback } from './callback.js';
-export { rawCpp, boardResolve } from './emit.js';
+export { rawCpp, rawCppExpr, boardResolve } from './emit.js';
 export { HIGH, LOW, OUTPUT, INPUT, INPUT_PULLUP, INPUT_PULLDOWN, OUTPUT_OPEN_DRAIN, ANALOG, LED_BUILTIN, LSBFIRST, MSBFIRST, WDTO_15MS, WDTO_30MS, WDTO_60MS, WDTO_120MS, WDTO_250MS, WDTO_500MS, WDTO_1S, WDTO_2S, WDTO_4S, WDTO_8S } from './constants.js';
 export { delay, millis, micros, delayMicroseconds, map, constrain, TimingClass, Timing } from './timing.js';
 export { freeHeap, setInterval, setTimeout, clearInterval, clearTimeout } from './timing.js';
@@ -44,5 +44,25 @@ export { DACClass, DAC } from './dac.js';
 export { PreferencesClass, Preferences } from './preferences.js';
 export { HardwareTimer, Timer0, Timer1, Timer2 } from './timer.js';
 export { FSClass, FS } from './fs.js';
+export { fsBegin, fsReadText, fsWriteText, fsExists, fsRemove } from './fs.js';
+export { MdnsClass, MDNS } from './mdns.js';
+export { mdnsStart, mdnsSetHostname, mdnsAddService, mdnsAnnounce, mdnsStop } from './mdns.js';
+export { MqttClass, MQTT } from './mqtt.js';
+export { mqttConnect, mqttOnMessage, mqttSubscribe, mqttPublish, mqttConnected, mqttDisconnect } from './mqtt.js';
+export { OtaClass, OTA } from './ota.js';
+export { otaFromUrl, otaBegin, otaWrite, otaApply } from './ota.js';
+export { TemperatureClass, Temperature } from './temperature.js';
+export { tempRead } from './temperature.js';
+export { hwtimerSetFrequency, hwtimerOnOverflow, hwtimerStart, hwtimerStop } from './timer.js';
+export { CapacitiveClass, Capacitive } from './capacitive.js';
+export { capacitiveRead } from './capacitive.js';
 export { PowerClass, Power } from './power.js';
 export { AsyncClass, Async } from './async.js';
+export { WiFiClass, WiFi, WiFiStatus, WiFiEncryption } from './wifi.js';
+export { HttpClass, Http, HttpRequest, HttpMethod } from './http.js';
+export {
+  BleClass, Ble, BleServer,
+  BleValueType, BlePerm, BleStatus, BleAdvertisingMode, GATT,
+} from './ble.js';
+export type { GattCharacteristicDef, CharValue } from './ble.js';
+export { RmtChannel } from './rmt.js';

package/src/mdns.ts

@@ -0,0 +1,50 @@
+/**
+ * MdnsClass — mDNS service discovery (ESP-IDF esp_mdns).
+ *
+ * Lowered to native mDNS HAL ops (mdns.*): ESP-IDF's esp_mdns component
+ * advertises the device on the local network as `<hostname>.local` and
+ * publishes services (e.g. `_http._tcp`) for discovery by Bonjour/Avahi.
+ *
+ * The semantic primitives (mdnsStart / mdnsAddService / ...) are resolved to
+ * mdns.* HAL ops by the transpiler; this class is the ergonomic surface.
+ *
+ * Requires WiFi to be connected (mDNS rides on the station interface).
+ */
+export class MdnsClass {
+  static readonly __instance_name = "MDNS";
+
+  /** Initialize mDNS and set the host name (advertised as <name>.local). */
+  start(hostname: string): boolean {
+    mdnsStart(hostname);
+    return true;
+  }
+
+  /** Set/override the host name after start(). */
+  setHostname(name: string): void {
+    mdnsSetHostname(name);
+  }
+
+  /** Publish a service instance. proto is "_tcp" or "_udp". */
+  addService(instance: string, proto: string, port: number): void {
+    mdnsAddService(instance, proto, port);
+  }
+
+  /** Advertise that the device is reachable (sends a probe/announce). */
+  announce(): void {
+    mdnsAnnounce();
+  }
+
+  /** Tear down the mDNS responder. */
+  stop(): void {
+    mdnsStop();
+  }
+}
+
+export const MDNS = new MdnsClass();
+
+// ── Semantic primitives (resolved to mdns.* HAL ops by the transpiler) ──
+export function mdnsStart(hostname: string): void {}
+export function mdnsSetHostname(name: string): void {}
+export function mdnsAddService(instance: string, proto: string, port: number): void {}
+export function mdnsAnnounce(): void {}
+export function mdnsStop(): void {}

package/src/mqtt.ts

@@ -0,0 +1,57 @@
+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 {
+  static readonly __instance_name = "MQTT";
+
+  /** Connect to a broker URI (e.g. "mqtt://broker.local" or "mqtts://..."). */
+  connect(brokerUri: string, clientId: string): boolean {
+    mqttConnect(brokerUri, clientId);
+    return true;
+  }
+
+  /** Set a handler invoked for every received PUBLISH on a subscribed topic.
+   *  The handler receives (topic, payload). */
+  onMessage(handler: (topic: string, payload: string) => void): void {
+    mqttOnMessage(callback(handler));
+  }
+
+  /** Subscribe to a topic filter (e.g. "sensors/#"). */
+  subscribe(topic: string): void {
+    mqttSubscribe(topic);
+  }
+
+  /** Publish a message to a topic. */
+  publish(topic: string, data: string): void {
+    mqttPublish(topic, data);
+  }
+
+  /** True if the client is currently connected to the broker. */
+  connected(): boolean {
+    return mqttConnected();
+  }
+
+  /** Disconnect from the broker and free the client. */
+  disconnect(): void {
+    mqttDisconnect();
+  }
+}
+
+export const MQTT = new MqttClass();
+
+// ── Semantic primitives (resolved to mqtt.* HAL ops by the transpiler) ──
+export function mqttConnect(brokerUri: string, clientId: string): void {}
+export function mqttOnMessage(handler: string): void {}
+export function mqttSubscribe(topic: string): void {}
+export function mqttPublish(topic: string, data: string): void {}
+export function mqttConnected(): boolean { return false; }
+export function mqttDisconnect(): void {}

package/src/ota.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 {
+  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 {
+    return otaFromUrl(url);
+  }
+
+  /** Begin a manual update session (caller writes chunks via write()). */
+  begin(): boolean {
+    return otaBegin();
+  }
+
+  /** Write a chunk of firmware data to the OTA partition. */
+  write(chunk: string): void {
+    otaWrite(chunk);
+  }
+
+  /** Finalize the update: verify, set the boot partition, and reboot. */
+  apply(): void {
+    otaApply();
+  }
+}
+
+export const OTA = new OtaClass();
+
+// ── Semantic primitives (resolved to ota.* HAL ops by the transpiler) ──
+export function otaFromUrl(url: string): boolean { return false; }
+export function otaBegin(): boolean { return false; }
+export function otaWrite(chunk: string): void {}
+export function otaApply(): void {}

package/src/power.ts

@@ -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.
@@ -14,6 +14,16 @@ export class PowerClass {
     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: number, level: 0 | 1): void {
+    powerDeepSleepPin(pin, level);
+  }
+
   lightSleep(): void {
     powerLightSleep();
   }

package/src/preferences.ts

@@ -1,57 +1,86 @@
-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 {
   static readonly __instance_name = "Preferences";
-  // 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: string, readOnly: boolean = false): void {
-    rawCpp(`Preferences.begin(${name}.c_str(), ${readOnly});`);
+    preferencesBegin(name, readOnly);
   }
+
   end(): void {
-    rawCpp(`Preferences.end();`);
+    preferencesEnd();
   }
+
   clear(): void {
-    rawCpp(`Preferences.clear();`);
+    preferencesClear();
   }
+
   remove(key: string): void {
-    rawCpp(`Preferences.remove(${key}.c_str());`);
+    preferencesRemove(key);
   }
+
   putInt(key: string, value: number): void {
-    rawCpp(`Preferences.putInt(${key}.c_str(), ${value});`);
+    preferencesPutInt(key, value);
   }
+
   getInt(key: string, defaultValue: number = 0): number {
-    rawCpp(`return Preferences.getInt(${key}.c_str(), ${defaultValue});`);
-    return 0;
+    return preferencesGetInt(key, defaultValue);
   }
+
   putUInt(key: string, value: number): void {
-    rawCpp(`Preferences.putUInt(${key}.c_str(), ${value});`);
+    preferencesPutUInt(key, value);
   }
+
   getUInt(key: string, defaultValue: number = 0): number {
-    rawCpp(`return Preferences.getUInt(${key}.c_str(), ${defaultValue});`);
-    return 0;
-  }
-  putFloat(key: string, value: number): void {
-    rawCpp(`Preferences.putFloat(${key}.c_str(), ${value});`);
-  }
-  getFloat(key: string, defaultValue: number = 0): number {
-    rawCpp(`return Preferences.getFloat(${key}.c_str(), ${defaultValue});`);
-    return 0;
+    return preferencesGetUInt(key, defaultValue);
   }
+
   putBool(key: string, value: boolean): void {
-    rawCpp(`Preferences.putBool(${key}.c_str(), ${value});`);
+    preferencesPutBool(key, value);
   }
+
   getBool(key: string, defaultValue: boolean = false): boolean {
-    rawCpp(`return Preferences.getBool(${key}.c_str(), ${defaultValue});`);
-    return false;
+    return preferencesGetBool(key, defaultValue);
+  }
+
+  putFloat(key: string, value: number): void {
+    preferencesPutFloat(key, value);
   }
+
+  getFloat(key: string, defaultValue: number = 0): number {
+    return preferencesGetFloat(key, defaultValue);
+  }
+
   putString(key: string, value: string): void {
-    rawCpp(`Preferences.putString(${key}.c_str(), ${value}.c_str());`);
+    preferencesPutString(key, value);
   }
+
   getString(key: string, defaultValue: string = ""): string {
-    rawCpp(`return Preferences.getString(${key}.c_str(), ${defaultValue}.c_str());`);
-    return "";
+    return preferencesGetString(key, defaultValue);
   }
 }
 

package/src/rmt.ts

@@ -0,0 +1,125 @@
+// ---------------------------------------------------------------------------
+// @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 type { Pin } from './gpio.js';
+import {
+  rmtTxInit,
+  rmtRxInit,
+  rmtTxWriteBytes,
+  rmtTxWriteSymbols,
+  rmtTxWaitDone,
+  rmtTxDeinit,
+  rmtRxOnReceived,
+  rmtRxStart,
+  rmtRxStop,
+  rmtRxRead,
+  rmtRxDeinit,
+} from './emit.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 class RmtChannel {
+  private _pin: RmtPin;
+
+  constructor(pin: RmtPin) {
+    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: number,
+    bit0Hi: number, bit0Lo: number,
+    bit1Hi: number, bit1Lo: number,
+    msbFirst: boolean = false,
+    queueDepth: number = 4,
+  ): void {
+    rmtTxInit(
+      this._pin,
+      resolutionHz,
+      bit0Hi, bit0Lo,
+      bit1Hi, bit1Lo,
+      msbFirst,
+      queueDepth,
+    );
+  }
+
+  /** Write bytes via the channel's bytes-encoder (timings fixed at txInit). */
+  txWriteBytes(bytes: number[] | Uint8Array): void {
+    rmtTxWriteBytes(this._pin, bytes);
+  }
+
+  /** Write raw RMT symbols — arbitrary [hiTicks, loTicks] pairs. */
+  txWriteSymbols(symbols: [number, number][]): void {
+    rmtTxWriteSymbols(this._pin, symbols);
+  }
+
+  /** Block until the queued TX completes. */
+  txWaitDone(timeoutMs?: number): void {
+    rmtTxWaitDone(this._pin, timeoutMs);
+  }
+
+  /** Tear down the TX channel and release its slot. */
+  txDeinit(): void {
+    rmtTxDeinit(this._pin);
+  }
+
+  // ── RX ─────────────────────────────────────────────────────────────────────
+  /** Initialize the channel for RX. Idempotent per pin. */
+  rxInit(resolutionHz: number): void {
+    rmtRxInit(this._pin, resolutionHz);
+  }
+
+  /** Register a callback-by-name invoked when an RX burst completes. */
+  rxOnReceived(handler: string): void {
+    rmtRxOnReceived(this._pin, handler);
+  }
+
+  /** Start receiving. */
+  rxStart(): void {
+    rmtRxStart(this._pin);
+  }
+
+  /** Stop receiving. */
+  rxStop(): void {
+    rmtRxStop(this._pin);
+  }
+
+  /** Blocking read — returns flattened symbols [d0,l0,d1,l1,…] in ticks. */
+  rxRead(maxCount: number): number[] {
+    return rmtRxRead(this._pin, maxCount);
+  }
+
+  /** Tear down the RX channel and release its slot. */
+  rxDeinit(): void {
+    rmtRxDeinit(this._pin);
+  }
+}

package/src/temperature.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 {
+  static readonly __instance_name = "Temperature";
+
+  /** Read the on-chip die temperature in degrees Celsius. */
+  read(): number {
+    return tempRead();
+  }
+}
+
+export const Temperature = new TemperatureClass();
+
+// ── Semantic primitive (resolved to temp.* HAL op by the transpiler) ──
+export function tempRead(): number { return 0; }

package/src/timer.ts

@@ -1,12 +1,16 @@
-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 {
   private _instance: number;
@@ -15,38 +19,27 @@ export class HardwareTimer {
     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: number): void {
-    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: () => void): void {
-    rawCpp(`Timer${this._instance}.onOverflow(${callback(handler)});`);
+    hwtimerOnOverflow(this._instance, callback(handler));
   }
 
-  /**
-   * Starts the timer.
-   */
+  /** Starts the timer. */
   start(): void {
-    rawCpp(`Timer${this._instance}.start();`);
+    hwtimerStart(this._instance);
   }
 
-  /**
-   * Stops the timer.
-   */
+  /** Stops the timer. */
   stop(): void {
-    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(): number {
     // "peripherals.timer" (singular) matches the board-resolver's array-key
     // derivation (TIMER_INSTANCES → peripherals.timer.<index>.*).
@@ -57,3 +50,9 @@ 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: number, hz: number): void {}
+export function hwtimerOnOverflow(instance: number, handler: string): void {}
+export function hwtimerStart(instance: number): void {}
+export function hwtimerStop(instance: number): void {}