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

package/dist/emit.d.ts

@@ -53,6 +53,15 @@ export declare function i2cRequestFrom(bus: string, address: number, quantity: n
 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. */
@@ -67,6 +76,14 @@ export declare function spiEndTx(bus: string): void;
 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. */

package/dist/emit.js

@@ -85,6 +85,15 @@ export function i2cRequestFrom(bus, address, quantity, stop) { return 0; }
 export function i2cAvailable(bus) { return 0; }
 /** Read a byte from I2C. */
 export function i2cRead(bus) { return 0; }
+/**
+ * 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 function i2cReadBuffer(bus, count, buffer) { }
 // ---------------------------------------------------------------------------
 // SPI — serial peripheral interface
 // ---------------------------------------------------------------------------
@@ -102,6 +111,14 @@ export function spiEndTx(bus) { }
 export function spiCsLow(pin) { }
 /** Set SPI chip-select pin HIGH. */
 export function spiCsHigh(pin) { }
+/**
+ * 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 function spiReadBuffer(bus, count, buffer) { }
 /** Set SPI data mode. */
 export function spiSetMode(bus, mode) { }
 /** Set SPI bit order. */

package/dist/i2c.d.ts

@@ -2,6 +2,13 @@ export declare class I2CDevice {
     private _bus;
     private _address;
     constructor(bus: string, address: number);
+    /** The 7-bit I2C address this accessor targets. Exposed so I2CDevice
+     *  structurally satisfies the @typecad/simulator II2CDeviceAccessor contract
+     *  (which declares `readonly address`), letting the same driver function be
+     *  typed against the contract and accept either a real board device or a
+     *  simulated one. The transpiler strips HAL class bodies to IR, so this
+     *  getter carries no runtime cost in the generated C++. */
+    get address(): number;
     writeByte(register: number, value: number): void;
     readByte(register: number): number;
     writeBytes(register: number, data: number[] | Uint8Array): void;

package/dist/i2c.js

@@ -1,10 +1,19 @@
-import { i2cBegin, i2cEnd, i2cSetClock, i2cBeginTx, i2cWrite, i2cWriteBuffer, i2cEndTx, i2cRequestFrom, i2cAvailable, i2cRead, rawCpp } from './emit.js';
+import { i2cBegin, i2cEnd, i2cSetClock, i2cBeginTx, i2cWrite, i2cWriteBuffer, i2cEndTx, i2cRequestFrom, i2cAvailable, i2cRead, i2cReadBuffer, rawCpp } from './emit.js';
 import { include } from './include.js';
 export class I2CDevice {
     constructor(bus, address) {
         this._bus = bus;
         this._address = address;
     }
+    /** The 7-bit I2C address this accessor targets. Exposed so I2CDevice
+     *  structurally satisfies the @typecad/simulator II2CDeviceAccessor contract
+     *  (which declares `readonly address`), letting the same driver function be
+     *  typed against the contract and accept either a real board device or a
+     *  simulated one. The transpiler strips HAL class bodies to IR, so this
+     *  getter carries no runtime cost in the generated C++. */
+    get address() {
+        return this._address;
+    }
     writeByte(register, value) {
         include("<Wire.h>");
         i2cBeginTx(this._bus, this._address);
@@ -33,9 +42,11 @@ export class I2CDevice {
         i2cWrite(this._bus, register);
         i2cEndTx(this._bus, false);
         i2cRequestFrom(this._bus, this._address, count, true);
-        rawCpp(`static uint8_t __buf[${count}];`);
-        rawCpp(`for (int __i = 0; __i < ${count}; __i++) __buf[__i] = ${this._bus}.read();`);
-        rawCpp(`return __buf;`);
+        // Drain the requested bytes 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.
+        i2cReadBuffer(this._bus, count, new Uint8Array(count));
         return new Uint8Array(count);
     }
 }

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typecad/hal",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.6",
   "description": "TypeCAD hardware abstraction layer — GPIO, I2C, SPI, UART as regular TypeScript",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,9 +49,9 @@
   },
   "author": "typecad0",
   "devDependencies": {
-    "@typecad/expect": "1.0.0-alpha.3",
-    "@typecad/board-arduino-uno": "1.0.0-alpha.3",
-    "@typecad/mcu-atmega328p": "1.0.0-alpha.3"
+    "@typecad/expect": "1.0.0-alpha.6",
+    "@typecad/board-arduino-uno": "1.0.0-alpha.6",
+    "@typecad/mcu-atmega328p": "1.0.0-alpha.6"
   },
   "sideEffects": false,
   "exports": {

package/src/emit.ts

@@ -99,6 +99,15 @@ export function i2cRequestFrom(bus: string, address: number, quantity: number, s
 export function i2cAvailable(bus: string): number { return 0; }
 /** Read a byte from I2C. */
 export function i2cRead(bus: string): number { return 0; }
+/**
+ * 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 function i2cReadBuffer(bus: string, count: number, buffer: number[] | Uint8Array): void {}
 
 // ---------------------------------------------------------------------------
 // SPI — serial peripheral interface
@@ -118,6 +127,14 @@ export function spiEndTx(bus: string): void {}
 export function spiCsLow(pin: number | string): void {}
 /** Set SPI chip-select pin HIGH. */
 export 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 function spiReadBuffer(bus: string, count: number, buffer: number[] | Uint8Array): void {}
 /** Set SPI data mode. */
 export function spiSetMode(bus: string, mode: number): void {}
 /** Set SPI bit order. */

package/src/i2c.ts

@@ -1,4 +1,4 @@
-import { i2cBegin, i2cEnd, i2cSetClock, i2cBeginTx, i2cWrite, i2cWriteBuffer, i2cEndTx, i2cRequestFrom, i2cAvailable, i2cRead, rawCpp } from './emit.js';
+import { i2cBegin, i2cEnd, i2cSetClock, i2cBeginTx, i2cWrite, i2cWriteBuffer, i2cEndTx, i2cRequestFrom, i2cAvailable, i2cRead, i2cReadBuffer, rawCpp } from './emit.js';
 import { include } from './include.js';
 
 export class I2CDevice {
@@ -10,6 +10,16 @@ export class I2CDevice {
     this._address = address;
   }
 
+  /** The 7-bit I2C address this accessor targets. Exposed so I2CDevice
+   *  structurally satisfies the @typecad/simulator II2CDeviceAccessor contract
+   *  (which declares `readonly address`), letting the same driver function be
+   *  typed against the contract and accept either a real board device or a
+   *  simulated one. The transpiler strips HAL class bodies to IR, so this
+   *  getter carries no runtime cost in the generated C++. */
+  get address(): number {
+    return this._address;
+  }
+
   writeByte(register: number, value: number): void {
     include("<Wire.h>");
     i2cBeginTx(this._bus, this._address);
@@ -41,9 +51,11 @@ export class I2CDevice {
     i2cWrite(this._bus, register);
     i2cEndTx(this._bus, false);
     i2cRequestFrom(this._bus, this._address, count, true);
-    rawCpp(`static uint8_t __buf[${count}];`);
-    rawCpp(`for (int __i = 0; __i < ${count}; __i++) __buf[__i] = ${this._bus}.read();`);
-    rawCpp(`return __buf;`);
+    // Drain the requested bytes 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.
+    i2cReadBuffer(this._bus, count, new Uint8Array(count));
     return new Uint8Array(count);
   }
 }

package/src/register.ts

@@ -27,9 +27,21 @@ export type Bit = 0 | 1;
 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 function register(_address: number): ClassDecorator {
+  return () => {};
+}
 
 /** 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 function bits(_hi: number, _lo: number): PropertyDecorator {
+  return () => {};
+}

package/src/spi.ts

@@ -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';
 import type { Pin } from './gpio.js';
 import type { SPIMode, SPISettings } from './types.js';
@@ -30,12 +30,15 @@ export class SPIDevice {
 
   readRegister(register: number, count: number): Uint8Array {
     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);
   }