@typecad/framework-zephyr 1.0.0-alpha.13 → 1.0.0-alpha.15

package/dist/lowering/adc.d.ts

@@ -1,14 +1,35 @@
 import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
 import type { ZephyrChipDescriptor } from '../chips/types.js';
-/** Resolve the SAADC channel index for a HAL pin number; -1 if unmapped. */
+/**
+ * Resolve the SAADC channel index for an adc.read argument; -1 if unmapped.
+ *
+ * The numeric argument serves two HAL forms: `InputPin.readAnalog()` passes
+ * a GPIO number, while the Arduino-compat `ADC.read(channel)` passes an ADC
+ * channel number. Pin-first resolution keeps readAnalog behavior unchanged;
+ * the channel fallback makes `ADC.read(n)` resolve on targets where channel
+ * n does not alias GPIO n (e.g. the XIAO's AIN2 = P0.28). Where a number
+ * matches both a mapped pin and another channel's index, the pin wins.
+ */
 export declare function adcChannelForPin(chip: ZephyrChipDescriptor, pin: number): number;
+/**
+ * Resolve the owning ADC controller's node label for an adc.read argument.
+ * Defaults to the descriptor's primary (`chip.adc.nodeLabel`) — channels on
+ * additional controllers (STM32 adc3-only routes, ESP32 adc2 pads) carry
+ * their controller explicitly, and their device handle is
+ * `__tc_adc_<label>_dev` (the primary keeps the unsuffixed `__tc_adc_dev`
+ * so single-controller output is unchanged).
+ */
+export declare function adcControllerForPin(chip: ZephyrChipDescriptor, pin: number): string;
 /**
  * Emit the per-channel ADC setup state. One block per channel in the chip
- * descriptor, each guarded by a `static bool __tc_adc<N>_ready` so the first
- * read configures it and subsequent reads skip. Called from shimLines when
- * the program uses ADC.
+ * descriptor that the PROGRAM ACTUALLY READS (`usedPins`) — an unread
+ * channel's `static` setup function would trip -Wunused-function in the
+ * single generated TU. When `usedPins` is omitted (probe paths with no
+ * program), every descriptor channel is emitted. Each block is guarded by a
+ * `static bool __tc_adc<N>_ready` so the first read configures it and
+ * subsequent reads skip. Called from shimLines when the program uses ADC.
  */
-export declare function adcInitLines(chip: ZephyrChipDescriptor): string[];
+export declare function adcInitLines(chip: ZephyrChipDescriptor, usedPins?: ReadonlySet<number>, overrideDevices?: ReadonlySet<string>): string[];
 /**
  * Resolve a HAL adc.* op to Zephyr C++.
  * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.

package/dist/lowering/adc.js

@@ -11,26 +11,115 @@
 // then just read. A static `adc_channel_cfg` + a per-channel "configured" flag
 // guards the setup, so repeated reads don't reconfigure.
 // ---------------------------------------------------------------------------
-/** Resolve the SAADC channel index for a HAL pin number; -1 if unmapped. */
+import { ZEPHYR_ADC_GAINS, ZEPHYR_ADC_REFERENCES } from '@typecad/hal';
+/**
+ * Resolve the SAADC channel index for an adc.read argument; -1 if unmapped.
+ *
+ * The numeric argument serves two HAL forms: `InputPin.readAnalog()` passes
+ * a GPIO number, while the Arduino-compat `ADC.read(channel)` passes an ADC
+ * channel number. Pin-first resolution keeps readAnalog behavior unchanged;
+ * the channel fallback makes `ADC.read(n)` resolve on targets where channel
+ * n does not alias GPIO n (e.g. the XIAO's AIN2 = P0.28). Where a number
+ * matches both a mapped pin and another channel's index, the pin wins.
+ */
 export function adcChannelForPin(chip, pin) {
-    const ch = chip.adc?.channels.find((c) => c.pin === pin);
-    return ch ? ch.channel : -1;
+    const channels = chip.adc?.channels ?? [];
+    const byPin = channels.find((c) => c.pin === pin);
+    if (byPin)
+        return byPin.channel;
+    const byChannel = channels.find((c) => c.channel === pin);
+    return byChannel ? byChannel.channel : -1;
+}
+/**
+ * Resolve the owning ADC controller's node label for an adc.read argument.
+ * Defaults to the descriptor's primary (`chip.adc.nodeLabel`) — channels on
+ * additional controllers (STM32 adc3-only routes, ESP32 adc2 pads) carry
+ * their controller explicitly, and their device handle is
+ * `__tc_adc_<label>_dev` (the primary keeps the unsuffixed `__tc_adc_dev`
+ * so single-controller output is unchanged).
+ */
+export function adcControllerForPin(chip, pin) {
+    const channels = chip.adc?.channels ?? [];
+    const byPin = channels.find((c) => c.pin === pin);
+    if (byPin)
+        return byPin.controller ?? chip.adc?.nodeLabel ?? 'adc';
+    const byChannel = channels.find((c) => c.channel === pin);
+    return byChannel?.controller ?? chip.adc?.nodeLabel ?? 'adc';
+}
+/** The C++ device-handle symbol for an ADC controller nodelabel. The primary
+ *  controller maps to the historical unsuffixed `__tc_adc_dev`. */
+function adcDevSymbol(controller, primary) {
+    return controller === primary ? '__tc_adc_dev' : `__tc_adc_${controller}_dev`;
+}
+// ── Thin ADC (hal/adc-pin.ts) — gain/reference tokens ──────────────────────
+//
+// "ADC.GAIN_1_4" / "ADC.REF_INTERNAL" token text maps name-for-
+// name onto the enum adc_gain / adc_reference macros. The name sets come from
+// the GENERATED Zephyr token tables (scripts/gen-zephyr-hal-tokens.mjs —
+// parsed from the pinned tree's headers, so the set cannot drift from
+// upstream); empty/absent tokens mean "use the chip descriptor's pair".
+const ADC_GAIN_TOKENS = Object.fromEntries(ZEPHYR_ADC_GAINS.map((g) => [`ADC.GAIN_${g}`, `ADC_GAIN_${g}`]));
+const ADC_REF_TOKENS = Object.fromEntries(ZEPHYR_ADC_REFERENCES.map((r) => [`ADC.REF_${r}`, `ADC_REF_${r}`]));
+/** Resolve one thin-ADC token to its macro; undefined when absent/empty.
+ *  Unknown tokens are build errors naming the valid spellings. */
+function adcThinToken(token, map, kind) {
+    const t = String(token ?? '').trim();
+    if (!t || t === '0' || t === "''")
+        return undefined;
+    const m = map[t];
+    if (!m) {
+        throw new Error(`ADC ${kind} token '${t}' is not a known ADC.* token — valid ${kind}s: ${Object.keys(map).join(', ')}.`);
+    }
+    return m;
 }
 /**
  * Emit the per-channel ADC setup state. One block per channel in the chip
- * descriptor, each guarded by a `static bool __tc_adc<N>_ready` so the first
- * read configures it and subsequent reads skip. Called from shimLines when
- * the program uses ADC.
+ * descriptor that the PROGRAM ACTUALLY READS (`usedPins`) — an unread
+ * channel's `static` setup function would trip -Wunused-function in the
+ * single generated TU. When `usedPins` is omitted (probe paths with no
+ * program), every descriptor channel is emitted. Each block is guarded by a
+ * `static bool __tc_adc<N>_ready` so the first read configures it and
+ * subsequent reads skip. Called from shimLines when the program uses ADC.
  */
-export function adcInitLines(chip) {
-    const dev = `DEVICE_DT_GET(DT_NODELABEL(${chip.adc?.nodeLabel ?? 'adc'}))`;
+export function adcInitLines(chip, usedPins, overrideDevices) {
+    const primary = chip.adc?.nodeLabel ?? 'adc';
     const res = chip.adc?.resolution ?? 12;
     const vref = chip.adc?.vrefMv ?? 3000;
+    // Gain/reference are SoC-specific: the nRF SAADC scheme (gain 1/4 against
+    // the 0.6V internal ref, vref-mv 3000 = VDD) is the default; the STM32
+    // driver requires exactly ADC_GAIN_1 + ADC_REF_INTERNAL (Zephyr maps
+    // "internal" to the VREF+ pad) with vref-mv = VDDA. The descriptor carries
+    // the SoC's pair so the emitted channel setup validates in the driver.
+    const gain = chip.adc?.gain ?? 'ADC_GAIN_1_4';
+    const reference = chip.adc?.reference ?? 'ADC_REF_INTERNAL';
+    const owns = (c, label) => (c.controller ?? primary) === label;
+    const channels = (chip.adc?.channels ?? []).filter((c) => !usedPins ||
+        // Pin-form usage (the ADC/readAnalog path): the exact channel.
+        [...usedPins].some((n) => n === c.pin) ||
+        // Channel-number fallback (the Arduino-compat ADC.read(n) form) — must
+        // match the CONTROLLER too, or colliding indices across controllers
+        // (both ESP32 SARADC units expose channel 0) over-include.
+        [...usedPins].some((n) => adcChannelForPin(chip, n) === c.channel && owns(c, adcControllerForPin(chip, n))));
     const lines = ['// CUTTLEFISH_ADC_BEGIN'];
-    lines.push(`static const struct device* __tc_adc_dev = ${dev};`);
-    for (const c of chip.adc?.channels ?? []) {
+    lines.push(`static const struct device* __tc_adc_dev = DEVICE_DT_GET(DT_NODELABEL(${primary}));`);
+    // Additional controllers referenced by used channels get their own device
+    // handle (sorted for deterministic output). Channel indices collide across
+    // controllers, so non-primary setup symbols carry the controller label.
+    const extraControllers = [...new Set(channels.map((c) => c.controller).filter((x) => !!x && x !== primary))].sort();
+    // Inline-override devices (escape hatch): handles for the DT labels the
+    // construction opts name — they may not appear in the manifest at all.
+    for (const label of (overrideDevices ?? [])) {
+        if (label !== primary && !extraControllers.includes(label))
+            extraControllers.push(label);
+    }
+    for (const label of extraControllers) {
+        lines.push(`static const struct device* __tc_adc_${label}_dev = DEVICE_DT_GET(DT_NODELABEL(${label}));`);
+    }
+    for (const c of channels) {
         const n = c.channel;
-        lines.push(`static bool __tc_adc${n}_ready = false;`, `static void __tc_adc${n}_setup(void) {`, `    if (__tc_adc${n}_ready) return;`, `    const struct adc_channel_cfg cfg = {`, `        .gain = ADC_GAIN_1_4,`, `        .reference = ADC_REF_INTERNAL,`, `        .acquisition_time = ADC_ACQ_TIME_DEFAULT,`, `        .channel_id = ${n},`, `        .differential = 0,`, `    };`, `    adc_channel_setup(__tc_adc_dev, &cfg);`, `    __tc_adc${n}_ready = true;`, `}`);
+        const dev = adcDevSymbol(c.controller ?? primary, primary);
+        const sym = c.controller && c.controller !== primary ? `__tc_adc_${c.controller}_${n}` : `__tc_adc${n}`;
+        lines.push(`static bool ${sym}_ready = false;`, `static void ${sym}_setup(void) {`, `    if (${sym}_ready) return;`, `    const struct adc_channel_cfg cfg = {`, `        .gain = ${gain},`, `        .reference = ${reference},`, `        .acquisition_time = ADC_ACQ_TIME_DEFAULT,`, `        .channel_id = ${n},`, `        .differential = 0,`, `    };`, `    adc_channel_setup(${dev}, &cfg);`, `    ${sym}_ready = true;`, `}`);
     }
     lines.push(`#define __TC_ADC_VREF_MV ${vref}`);
     lines.push(`#define __TC_ADC_RESOLUTION ${res}`);
@@ -45,30 +134,47 @@ export function lowerAdc(op, chip) {
     const o = op;
     const res = chip.adc?.resolution ?? 12;
     const vref = chip.adc?.vrefMv ?? 3000;
+    const gain = chip.adc?.gain ?? 'ADC_GAIN_1_4';
+    const reference = chip.adc?.reference ?? 'ADC_REF_INTERNAL';
     switch (op.operation) {
-        case 'adc.read': {
-            const ch = adcChannelForPin(chip, o.pin);
-            // GCC statement-expression: configures-on-first-call, reads, returns raw.
-            return {
-                expression: `({ __tc_adc${ch}_setup(); int16_t __b = 0; struct adc_sequence __s = { .channels = BIT(${ch}), .buffer = &__b, .buffer_size = sizeof(__b), .resolution = ${res} }; adc_read(__tc_adc_dev, &__s); __b; })`,
-            };
-        }
-        case 'adc.read_voltage': {
-            const ch = adcChannelForPin(chip, o.pin);
-            // Read raw, convert to millivolts via adc_raw_to_millivolts (gain 1/4,
-            // internal ref). Returns mV as int.
+        case 'adc.read_raw':
+        case 'adc.read_mv': {
+            // Construction-time overrides (hal/adc-pin.ts opts: channel/device/
+            // pinctrl): the user vouches for the routing on a pin the facts layer
+            // does not cover. The channel and device symbol come from the op; the
+            // marker comment carries device/pinctrl to the overlay regen (the
+            // transpiler cannot synthesize DT nodes) and suppresses the
+            // unavailable-pin diagnostic.
+            const hasOverride = (typeof o.channelOverride === 'number' && o.channelOverride >= 0)
+                || (typeof o.deviceOverride === 'string' && o.deviceOverride !== '')
+                || (typeof o.pinctrlOverride === 'string' && o.pinctrlOverride !== '');
+            const ch = hasOverride && typeof o.channelOverride === 'number' && o.channelOverride >= 0
+                ? o.channelOverride
+                : adcChannelForPin(chip, o.pin);
+            const primary = chip.adc?.nodeLabel ?? 'adc';
+            const devCtrl = (typeof o.deviceOverride === 'string' && o.deviceOverride !== '')
+                ? o.deviceOverride
+                : adcControllerForPin(chip, o.pin);
+            const dev = adcDevSymbol(devCtrl, primary);
+            const gainMacro = adcThinToken(o.gain, ADC_GAIN_TOKENS, 'gain');
+            const refMacro = adcThinToken(o.reference, ADC_REF_TOKENS, 'reference');
+            const g = gainMacro ?? gain;
+            const r = refMacro ?? reference;
+            const marker = hasOverride
+                ? `/* cuttlefish-user-facts: adc pin=${o.pin}`
+                    + `${typeof o.deviceOverride === 'string' && o.deviceOverride !== '' ? ` device=${o.deviceOverride}` : ''}`
+                    + `${typeof o.pinctrlOverride === 'string' && o.pinctrlOverride !== '' ? ` pinctrl=${o.pinctrlOverride}` : ''}`
+                    + ` channel=${ch} */ `
+                : '';
+            const setup = `static bool __tc_adct${o.pin}_done = false; if (!__tc_adct${o.pin}_done) { const struct adc_channel_cfg __tc_adct${o.pin}_cfg = { .gain = ${g}, .reference = ${r}, .acquisition_time = ADC_ACQ_TIME_DEFAULT, .channel_id = ${ch}, .differential = 0 }; adc_channel_setup(${dev}, &__tc_adct${o.pin}_cfg); __tc_adct${o.pin}_done = true; }`;
+            const read = `int16_t __b = 0; struct adc_sequence __s = { .channels = BIT(${ch}), .buffer = &__b, .buffer_size = sizeof(__b), .resolution = ${res} }; adc_read(${dev}, &__s);`;
+            if (op.operation === 'adc.read_raw') {
+                return { expression: `({ ${marker}${setup} ${read} __b; })` };
+            }
             return {
-                expression: `({ __tc_adc${ch}_setup(); int16_t __b = 0; struct adc_sequence __s = { .channels = BIT(${ch}), .buffer = &__b, .buffer_size = sizeof(__b), .resolution = ${res} }; adc_read(__tc_adc_dev, &__s); int32_t __v = __b; adc_raw_to_millivolts(${vref}, ADC_GAIN_1_4, ${res}, &__v); __v; })`,
+                expression: `({ ${marker}${setup} ${read} int32_t __v = __b; adc_raw_to_millivolts(${vref}, ${g}, ${res}, &__v); __v; })`,
             };
         }
-        case 'adc.get_resolution':
-            return { expression: String(res) };
-        case 'adc.set_reference':
-            // Zephyr configures the reference at channel-setup time; runtime switching
-            // would require re-setup. Record the intent as a no-op statement.
-            return { code: `/* adc.set_reference(${o.reference}): configured at channel setup (ADC_REF_INTERNAL) */` };
-        case 'adc.get_reference':
-            return { expression: `0 /* DEFAULT (ADC_REF_INTERNAL) */` };
         default:
             throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
                 `Open an issue or use rawCpp() to emit it manually.`);

package/dist/lowering/ble.js

@@ -88,6 +88,9 @@ export function bleInitLines() {
         `// bt_gatt_chrc metadata for each characteristic declaration attr.`,
         `static struct bt_gatt_chrc __tc_ble_chrc_meta[__TC_BLE_MAX_CHARS];`,
         `// The flat attribute array + its wrapping service. Plus per-char CCC cfg.`,
+        `static struct bt_gatt_ccc_managed_user_data __tc_ble_ccc[__TC_BLE_MAX_CHARS];`,
+        `// write_ccc dereferences cfg_changed — every slot needs the no-op.`,
+        `static void __tc_ble_ccc_changed(const struct bt_gatt_attr* a, uint16_t v) { (void)a; (void)v; }`,
         `static struct bt_gatt_attr __tc_ble_attrs[__TC_BLE_MAX_ATTRS];`,
         `static size_t __tc_ble_attr_count = 0;`,
         `static struct bt_gatt_service __tc_ble_svc;`,
@@ -142,8 +145,10 @@ export function bleInitLines() {
         `    if (idx < 0 || idx >= __TC_BLE_MAX_CHARS || !__tc_ble.on_read[idx]) return 0;`,
         `    const char* t = __tc_ble_char_defs[idx].type;`,
         `    if (t && strcmp(t, "utf8") == 0) {`,
-        `        const char* s_c = reinterpret_cast<const char*(*)(void)>(__tc_ble.on_read[idx])();`,
-        `        return bt_gatt_attr_read(conn, attr, buf, len, offset, s_c, strlen(s_c));`,
+        `        // Hoisted string callbacks return std::string BY VALUE — call through`,
+        `        // the true signature and borrow c_str() for the copy below.`,
+        `        std::string s_v = reinterpret_cast<std::string(*)(void)>(__tc_ble.on_read[idx])();`,
+        `        return bt_gatt_attr_read(conn, attr, buf, len, offset, s_v.c_str(), s_v.size());`,
         `    } else if (t && strcmp(t, "float32") == 0) {`,
         `        double d = reinterpret_cast<double(*)(void)>(__tc_ble.on_read[idx])();`,
         `        float f = static_cast<float>(d);`,
@@ -263,6 +268,7 @@ export function bleInitLines() {
         `// (declaration + value); the value attr carries the char index in user_data.`,
         `static void __tc_ble_build_svc_table(void) {`,
         `    size_t a = 0;`,
+        `    for (int c = 0; c < __TC_BLE_MAX_CHARS; c++) { __tc_ble_ccc[c].cfg_changed = __tc_ble_ccc_changed; }`,
         `    for (int s = 0; s < static_cast<int>(__tc_ble.svc_count); s++) {`,
         `        // Primary service declaration.`,
         `        __tc_ble_attrs[a].uuid = BT_UUID_GATT_PRIMARY;`,
@@ -298,6 +304,17 @@ export function bleInitLines() {
         `            __tc_ble_attrs[a].perm = BT_GATT_PERM_READ | BT_GATT_PERM_WRITE;`,
         `            __tc_ble.val_attr_idx[c] = static_cast<int>(a);`,
         `            a++;`,
+        `            if (__tc_ble_char_defs[c].perms & 4) {`,
+        `                // CCC descriptor — without it a central cannot subscribe`,
+        `                // and notifications never reach anyone.`,
+        `                __tc_ble_attrs[a].uuid = BT_UUID_GATT_CCC;`,
+        `                __tc_ble_attrs[a].read = bt_gatt_attr_read_ccc;`,
+        `                __tc_ble_attrs[a].write = bt_gatt_attr_write_ccc;`,
+        `                __tc_ble_attrs[a].user_data = &__tc_ble_ccc[c];`,
+        `                __tc_ble_attrs[a].handle = 0;`,
+        `                __tc_ble_attrs[a].perm = BT_GATT_PERM_READ | BT_GATT_PERM_WRITE;`,
+        `                a++;`,
+        `            }`,
         `        }`,
         `    }`,
         `    __tc_ble_attr_count = a;`,
@@ -320,24 +337,28 @@ export function bleInitLines() {
         `    bt_gatt_service_register(&__tc_ble_svc);`,
         `    __tc_ble.status = 1; // Initializing`,
         `    bt_enable(NULL);  // synchronous`,
+        `    bt_enable(NULL);  // synchronous`,
         `    __tc_ble.inited = true;`,
         `    __tc_ble_advertise_start();`,
         `}`,
         ``,
         `// ── Notify ──`,
+        `// Explicit-conn: the NULL (broadcast) form hit an ESP32 controller assert`,
+        `// (lld_con.c) on the first push after subscription on the S3.`,
         `static void __tc_ble_notify(int idx, int16_t value) {`,
         `    if (idx < 0 || idx >= __TC_BLE_MAX_CHARS) return;`,
+        `    if (__tc_ble.conn == NULL) return;   // no link: a NULL-conn notify asserted the controller`,
         `    int ai = __tc_ble.val_attr_idx[idx];`,
         `    if (ai == 0) return;`,
         `    const char* t = __tc_ble_char_defs[idx].type;`,
         `    if (t && strcmp(t, "uint32") == 0) {`,
-        `        uint32_t u = static_cast<uint32_t>(value); bt_gatt_notify(NULL, &__tc_ble_attrs[ai], &u, sizeof(u));`,
+        `        uint32_t u = static_cast<uint32_t>(value); bt_gatt_notify(__tc_ble.conn, &__tc_ble_attrs[ai], &u, sizeof(u));`,
         `    } else if (t && strcmp(t, "float32") == 0) {`,
-        `        float f = static_cast<float>(value); bt_gatt_notify(NULL, &__tc_ble_attrs[ai], &f, sizeof(f));`,
+        `        float f = static_cast<float>(value); bt_gatt_notify(__tc_ble.conn, &__tc_ble_attrs[ai], &f, sizeof(f));`,
         `    } else if (t && strcmp(t, "boolean") == 0) {`,
-        `        uint8_t b = value ? 1 : 0; bt_gatt_notify(NULL, &__tc_ble_attrs[ai], &b, sizeof(b));`,
+        `        uint8_t b = value ? 1 : 0; bt_gatt_notify(__tc_ble.conn, &__tc_ble_attrs[ai], &b, sizeof(b));`,
         `    } else {`,
-        `        int16_t s16 = value; bt_gatt_notify(NULL, &__tc_ble_attrs[ai], &s16, sizeof(s16));`,
+        `        int16_t s16 = value; bt_gatt_notify(__tc_ble.conn, &__tc_ble_attrs[ai], &s16, sizeof(s16));`,
         `    }`,
         `}`,
         ``,
@@ -345,18 +366,7 @@ export function bleInitLines() {
         `    return __tc_ble.status == 3 && __tc_ble.connected_clients > 0;`,
         `}`,
         `static inline int __tc_ble_client_count(void) { return __tc_ble.connected_clients; }`,
-        `static inline void __tc_ble_set_name(const char* name) { strncpy(__tc_ble.name, name, sizeof(__tc_ble.name) - 1); __tc_ble.name[sizeof(__tc_ble.name) - 1] = 0; }`,
-        `static inline void __tc_ble_set_tx_power(int dbm) { (void)dbm; /* nRF TX power via bt_le_set_tx_power — deferred */ }`,
         ``,
-        `static inline bool __tc_ble_until_connected(uint32_t timeout_ms) {`,
-        `    int64_t deadline = static_cast<int64_t>(k_uptime_get()) + static_cast<int64_t>(timeout_ms);`,
-        `    while (!__tc_ble_is_connected()) {`,
-        `        if (timeout_ms > 0 && k_uptime_get() >= deadline) return false;`,
-        `        k_msleep(50);`,
-        `    }`,
-        `    return true;`,
-        `}`,
-        `static inline void __tc_ble_until_connected_start(void) { /* __tc_ble_server_begin already started advertising */ }`,
         `// CUTTLEFISH_BLE_END`,
         ``,
     ];
@@ -399,21 +409,14 @@ export function lowerBle(op) {
         case 'ble.on_disconnect':
             return { code: `__tc_ble.on_disconnect = (${s(o.handler)});` };
         case 'ble.notify':
-            return { expression: `__tc_ble_notify(__tc_ble.current_char, ${s(o.value)})` };
+            // Index-based: val_attr_idx[idx] resolves the registered attr (the
+            // declaration-order slot). current_char would be whatever add_char ran
+            // last — wrong for a standalone notify after later declarations.
+            return { expression: `__tc_ble_notify(${s(o.index ?? 0)}, ${s(o.value)})` };
         case 'ble.is_connected':
             return { expression: `__tc_ble_is_connected()` };
         case 'ble.client_count':
             return { expression: `__tc_ble_client_count()` };
-        case 'ble.status':
-            return { expression: `__tc_ble.status` };
-        case 'ble.set_name':
-            return { code: `__tc_ble_set_name(${s(o.name)});` };
-        case 'ble.set_tx_power':
-            return { code: `__tc_ble_set_tx_power(${s(o.dbm)});` };
-        case 'ble.until_connected':
-            return { expression: `__tc_ble_until_connected(${s(o.timeoutMs)})` };
-        case 'ble.until_connected_start':
-            return { code: `__tc_ble_until_connected_start();` };
         default:
             throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
                 `Open an issue or use rawCpp() to emit it manually.`);

package/dist/lowering/dac.js

@@ -46,17 +46,17 @@ export function lowerDac(op, chip) {
         };
     }
     switch (op.operation) {
-        case 'dac.write': {
-            // Lazy one-time channel setup on first write (the HAL DAC surface has no
-            // begin()), then output the value. Arduino analogWrite is 0–255 against
-            // the channel's resolution; dac_write_value takes the raw code.
+        case 'dac.write_value': {
+            // Thin DAC: raw code with the construction resolution (0 = the
+            // descriptor channel's), lazy setup per pin.
+            const res = Number(o.resolution) > 0 ? Number(o.resolution) : ch.resolution;
             return {
                 code: [
-                    `{ static bool __tc_dac_done = false;`,
-                    `  if (!__tc_dac_done) {`,
-                    `    static const struct dac_channel_cfg __tc_dac_cfg = { .channel_id = ${ch.channel}, .resolution = ${ch.resolution} };`,
-                    `    (void)dac_channel_setup(__tc_dac_dev, &__tc_dac_cfg);`,
-                    `    __tc_dac_done = true;`,
+                    `{ static bool __tc_dact${o.pin}_done = false;`,
+                    `  if (!__tc_dact${o.pin}_done) {`,
+                    `    static const struct dac_channel_cfg __tc_dact${o.pin}_cfg = { .channel_id = ${ch.channel}, .resolution = ${res} };`,
+                    `    (void)dac_channel_setup(__tc_dac_dev, &__tc_dact${o.pin}_cfg);`,
+                    `    __tc_dact${o.pin}_done = true;`,
                     `  }`,
                     `  (void)dac_write_value(__tc_dac_dev, ${ch.channel}, ${o.value}); }`,
                 ].join(' '),

package/dist/lowering/fs.js

@@ -31,21 +31,29 @@ export function fsInitLines() {
         'FS_LITTLEFS_DECLARE_DEFAULT_CONFIG(__tc_fs_data);',
         'static struct fs_mount_t __tc_fs_mp_init = {',
         '    .type = FS_LITTLEFS,',
+        '    .mnt_point = "/lfs",',
         '    .fs_data = &__tc_fs_data,',
         '    .storage_dev = (void *)FIXED_PARTITION_ID(storage_partition),',
-        '    .mnt_point = "/lfs",',
         '};',
         '',
         'static void __tc_fs_ensure_mount(void) {',
         '    if (__tc_fs_mounted) return;',
         '    __tc_fs_mp = __tc_fs_mp_init;',
         '    int rc = fs_mount(&__tc_fs_mp);',
-        '    if (rc == -ENODATA || rc == -EINVAL) {',
-        '        // Unformatted partition — format it for littlefs, then remount.',
+        '    if (rc != 0) {',
+        '        // Any mount failure with a valid config means the partition is',
+        '        // unformatted or corrupt (littlefs reports -EIO on erased flash,',
+        '        // not only -ENODATA/-EINVAL) — format it and remount once.',
         '        (void)fs_mkfs(FS_LITTLEFS, static_cast<uintptr_t>(FIXED_PARTITION_ID(storage_partition)), NULL, 0);',
-        '        (void)fs_mount(&__tc_fs_mp);',
+        '        rc = fs_mount(&__tc_fs_mp);',
+        '    }',
+        '    if (rc == 0) {',
+        '        __tc_fs_mounted = true;',
+        '    } else {',
+        '        char __tc_fs_err[48];',
+        '        (void)snprintf(__tc_fs_err, sizeof(__tc_fs_err), "cuttlefish-fs: mount failed rc=%d", rc);',
+        '        __tc_println(__tc_fs_err);',
         '    }',
-        '    __tc_fs_mounted = true;',
         '}',
         '',
         '// Join the mount point with the user path (paths are within the FS).',
@@ -66,8 +74,11 @@ export function fsInitLines() {
         '    struct fs_file_t f;',
         '    fs_file_t_init(&f);',
         '    if (fs_open(&f, __tc_fs_path(path), FS_O_READ) == 0) {',
-        '        (void)fs_read(&f, buf, sizeof(buf) - 1);',
-        '        buf[sizeof(buf) - 1] = 0;',
+        '        // Terminate at the READ length: the buffer is static and shared',
+        '        // across reads, so bytes from a longer previous file survive a',
+        '        // short read otherwise.',
+        '        ssize_t n = fs_read(&f, buf, sizeof(buf) - 1);',
+        '        buf[(n > 0) ? n : 0] = 0;',
         '        (void)fs_close(&f);',
         '    }',
         '    return buf;',
@@ -103,9 +114,6 @@ export function fsInitLines() {
 export function lowerFs(op) {
     const o = op;
     switch (op.operation) {
-        case 'fs.begin':
-            // No payload (the op carries only its discriminator).
-            return { code: 'return __tc_fs_begin();' };
         case 'fs.read_text':
             return { code: `return __tc_fs_read_text(${o.path});` };
         case 'fs.write_text':

package/dist/lowering/gpio.d.ts

@@ -2,6 +2,8 @@ import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
 import type { ZephyrChipDescriptor } from '../chips/types.js';
 /** The C identifier emitted for a pin's gpio_dt_spec variable. */
 export declare function dtSpecVarName(dtSpec: string): string;
+/** Map thin-GPIO flag token text to the GPIO_* macro expression. */
+export declare function gpioFlagsToMacros(flags: string): string;
 /**
  * Resolve a HAL gpio.* op to Zephyr C++.
  * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.

package/dist/lowering/gpio.js

@@ -14,7 +14,8 @@
 //     The manifest validator's probe (which sends {operation, pin:0} with no
 //     port) hits this path, so it must return a lowered result, not undefined.
 // ---------------------------------------------------------------------------
-import { controllerNodelabelForPin } from '../chips/controllers.js';
+import { controllerNodelabelForPin, controllerRawPinForPin } from '../chips/controllers.js';
+import { ZEPHYR_GPIO_FLAGS } from '@typecad/hal';
 /** The C identifier emitted for a pin's gpio_dt_spec variable. */
 export function dtSpecVarName(dtSpec) {
     return `__tc_dt_${dtSpec}`;
@@ -55,6 +56,50 @@ function flagsForMode(mode) {
     const base = MODE_MAP[mode] ?? 'GPIO_INPUT';
     return base + dtFlagsForMode(mode);
 }
+// ── Thin GPIO (hal/gpio-pin.ts) — flag tokens ─────────────────────────────
+//
+// "GPIO.OUTPUT | GPIO.PULL_UP" token text maps name-for-name onto the GPIO_*
+// macros. The name set comes from the GENERATED Zephyr token table (parsed
+// from the pinned tree's headers); unknown tokens are build errors listing
+// the valid spellings — the sensor-catalog discipline.
+const GPIO_FLAG_TOKENS = Object.fromEntries(ZEPHYR_GPIO_FLAGS.map((f) => [`GPIO.${f}`, `GPIO_${f}`]));
+/** Map thin-GPIO flag token text to the GPIO_* macro expression. */
+export function gpioFlagsToMacros(flags) {
+    const tokens = String(flags ?? '')
+        .split('|')
+        .map((t) => t.trim())
+        .filter(Boolean);
+    if (tokens.length === 0)
+        return 'GPIO_INPUT';
+    const macros = tokens.map((t) => {
+        const m = GPIO_FLAG_TOKENS[t];
+        if (!m) {
+            throw new Error(`GPIO flag '${t}' is not a known GPIO.* token — valid: ${Object.keys(GPIO_FLAG_TOKENS).join(', ')}.`);
+        }
+        return m;
+    });
+    return macros.join(' | ');
+}
+/** Guarded per-pin configure statement for the dt-spec path: construction
+ *  flags apply exactly once, ahead of the first use. */
+function dtSpecConfigure(varName, dtSpec, flags) {
+    return `{ ${dtSpecGuardConfigure(varName, dtSpec, flags)} }`;
+}
+/** The guard body only (no wrapping braces) — for fusing into
+ *  statement-expressions. */
+function dtSpecGuardConfigure(varName, dtSpec, flags) {
+    const done = `__tc_gpio_cfg_${dtSpec.replace(/-/g, '_')}_done`;
+    return `static bool ${done} = false; if (!${done}) { gpio_pin_configure_dt(&${varName}, ${gpioFlagsToMacros(flags)}); ${done} = true; }`;
+}
+/** Guarded per-pin configure statement for the raw-controller path. */
+function rawConfigure(controller, rawPin, pin, flags) {
+    return `{ ${rawGuardConfigure(controller, rawPin, pin, flags)} }`;
+}
+/** The raw-path guard body only — for fusing into statement-expressions. */
+function rawGuardConfigure(controller, rawPin, pin, flags) {
+    const done = `__tc_gpio_cfg_raw${pin}_done`;
+    return `static bool ${done} = false; if (!${done}) { gpio_pin_configure(${controller}, ${rawPin}, ${gpioFlagsToMacros(flags)}); ${done} = true; }`;
+}
 /**
  * Resolve a HAL gpio.* op to Zephyr C++.
  * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
@@ -73,9 +118,17 @@ function lowerGpioDtSpec(op, dtSpec) {
     const o = op;
     const varName = dtSpecVarName(dtSpec);
     switch (op.operation) {
-        case 'gpio.set_mode': {
-            return { code: `gpio_pin_configure_dt(&${varName}, ${flagsForMode(o.mode)});` };
-        }
+        case 'gpio.configure':
+            // Thin GPIO: construction flags, applied once per pin (guard).
+            return { code: dtSpecConfigure(varName, dtSpec, o.flags) };
+        case 'gpio.read_cfg':
+            // Thin GPIO get(): the guarded configure FUSED into the read — one
+            // statement-expression, correct in any expression position (a method's
+            // leading side-effect ops are dropped when the call sits in a pure
+            // expression, e.g. an if-condition).
+            return {
+                expression: `({ ${dtSpecGuardConfigure(varName, dtSpec, o.flags)} gpio_pin_get_dt(&${varName}); })`,
+            };
         case 'gpio.write': {
             // Literal 0/1 stays as-is; runtime expression coerced to int via ternary.
             const v = o.value;
@@ -99,19 +152,46 @@ function lowerGpioRaw(op, chip) {
     const o = op;
     const pin = o.pin;
     // Resolve the owning controller by pin range (ESP32-S3 splits GPIO across
-    // gpio0/gpio1). For single-controller SoCs this is just chip.gpioController.
+    // gpio0/gpio1; STM32 across gpioa/gpiob/gpioc). For single-controller SoCs
+    // this is just chip.gpioController. The raw API takes the PORT-RELATIVE
+    // index (STM32 gpiob is 0-15), not the global HAL pin number.
     const controller = `DEVICE_DT_GET(DT_NODELABEL(${controllerNodelabelForPin(chip, pin)}))`;
+    const rawPin = controllerRawPinForPin(chip, pin);
     switch (op.operation) {
-        case 'gpio.set_mode': {
-            return { code: `gpio_pin_configure(${controller}, ${pin}, ${flagsForMode(o.mode)});` };
+        case 'gpio.configure':
+            // Thin GPIO: construction flags, applied once per pin (guard).
+            return { code: rawConfigure(controller, rawPin, pin, o.flags) };
+        case 'gpio.read_cfg':
+            // Fused guarded configure + raw read (see the dt-spec path above).
+            return {
+                expression: `({ ${rawGuardConfigure(controller, rawPin, pin, o.flags)} gpio_pin_get_raw(${controller}, ${rawPin}); })`,
+            };
+        case 'gpio.shift_out':
+        case 'gpio.shift_in': {
+            // Bit-bang over the raw-controller path (shift pairs are arbitrary
+            // pins): configure both once (guarded), then clock the bits. Zephyr
+            // verbs only — gpio_pin_set_raw / gpio_pin_get_raw / k_busy_wait.
+            const dataCtrl = `DEVICE_DT_GET(DT_NODELABEL(${controllerNodelabelForPin(chip, o.dataPin)}))`;
+            const dataRaw = controllerRawPinForPin(chip, o.dataPin);
+            const clkCtrl = `DEVICE_DT_GET(DT_NODELABEL(${controllerNodelabelForPin(chip, o.clockPin)}))`;
+            const clkRaw = controllerRawPinForPin(chip, o.clockPin);
+            const cfg = `{ static bool __tc_shf${o.dataPin}_${o.clockPin}_done = false; if (!__tc_shf${o.dataPin}_${o.clockPin}_done) { gpio_pin_configure(${dataCtrl}, ${dataRaw}, GPIO_INPUT); gpio_pin_configure(${clkCtrl}, ${clkRaw}, GPIO_OUTPUT); __tc_shf${o.dataPin}_${o.clockPin}_done = true; } }`;
+            if (op.operation === 'gpio.shift_out') {
+                return {
+                    code: `${cfg} for (int __i = ${(o.msbFirst ?? true) ? '7' : '0'}; ${(o.msbFirst ?? true) ? '__i >= 0' : '__i < 8'}; ${(o.msbFirst ?? true) ? '__i--' : '__i++'}) { gpio_pin_set_raw(${dataCtrl}, ${dataRaw}, ((static_cast<uint8_t>(${o.value})) >> __i) & 1); gpio_pin_set_raw(${clkCtrl}, ${clkRaw}, 1); k_busy_wait(1); gpio_pin_set_raw(${clkCtrl}, ${clkRaw}, 0); }`,
+                };
+            }
+            return {
+                expression: `({ ${cfg} uint8_t __b = 0; for (int __i = ${(o.msbFirst ?? true) ? '7' : '0'}; ${(o.msbFirst ?? true) ? '__i >= 0' : '__i < 8'}; ${(o.msbFirst ?? true) ? '__i--' : '__i++'}) { gpio_pin_set_raw(${clkCtrl}, ${clkRaw}, 1); k_busy_wait(1); __b = static_cast<uint8_t>((__b << 1) | (gpio_pin_get_raw(${dataCtrl}, ${dataRaw}) & 1)); gpio_pin_set_raw(${clkCtrl}, ${clkRaw}, 0); } __b; })`,
+            };
         }
         case 'gpio.write': {
             const v = o.value;
             const rhs = typeof v === 'string' ? `((${v}) ? 1 : 0)` : v ? 1 : 0;
-            return { code: `gpio_pin_set_raw(${controller}, ${pin}, ${rhs});` };
+            return { code: `gpio_pin_set_raw(${controller}, ${rawPin}, ${rhs});` };
         }
         case 'gpio.read':
-            return { expression: `gpio_pin_get_raw(${controller}, ${pin})` };
+            return { expression: `gpio_pin_get_raw(${controller}, ${rawPin})` };
         case 'gpio.toggle':
             // Native atomic toggle — never read-modify-write. gpio_pin_get_raw on
             // a direction-only output reads the input latch, which is undefined on
@@ -119,7 +199,7 @@ function lowerGpioRaw(op, chip) {
             // gpio_pin_toggle is the driver-level atomic toggle, and for pins
             // configured without GPIO_ACTIVE_LOW the logical level equals the
             // physical one, so it matches the get_raw/set_raw used elsewhere.
-            return { code: `gpio_pin_toggle(${controller}, ${pin});` };
+            return { code: `gpio_pin_toggle(${controller}, ${rawPin});` };
         default:
             throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
                 `Open an issue or use rawCpp() to emit it manually.`);