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

package/dist/emit.d.ts

@@ -1,224 +1,148 @@
+import type { SerialValue } from './types.js';
 /** 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;
-import type { Pin } from './gpio.js';
-type RmtPin = Pin | number | string;
-/** Positional semantic primitive. Args: pin, resolutionHz, bit0Hi, bit0Lo,
- *  bit1Hi, bit1Lo, msbFirst, queueDepth. Use rmtTxInit() from hal/rmt.ts. */
-export declare function rmtTxInit(pin: RmtPin, 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 init). */
-export declare function rmtTxWriteBytes(pin: RmtPin, bytes: number[] | Uint8Array): void;
-/** Write raw RMT symbols — arbitrary [hiTicks, loTicks] pairs. */
-export declare function rmtTxWriteSymbols(pin: RmtPin, symbols: [number, number][]): void;
-/** Block until the queued TX completes. */
-export declare function rmtTxWaitDone(pin: RmtPin, timeoutMs?: number): void;
-/** Tear down the TX channel and release its slot. */
-export declare function rmtTxDeinit(pin: RmtPin): void;
-/** Positional semantic primitive — use rmtRxInit() from hal/rmt.ts. */
-export declare function rmtRxInit(pin: RmtPin, resolutionHz: number): void;
-/** Register a callback-by-name invoked when an RX burst completes. */
-export declare function rmtRxOnReceived(pin: RmtPin, handler: string): void;
-/** Start receiving. */
-export declare function rmtRxStart(pin: RmtPin): void;
-/** Stop receiving. */
-export declare function rmtRxStop(pin: RmtPin): void;
-/** Blocking read — returns flattened symbols [d0,l0,d1,l1,…] in ticks. */
-export declare function rmtRxRead(pin: RmtPin, maxCount: number): number[];
-/** Tear down the RX channel and release its slot. */
-export declare function rmtRxDeinit(pin: RmtPin): 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;
+/** Thin GPIO (hal/gpio-pin.ts): configure with Zephyr flag tokens
+ *  ("GPIO.OUTPUT | GPIO.PULL_UP"). The lowering maps token names to the
+ *  GPIO_* macros; the emitted configure is guarded per pin (first use wins). */
+export declare function gpioConfigure(pin: number | string, flags: number | string): void;
+/** GPIO.shiftOut/shiftIn: bit-banged shift via two pins (one op each). */
+export declare function gpioShiftOut(dataPin: number | import('./gpio.js').Pin, clockPin: number | import('./gpio.js').Pin, value: number, msbFirst: boolean): void;
+export declare function gpioShiftIn(dataPin: number | import('./gpio.js').Pin, clockPin: number | import('./gpio.js').Pin, msbFirst: boolean): number;
+/** Thin GPIO read with FUSED guarded configure — one op, one statement-
+ *  expression: correct in any expression position (if-conditions drop a
+ *  method's leading side-effect ops, so get() must not rely on a separate
+ *  configure op). */
+export declare function gpioReadCfg(pin: number | string, flags: number | string): number;
+/** Thin PWM (hal/pwm-pin.ts): set pulse width in ns against the constructed
+ *  period. The first use also applies the construction period
+ *  (pwm_set_dt with an idle pulse), then pwm_set_pulse_dt. */
+export declare function pwmSetPulse(pin: number | string, periodNs: number, pulseNs: number, controller?: string, channel?: number): void;
+/** Thin PWM duty sugar: pulse = duty(0.0–1.0) × periodNs — one
+ *  pwm_set_pulse_dt call, no 0–255 scaling. */
+export declare function pwmSetDuty(pin: number | string, periodNs: number, duty: number, controller?: string, channel?: number): void;
+/** Thin PWM: change the period at runtime (pwm_set_dt; the pulse resets to
+ *  idle — Zephyr 4.4 has no period-only setter). */
+export declare function pwmSetPeriod(pin: number | string, periodNs: number, controller?: string, channel?: number): void;
+/** Thin ADC (hal/adc-pin.ts): raw read with construction-time gain/reference
+ *  tokens ("ADC.GAIN_1_4" / "ADC.REF_INTERNAL"); empty strings
+ *  mean "use the chip descriptor's defaults". */
+export declare function adcReadRaw(pin: number | string, gain: number | string, reference: number | string, channel?: number, device?: string, pinctrl?: string): number;
+/** Thin ADC: millivolts read (adc_raw_to_millivolts) with the same
+ *  construction-time gain/reference tokens. */
+export declare function adcReadMv(pin: number | string, gain: number | string, reference: number | string, channel?: number, device?: string, pinctrl?: string): number;
+/** Thin GPIO interrupts (hal/gpio-pin.ts onInterrupt): attach with Zephyr
+ *  INT_* tokens ("GPIO.INT_EDGE_FALLING") instead of mode strings. */
+export declare function interruptAttachFlags(pin: number | string, handler: string, intFlags: number | 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;
-/**
- * Drain `count` bytes requested from the I2C bus into a caller-provided buffer.
- * Semantic primitive: lowers to the `i2c.read_buffer` HAL op. The `buffer`
- * argument is emitted as a placeholder (`__HAL_READ_BUF__`) that the var-init
- * transformer rewrites to the caller's own buffer variable, so bytes land in
- * the `uint8_t data[N]` declared in user scope — NOT an internal temp that
- * decays to a pointer on return. Keeps `data.length` / `data[i]` valid.
- */
-export declare function i2cReadBuffer(bus: string, count: number, buffer: number[] | Uint8Array): void;
-/** 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;
-/**
- * Read `count` bytes from the SPI bus into a caller-provided buffer by clocking
- * dummy (0x00) transfers. Semantic primitive: lowers to the `spi.read_buffer`
- * HAL op (per-byte `bus.transfer(0)` read loop). The `buffer` placeholder is
- * rewritten to the caller's variable. Mirrors i2cReadBuffer. The caller is
- * responsible for asserting/de-asserting chip-select around it.
- */
-export declare function spiReadBuffer(bus: string, count: number, buffer: number[] | Uint8Array): 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;
+/** Time.sleep — yielding sleep in milliseconds (Zephyr: k_msleep). */
+export declare function timeSleep(ms: number): void;
+/** Time.now — milliseconds since boot as a double (Zephyr: k_uptime_get). */
+export declare function timeNow(): number;
+/** Time.nowUs — microseconds since boot as a double, uptime-derived
+ *  (k_uptime_get() * 1000) on every board — uniform, monotonic. */
+export declare function timeNowUs(): number;
+/** Time.busyWaitUs — spin-wait the given microseconds, no yield (Zephyr: k_busy_wait). */
+export declare function timeBusyWaitUs(us: number): void;
+export declare function i2cRegWrite(bus: string, address: number, hz: number, reg: number, value: number): void;
+export declare function i2cRegRead(bus: string, address: number, hz: number, reg: number): number;
+export declare function i2cRegUpdate(bus: string, address: number, hz: number, reg: number, mask: number, value: number): void;
+export declare function i2cDevWrite(bus: string, address: number, hz: number, data: number[] | Uint8Array): void;
+/** Enable the USB device + open the CDC serial port with a baud hint. */
+export declare function usbBegin(port: string): void;
+/** Disable the CDC serial port. */
+export declare function usbEnd(port: string): void;
+/** Print value to the USB serial port. */
+export declare function usbPrint(port: string, value: SerialValue): void;
+/** Print value with newline to the USB serial port. */
+export declare function usbPrintln(port: string, value: SerialValue): void;
+/** Read a byte from the USB serial port (-1 if none). */
+export declare function usbRead(port: string): number;
+/** Check if bytes are available from the USB serial port. */
+export declare function usbAvailable(port: string): number;
+/** True when the host has opened the port (DTR asserted). */
+export declare function usbConnected(port: string): boolean;
+/** Thin waitLinked(): bounded DTR poll in the shim. */
+export declare function usbWaitReady(port: string, timeoutMs: number): boolean;
+/** Thin DAC (hal/dac-pin.ts): raw dac_write_value with a construction-time
+ *  resolution (0 = the chip descriptor's channel resolution). */
+export declare function dacWriteValue(pin: number | string, value: number, resolution: number): void;
 /** Disable the watchdog timer. */
 export declare function wdtDisable(): void;
+/** Thin Watchdog (hal/watchdog.ts): arm with the construction timeout in ms
+ *  (wdt_install_timeout + wdt_setup). */
+export declare function wdtSetup(timeoutMs: number): void;
+/** Thin Watchdog: feed (wdt_feed). */
+export declare function wdtFeed(): void;
+/** Thin Counter (hal/counter.ts): register the alarm handler. */
+export declare function counterOnAlarm(instance: number, handler: string): void;
+/** Thin Counter: apply hz as the top value and start (counter_start). */
+export declare function counterStart(instance: number, hz: number): void;
+/** Thin Counter: stop (counter_stop). */
+export declare function counterStop(instance: number): void;
+export declare function spiTransceiveDt(bus: string, cs: number, hz: number, mode: number, tx: number[] | Uint8Array, rx: Uint8Array | number[]): void;
+export declare function spiWriteDt(bus: string, cs: number, hz: number, mode: number, tx: number[] | Uint8Array): void;
+/** SPITarget.readReg sugar: one-byte register read via spi_transceive_dt
+ *  against an INTERNAL buffer — no caller array needed. */
+export declare function spiReadReg(bus: string, cs: number, hz: number, mode: number, reg: number): number;
+export declare function uartPollWrite(port: string, baud: number, data: SerialValue): void;
+export declare function uartRxAvailable(port: string, ring: number): number;
+export declare function uartRxPeek(port: string, ring: number): number;
+export declare function uartRxRead(port: string, ring: number): number;
+export declare function threadStart(index: number, stackBytes: number, priority: number, handler: string): void;
+/** Thin Thread: block until exit (k_thread_join, K_FOREVER). */
+export declare function threadJoin(index: number): 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;
-/** Enter deep sleep until `pin` reaches `level` (pin wakeup). Architecture-aware:
- *  ext0 on Xtensa (RTC pins), gpio-wakeup on RISC-V. */
-export declare function powerDeepSleepPin(pin: number, level: number): void;
-export declare function preferencesBegin(namespace: string, readOnly: boolean): void;
-export declare function preferencesEnd(): void;
-export declare function preferencesClear(): void;
-export declare function preferencesRemove(key: string): void;
-export declare function preferencesPutInt(key: string, value: number): void;
-export declare function preferencesGetInt(key: string, defaultValue: number): number;
-export declare function preferencesPutUInt(key: string, value: number): void;
-export declare function preferencesGetUInt(key: string, defaultValue: number): number;
-export declare function preferencesPutBool(key: string, value: boolean): void;
-export declare function preferencesGetBool(key: string, defaultValue: boolean): boolean;
-export declare function preferencesPutFloat(key: string, value: number): void;
-export declare function preferencesGetFloat(key: string, defaultValue: number): number;
-export declare function preferencesPutString(key: string, value: string): void;
-export declare function preferencesGetString(key: string, defaultValue: string): string;
-export declare function wifiConnect(ssid: string, password?: string, timeoutMs?: number): boolean;
+export declare function fsReadText(path: string): string;
+export declare function fsWriteText(path: string, content: string): void;
+export declare function fsExists(path: string): boolean;
+export declare function fsRemove(path: string): boolean;
+export declare function mqttConnect(brokerUri: string, clientId: string): boolean;
+export declare function mqttOnMessage(handler: string): void;
+export declare function mqttSubscribe(topic: string): void;
+export declare function mqttPublish(topic: string, data: string): void;
+export declare function mqttConnected(): boolean;
+export declare function mqttDisconnect(): void;
+export declare function preferencesClear(ns: string): void;
+export declare function preferencesRemove(ns: string, key: string): void;
+export declare function preferencesPutInt(ns: string, key: string, value: number): void;
+export declare function preferencesGetInt(ns: string, key: string, defaultValue: number): number;
+export declare function preferencesPutBool(ns: string, key: string, value: boolean): void;
+export declare function preferencesGetBool(ns: string, key: string, defaultValue: boolean): boolean;
+export declare function preferencesPutFloat(ns: string, key: string, value: number): void;
+export declare function preferencesGetFloat(ns: string, key: string, defaultValue: number): number;
+export declare function preferencesPutString(ns: string, key: string, value: string): void;
+export declare function preferencesGetString(ns: string, key: string, defaultValue: string): string;
 export declare function wifiConnectStart(ssid: string, password?: string): void;
+/** Join with the station's construction facts (the thin WiFi.join). */
+export declare function wifiJoin(ssid: string, psk: string | undefined, security: number, channel: number, band: number, timeoutMs: number, ps: number, ipAddr: string | undefined, gateway: string | undefined, netmask: string | undefined): boolean;
 export declare function wifiDisconnect(): void;
-export declare function wifiStatus(): number;
 export declare function wifiIsConnected(): boolean;
 export declare function wifiLocalIp(): string;
 export declare function wifiRssi(): number;
-export declare function wifiMac(): string;
-export declare function wifiSetHostname(name: string): void;
-export declare function wifiSetStaticIp(ip: string, gateway: string, subnet: string, dns?: string): void;
-export declare function wifiSetAutoReconnect(enabled: boolean): void;
-export declare function wifiSetPowerSave(mode: string): void;
-export declare function wifiSetTxPower(dbm: number): void;
+export declare function wifiMac(): number;
 export declare function wifiOnEvent(event: string, handler: string): void;
 export declare function wifiApStart(ssid: string, password?: string, channel?: number, hidden?: boolean, maxClients?: number): boolean;
 export declare function wifiApStop(): void;
-export declare function wifiApClientCount(): number;
-export declare function wifiApIp(): string;
-export declare function wifiApSetChannel(channel: number): void;
-export declare function wifiApSetHidden(hidden: boolean): void;
-export declare function wifiApSetMaxClients(maxClients: number): void;
 export declare function wifiScan(): number;
-export declare function wifiScanStart(): void;
 export declare function wifiScanCount(): number;
 export declare function wifiScanSsid(index: number): string;
 export declare function wifiScanRssi(index: number): number;
-export declare function wifiScanEncryption(index: number): number;
+export declare function wifiScanEncryption(index: number): string;
 export declare function wifiScanChannel(index: number): number;
-export declare function wifiSaveCredentials(ssid: string, password: string): void;
-export declare function wifiConnectSaved(timeoutMs?: number): boolean;
-export declare function wifiClearCredentials(): void;
-export declare function wifiWaitConnected(timeoutMs?: number): boolean;
-export declare function wifiWaitDisconnected(): void;
 export declare function httpBegin(method: string, url: string): void;
-export declare function httpReset(): void;
 export declare function httpSetHeader(name: string, value: string): void;
 export declare function httpSetTimeout(ms: number): void;
 export declare function httpSetMaxBody(bytes: number): void;
 export declare function httpSetBody(data: string, json?: boolean): void;
-export declare function httpSetInsecure(): void;
+export declare function httpSetInsecure(insecure: boolean): void;
 export declare function httpSetCaCert(pem: string): void;
 export declare function httpSend(): boolean;
-export declare function httpSendStart(): void;
 export declare function httpStatus(): number;
 export declare function httpOk(): boolean;
 export declare function httpBody(): string;
@@ -233,14 +157,9 @@ export declare function bleOnRead(index: number, handler: string): void;
 export declare function bleOnWrite(index: number, handler: string): void;
 export declare function bleOnConnect(handler: string): void;
 export declare function bleOnDisconnect(handler: string): void;
-export declare function bleNotify(index: number, value: number | string): void;
+export declare function bleNotify(index: number, value: number): void;
 export declare function bleIsConnected(): boolean;
 export declare function bleClientCount(): number;
-export declare function bleSetName(name: string): void;
-export declare function bleUntilConnected(timeoutMs?: number): boolean;
-export declare function bleUntilConnectedStart(): void;
-export declare function bleSetTxPower(dbm: number): void;
-export declare function bleStatus(): number;
 /** Emit raw C++ code (escape hatch for unsupported operations). */
 export declare function rawCpp(code: string): void;
 /**
@@ -257,4 +176,12 @@ export declare function rawCpp(code: string): void;
  *   wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
  */
 export declare function rawCppExpr<T>(code: string): T;
-export {};
+/** Fetch a fresh sample from a DT-bound sensor part. Args: part token, bus
+ *  name, bus port (I2C address or SPI CS pin), bus kind ('i2c' | 'spi'),
+ *  SPI clock Hz, SPI mode 0-3, alert pin (-1 = none). */
+export declare function sensorFetch(part: string, bus: string, port: number, kind: string, spiHz: number, spiMode: number, alertPin: number): void;
+/** Read one channel (a SENSOR_CHAN_* suffix, see CHAN) from the fetched sample.
+ *  Returns the value as a double (Zephyr's sensor_value val1 + val2/1e6).
+ *  Carries the same construction facts as sensorFetch so either op alone
+ *  yields a complete device. */
+export declare function sensorGet(part: string, bus: string, port: number, kind: string, spiHz: number, spiMode: number, alertPin: number, chan: string): number;