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

package/src/ble.ts

@@ -1,3 +1,22 @@
+// ---------------------------------------------------------------------------
+// BLE — the thin Zephyr-shaped GATT peripheral
+//
+// The advertised identity is a CONSTRUCTION fact: `new BLE('TempSensor')`.
+// The GATT database is declared through service()/char() chains (each char's
+// uuid/type/perms ride its add op — the sensor discipline), handlers attach
+// with onRead/onWrite, and the verbs map 1:1 onto Zephyr's bt_* GATT surface:
+//
+//   start()   → register the deferred service table + bt_enable + advertise
+//   stop()    → bt_le_adv_stop
+//   linked()  → a central is connected
+//   onConnect()/onDrop() → bt_conn callbacks
+//   notify(i, v) → bt_gatt_notify on the declared characteristic i
+//
+// Ordering contract (same as the runtime shim's current_char keying):
+// onRead/onWrite/notify bind to the char() they immediately follow in the
+// chain. Declare handlers right where the characteristic is declared.
+// ----------------------------------------------------------------------------
+
 import {
   bleServerBegin,
   bleAdvertiseStart,
@@ -11,11 +30,6 @@ import {
   bleNotify,
   bleIsConnected,
   bleClientCount,
-  bleSetName,
-  bleUntilConnected,
-  bleUntilConnectedStart,
-  bleSetTxPower,
-  bleStatus,
 } from './emit.js';
 import { callback } from './callback.js';
 
@@ -40,20 +54,6 @@ export enum BlePerm {
   Notify = 4,
 }
 
-/** BLE peripheral status (mirrored by the runtime shim). */
-export enum BleStatus {
-  Idle = 0,
-  Initializing = 1,
-  Advertising = 2,
-  Connected = 3,
-  Error = 4,
-}
-
-export enum BleAdvertisingMode {
-  Connectable = 'connectable',
-  NonConnectable = 'non_connectable',
-}
-
 /** A well-known GATT characteristic entry in the catalog. */
 export interface GattCharacteristicDef {
   readonly uuid: string;
@@ -64,9 +64,10 @@ export interface GattCharacteristicDef {
 }
 
 /**
- * Standard GATT services/characteristics. Autocomplete walks the hierarchy:
- *   GATT.ENVIRONMENTAL. -> TEMPERATURE, HUMIDITY, ...
- * Pass the .uuid, .type, and computed perms to BleServer.characteristic().
+ * Standard GATT services/characteristics — uuid/type/perms reference data.
+ * Pass the pieces explicitly to char():
+ *   GATT.ENVIRONMENTAL.TEMPERATURE →
+ *     char('2A6E', BleValueType.Int16, BlePerm.Read | BlePerm.Notify)
  */
 export const GATT = {
   DEVICE_INFO: {
@@ -88,122 +89,94 @@ export const GATT = {
 export type CharValue = number | string | boolean | Uint8Array;
 
 /**
- * BLE GATT peripheral control, lowered to native ESP-IDF NimBLE
- * (`nimble_host` / `ble_gap` / `ble_gatts`) by framework-esp32.
- *
- * No `include()` calls here — NimBLE headers are framework-owned and added via
- * forcedIncludes when the program uses ble.* ops.
- *
- * Transpiler note: method bodies pass parameters directly into semantic calls
- * (no local consts / module counters) so the resolver can statically track every
- * argument. The characteristic index is carried through the chain via
- * `this._charCount` fieldValues, mirroring how HttpRequest carries _method/_url.
+ * The GATT declaration chain returned by BLE.service()/BLE.char(). Each char()
+ * appends a characteristic; onRead/onWrite/notify bind to the most recent one.
  */
-export class BleClass {
-  static readonly __instance_name = "Ble";
-
-  /** Begin building a GATT server with the given advertised device name. */
-  server(name: string): BleServer {
-    bleSetName(name);
-    return new BleServer(name, 0, 1);
+export class BleChain {
+  /** Begin a new service grouping; subsequent char() calls attach to it. */
+  service(uuid: string): BleChain {
+    bleAddService(uuid);
+    return this;
   }
 
-  /** Initialize NimBLE, register services, and start advertising. */
-  begin(): void {
-    bleServerBegin("TypeCAD");
-    bleAdvertiseStart();
+  /** Append a characteristic by uuid, value type, and permissions
+   *  (`BlePerm.Read | BlePerm.Notify`). Returns this for chaining. */
+  char(uuid: string, type: BleValueType, perms: number): BleChain {
+    bleAddChar(0, uuid, type, perms, 0);
+    return this;
   }
 
-  advertise(): void { bleAdvertiseStart(); }
-  stopAdvertising(): void { bleAdvertiseStop(); }
+  /** Read handler for the most recently declared characteristic. */
+  onRead(handler: () => CharValue): BleChain {
+    bleOnRead(0, callback(handler));
+    return this;
+  }
 
-  /** Blocking at top level; cooperatively awaitable inside async functions. */
-  untilConnected(timeoutMs: number = 0): Promise<boolean> {
-    bleUntilConnected(timeoutMs);
-    return Promise.resolve(false);
+  /** Write handler for the most recently declared characteristic. */
+  onWrite(handler: (value: number) => void): BleChain {
+    bleOnWrite(0, callback(handler));
+    return this;
   }
 
-  untilConnectedStart(): void { bleUntilConnectedStart(); }
-  isConnected(): boolean { return bleIsConnected(); }
-  status(): BleStatus { return bleStatus() as BleStatus; }
-  clientCount(): number { return bleClientCount(); }
-  txPower(dbm: number): this { bleSetTxPower(dbm); return this; }
-  notify(index: number, value: number): void { bleNotify(index, value); }
 }
 
-/**
- * Fluent GATT server builder. Returned by `Ble.server()`.
- *
- * Single-class fluent chain (like HttpRequest): characteristic() returns `this`,
- * so onRead/onWrite/onSubscribe chain directly. The _charCount field tracks
- * which characteristic slot the callbacks attach to.
- *
- * Field tracking (read by the transpiler resolver via ctor field assignment):
- *   _name      — advertised device name
- *   _charCount — current characteristic index (the last characteristic() target)
- *   _svcCount  — current service index
- */
-export class BleServer {
-  private _name: string;
-  private _charCount: number;
-  private _lastChar: number;
-  private _svcCount: number;
+/** A GATT peripheral. The advertised device name is the construction fact. */
+export class BLE {
+  private readonly _name: string;
 
-  constructor(name: string, charCount: number, svcCount: number) {
+  constructor(name: string) {
     this._name = name;
-    this._charCount = charCount;
-    this._lastChar = charCount;
-    this._svcCount = svcCount;
   }
 
-  /** Add a characteristic by UUID, value type, and permissions.
-   *  Combine permissions with `|`: `BlePerm.Read | BlePerm.Notify`.
-   *  Returns this for chaining. */
-  characteristic(uuid: string, type: BleValueType, perms: number): this {
-    bleAddChar(this._charCount, uuid, type, perms, this._svcCount);
-    return this;
+  /** Begin a service grouping; chain char() declarations off it. */
+  service(uuid: string): BleChain {
+    bleAddService(uuid);
+    return new BleChain();
   }
 
-  /** Begin a new service grouping. Subsequent characteristics attach to it. */
-  service(uuid: string): this {
-    bleAddService(uuid);
-    return this;
+  /** Append a characteristic under the default (Environmental Sensing)
+   *  service — the common single-service case. */
+  char(uuid: string, type: BleValueType, perms: number): BleChain {
+    bleAddChar(0, uuid, type, perms, 0);
+    return new BleChain();
   }
 
-  /** Register a read handler for the most recently added characteristic. */
-  onRead(handler: () => CharValue): this {
-    bleOnRead(this._lastChar, callback(handler));
-    return this;
+  /** Register the declared GATT database, enable the stack, and start
+   *  advertising the construction name. */
+  start(): void {
+    bleServerBegin(this._name);
+    bleAdvertiseStart();
   }
 
-  /** Register a write handler for the most recently added characteristic. */
-  onWrite(handler: (value: number) => void): this {
-    bleOnWrite(this._lastChar, callback(handler));
-    return this;
+  /** Stop advertising (the GATT database and any link stay up). */
+  stop(): void {
+    bleAdvertiseStop();
   }
 
-  /** Register a connect handler (called when a central connects). */
-  onConnect(handler: () => void): this {
-    bleOnConnect(callback(handler));
-    return this;
+  /** True while a central is connected. */
+  linked(): boolean {
+    return bleIsConnected();
   }
 
-  /** Register a disconnect handler (called when a central disconnects). */
-  onDisconnect(handler: () => void): this {
-    bleOnDisconnect(callback(handler));
-    return this;
+  /** Number of connected centrals (0 or 1 — the shim is single-connection). */
+  clients(): number {
+    return bleClientCount();
   }
 
-  /** Push a new value to subscribed clients on the most recently added characteristic. */
-  notify(value: number): void {
-    bleNotify(this._lastChar, value);
+  /** Fires when a central connects. */
+  onConnect(handler: () => void): void {
+    bleOnConnect(callback(handler));
   }
 
-  /** Initialize NimBLE, register services, and start advertising. */
-  begin(): void {
-    bleServerBegin(this._name);
-    bleAdvertiseStart();
+  /** Fires when the central disconnects. */
+  onDrop(handler: () => void): void {
+    bleOnDisconnect(callback(handler));
   }
-}
 
-export const Ble = new BleClass();
+  /** Push a value to subscribed clients on a characteristic
+   *  (bt_gatt_notify). `index` is the characteristic's declaration order
+   *  (0-based — the first char() is 0). */
+  notify(index: number, value: number): void {
+    bleNotify(index, value);
+  }
+}

package/src/counter.ts

@@ -0,0 +1,40 @@
+// ---------------------------------------------------------------------------
+// Counter — the thin Zephyr-shaped hardware counter/timer
+//
+// Zephyr's counter driver with Zephyr's verbs. The instance index selects
+// one of the chip's declared free counters (instance 0 = the first, e.g.
+// RTC1 on the nRF52840; the build errors name the available ones). The alarm
+// frequency is a construction fact: start() applies hz as the top value
+// (counter_freq / hz) and arms the alarm callback.
+// ----------------------------------------------------------------------------
+
+import { counterOnAlarm, counterStart, counterStop } from './emit.js';
+import { callback } from './callback.js';
+
+export class Counter {
+  private readonly _instance: number;
+  private readonly _hz: number;
+
+  /** Construct a counter handle. `hz` is the alarm frequency — start()
+   *  realizes it as a top value of counter_freq / hz. */
+  constructor(instance: number, opts: { hz: number }) {
+    this._instance = instance;
+    this._hz = opts.hz;
+  }
+
+  /** Register the alarm handler (fires once per top-value wrap). */
+  onAlarm(handler: () => void): void {
+    counterOnAlarm(this._instance, callback(handler));
+  }
+
+  /** Apply hz as the top value, arm the alarm, and start counting
+   *  (counter_set_top_value + counter_start). */
+  start(): void {
+    counterStart(this._instance, this._hz);
+  }
+
+  /** Stop counting (counter_stop). */
+  stop(): void {
+    counterStop(this._instance);
+  }
+}

package/src/dac-pin.ts

@@ -0,0 +1,28 @@
+// ---------------------------------------------------------------------------
+// DAC — the thin Zephyr-shaped analog output
+//
+// Construction carries the resolution (default: the chip descriptor's channel
+// resolution); write() lowers to a lazy dac_channel_setup (once) +
+// dac_write_value with the RAW code — no 0–255 Arduino range.
+// ----------------------------------------------------------------------------
+
+import { dacWriteValue } from './emit.js';
+import type { Pin } from './gpio.js';
+
+export class DAC {
+  private readonly _pin: number;
+  private readonly _resolution: number;
+
+  /** Construct a DAC channel. `resolution` in bits; 0/omitted = the chip
+   *  descriptor's channel resolution (e.g. 8 on the ESP32's two channels). */
+  constructor(pin: number | Pin, opts?: { resolution?: number }) {
+    this._pin = typeof pin === 'number' ? pin : pin.number;
+    this._resolution = opts?.resolution ?? 0;
+  }
+
+  /** Write the raw code (dac_write_value). For an 8-bit channel the range
+   *  is 0–255; for 12-bit, 0–4095 — the channel's resolution decides. */
+  write(value: number): void {
+    dacWriteValue(this._pin, value, this._resolution);
+  }
+}