@typecad/framework-zephyr 1.0.0-alpha.8

package/dist/lowering/index.js

@@ -0,0 +1,93 @@
+// ---------------------------------------------------------------------------
+// HAL lowering dispatcher
+//
+// Routes a HALOpIR to the per-category lowering module by category prefix
+// (e.g. 'gpio.write' → lowerGpio). Returns undefined for categories the
+// framework does not lower (display/fs/mdns/ota/rmt/dac/
+// hwtimer/capacitive/temp/espnow/crypto/i2s/twai/usb/eth/pcnt/mcpwm — see
+// the manifest), so the transpiler falls back and the manifest validator
+// cross-checks the unsupported categories. (board.* is registered below but is
+// a dead-letter — its values are constant-folded at IR-build time.)
+//
+// Prefix dispatch (matching framework-esp32's lowerHalOp) keeps this resilient:
+// a new op added to a category's lowering fn is picked up here automatically,
+// without also editing a 40-case switch. The per-fn default arm still throws a
+// clear "unsupported op" error for ops that fall within a category prefix but
+// aren't handled, so coverage stays honest.
+// ---------------------------------------------------------------------------
+import { getActiveChip } from '../chips/index.js';
+import { lowerGpio } from './gpio.js';
+import { lowerTiming } from './timing.js';
+import { lowerAdc } from './adc.js';
+import { lowerPwm } from './pwm.js';
+import { lowerI2c } from './i2c.js';
+import { lowerSpi } from './spi.js';
+import { lowerUart } from './uart.js';
+import { lowerInterrupt } from './interrupts.js';
+import { lowerWdt } from './wdt.js';
+import { lowerPower } from './power.js';
+import { lowerTone } from './tone.js';
+import { lowerPulseOrShift } from './pulse.js';
+import { lowerBle } from './ble.js';
+import { lowerWorker } from './worker.js';
+import { lowerWifi } from './wifi.js';
+import { lowerHttp } from './http.js';
+import { lowerMqtt } from './mqtt.js';
+import { lowerPreferences } from './preferences.js';
+import { lowerBoard } from './board.js';
+import { lowerRandom } from './random.js';
+export { lowerGpio, lowerTiming, lowerAdc, lowerPwm, lowerI2c, lowerSpi, lowerUart, lowerInterrupt, lowerWdt, lowerPower, lowerTone, lowerPulseOrShift, lowerBle, lowerWifi, lowerHttp, lowerMqtt, lowerPreferences, lowerBoard, lowerRandom, };
+/**
+ * Lower a HAL op to Zephyr C++. Returns undefined for unsupported categories
+ * (mirrors lowerHalOp in framework-esp32/src/lowering/index.ts).
+ */
+export function lowerHalOp(op) {
+    const chip = getActiveChip();
+    if (op.operation.startsWith('gpio.'))
+        return lowerGpio(op, chip);
+    if (op.operation.startsWith('timing.'))
+        return lowerTiming(op);
+    if (op.operation.startsWith('adc.'))
+        return lowerAdc(op, chip);
+    if (op.operation.startsWith('pwm.'))
+        return lowerPwm(op, chip);
+    if (op.operation.startsWith('i2c.'))
+        return lowerI2c(op, chip);
+    if (op.operation.startsWith('spi.'))
+        return lowerSpi(op, chip);
+    if (op.operation.startsWith('uart.'))
+        return lowerUart(op);
+    if (op.operation.startsWith('interrupt.'))
+        return lowerInterrupt(op, chip);
+    if (op.operation.startsWith('wdt.'))
+        return lowerWdt(op);
+    if (op.operation.startsWith('power.'))
+        return lowerPower(op);
+    if (op.operation.startsWith('tone.'))
+        return lowerTone(op, chip);
+    // pulse.* and shift.* share a bit-bang lowering module.
+    if (op.operation.startsWith('pulse.') || op.operation.startsWith('shift.'))
+        return lowerPulseOrShift(op, chip);
+    if (op.operation.startsWith('ble.'))
+        return lowerBle(op);
+    if (op.operation.startsWith('worker.'))
+        return lowerWorker(op);
+    if (op.operation.startsWith('wifi.'))
+        return lowerWifi(op);
+    if (op.operation.startsWith('http.'))
+        return lowerHttp(op);
+    if (op.operation.startsWith('mqtt.'))
+        return lowerMqtt(op);
+    if (op.operation.startsWith('preferences.'))
+        return lowerPreferences(op);
+    // board.resolve is constant-folded at IR-build time; lowerBoard is the
+    // dead-letter reached only on an unresolvable path.
+    if (op.operation.startsWith('board.'))
+        return lowerBoard(op);
+    if (op.operation.startsWith('random.'))
+        return lowerRandom(op);
+    // raw / snprintf.emit / display.* / ... — not lowered by this
+    // framework. Return undefined so the transpiler falls back and the manifest
+    // validator confirms the unsupported declaration.
+    return undefined;
+}

package/dist/lowering/interrupts.d.ts

@@ -0,0 +1,21 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+/**
+ * Emit the per-pin interrupt callback state + trampolines. Called from shimLines
+ * when the program uses interrupts. The trampoline calls a user function via a
+ * function-pointer static, set at attach time.
+ */
+export declare function interruptInitLines(chip: ZephyrChipDescriptor): string[];
+/**
+ * Resolve a HAL interrupt.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ *
+ * Note: attach requires the pin to be in the descriptor's interruptPins. If a
+ * program attaches to an unlisted pin, we fall back to a diagnostic comment
+ * (the probe uses an unknown pin, so the manifest marks these 'supported' via
+ * the comment lowering — the probe sees a non-undefined return).
+ */
+export declare function lowerInterrupt(op: HALOpIR, chip: ZephyrChipDescriptor): {
+    code?: string;
+    expression?: string;
+};

package/dist/lowering/interrupts.js

@@ -0,0 +1,91 @@
+// ---------------------------------------------------------------------------
+// Interrupt lowering — gpio_init_callback + gpio_add_callback
+//
+// The most complex lowering: Zephyr's GPIO interrupt model requires a
+// `struct gpio_callback` per pin, registered with gpio_add_callback, with a
+// trampoline that calls the user's C handler. The descriptor's gpio.interruptPins
+// lists the pins with DT specs (buttons). The user's handler is a free C
+// function; the trampoline calls it with no args (Arduino attachInterrupt style).
+//
+// Each interrupt pin gets a static callback struct + a trampoline in shimLines.
+// attach enables + adds the callback; detach disables + removes it.
+// ---------------------------------------------------------------------------
+/** Look up an interrupt pin spec by HAL pin number. */
+function findIntPin(chip, pin) {
+    return chip.gpio.interruptPins?.find((p) => p.pin === pin);
+}
+/** The C variable name for a pin's gpio_dt_spec. */
+function dtSpecVar(dtSpec) {
+    return `__tc_int_${dtSpec.replace(/-/g, '_')}`;
+}
+/** Map a HAL interrupt mode string to Zephyr GPIO_INT_* flags. */
+function modeToFlags(mode) {
+    switch (mode.toLowerCase()) {
+        case 'rising': return 'GPIO_INT_EDGE_RISING';
+        case 'falling': return 'GPIO_INT_EDGE_FALLING';
+        case 'change': return 'GPIO_INT_EDGE_BOTH';
+        case 'high': return 'GPIO_INT_LEVEL_HIGH';
+        case 'low': return 'GPIO_INT_LEVEL_LOW';
+        default: return 'GPIO_INT_EDGE_BOTH';
+    }
+}
+/**
+ * Emit the per-pin interrupt callback state + trampolines. Called from shimLines
+ * when the program uses interrupts. The trampoline calls a user function via a
+ * function-pointer static, set at attach time.
+ */
+export function interruptInitLines(chip) {
+    const pins = chip.gpio.interruptPins ?? [];
+    if (pins.length === 0)
+        return [];
+    const lines = ['// CUTTLEFISH_INT_BEGIN'];
+    for (const pin of pins) {
+        const v = dtSpecVar(pin.dtSpec);
+        lines.push(`static const struct gpio_dt_spec ${v} = GPIO_DT_SPEC_GET(DT_ALIAS(${pin.dtSpec}), gpios);`, `static struct gpio_callback ${v}_cb;`, `static void (*${v}_handler)(void) = NULL;`, `static void ${v}_tramp(const struct device* port, struct gpio_callback* cb, gpio_port_pins_t pins_v) {`, `    (void)port; (void)cb; (void)pins_v;`, `    if (${v}_handler) { ${v}_handler(); }`, `}`);
+    }
+    lines.push('// CUTTLEFISH_INT_END');
+    return lines;
+}
+/**
+ * Resolve a HAL interrupt.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ *
+ * Note: attach requires the pin to be in the descriptor's interruptPins. If a
+ * program attaches to an unlisted pin, we fall back to a diagnostic comment
+ * (the probe uses an unknown pin, so the manifest marks these 'supported' via
+ * the comment lowering — the probe sees a non-undefined return).
+ */
+export function lowerInterrupt(op, chip) {
+    const o = op;
+    const pin = findIntPin(chip, o.pin);
+    if (!pin) {
+        // Fallback (also covers the manifest probe): a diagnostic comment so the
+        // resolver returns non-undefined. Real attach needs a descriptor entry.
+        if (op.operation === 'interrupt.attach') {
+            return { code: `/* interrupt.attach(pin ${o.pin}): no DT spec — add to chip descriptor gpio.interruptPins */` };
+        }
+        return { code: `/* interrupt.detach(pin ${o.pin}): no DT spec */` };
+    }
+    const v = dtSpecVar(pin.dtSpec);
+    switch (op.operation) {
+        case 'interrupt.attach': {
+            const flags = modeToFlags(o.mode);
+            return {
+                code: [
+                    `${v}_handler = (${o.handler});`,
+                    `gpio_pin_configure_dt(&${v}, GPIO_INPUT);`,
+                    `gpio_init_callback(&${v}_cb, ${v}_tramp, BIT(${v}.pin));`,
+                    `gpio_pin_interrupt_configure_dt(&${v}, ${flags});`,
+                    `gpio_add_callback(${v}.port, &${v}_cb);`,
+                ].join(' '),
+            };
+        }
+        case 'interrupt.detach':
+            return {
+                code: `gpio_pin_interrupt_configure_dt(&${v}, GPIO_INT_DISABLE); gpio_remove_callback(${v}.port, &${v}_cb); ${v}_handler = NULL;`,
+            };
+        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/mqtt.d.ts

@@ -0,0 +1,19 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+/**
+ * The MQTT runtime shim. All helpers are `static`/`inline` so unused ones
+ * don't trip -Wunused-function in the single generated TU (mirrors http.ts).
+ *
+ * The poll thread is the load-bearing piece: it owns the lifetime of the
+ * socket and dispatches every event (CONNACK, PUBLISH, DISCONNECT) via the
+ * library's evt_cb. connect() spawns it; disconnect()/abort() terminates it.
+ */
+export declare function mqttInitLines(): string[];
+/**
+ * Resolve a HAL mqtt.* op to Zephyr C++ via the __tc_mqtt_* shim. Returns
+ * `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ * Throws on an unrecognized mqtt.* op (coverage stays honest — mirrors http.ts).
+ */
+export declare function lowerMqtt(op: HALOpIR): {
+    code?: string;
+    expression?: string;
+};

package/dist/lowering/mqtt.js

@@ -0,0 +1,366 @@
+// ---------------------------------------------------------------------------
+// MQTT 3.1.1 client lowering — Zephyr <zephyr/net/mqtt.h> over sockets
+//
+// Zephyr's MQTT library is event-driven but has no internal task: the app
+// must call mqtt_input() when the socket is readable and mqtt_live()
+// periodically for keepalive. The generated firmware is setup()/loop(),
+// and the user's loop() is not ours to edit — so the connect shim spawns a
+// dedicated k_thread that runs the poll loop (poll() → mqtt_input/mqtt_live)
+// until disconnect. This mirrors a "managed client" model (like ESP-IDF's
+// esp_mqtt internal task) and keeps the user's loop() untouched.
+//
+// mqtt_connect() does no DNS — the broker is a resolved sockaddr — so the
+// 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).
+//
+// One client slot (HAL singleton). on_message callbacks are dispatched on the
+// poll thread.
+//
+// EMIT BOUNDARY: emitted bytes land in user firmware. Covered by the TypeCAD
+// Runtime Exception (RUNTIME_EXCEPTION.md at the repo root).
+// ---------------------------------------------------------------------------
+/** Render a HAL field: pass through (already rendered by the resolver). */
+function s(v) {
+    return String(v);
+}
+/**
+ * The MQTT runtime shim. All helpers are `static`/`inline` so unused ones
+ * don't trip -Wunused-function in the single generated TU (mirrors http.ts).
+ *
+ * The poll thread is the load-bearing piece: it owns the lifetime of the
+ * socket and dispatches every event (CONNACK, PUBLISH, DISCONNECT) via the
+ * library's evt_cb. connect() spawns it; disconnect()/abort() terminates it.
+ */
+export function mqttInitLines() {
+    return [
+        `// CUTTLEFISH_MQTT_BEGIN`,
+        `#define __TC_MQTT_SEC_TAG 2`,
+        `#define __TC_MQTT_RX_SIZE 256`,
+        `#define __TC_MQTT_TX_SIZE 256`,
+        `#define __TC_MQTT_PAYLOAD_SIZE 256`,
+        ``,
+        `// Single-slot MQTT client. scheme/host/port are parsed from the broker URI`,
+        `// 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.`,
+        `typedef void (*__tc_mqtt_msg_cb_t)(const char* topic, const char* payload);`,
+        `static struct {`,
+        `    struct mqtt_client client;`,
+        `    struct sockaddr_storage broker;`,
+        `    char uri[256];`,
+        `    char scheme[8];            // "mqtt" or "mqtts"`,
+        `    char host[128];`,
+        `    uint16_t port;             // 1883 / 8883 unless overridden in the URI`,
+        `    char client_id[64];`,
+        `    bool tls;                  // scheme == "mqtts"`,
+        `    volatile bool connected;`,
+        `    volatile bool stop_poll;   // set by disconnect to terminate the poll thread`,
+        `    __tc_mqtt_msg_cb_t on_message;`,
+        `    uint8_t rxbuf[__TC_MQTT_RX_SIZE];`,
+        `    uint8_t txbuf[__TC_MQTT_TX_SIZE];`,
+        `    char msg_topic[__TC_MQTT_PAYLOAD_SIZE];   // NUL-terminated topic for the cb`,
+        `    char msg_payload[__TC_MQTT_PAYLOAD_SIZE]; // NUL-terminated payload for the cb`,
+        `    struct k_thread poll_thread;`,
+        `} __tc_mqtt;`,
+        `static K_THREAD_STACK_DEFINE(__tc_mqtt_stack, 4096);`,
+        ``,
+        `// ── event callback ──────────────────────────────────────────────────────`,
+        `// Dispatched by mqtt_input() on the poll thread. CONNACK flips \`connected\`;`,
+        `// PUBLISH reads the payload and fires the user on_message callback;`,
+        `// DISCONNECT clears connected.`,
+        `static void __tc_mqtt_evt_cb(struct mqtt_client* client, const struct mqtt_evt* evt) {`,
+        `    (void)client;`,
+        `    switch (evt->type) {`,
+        `    case MQTT_EVT_CONNACK:`,
+        `        if (evt->result == 0) {`,
+        `            __tc_mqtt.connected = true;`,
+        `        } else {`,
+        `            printk("tc-mqtt: CONNACK rejected (result=%d)\\n", evt->result);`,
+        `        }`,
+        `        break;`,
+        `    case MQTT_EVT_DISCONNECT:`,
+        `        __tc_mqtt.connected = false;`,
+        `        break;`,
+        `    case MQTT_EVT_PUBLISH: {`,
+        `        // Topic comes in evt->param.publish.message.topic.topic (mqtt_utf8).`,
+        `        const struct mqtt_publish_param* p = &evt->param.publish;`,
+        `        uint32_t tlen = p->message.topic.topic.size;`,
+        `        if (tlen >= sizeof(__tc_mqtt.msg_topic)) tlen = sizeof(__tc_mqtt.msg_topic) - 1U;`,
+        `        (void)memcpy(__tc_mqtt.msg_topic, p->message.topic.topic.utf8, tlen);`,
+        `        __tc_mqtt.msg_topic[tlen] = '\\0';`,
+        `        // Payload must be read off the socket (mqtt_utf8 payload pointer is not`,
+        `        // valid until read). mqtt_read_publish_payload returns the byte count.`,
+        `        int32_t rlen = mqtt_read_publish_payload(client, __tc_mqtt.msg_payload,`,
+        `                                                sizeof(__tc_mqtt.msg_payload) - 1U);`,
+        `        if (rlen < 0) rlen = 0;`,
+        `        __tc_mqtt.msg_payload[static_cast<uint32_t>(rlen)] = '\\0';`,
+        `        if (__tc_mqtt.on_message != nullptr) {`,
+        `            __tc_mqtt.on_message(__tc_mqtt.msg_topic, __tc_mqtt.msg_payload);`,
+        `        }`,
+        `        // Ack QoS 1 publishes so the broker doesn't resend. (We subscribe/publish`,
+        `        // at QoS 1.) QoS 0 needs no ack; QoS 2 is not exercised by the HAL surface.`,
+        `        if (p->message.topic.qos == MQTT_QOS_1_AT_LEAST_ONCE) {`,
+        `            struct mqtt_puback_param ack = { .message_id = p->message_id };`,
+        `            (void)mqtt_publish_qos1_ack(client, &ack);`,
+        `        }`,
+        `        break;`,
+        `    }`,
+        `    default:`,
+        `        // PUBACK/SUBACK/PINGRESP etc. — no action needed for the HAL surface.`,
+        `        break;`,
+        `    }`,
+        `}`,
+        ``,
+        `// ── poll thread ─────────────────────────────────────────────────────────`,
+        `// Runs mqtt_input on socket-readable and mqtt_live for keepalive until the`,
+        `// user disconnects (stop_poll) or the broker drops the connection. The fd is`,
+        `// only valid after mqtt_connect() returns 0; it lives in transport.tcp.sock`,
+        `// (plain) or transport.tls.sock (TLS).`,
+        `static int32_t __tc_mqtt_socket_fd(void) {`,
+        `    if (__tc_mqtt.tls) {`,
+        `#if defined(CONFIG_MQTT_LIB_TLS)`,
+        `        return __tc_mqtt.client.transport.tls.sock;`,
+        `#else`,
+        `        return -1;`,
+        `#endif`,
+        `    }`,
+        `    return __tc_mqtt.client.transport.tcp.sock;`,
+        `}`,
+        ``,
+        `static void __tc_mqtt_poll_thread(void* a1, void* a2, void* a3) {`,
+        `    (void)a1; (void)a2; (void)a3;`,
+        `    while (!__tc_mqtt.stop_poll) {`,
+        `        int32_t timeout = mqtt_keepalive_time_left(&__tc_mqtt.client);`,
+        `        if (timeout < 0) timeout = 1000;`,
+        `        struct zsock_pollfd fds[1];`,
+        `        fds[0].fd = __tc_mqtt_socket_fd();`,
+        `        fds[0].events = ZSOCK_POLLIN;`,
+        `        fds[0].revents = 0;`,
+        `        int pr = zsock_poll(fds, 1, timeout);`,
+        `        if (pr < 0) {`,
+        `            printk("tc-mqtt: poll failed (errno %d)\\n", -pr);`,
+        `            __tc_mqtt.connected = false;`,
+        `            break;`,
+        `        }`,
+        `        if (pr > 0 && (fds[0].revents & (ZSOCK_POLLIN | ZSOCK_POLLHUP | ZSOCK_POLLERR)) != 0) {`,
+        `            int er = mqtt_input(&__tc_mqtt.client);`,
+        `            if (er != 0) {`,
+        `                printk("tc-mqtt: input failed (errno %d)\\n", -er);`,
+        `                __tc_mqtt.connected = false;`,
+        `                break;`,
+        `            }`,
+        `            if (!__tc_mqtt.connected && !__tc_mqtt.stop_poll) {`,
+        `                // Broker closed (DISCONNECT event observed).`,
+        `                break;`,
+        `            }`,
+        `        } else {`,
+        `            // Timeout: send PINGREQ if the keepalive interval has elapsed.`,
+        `            (void)mqtt_live(&__tc_mqtt.client);`,
+        `        }`,
+        `    }`,
+        `}`,
+        ``,
+        `// ── URI parser ──────────────────────────────────────────────────────────`,
+        `// Splits "scheme://host[:port]" → scheme/host/port. mqtt→1883, mqtts→8883.`,
+        `// Sets __tc_mqtt.tls. Returns false on an unparseable URI.`,
+        `static bool __tc_mqtt_parse_uri(const char* uri) {`,
+        `    const char* sep = strstr(uri, "://");`,
+        `    if (sep == nullptr) return false;`,
+        `    size_t scheme_len = static_cast<size_t>(sep - uri);`,
+        `    if (scheme_len >= sizeof(__tc_mqtt.scheme)) scheme_len = sizeof(__tc_mqtt.scheme) - 1U;`,
+        `    for (size_t i = 0U; i < scheme_len; i++) {`,
+        `        char c = uri[i];`,
+        `        __tc_mqtt.scheme[i] = (c >= 'A' && c <= 'Z') ? static_cast<char>(c + 32) : c;`,
+        `    }`,
+        `    __tc_mqtt.scheme[scheme_len] = '\\0';`,
+        `    __tc_mqtt.tls = (strcmp(__tc_mqtt.scheme, "mqtts") == 0);`,
+        `    __tc_mqtt.port = __tc_mqtt.tls ? 8883U : 1883U;`,
+        `    const char* p = sep + 3; // past "://"`,
+        `    size_t host_len = 0U;`,
+        `    while (*p != '\\0' && *p != ':' && *p != '/' && host_len < (sizeof(__tc_mqtt.host) - 1U)) {`,
+        `        __tc_mqtt.host[host_len++] = *p++;`,
+        `    }`,
+        `    __tc_mqtt.host[host_len] = '\\0';`,
+        `    if (*p == ':') {`,
+        `        p++;`,
+        `        uint32_t portval = 0U;`,
+        `        while (*p >= '0' && *p <= '9') {`,
+        `            portval = (portval * 10U) + static_cast<uint32_t>(*p - '0');`,
+        `            p++;`,
+        `            if (portval > 65535U) portval = 65535U;`,
+        `        }`,
+        `        if (portval > 0U) __tc_mqtt.port = static_cast<uint16_t>(portval);`,
+        `    }`,
+        `    return host_len > 0U;`,
+        `}`,
+        ``,
+        `// ── 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`,
+        `// input cycles ourselves) or a short timeout. Sets connected.`,
+        `static void __tc_mqtt_connect(const char* uri, const char* clientId) {`,
+        `    (void)strncpy(__tc_mqtt.uri, uri, sizeof(__tc_mqtt.uri) - 1U);`,
+        `    __tc_mqtt.uri[sizeof(__tc_mqtt.uri) - 1U] = '\\0';`,
+        `    (void)strncpy(__tc_mqtt.client_id, clientId, sizeof(__tc_mqtt.client_id) - 1U);`,
+        `    __tc_mqtt.client_id[sizeof(__tc_mqtt.client_id) - 1U] = '\\0';`,
+        `    __tc_mqtt.connected = false;`,
+        `    __tc_mqtt.stop_poll = false;`,
+        `    if (!__tc_mqtt_parse_uri(uri)) {`,
+        `        printk("tc-mqtt: bad broker URI\\n");`,
+        `        return;`,
+        `    }`,
+        `    // DNS-resolve the broker host into the sockaddr_storage.`,
+        `    char port_str[8];`,
+        `    (void)snprintk(port_str, sizeof(port_str), "%u", static_cast<unsigned int>(__tc_mqtt.port));`,
+        `    struct zsock_addrinfo hints = { 0 };`,
+        `    hints.ai_family = AF_INET;`,
+        `    hints.ai_socktype = SOCK_STREAM;`,
+        `    struct zsock_addrinfo* res = nullptr;`,
+        `    int gai = zsock_getaddrinfo(__tc_mqtt.host, port_str, &hints, &res);`,
+        `    if (gai != 0 || res == nullptr) {`,
+        `        printk("tc-mqtt: DNS failed for %s (gai=%d)\\n", __tc_mqtt.host, gai);`,
+        `        return;`,
+        `    }`,
+        `    (void)memcpy(&__tc_mqtt.broker, res->ai_addr, res->ai_addrlen);`,
+        `    zsock_freeaddrinfo(res);`,
+        ``,
+        `    mqtt_client_init(&__tc_mqtt.client);`,
+        `    __tc_mqtt.client.broker = &__tc_mqtt.broker;`,
+        `    __tc_mqtt.client.evt_cb = __tc_mqtt_evt_cb;`,
+        `    __tc_mqtt.client.client_id.utf8 = reinterpret_cast<const uint8_t*>(__tc_mqtt.client_id);`,
+        `    __tc_mqtt.client.client_id.size = static_cast<uint32_t>(strlen(__tc_mqtt.client_id));`,
+        `    __tc_mqtt.client.protocol_version = MQTT_VERSION_3_1_1;`,
+        `    __tc_mqtt.client.clean_session = 1U;`,
+        `    __tc_mqtt.client.keepalive = 60U;`,
+        `    __tc_mqtt.client.rx_buf = __tc_mqtt.rxbuf;`,
+        `    __tc_mqtt.client.rx_buf_size = sizeof(__tc_mqtt.rxbuf);`,
+        `    __tc_mqtt.client.tx_buf = __tc_mqtt.txbuf;`,
+        `    __tc_mqtt.client.tx_buf_size = sizeof(__tc_mqtt.txbuf);`,
+        ``,
+        `    if (__tc_mqtt.tls) {`,
+        `#if defined(CONFIG_MQTT_LIB_TLS)`,
+        `        __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;`,
+        `        tls_cfg->cipher_list = nullptr;`,
+        `        tls_cfg->hostname = __tc_mqtt.host;`,
+        `#else`,
+        `        printk("tc-mqtt: mqtts:// requested but CONFIG_MQTT_LIB_TLS is off\\n");`,
+        `        return;`,
+        `#endif`,
+        `    } else {`,
+        `        __tc_mqtt.client.transport.type = MQTT_TRANSPORT_NON_SECURE;`,
+        `    }`,
+        ``,
+        `    int rc = mqtt_connect(&__tc_mqtt.client);`,
+        `    if (rc != 0) {`,
+        `        printk("tc-mqtt: connect failed (errno %d)\\n", -rc);`,
+        `        (void)mqtt_abort(&__tc_mqtt.client);`,
+        `        return;`,
+        `    }`,
+        `    printk("tc-mqtt: connecting to %s:%u\\n", __tc_mqtt.host,`,
+        `           static_cast<unsigned int>(__tc_mqtt.port));`,
+        `    // Drive input locally until CONNACK arrives (poll thread hasn't started).`,
+        `    // mqtt_connect opened the socket; poll it for the connect-ack. Cap the wait`,
+        `    // so a silent broker doesn't hang setup forever.`,
+        `    for (int32_t i = 0; i < 30 && !__tc_mqtt.connected; i++) {`,
+        `        struct zsock_pollfd fds[1];`,
+        `        fds[0].fd = __tc_mqtt_socket_fd();`,
+        `        fds[0].events = ZSOCK_POLLIN;`,
+        `        fds[0].revents = 0;`,
+        `        int pr = zsock_poll(fds, 1, 1000);`,
+        `        if (pr > 0 && (fds[0].revents & ZSOCK_POLLIN) != 0) {`,
+        `            (void)mqtt_input(&__tc_mqtt.client);`,
+        `        }`,
+        `    }`,
+        `    if (!__tc_mqtt.connected) {`,
+        `        printk("tc-mqtt: connect timed out waiting for CONNACK\\n");`,
+        `        (void)mqtt_abort(&__tc_mqtt.client);`,
+        `        return;`,
+        `    }`,
+        `    // Connected — hand off the socket to the background poll thread.`,
+        `    (void)k_thread_create(&__tc_mqtt.poll_thread, __tc_mqtt_stack,`,
+        `                          K_THREAD_STACK_SIZEOF(__tc_mqtt_stack),`,
+        `                          __tc_mqtt_poll_thread, nullptr, nullptr, nullptr,`,
+        `                          5, 0, K_NO_WAIT);`,
+        `}`,
+        ``,
+        `static inline void __tc_mqtt_set_on_message(__tc_mqtt_msg_cb_t fn) {`,
+        `    __tc_mqtt.on_message = fn;`,
+        `}`,
+        ``,
+        `static inline void __tc_mqtt_subscribe(const char* topic) {`,
+        `    static struct mqtt_topic topics[4];`,
+        `    static uint16_t msg_id = 1;`,
+        `    if (msg_id == 0) msg_id = 1;`,
+        `    topics[0].topic.utf8 = reinterpret_cast<const uint8_t*>(topic);`,
+        `    topics[0].topic.size = static_cast<uint32_t>(strlen(topic));`,
+        `    topics[0].qos = MQTT_QOS_1_AT_LEAST_ONCE;`,
+        `    struct mqtt_subscription_list list;`,
+        `    list.list = topics;`,
+        `    list.list_count = 1U;`,
+        `    list.message_id = msg_id++;`,
+        `    (void)mqtt_subscribe(&__tc_mqtt.client, &list);`,
+        `}`,
+        ``,
+        `static inline void __tc_mqtt_publish(const char* topic, const char* data) {`,
+        `    static uint16_t msg_id = 1;`,
+        `    if (msg_id == 0) msg_id = 1;`,
+        `    struct mqtt_publish_param param;`,
+        `    (void)memset(&param, 0, sizeof(param));`,
+        `    param.message.topic.topic.utf8 = reinterpret_cast<const uint8_t*>(topic);`,
+        `    param.message.topic.topic.size = static_cast<uint32_t>(strlen(topic));`,
+        `    param.message.topic.qos = MQTT_QOS_1_AT_LEAST_ONCE;`,
+        `    param.message.payload.data = reinterpret_cast<uint8_t*>(const_cast<char*>(data));`,
+        `    param.message.payload.len = static_cast<uint32_t>(strlen(data));`,
+        `    param.message_id = msg_id++;`,
+        `    param.dup_flag = 0U;`,
+        `    param.retain_flag = 0U;`,
+        `    (void)mqtt_publish(&__tc_mqtt.client, &param);`,
+        `}`,
+        ``,
+        `static inline bool __tc_mqtt_connected(void) { return __tc_mqtt.connected; }`,
+        ``,
+        `static inline void __tc_mqtt_disconnect(void) {`,
+        `    __tc_mqtt.stop_poll = true;`,
+        `    (void)mqtt_disconnect(&__tc_mqtt.client, nullptr);`,
+        `    __tc_mqtt.connected = false;`,
+        `    // Allow the poll thread to observe stop_poll and exit.`,
+        `    k_msleep(50);`,
+        `}`,
+        `// CUTTLEFISH_MQTT_END`,
+        ``,
+    ];
+}
+/**
+ * Resolve a HAL mqtt.* op to Zephyr C++ via the __tc_mqtt_* shim. Returns
+ * `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ * Throws on an unrecognized mqtt.* op (coverage stays honest — mirrors http.ts).
+ */
+export function lowerMqtt(op) {
+    const o = op;
+    switch (op.operation) {
+        case 'mqtt.connect':
+            return { code: `__tc_mqtt_connect(${s(o.brokerUri)}, ${s(o.clientId)});` };
+        case 'mqtt.on_message':
+            return { code: `__tc_mqtt_set_on_message(${s(o.handler)});` };
+        case 'mqtt.subscribe':
+            return { code: `__tc_mqtt_subscribe(${s(o.topic)});` };
+        case 'mqtt.publish':
+            return { code: `__tc_mqtt_publish(${s(o.topic)}, ${s(o.data)});` };
+        case 'mqtt.connected':
+            return { expression: `(__tc_mqtt.connected)` };
+        case 'mqtt.disconnect':
+            return { code: `__tc_mqtt_disconnect();` };
+        default:
+            throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`.`);
+    }
+}

package/dist/lowering/power.d.ts

@@ -0,0 +1,9 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+/**
+ * Resolve a HAL power.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ */
+export declare function lowerPower(op: HALOpIR): {
+    code?: string;
+    expression?: string;
+};