@typecad/framework-zephyr 1.0.0-alpha.16 → 1.0.0-alpha.19

package/src/lowering/i2s.ts

@@ -0,0 +1,143 @@
+// ---------------------------------------------------------------------------
+// I2S lowering — Zephyr's i2s API over the harvested controller node
+//
+// The controller is addressed by its DT nodelabel (chip.i2s, the harvested
+// i2s@ node — ESP32 I2S0/1). Each direction lazy-inits on first use (the
+// PWM discipline): configure + trigger START once, then every write/read is
+// one block. The shim owns the mem slab (2 blocks), the TX packing buffer,
+// and the RX receive buffer; blockAt/readAt index the last received block.
+// ---------------------------------------------------------------------------
+
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+
+/** The C variable names for an I2S controller's state. */
+function prefix(idx: number): string {
+  return `__tc_i2s${idx}`;
+}
+
+/** Which i2s.* verbs the program actually uses on a controller — the init
+ *  block emits only the state those verbs reference (a write-only program
+ *  must not carry an unused rx buffer: -Werror fails the build). */
+export interface I2sUsage {
+  write: boolean;
+  read: boolean;
+  readAt: boolean;
+}
+
+/**
+ * Emit the per-controller I2S state: device handle, mem slab, TX/RX block
+ * buffers, and the lazy per-direction init helpers. Called from shimLines
+ * when the program uses i2s.* on this controller and the chip declares it.
+ * The once-flags live HERE (shim scope), not in the lowered call sites — a
+ * second write() statement must not reconfigure/re-start a running stream
+ * (i2s_configure is legal only before the first trigger).
+ */
+export function i2sInitLines(chip: ZephyrChipDescriptor, controllerIndex: number, blockBytes: number, usage: I2sUsage): string[] {
+  const ctrl = chip.i2s?.controllers[controllerIndex];
+  if (!ctrl) return [];
+  const p = prefix(controllerIndex);
+  // readAt rides the RX engine too (its lowering lazily starts RX like read
+  // does) — a readAt-only program still references the whole engine state.
+  const needsEngine = usage.write || usage.read || usage.readAt;
+  const lines: string[] = [
+    '// CUTTLEFISH_I2S_BEGIN',
+    `static const struct device* ${p}_dev = DEVICE_DT_GET(DT_NODELABEL(${ctrl.nodeLabel}));`,
+  ];
+  if (needsEngine) {
+    lines.push(
+      `K_MEM_SLAB_DEFINE_STATIC(${p}_slab, ${blockBytes}, 2, 4);`,
+      `K_MEM_SLAB_DEFINE_STATIC(${p}_rxslab, ${blockBytes}, 2, 4);`,
+      `static void ${p}_init(uint32_t hz, uint8_t channels, uint8_t bits, size_t block_bytes) {`,
+      '    struct i2s_config cfg = { 0 };',
+      '    cfg.word_size = bits;',
+      '    cfg.channels = channels;',
+      '    cfg.format = I2S_FMT_DATA_FORMAT_I2S;',
+      '    cfg.options = 0;',
+      '    cfg.frame_clk_freq = hz;',
+      `    cfg.mem_slab = &${p}_slab;`,
+      '    cfg.block_size = block_bytes;',
+      '    cfg.timeout = 200;',
+      `    int err = i2s_configure(${p}_dev, I2S_DIR_TX, &cfg);`,
+      '    if (err != 0) { printk("typecad-hal i2s: tx configure failed: %d\\n", err); }',
+      `    cfg.mem_slab = &${p}_rxslab;`,
+      `    err = i2s_configure(${p}_dev, I2S_DIR_RX, &cfg);`,
+      '    if (err != 0) { printk("typecad-hal i2s: rx configure failed: %d\\n", err); }',
+      '}',
+      `static bool ${p}_init_done = false;`,
+    );
+  }
+  if (usage.write) {
+    lines.push(
+      `static int16_t ${p}_txbuf[${blockBytes / 2}];`,
+      `static bool ${p}_tx_started = false;`,
+    );
+  }
+  if (usage.read || usage.readAt) {
+    lines.push(`static int16_t ${p}_rxbuf[${blockBytes / 2}];`);
+    lines.push(`static bool ${p}_rx_started = false;`);
+  }
+  lines.push('// CUTTLEFISH_I2S_END');
+  return lines;
+}
+
+/**
+ * Resolve a HAL i2s.* op to Zephyr C++.
+ * Returns `{ code }` for write, `{ expression }` for read/readAt.
+ */
+export function lowerI2s(
+  op: HALOpIR,
+  chip: ZephyrChipDescriptor,
+): { code?: string; expression?: string } {
+  const o = op as any;
+  // DAC discipline: no harvested i2s@ node lowers to the honest comment.
+  if (!chip.i2s || chip.i2s.controllers.length === 0) {
+    return { code: `/* ${op.operation}: this board's chip data declares no I2S controller (no harvested i2s@ node) */` };
+  }
+  const idx = Math.min(Number(o.instance ?? 0), chip.i2s.controllers.length - 1);
+  const p = prefix(idx);
+  const hz = Number(o.hz ?? 16000);
+  const channels = Number(o.channels ?? 2);
+  const bits = Number(o.bits ?? 16);
+  const blockFrames = Number(o.blockFrames ?? 64);
+  const blockBytes = blockFrames * channels * (bits / 8);
+
+  switch (op.operation) {
+    case 'i2s.write': {
+      const samples = (o.samples ?? []) as (number | string)[];
+      const cap = blockFrames * channels;
+      if (samples.length > cap) {
+        throw new Error(
+          `I2S write: one block carries at most ${cap} samples (${blockFrames} frames × ${channels} channels) — got ${samples.length}.`,
+        );
+      }
+      // Zero-pad to the full block; samples are 16-bit.
+      const writes: string[] = [];
+      for (let i = 0; i < cap; i++) {
+        const v = i < samples.length ? samples[i] : 0;
+        writes.push(`${p}_txbuf[${i}] = static_cast<int16_t>(${v});`);
+      }
+      return {
+        code: `{ if (!${p}_init_done) { ${p}_init_done = true; ${p}_init(${hz}U, ${channels}U, ${bits}U, ${blockBytes}U); } ${writes.join(' ')} int err = i2s_buf_write(${p}_dev, ${p}_txbuf, ${blockBytes}U); if (err != 0) { printk("typecad-hal i2s: write failed: %d\\n", err); } else { if (!${p}_tx_started) { ${p}_tx_started = true; err = i2s_trigger(${p}_dev, I2S_DIR_TX, I2S_TRIGGER_START); if (err != 0) { printk("typecad-hal i2s: tx start failed: %d\\n", err); } } } }`,
+      };
+    }
+    case 'i2s.read': {
+      return {
+        expression: `({ if (!${p}_init_done) { ${p}_init_done = true; ${p}_init(${hz}U, ${channels}U, ${bits}U, ${blockBytes}U); } if (!${p}_rx_started) { ${p}_rx_started = true; int err = i2s_trigger(${p}_dev, I2S_DIR_RX, I2S_TRIGGER_START); if (err != 0) { printk("typecad-hal i2s: rx start failed: %d\\n", err); } } size_t got = 0U; int err = i2s_buf_read(${p}_dev, ${p}_rxbuf, &got); if (err != 0) { printk("typecad-hal i2s: read failed: %d\\n", err); } static_cast<double>(${p}_rxbuf[0]); })`,
+      };
+    }
+    case 'i2s.read_at': {
+      // Same lazy RX start as read(): readAt indexes the last RECEIVED
+      // block, so the stream must be running — and a readAt-only program
+      // references (and therefore compiles in) the whole engine state.
+      return {
+        expression: `({ if (!${p}_init_done) { ${p}_init_done = true; ${p}_init(${hz}U, ${channels}U, ${bits}U, ${blockBytes}U); } if (!${p}_rx_started) { ${p}_rx_started = true; int err = i2s_trigger(${p}_dev, I2S_DIR_RX, I2S_TRIGGER_START); if (err != 0) { printk("typecad-hal i2s: rx start failed: %d\\n", err); } } int32_t at = static_cast<int32_t>(${o.index}); double v = 0.0; if (at >= 0 && static_cast<uint32_t>(at) < (sizeof(${p}_rxbuf) / sizeof(${p}_rxbuf[0]))) { v = static_cast<double>(${p}_rxbuf[at]); } v; })`,
+      };
+    }
+    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/src/lowering/index.ts

@@ -40,12 +40,21 @@ import { lowerFs } from './fs.js';
 import { lowerSensor } from './sensor.js';
 import { lowerHwtimer, lowerCounter } from './hwtimer.js';
 import { lowerThread } from './thread.js';
+import { lowerTrace } from './trace.js';
+import { lowerStrip } from './strip.js';
+import { lowerHid } from './hid.js';
+import { lowerMatrix } from './matrix.js';
+import { lowerPower } from './power.js';
+import { lowerClock } from './clock.js';
+import { lowerCan } from './can.js';
+import { lowerI2s } from './i2s.js';
 
 export {
   lowerGpio, lowerTiming, lowerAdc, lowerPwm, lowerI2c, lowerSpi, lowerUart,
   lowerUsb, lowerInterrupt, lowerWdt, lowerBle,
   lowerWifi, lowerHttp, lowerMqtt, lowerPreferences, lowerBoard, lowerRandom,
-  lowerDac, lowerFs, lowerHwtimer, lowerCounter, lowerSensor, lowerThread,
+  lowerDac, lowerFs, lowerHwtimer, lowerCounter, lowerSensor, lowerThread, lowerTrace,
+  lowerStrip, lowerHid, lowerMatrix, lowerPower, lowerClock, lowerCan, lowerI2s,
 };
 
 /**
@@ -83,6 +92,14 @@ export function lowerHalOp(
   if (op.operation.startsWith('random.')) return lowerRandom(op);
   if (op.operation.startsWith('sensor.')) return lowerSensor(op);
   if (op.operation.startsWith('thread.'))   return lowerThread(op);
+  if (op.operation.startsWith('trace.'))    return lowerTrace(op);
+  if (op.operation.startsWith('strip.'))    return lowerStrip(op, chip);
+  if (op.operation.startsWith('hid.'))      return lowerHid(op, chip);
+  if (op.operation.startsWith('matrix.'))   return lowerMatrix(op);
+  if (op.operation.startsWith('power.'))    return lowerPower(op, chip);
+  if (op.operation.startsWith('clock.'))    return lowerClock(op);
+  if (op.operation.startsWith('can.'))      return lowerCan(op, chip);
+  if (op.operation.startsWith('i2s.'))      return lowerI2s(op, chip);
 
   // raw / snprintf.emit / display.* / ... — not lowered by this
   // framework. Return undefined so the transpiler falls back and the manifest

package/src/lowering/interrupts.ts

@@ -116,6 +116,12 @@ export function collectInterruptPins(program: unknown): Set<number> {
     }
   };
   visit(program);
+  // Ops resolved to text while inlining one HAL call into another never become
+  // IR nodes — they ride on ProgramIR.resolvedHalOps (see strategy.ts's
+  // visitResolvedHalOps for the full story).
+  for (const op of (program as { resolvedHalOps?: unknown[] })?.resolvedHalOps ?? []) {
+    visit({ operation: op });
+  }
   return pins;
 }
 

package/src/lowering/matrix.ts

@@ -0,0 +1,70 @@
+// ---------------------------------------------------------------------------
+// Matrix lowering — gpio-kbd-matrix node + input-event trampoline
+//
+// The gpio-kbd-matrix driver (Zephyr input subsystem) scans the grid and
+// reports each key as ABS_X (column) + ABS_Y (row) + BTN_TOUCH (press).
+// The shim decodes the triple and calls the user's lowered callback as
+// (row, col, pressed). The overlay generator synthesizes the DT node with
+// row-gpios/col-gpios phandle arrays from the construction pad lists —
+// the lowering's comment marker carries rows/cols to the toolchain scan
+// (the pwm user-facts marker precedent).
+// ----------------------------------------------------------------------------
+
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+
+/**
+ * Emit the matrix trampoline state. Called from shimLines when the program
+ * uses matrix.* — the listener targets the synthesized tc_matrix node, the
+ * handler pointer is assigned by the on_key lowering.
+ */
+export function matrixInitLines(): string[] {
+  return [
+    '// CUTTLEFISH_MATRIX_BEGIN',
+    'static void (*__tc_matrix_on_key)(double, double, bool) = NULL;',
+    'static int32_t __tc_matrix_row = -1;',
+    'static int32_t __tc_matrix_col = -1;',
+    'static void __tc_matrix_cb(struct input_event* evt, void* user_data) {',
+    '    (void)user_data;',
+    '    switch (evt->code) {',
+    '    case INPUT_ABS_X:',
+    '        __tc_matrix_col = evt->value;',
+    '        break;',
+    '    case INPUT_ABS_Y:',
+    '        __tc_matrix_row = evt->value;',
+    '        break;',
+    '    case INPUT_BTN_TOUCH:',
+    '        if (__tc_matrix_on_key != NULL && __tc_matrix_row >= 0 && __tc_matrix_col >= 0) {',
+    '            __tc_matrix_on_key(static_cast<double>(__tc_matrix_row), static_cast<double>(__tc_matrix_col), evt->value != 0);',
+    '        }',
+    '        break;',
+    '    default:',
+    '        break;',
+    '    }',
+    '}',
+    'INPUT_CALLBACK_DEFINE(DEVICE_DT_GET(DT_NODELABEL(tc_matrix)), __tc_matrix_cb, NULL);',
+    '// CUTTLEFISH_MATRIX_END',
+  ];
+}
+
+/**
+ * Resolve a HAL matrix.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops.
+ */
+export function lowerMatrix(op: HALOpIR): { code?: string; expression?: string } {
+  const o = op as any;
+
+  switch (op.operation) {
+    case 'matrix.on_key': {
+      // The comment marker carries the construction pad lists to the
+      // toolchain's overlay scan (the pwm user-facts precedent).
+      return {
+        code: `/* cuttlefish-matrix: rows=${o.rows} cols=${o.cols} */ __tc_matrix_on_key = ${o.handler};`,
+      };
+    }
+    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/src/lowering/mqtt.ts

@@ -13,7 +13,11 @@
 // shim getaddrinfo-resolves the broker host itself (like the HTTP shim).
 // URI scheme: mqtt:// → 1883 plain TCP, mqtts:// → 8883 TLS
 // (MQTT_TRANSPORT_SECURE + mqtt_sec_config, reusing the same mbedTLS matrix
-// the HTTP TLS path established).
+// the HTTP TLS path established). caCert pins the broker's CA — the PEM is
+// DER-decoded at emit time and registered via tls_credential_add as a
+// CA_CERTIFICATE sec tag with TLS_PEER_VERIFY_REQUIRED (verified TLS, the
+// MQTT analogue of Request's caCert); mqtts:// without a CA stays
+// encrypted-but-unverified (TLS_PEER_VERIFY_NONE).
 //
 // One client slot (HAL singleton). on_message callbacks are dispatched on the
 // poll thread.
@@ -49,6 +53,8 @@ export function mqttInitLines(): string[] {
     `// at connect time; host drives both DNS resolution and the TLS SNI/hostname.`,
     `// on_message is the user callback (set via mqtt.on_message); it fires on the`,
     `// poll thread for every incoming PUBLISH on a subscribed topic.`,
+    `// ca_der is the pinned CA (DER, user-owned from the caCert fact); nullptr`,
+    `// means mqtts:// runs encrypted-but-unverified.`,
     `typedef void (*__tc_mqtt_msg_cb_t)(const char* topic, const char* payload);`,
     `static struct {`,
     `    struct mqtt_client client;`,
@@ -59,6 +65,16 @@ export function mqttInitLines(): string[] {
     `    uint16_t port;             // 1883 / 8883 unless overridden in the URI`,
     `    char client_id[64];`,
     `    bool tls;                  // scheme == "mqtts"`,
+    `    const uint8_t* ca_der;     // pinned CA (DER), nullptr = no CA`,
+    `    size_t ca_der_len;`,
+    `    // What this shim last registered under __TC_MQTT_SEC_TAG (DER arrays`,
+    `    // are function-static, so pointer identity is stable). Zephyr's`,
+    `    // credential store never REPLACES a tag — repeats are skipped, a`,
+    `    // different CA at an occupied tag is reported, not silent.`,
+    `    const uint8_t* ca_added;`,
+    `    size_t ca_added_len;`,
+    `    bool ca_added_set;`,
+    `    sec_tag_t sec_tags[1];     // backs tls.config.sec_tag_list (static lifetime)`,
     `    volatile bool connected;`,
     `    volatile bool stop_poll;   // set by disconnect to terminate the poll thread`,
     `    __tc_mqtt_msg_cb_t on_message;`,
@@ -200,6 +216,35 @@ export function mqttInitLines(): string[] {
     `    return host_len > 0U;`,
     `}`,
     ``,
+    `// Strict IPv4 dotted-quad predicate: exactly four 0-255 groups. A`,
+    `// digit-and-dot scan would also swallow numeric-only DNS names ("123"),`,
+    `// silently skipping the TLS hostname check for them (same helper as the`,
+    `// HTTP shim).`,
+    `static bool __tc_mqtt_host_is_ipv4(const char* h) {`,
+    `    uint32_t quads = 0U;`,
+    `    uint32_t val = 0U;`,
+    `    uint32_t digits = 0U;`,
+    `    for (const char* p = h; ; p++) {`,
+    `        if (*p >= '0' && *p <= '9') {`,
+    `            val = (val * 10U) + static_cast<uint32_t>(*p - '0');`,
+    `            digits++;`,
+    `            if (digits > 3U || val > 255U) return false;`,
+    `        } else if (*p == '.') {`,
+    `            if (digits == 0U || quads >= 3U) return false;`,
+    `            quads++;`,
+    `            val = 0U;`,
+    `            digits = 0U;`,
+    `        } else if (*p == '\\0') {`,
+    `            if (digits == 0U) return false;`,
+    `            quads++;`,
+    `            break;`,
+    `        } else {`,
+    `            return false;`,
+    `        }`,
+    `    }`,
+    `    return quads == 4U;`,
+    `}`,
+    ``,
     `// ── connect ─────────────────────────────────────────────────────────────`,
     `// Parse URI → resolve broker → init client → mqtt_connect → spawn poll thread.`,
     `// Blocks until CONNACK (the poll thread isn't running yet, so we drive a few`,
@@ -248,14 +293,47 @@ export function mqttInitLines(): string[] {
     `        __tc_mqtt.client.transport.type = MQTT_TRANSPORT_SECURE;`,
     `        struct mqtt_sec_config* tls_cfg = &__tc_mqtt.client.transport.tls.config;`,
     `        (void)memset(tls_cfg, 0, sizeof(*tls_cfg));`,
-    `        // The HAL MQTT surface has no CA-pinning op (unlike HTTP's caCert), so`,
-    `        // there is no way to register a trusted CA here. Verify-NONE keeps the`,
-    `        // TLS session encrypted but skips identity verification — the strongest`,
-    `        // the current surface can express. A future mqtt.set_ca_cert op would`,
-    `        // flip this to REQUIRED + a registered sec_tag (like the HTTPS path).`,
-    `        tls_cfg->peer_verify = TLS_PEER_VERIFY_NONE;`,
+    `        if (__tc_mqtt.ca_der != nullptr) {`,
+    `            // Pinned CA (the caCert construction fact): register it as a`,
+    `            // CA_CERTIFICATE sec tag and REQUIRE peer verification — the MQTT`,
+    `            // analogue of the HTTPS caCert path. Zephyr's credential store`,
+    `            // never REPLACES a tag+type pair: re-registering the same DER`,
+    `            // (pointer identity — the arrays are function-static) is skipped`,
+    `            // silently; a DIFFERENT CA hitting an occupied tag is reported so`,
+    `            // a wrong-CA verify is never silent; any other failure keeps the`,
+    `            // tag list empty and verification required — fail closed.`,
+    `            if (!__tc_mqtt.ca_added_set || __tc_mqtt.ca_added != __tc_mqtt.ca_der`,
+    `                || __tc_mqtt.ca_added_len != __tc_mqtt.ca_der_len) {`,
+    `                int cred_rc = tls_credential_add(__TC_MQTT_SEC_TAG,`,
+    `                                                 TLS_CREDENTIAL_CA_CERTIFICATE,`,
+    `                                                 __tc_mqtt.ca_der, __tc_mqtt.ca_der_len);`,
+    `                __tc_mqtt.ca_added = __tc_mqtt.ca_der;`,
+    `                __tc_mqtt.ca_added_len = __tc_mqtt.ca_der_len;`,
+    `                __tc_mqtt.ca_added_set = true;`,
+    `                if (cred_rc == -17 /* -EEXIST */) {`,
+    `                    printk("tc-mqtt: sec tag %d already holds a CA; the first one stays active (rc=%d)\\n", __TC_MQTT_SEC_TAG, cred_rc);`,
+    `                } else if (cred_rc != 0) {`,
+    `                    printk("tc-mqtt: CA registration failed (rc=%d) - verifying against no credentials\\n", cred_rc);`,
+    `                }`,
+    `            }`,
+    `            if (__tc_mqtt.ca_added_set) {`,
+    `                __tc_mqtt.sec_tags[0] = __TC_MQTT_SEC_TAG;`,
+    `                tls_cfg->sec_tag_list = __tc_mqtt.sec_tags;`,
+    `                tls_cfg->sec_tag_count = 1U;`,
+    `            }`,
+    `            tls_cfg->peer_verify = TLS_PEER_VERIFY_REQUIRED;`,
+    `        } else {`,
+    `            // No CA pinned: the session is encrypted but the broker's identity`,
+    `            // is not verified — the strongest the no-caCert form can express.`,
+    `            tls_cfg->peer_verify = TLS_PEER_VERIFY_NONE;`,
+    `        }`,
     `        tls_cfg->cipher_list = nullptr;`,
-    `        tls_cfg->hostname = __tc_mqtt.host;`,
+    `        // mbedtls does not match IP literals against SAN entries — set the`,
+    `        // hostname (SNI + identity check) only for name hosts; IP brokers`,
+    `        // verify chain-only (same policy as the HTTPS path).`,
+    `        if (!__tc_mqtt_host_is_ipv4(__tc_mqtt.host)) {`,
+    `            tls_cfg->hostname = __tc_mqtt.host;`,
+    `        }`,
     `#else`,
     `        printk("tc-mqtt: mqtts:// requested but CONFIG_MQTT_LIB_TLS is off\\n");`,
     `        return;`,
@@ -307,6 +385,10 @@ export function mqttInitLines(): string[] {
     `    __tc_mqtt.on_message = fn;`,
     `}`,
     ``,
+    `// ca_cert is the DER-decoded PEM from the caCert construction fact`,
+    `// (user-owned static array; nullptr = no pinned CA).`,
+    `static inline void __tc_mqtt_set_ca_cert_der(const uint8_t* der, size_t len) { __tc_mqtt.ca_der = der; __tc_mqtt.ca_der_len = len; }`,
+    ``,
     `static inline void __tc_mqtt_subscribe(const char* topic) {`,
     `    static struct mqtt_topic topics[4];`,
     `    static uint16_t msg_id = 1;`,
@@ -361,6 +443,25 @@ export function lowerMqtt(op: HALOpIR): { code?: string; expression?: string } {
   switch (op.operation) {
     case 'mqtt.connect':
       return { code: `__tc_mqtt_connect(${s(o.brokerUri)}, ${s(o.clientId)});` };
+    case 'mqtt.set_ca_cert': {
+      // PEM → DER at emit time (this tree's tf-psa-crypto mbedTLS has no PEM
+      // parser — same decode as http.set_ca_cert; tls_credential_add takes
+      // the DER directly).
+      const pem = String(o.pem ?? '').replace(/^"|"$/g, '').replace(/\\n/g, '\n');
+      if (pem.replace(/\s+/g, '') === '') {
+        // No-CA sentinel (Mqtt always emits the op from connect(); opts.caCert
+        // defaults to '') — elide silently so plain-mqtt:// carries no comment.
+        return { code: '' };
+      }
+      const b64 = pem.replace(/-----[A-Z ]+-----/g, '').replace(/\s+/g, '');
+      const der = Buffer.from(b64, 'base64');
+      // Every X.509 DER starts with the ASN.1 SEQUENCE tag (0x30); a long
+      // but non-cert payload fails here instead of at a confusing handshake
+      // error on the target (same check as http.set_ca_cert).
+      if (der.length < 100 || der[0] !== 0x30) return { code: `// tc-mqtt: caCert PEM failed to decode` };
+      const hex = [...der].map((b) => `0x${b.toString(16).padStart(2, '0')}`).join(', ');
+      return { code: `{ static const uint8_t __tc_mqtt_ca_der[] = { ${hex} }; __tc_mqtt_set_ca_cert_der(__tc_mqtt_ca_der, sizeof(__tc_mqtt_ca_der)); }` };
+    }
     case 'mqtt.on_message':
       return { code: `__tc_mqtt_set_on_message(${s(o.handler)});` };
     case 'mqtt.subscribe':

package/src/lowering/power.ts

@@ -0,0 +1,41 @@
+// ---------------------------------------------------------------------------
+// Power lowering — sys_poweroff() for explicit soft-off entry
+//
+// Both SoC families implement the kernel's sys_poweroff(): ESP32 parks the
+// RTC domain and calls esp_deep_sleep_start(); STM32 enters standby-class
+// deep sleep. The call never returns — wake is a reset or a wake source
+// (board-specific: the Black Pill's WKUP pin is PA0; ESP32 GPIOs armed as
+// wake triggers). Statement emission continues after the call site, but
+// nothing there runs — the transpiler treats it as any other void call.
+// ----------------------------------------------------------------------------
+
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+
+/**
+ * Resolve a HAL power.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops.
+ */
+export function lowerPower(op: HALOpIR, chip?: ZephyrChipDescriptor): { code?: string; expression?: string } {
+  const o = op as any;
+  switch (op.operation) {
+    case 'power.off':
+      return { code: 'sys_poweroff();' };
+    case 'power.off_for': {
+      // DAC discipline: without the RTC wake-timer fact, a timed off would
+      // sleep with no wake source — lower to a comment naming it.
+      if (!chip?.powerWakeTimer) {
+        return { code: `/* Power.offFor(${o.ms} ms): this board's SoC declares no RTC wake timer — soft-off here has no armed wake; use Power.off() */` };
+      }
+      // Arm the RTC timer (µs), then enter soft-off; wake is a reboot.
+      return {
+        code: `{ esp_sleep_enable_timer_wakeup(static_cast<uint64_t>(${o.ms}) * 1000ULL); sys_poweroff(); }`,
+      };
+    }
+    default:
+      throw new Error(
+        `framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+          `Open an issue or use rawCpp() to emit it manually.`,
+      );
+  }
+}