@typecad/hal 1.0.0-alpha.13 → 1.0.0-alpha.15

package/dist/sensor.d.ts

@@ -0,0 +1,46 @@
+import type { I2CTarget } from './i2c-target.js';
+import type { SPITarget } from './spi-target.js';
+import type { SensorChannelOf, SensorBusOf } from './sensor-catalog.generated.js';
+/** Part ids the catalog knows (the Sensor<P> narrowing keys). */
+type SensorPartId = keyof SensorChannelOf;
+/** The bus-device argument a part accepts, from its generated bus map:
+ *  SPI-only parts take SPITarget, I2C-only take I2CTarget, dual-bus either. */
+type BusDeviceFor<B extends string> = B extends 'spi' ? SPITarget : B extends 'i2c' ? I2CTarget : I2CTarget | SPITarget;
+export type SensorBusDevice<P extends SensorPartId = SensorPartId> = BusDeviceFor<SensorBusOf[P]>;
+/** Construction options. */
+export interface SensorOptions {
+    /** SPI clock in Hz, SPI parts only. Default 1 MHz (safe for every
+     *  catalog part); raise to the breakout's datasheet maximum. */
+    spiHz?: number;
+    /** SPI mode (CPOL/CPHA bits), 0-3. Default 0. */
+    mode?: 0 | 1 | 2 | 3;
+    /** Alert GPIO, for parts whose binding declares alert-gpios. */
+    alert?: number;
+}
+export declare class Sensor<P extends SensorPartId = SensorPartId> {
+    private readonly _part;
+    private readonly _bus;
+    private readonly _port;
+    private readonly _kind;
+    private readonly _spiHz;
+    private readonly _mode;
+    private readonly _alert;
+    /** Construct a sensor handle. `part` is a `SENSOR.<name>` token;
+     *  `dev` is the bus device (e.g. `I2C1.device(0x44)`) carrying the bus
+     *  and address. The transpiler resolves the bus instance and address from
+     *  `dev` — the class fields are the IR carrier, not runtime state.
+     *  The `P` parameter is editor-only: it narrows `get()` to this part's
+     *  channels (from the generated SensorChannelOf map); the transpiler
+     *  re-validates at build time with the driver's full channel list. */
+    constructor(part: P, dev: SensorBusDevice<P>, opts?: SensorOptions);
+    /** Fetch a fresh sample (sensor_sample_fetch). Reads reflect the last
+     *  fetch — Zephyr's own fetch/get split, kept verbatim. */
+    fetch(): void;
+    /** Read one channel from the fetched sample (sensor_channel_get).
+     *  Returns the value as a double (val1 + val2/1e6). The parameter is
+     *  narrowed to this part's channels when constructed from a literal
+     *  SENSOR token — `sht3x.get(` completes AMBIENT_TEMP | HUMIDITY and
+     *  rejects the rest in the editor. */
+    get(chan: SensorChannelOf[P]): number;
+}
+export {};

package/dist/sensor.js

@@ -0,0 +1,52 @@
+// ---------------------------------------------------------------------------
+// Sensor — generic DT-bound sensor part (Zephyr's uniform sensor API)
+//
+// `new Sensor(SENSOR.sensirion_sht3xd, I2C1.device(0x44))` covers every part
+// in the generated catalog: the constructor's facts (part token + bus +
+// address) become a devicetree child node in the generated overlay, and the
+// methods lower to Zephyr's one-shape sensor API (sensor_sample_fetch /
+// sensor_channel_get). No per-part code exists anywhere — the catalog
+// (sensor-catalog.generated.ts) is data, generated from Zephyr's own binding
+// YAMLs and driver channel tables.
+//
+// The channel names are Zephyr verbiage minus the SENSOR_CHAN_ prefix
+// (CHAN.AMBIENT_TEMP ↔ SENSOR_CHAN_AMBIENT_TEMP), so any Zephyr sample or
+// binding doc greps straight into user code.
+// ---------------------------------------------------------------------------
+import { sensorFetch, sensorGet } from './emit.js';
+import { include } from './include.js';
+export class Sensor {
+    /** Construct a sensor handle. `part` is a `SENSOR.<name>` token;
+     *  `dev` is the bus device (e.g. `I2C1.device(0x44)`) carrying the bus
+     *  and address. The transpiler resolves the bus instance and address from
+     *  `dev` — the class fields are the IR carrier, not runtime state.
+     *  The `P` parameter is editor-only: it narrows `get()` to this part's
+     *  channels (from the generated SensorChannelOf map); the transpiler
+     *  re-validates at build time with the driver's full channel list. */
+    constructor(part, dev, opts) {
+        this._bus = '';
+        this._port = 0;
+        this._kind = 'i2c';
+        this._spiHz = 1000000;
+        this._mode = 0;
+        this._alert = -1;
+        this._part = part;
+        void dev;
+        void opts;
+    }
+    /** Fetch a fresh sample (sensor_sample_fetch). Reads reflect the last
+     *  fetch — Zephyr's own fetch/get split, kept verbatim. */
+    fetch() {
+        include('<zephyr/drivers/sensor.h>');
+        sensorFetch(this._part, this._bus, this._port, this._kind, this._spiHz, this._mode, this._alert);
+    }
+    /** Read one channel from the fetched sample (sensor_channel_get).
+     *  Returns the value as a double (val1 + val2/1e6). The parameter is
+     *  narrowed to this part's channels when constructed from a literal
+     *  SENSOR token — `sht3x.get(` completes AMBIENT_TEMP | HUMIDITY and
+     *  rejects the rest in the editor. */
+    get(chan) {
+        include('<zephyr/drivers/sensor.h>');
+        return sensorGet(this._part, this._bus, this._port, this._kind, this._spiHz, this._mode, this._alert, chan);
+    }
+}

package/dist/shift-pin.d.ts

@@ -0,0 +1,2 @@
+export declare function shiftOut(dataPin: number, clockPin: number, value: number, msbFirst?: boolean): void;
+export declare function shiftIn(dataPin: number, clockPin: number, msbFirst?: boolean): number;

package/dist/shift-pin.js

@@ -0,0 +1,13 @@
+// ---------------------------------------------------------------------------
+// shiftOut / shiftIn — the thin bit-bang shift (the legacy shiftOut/shiftIn
+// shape, Zephyr-lowered): clock idles low; each bit sets data then pulses the
+// clock. For real SPI, use SPITarget. Pin arguments accept board pin aliases
+// (resolved to their numbers by the transpiler).
+// ---------------------------------------------------------------------------
+import { gpioShiftOut, gpioShiftIn } from './emit.js';
+export function shiftOut(dataPin, clockPin, value, msbFirst = true) {
+    gpioShiftOut(dataPin, clockPin, value, msbFirst);
+}
+export function shiftIn(dataPin, clockPin, msbFirst = true) {
+    return gpioShiftIn(dataPin, clockPin, msbFirst);
+}

package/dist/spi-target.d.ts

@@ -0,0 +1,25 @@
+import type { Pin } from './gpio.js';
+export declare class SPITarget {
+    private readonly _bus;
+    private readonly _cs;
+    private readonly _hz;
+    private readonly _mode;
+    /** Construct a device handle. `bus` is the bus instance (SPI0, …); `cs`
+     *  is the chip-select pin; `hz` the bus clock (spi-max-frequency, default
+     *  1 MHz conservative); `mode` the SPI mode 0–3. */
+    constructor(bus: string, cs: number | Pin, opts?: {
+        hz?: number;
+        mode?: 0 | 1 | 2 | 3;
+    });
+    /** Full-duplex transfer (spi_transceive_dt): `tx` bytes out while `rx`
+     *  captures — the buffer you pass is the buffer filled, so declare it and
+     *  read it directly (rx.length decides the capture length). Omit `rx`
+     *  for a write-only transfer. */
+    transceive(tx: number[] | Uint8Array, rx?: Uint8Array): void;
+    /** Write bytes (spi_write_dt) — no capture. */
+    write(tx: number[] | Uint8Array): void;
+    /** Register read sugar: sends `reg`, returns the one captured byte
+     *  (spi_transceive_dt against an internal buffer — e.g. a BME280's ID
+     *  register 0xD0 reads 0x60). */
+    readReg(reg: number): number;
+}

package/dist/spi-target.js

@@ -0,0 +1,42 @@
+// ---------------------------------------------------------------------------
+// SPITarget — the thin Zephyr-shaped SPI device
+//
+// A chip-select peer on an SPI bus, addressed the Zephyr way: construction
+// emits a devicetree child node (cs-gpios index + spi-max-frequency + mode
+// bits — the same machinery sensors ride), and the verbs lower to
+// spi_transceive_dt / spi_write_dt against a static spi_dt_spec. Hardware
+// CS, no manual GPIO toggling, no runtime spi_config rebuilding.
+//
+// `bus` is the board's bus instance export (SPI0/SPI1), `cs` the chip-select
+// pin, and the options are the wire facts: `hz` (spi-max-frequency) and
+// `mode` (CPOL/CPHA bits 0–3 → spi-cpol/spi-cpha).
+// ----------------------------------------------------------------------------
+import { spiTransceiveDt, spiWriteDt, spiReadReg } from './emit.js';
+export class SPITarget {
+    /** Construct a device handle. `bus` is the bus instance (SPI0, …); `cs`
+     *  is the chip-select pin; `hz` the bus clock (spi-max-frequency, default
+     *  1 MHz conservative); `mode` the SPI mode 0–3. */
+    constructor(bus, cs, opts) {
+        this._bus = bus;
+        this._cs = typeof cs === 'number' ? cs : cs.number;
+        this._hz = opts?.hz ?? 1000000;
+        this._mode = opts?.mode ?? 0;
+    }
+    /** Full-duplex transfer (spi_transceive_dt): `tx` bytes out while `rx`
+     *  captures — the buffer you pass is the buffer filled, so declare it and
+     *  read it directly (rx.length decides the capture length). Omit `rx`
+     *  for a write-only transfer. */
+    transceive(tx, rx) {
+        spiTransceiveDt(this._bus, this._cs, this._hz, this._mode, tx, rx ?? new Uint8Array(0));
+    }
+    /** Write bytes (spi_write_dt) — no capture. */
+    write(tx) {
+        spiWriteDt(this._bus, this._cs, this._hz, this._mode, tx);
+    }
+    /** Register read sugar: sends `reg`, returns the one captured byte
+     *  (spi_transceive_dt against an internal buffer — e.g. a BME280's ID
+     *  register 0xD0 reads 0x60). */
+    readReg(reg) {
+        return spiReadReg(this._bus, this._cs, this._hz, this._mode, reg);
+    }
+}

package/dist/spi.d.ts

@@ -1,31 +1,13 @@
+import { SPITarget } from './spi-target.js';
 import type { Pin } from './gpio.js';
-import type { SPIMode, SPISettings } from './types.js';
-export declare class SPIDevice {
-    private _bus;
-    private _cs;
-    constructor(bus: string, chipSelect: number);
-    transfer(data: number | Uint8Array): number;
-    write(data: number | Uint8Array): void;
-    readRegister(register: number, count: number): Uint8Array;
-    writeRegister(register: number, value: number): void;
-}
 export declare class SPIBus {
-    static readonly __includes: string[];
     private _bus;
     constructor(bus: string);
-    device(chipSelect: Pin): SPIDevice;
-    begin(): this;
-    end(): void;
-    take(): this | null;
-    release(): void;
-    transfer(value: number | Uint8Array): number;
-    setFrequency(hz: number): void;
-    beginTransaction(settings: SPISettings): void;
-    endTransaction(): void;
-    setMode(mode: SPIMode): void;
-    setBitOrder(order: 'lsb' | 'msb'): void;
-    write(value: number): void;
-    write16(value: number): void;
+    /** The functional device target behind `chipSelect` on this controller —
+     *  transceive/write/regRead verbs callable directly, and the fact-carrier
+     *  `new Sensor(...)` accepts. */
+    device(chipSelect: Pin, opts?: {
+        hz?: number;
+        mode?: 0 | 1 | 2 | 3;
+    }): SPITarget;
 }
-/** Map TypeCAD SPI instance number to Arduino C++ object name. SPI0→SPI, SPI1→SPI1 */
-export declare function spiName(instance: number): string;

package/dist/spi.js

@@ -1,93 +1,21 @@
-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) {
-        this._bus = bus;
-        this._cs = chipSelect;
-    }
-    transfer(data) {
-        include("<SPI.h>");
-        spiCsLow(this._cs);
-        rawCpp(`auto __res = ${this._bus}.transfer(${data});`);
-        spiCsHigh(this._cs);
-        rawCpp(`return __res;`);
-        return 0;
-    }
-    write(data) {
-        include("<SPI.h>");
-        spiCsLow(this._cs);
-        spiTransfer(this._bus, data);
-        spiCsHigh(this._cs);
-    }
-    readRegister(register, count) {
-        include("<SPI.h>");
-        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) {
-        include("<SPI.h>");
-        spiCsLow(this._cs);
-        spiTransfer(this._bus, register);
-        spiTransfer(this._bus, value);
-        spiCsHigh(this._cs);
-    }
-}
+// ---------------------------------------------------------------------------
+// SPI — controller selector (legacy SPI API removed)
+//
+// The bus singletons (SPI0/SPI1…) are CONTROLLER SELECTORS; device(cs, opts?)
+// hands back the FUNCTIONAL SPITarget directly — transceive/write/regRead
+// verbs callable with no further construction. Equivalent to
+// `new SPITarget(this, cs, opts)`. The standalone SPIDevice fact-carrier was
+// absorbed by SPITarget.
+// ----------------------------------------------------------------------------
+import { SPITarget } from './spi-target.js';
 export class SPIBus {
     constructor(bus) {
         this._bus = bus;
     }
-    device(chipSelect) {
-        return new SPIDevice(this._bus, chipSelect.number);
-    }
-    begin() {
-        include("<SPI.h>");
-        spiBegin(this._bus);
-        return this;
-    }
-    end() {
-        spiEnd(this._bus);
-    }
-    take() {
-        return this;
+    /** The functional device target behind `chipSelect` on this controller —
+     *  transceive/write/regRead verbs callable directly, and the fact-carrier
+     *  `new Sensor(...)` accepts. */
+    device(chipSelect, opts) {
+        return new SPITarget(this._bus, chipSelect, opts);
     }
-    release() {
-        // No-op for standard Arduino.
-    }
-    transfer(value) {
-        return spiTransfer(this._bus, value);
-    }
-    setFrequency(hz) {
-        spiBeginTx(this._bus, `SPISettings(${hz}, MSBFIRST, SPI_MODE0)`);
-    }
-    beginTransaction(settings) {
-        spiBeginTx(this._bus, settings);
-    }
-    endTransaction() {
-        spiEndTx(this._bus);
-    }
-    setMode(mode) {
-        spiSetMode(this._bus, mode);
-    }
-    setBitOrder(order) {
-        spiSetBitOrder(this._bus, order);
-    }
-    write(value) {
-        spiTransfer(this._bus, value);
-    }
-    write16(value) {
-        rawCpp(`${this._bus}.transfer16(${value});`);
-    }
-}
-SPIBus.__includes = ["<SPI.h>"];
-/** Map TypeCAD SPI instance number to Arduino C++ object name. SPI0→SPI, SPI1→SPI1 */
-export function spiName(instance) {
-    return instance === 0 ? "SPI" : `SPI${instance}`;
 }

package/dist/thread.d.ts

@@ -0,0 +1,18 @@
+export declare class Thread {
+    private readonly _index;
+    private readonly _stackBytes;
+    private readonly _priority;
+    /** Construct a thread handle. `stackKb` defaults to 2 (generous for
+     *  generated code); `priority` defaults to 5 — preemptive, below main. */
+    constructor(index: number, opts?: {
+        stackKb?: number;
+        priority?: number;
+    });
+    /** Create the thread and schedule it immediately (k_thread_create with
+     *  K_NO_WAIT). The entry function runs concurrently with main from here. */
+    start(fn: () => void): void;
+    /** Block until the thread exits (k_thread_join with K_FOREVER). Requires
+     *  a prior start() on the same index — an unstarted slot is a build
+     *  error naming the slot's symbol. */
+    join(): void;
+}

package/dist/thread.js

@@ -0,0 +1,36 @@
+// ---------------------------------------------------------------------------
+// Thread — the thin Zephyr-shaped thread
+//
+// k_thread_create / k_thread_join with Zephyr's own model: construction
+// carries the thread's facts (stack size, priority); start(fn) creates and
+// schedules it (K_NO_WAIT — running immediately); join() blocks until it
+// exits (K_FOREVER). The entry function is a no-argument closure, trampolined
+// through Zephyr's (void*, void*, void*) entry signature — the same
+// callback machinery interrupts use.
+//
+// The `index` is the thread's identity (0, 1, 2, …) — the slot its stack and
+// k_thread state occupy, like Counter's instance. Priorities: Zephyr's scale
+// — 5 (the default) is preemptive, below main; negative would be cooperative.
+// ----------------------------------------------------------------------------
+import { threadStart, threadJoin } from './emit.js';
+import { callback } from './callback.js';
+export class Thread {
+    /** Construct a thread handle. `stackKb` defaults to 2 (generous for
+     *  generated code); `priority` defaults to 5 — preemptive, below main. */
+    constructor(index, opts) {
+        this._index = index;
+        this._stackBytes = (opts?.stackKb ?? 2) * 1024;
+        this._priority = opts?.priority ?? 5;
+    }
+    /** Create the thread and schedule it immediately (k_thread_create with
+     *  K_NO_WAIT). The entry function runs concurrently with main from here. */
+    start(fn) {
+        threadStart(this._index, this._stackBytes, this._priority, callback(fn));
+    }
+    /** Block until the thread exits (k_thread_join with K_FOREVER). Requires
+     *  a prior start() on the same index — an unstarted slot is a build
+     *  error naming the slot's symbol. */
+    join() {
+        threadJoin(this._index);
+    }
+}

package/dist/time.d.ts

@@ -0,0 +1,23 @@
+export declare class TimeClass {
+    static readonly __instance_name = "Time";
+    /** Yielding sleep in milliseconds (k_msleep). On the generated
+     *  single-threaded main this blocks the caller — the same semantics
+     *  delay() had, JS-spelled. Inside an async function, `await`-ed it
+     *  becomes cooperative: the async state machine arms a deadline and
+     *  yields (other tasks and timers run) until it passes — the same
+     *  machinery `await delay()` rides. */
+    sleep(ms: number): Promise<void>;
+    /** Milliseconds since boot as a double (k_uptime_get) — Date.now()-shaped:
+     *  milliseconds, monotonic, no uint32 wrap. */
+    now(): number;
+    /** Microseconds since boot as a double — uptime-derived
+     *  (k_uptime_get() * 1000) on every board: the cycle-counter form reads a
+     *  constant on SoCs without a free-running 64-bit counter, so the one
+     *  uniform, monotonic expression wins. Resolution is the uptime tick
+     *  (millisecond); for sub-ms determinism use Counter (hardware timer). */
+    nowUs(): number;
+    /** Spin-wait the given microseconds (k_busy_wait) — no yield; for sub-ms
+     *  protocol timing where a schedule point would break the waveform. */
+    busyWaitUs(us: number): void;
+}
+export declare const Time: TimeClass;

package/dist/time.js

@@ -0,0 +1,43 @@
+// ---------------------------------------------------------------------------
+// Time — the TS-flavored timing surface
+//
+// The Arduino-named forms (delay/millis/micros/delayMicroseconds, module
+// functions and the Timing class) are deprecated for new code but keep
+// lowering — framework-arduino is frozen on them. Time is the replacement:
+// plain-number milliseconds like the rest of the JS ecosystem (Date.now() is
+// ms), microseconds explicit in the name, and the honest Zephyr verbs —
+// k_msleep (yielding sleep), k_uptime_get (ms clock), k_busy_wait (spin).
+// ---------------------------------------------------------------------------
+import { timeSleep, timeNow, timeNowUs, timeBusyWaitUs } from './emit.js';
+export class TimeClass {
+    /** Yielding sleep in milliseconds (k_msleep). On the generated
+     *  single-threaded main this blocks the caller — the same semantics
+     *  delay() had, JS-spelled. Inside an async function, `await`-ed it
+     *  becomes cooperative: the async state machine arms a deadline and
+     *  yields (other tasks and timers run) until it passes — the same
+     *  machinery `await delay()` rides. */
+    sleep(ms) {
+        timeSleep(ms);
+        return Promise.resolve();
+    }
+    /** Milliseconds since boot as a double (k_uptime_get) — Date.now()-shaped:
+     *  milliseconds, monotonic, no uint32 wrap. */
+    now() {
+        return timeNow();
+    }
+    /** Microseconds since boot as a double — uptime-derived
+     *  (k_uptime_get() * 1000) on every board: the cycle-counter form reads a
+     *  constant on SoCs without a free-running 64-bit counter, so the one
+     *  uniform, monotonic expression wins. Resolution is the uptime tick
+     *  (millisecond); for sub-ms determinism use Counter (hardware timer). */
+    nowUs() {
+        return timeNowUs();
+    }
+    /** Spin-wait the given microseconds (k_busy_wait) — no yield; for sub-ms
+     *  protocol timing where a schedule point would break the waveform. */
+    busyWaitUs(us) {
+        timeBusyWaitUs(us);
+    }
+}
+TimeClass.__instance_name = 'Time';
+export const Time = new TimeClass();

package/dist/timing.d.ts

@@ -1,8 +1,20 @@
+/**
+ * The Arduino-named timing surface. Deprecated for new code — use `Time`
+ * (hal/time.ts): `Time.sleep`, `Time.now`, `Time.nowUs`, `Time.busyWaitUs`.
+ * Kept lowering: framework-arduino is frozen on this vocabulary, so this
+ * class is permanent, not scheduled for removal.
+ *
+ * @deprecated Use `Time` from '@typecad/hal'.
+ */
 export declare class TimingClass {
     static readonly __instance_name = "Timing";
+    /** @deprecated Use `Time.sleep(ms)`. */
     millis(): number;
+    /** @deprecated Use `Time.nowUs()`. */
     micros(): number;
+    /** @deprecated Use `Time.sleep(ms)`. */
     delay(ms: number): void;
+    /** @deprecated Use `Time.busyWaitUs(us)`. */
     delayMicroseconds(us: number): void;
     freeHeap(): number;
     setInterval(handler: () => void, timeout: number): number;
@@ -11,19 +23,17 @@ export declare class TimingClass {
     clearTimeout(id: number): void;
 }
 export declare const Timing: TimingClass;
+/** @deprecated Use `Time.sleep(ms)`. */
 export declare function delay(ms: number): void;
+/** @deprecated Use `Time.now()`. */
 export declare function millis(): number;
+/** @deprecated Use `Time.nowUs()`. */
 export declare function micros(): number;
+/** @deprecated Use `Time.busyWaitUs(us)`. */
 export declare function delayMicroseconds(us: number): void;
+/** @deprecated Use `Time.freeHeap()`. */
 export declare function freeHeap(): number;
 export declare function setInterval(handler: () => void, timeout: number): number;
 export declare function setTimeout(handler: () => void, timeout: number): number;
 export declare function clearInterval(id: number): void;
 export declare function clearTimeout(id: number): void;
-/** Re-map a number from one range to another. Passes through to the Arduino
- *  core `map()` macro — the transpiler lowers this to a bare `map(...)` call,
- *  so the target framework must provide the implementation (Arduino.h does). */
-export declare function map(value: number, fromLow: number, fromHigh: number, toLow: number, toHigh: number): number;
-/** Constrain a number to a range. Passes through to the Arduino core
- *  `constrain()` macro — see note on `map()` above. */
-export declare function constrain(value: number, low: number, high: number): number;

package/dist/timing.js

@@ -1,9 +1,21 @@
 import { rawCpp, getMillis, getMicros, getFreeHeap, delayMs, delayMicro } from './emit.js';
 import { callback } from './callback.js';
+/**
+ * The Arduino-named timing surface. Deprecated for new code — use `Time`
+ * (hal/time.ts): `Time.sleep`, `Time.now`, `Time.nowUs`, `Time.busyWaitUs`.
+ * Kept lowering: framework-arduino is frozen on this vocabulary, so this
+ * class is permanent, not scheduled for removal.
+ *
+ * @deprecated Use `Time` from '@typecad/hal'.
+ */
 export class TimingClass {
+    /** @deprecated Use `Time.sleep(ms)`. */
     millis() { return getMillis(); }
+    /** @deprecated Use `Time.nowUs()`. */
     micros() { return getMicros(); }
+    /** @deprecated Use `Time.sleep(ms)`. */
     delay(ms) { delayMs(ms); }
+    /** @deprecated Use `Time.busyWaitUs(us)`. */
     delayMicroseconds(us) { delayMicro(us); }
     freeHeap() {
         return getFreeHeap();
@@ -25,10 +37,15 @@ export class TimingClass {
 }
 TimingClass.__instance_name = "Timing";
 export const Timing = new TimingClass();
+/** @deprecated Use `Time.sleep(ms)`. */
 export function delay(ms) { delayMs(ms); }
+/** @deprecated Use `Time.now()`. */
 export function millis() { return getMillis(); }
+/** @deprecated Use `Time.nowUs()`. */
 export function micros() { return getMicros(); }
+/** @deprecated Use `Time.busyWaitUs(us)`. */
 export function delayMicroseconds(us) { delayMicro(us); }
+/** @deprecated Use `Time.freeHeap()`. */
 export function freeHeap() { return Timing.freeHeap(); }
 export function setInterval(handler, timeout) {
     rawCpp(`return __tc_setInterval(${callback(handler)}, ${timeout});`);
@@ -44,10 +61,3 @@ export function clearInterval(id) {
 export function clearTimeout(id) {
     rawCpp(`__tc_clearTimeout(${id});`);
 }
-/** Re-map a number from one range to another. Passes through to the Arduino
- *  core `map()` macro — the transpiler lowers this to a bare `map(...)` call,
- *  so the target framework must provide the implementation (Arduino.h does). */
-export function map(value, fromLow, fromHigh, toLow, toHigh) { return 0; }
-/** Constrain a number to a range. Passes through to the Arduino core
- *  `constrain()` macro — see note on `map()` above. */
-export function constrain(value, low, high) { return 0; }

package/dist/types.d.ts

@@ -2,6 +2,10 @@
 export type DigitalValue = boolean;
 /** An analog value is a plain number (resolution-dependent). */
 export type AnalogValue = number;
+/** A value a serial port (UART / USB console) can write: text, a number, or
+ *  a boolean. Numbers format as decimal (integer + trimmed fractional);
+ *  booleans print as 1/0. */
+export type SerialValue = string | number | boolean;
 export declare enum PinMode {
     INPUT = "INPUT",
     OUTPUT = "OUTPUT",
@@ -10,39 +14,5 @@ export declare enum PinMode {
     OUTPUT_OPEN_DRAIN = "OUTPUT_OPEN_DRAIN",
     ANALOG = "ANALOG"
 }
-export declare enum InterruptMode {
-    RISING = "RISING",
-    FALLING = "FALLING",
-    CHANGE = "CHANGE",
-    LOW = "LOW",
-    HIGH = "HIGH"
-}
 export type InterruptHandler = () => void;
-export interface PinGroupMember {
-    readonly number: number;
-    readonly gpio: number;
-    write(value: DigitalValue): void;
-    high(): void;
-    low(): void;
-    toggle(): void;
-    read(): DigitalValue;
-    isHigh(): boolean;
-    isLow(): boolean;
-}
-export interface IPinGroup<T extends PinGroupMember = PinGroupMember> {
-    readonly name: string;
-    readonly pins: ReadonlyArray<T>;
-    writePattern(pattern: number): void;
-    readPattern(): number;
-    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' | 'rp2350' | 'samd' | 'stm32' | 'nrf52' | (string & {});
-export type I2CAddress = number;
-export type SPIBitOrder = 'msb' | 'lsb';
-export type SPIMode = 0 | 1 | 2 | 3;
-export interface SPISettings {
-    frequency: number;
-    mode: SPIMode;
-    bitOrder: SPIBitOrder;
-}