tan-cli 0.7.0__py3-none-any.whl

tan/templates/vendored/iot/E1M-AEN801/src/cc3501e_bridge.c

@@ -0,0 +1,196 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright 2026 Alp Lab AB
+ *
+ * E1M-AEN SoM CC3501E bridge bring-up helper -- see cc3501e_bridge.h.
+ *
+ * The final reset is warm-aware.  cc3501e_reset() drops WIFI_EN for 50 ms, a
+ * supply cold cycle; on a CC3501E that is already running (an activated unit with
+ * vendor_sbl_container_enable=1 may then never relaunch) that must not happen on a
+ * mere re-run or warm reset of the application.  So when WIFI_EN already reads high
+ * AND the chip answers a PING the bring-up resets through nRESET only
+ * (cc3501e_hard_reset()), and uses cc3501e_reset() only from WIFI_EN low or, as a
+ * last resort, from a chip that stays silent through an nRESET-only reset.  WIFI_EN
+ * reading high alone is not trusted: a pull-up would make every power-on look warm
+ * (whether the module has one is an open question, issue #2797).
+ */
+
+#include "cc3501e_bridge.h"
+
+#include <stdio.h>
+
+#if defined(CONFIG_SOC_AE822FA0E5597LS0_RTSS_HE) || defined(CONFIG_SOC_AE822FA0E5597LS0_RTSS_HP)
+#include <zephyr/arch/cpu.h>
+#include <zephyr/devicetree.h>
+#include <zephyr/sys/sys_io.h>
+/*
+ * AEN LP-pad mux (Alif Ensemble E8, both M55-HE and M55-HP cores).  WIFI_EN
+ * (P15_5) and nRESET (P15_1) are on the Alif LP-GPIO island, bound by the
+ * generic snps,designware-gpio driver which does NOT apply Alif pinctrl --
+ * so the LP pads stay un-muxed and their output drivers OFF (confirmed on
+ * silicon on M55-HE: WIFI_EN never powers the CC3501E until these regs are
+ * set).  0x23 = the Alif GPIO-output pad config (driver + read-enable +
+ * drive strength).  TODO: drop this raw poke once the Alif GPIO backend
+ * muxes the LP island via pinctrl.
+ *
+ * ALIF_LPGPIO_PADCTRL_BASE (0x42007000) is not an M55-HE-local address: the
+ * shared upstream `pin-controller@1a603000` node (ensemble_common.dtsi,
+ * included by both cores' SoC dtsi) declares this exact window as its
+ * second `reg` range, and `alp_e1m_aen801_m55_hp-pinctrl.dtsi` already
+ * muxes a different LP-GPIO pad (P15_0, RTC_ALARM) from the M55-HP pinctrl
+ * driver through it, so the poke below is equally applicable on M55-HP.
+ * Running it on M55-HP is NOT bench-proven -- only running it on M55-HE has
+ * been confirmed on silicon.
+ */
+#define ALIF_LPGPIO_PADCTRL_BASE 0x42007000u
+#define ALIF_PAD_GPIO_OUTPUT     0x23u
+/* Latch WIFI_EN (P15_5) HIGH in the port's data register while the pad is still an
+ * INPUT.  Switching the direction afterwards then drives the already-high level; the
+ * other order (direction first, value second -- what gpio_dw's configure does even
+ * with an init flag) drives whatever DR holds, and with DR bit 5 = 0 that glitches
+ * the supply of a running chip low.  DR is written directly (read-modify-write, the
+ * same access gpio_dw's port_set_bits_raw makes) so this template stays on the
+ * portable <alp/...> headers: SWPORTA_DR is offset 0x00 of the DesignWare GPIO block
+ * (zephyr drivers/gpio/gpio_dw_registers.h), the block base is the `lpgpio` node's
+ * reg, and the LP-GPIO clock is already on because alp_gpio_open() opened the pin. */
+#define DW_GPIO_SWPORTA_DR 0x00u
+static void aen_wifi_en_latch_high(void)
+{
+	const mem_addr_t dr = DT_REG_ADDR(DT_NODELABEL(lpgpio)) + DW_GPIO_SWPORTA_DR;
+
+	sys_write32(sys_read32(dr) | (1u << 5), dr);
+}
+
+static void aen_lp_pads_enable_output(void)
+{
+	sys_write32(ALIF_PAD_GPIO_OUTPUT, ALIF_LPGPIO_PADCTRL_BASE + 5u * 4u); /* P15_5 WIFI_EN */
+	sys_write32(ALIF_PAD_GPIO_OUTPUT, ALIF_LPGPIO_PADCTRL_BASE + 1u * 4u); /* P15_1 nRESET  */
+}
+#else
+static inline void aen_lp_pads_enable_output(void)
+{
+}
+static inline void aen_wifi_en_latch_high(void)
+{
+}
+#endif
+
+alp_status_t cc3501e_bridge_bringup(cc3501e_t *fw)
+{
+	if (fw == NULL) {
+		return ALP_ERR_INVAL;
+	}
+
+	/* 1. Control pins: WIFI_EN (supply gate) + nRESET.  These are Alif LP-GPIO
+	 *    pads, not E1M edge pads -- the SoM owns them. */
+	alp_gpio_t *wifi_en = alp_gpio_open(CC3501E_BRIDGE_PIN_WIFI_EN);
+	alp_gpio_t *nrst    = alp_gpio_open(CC3501E_BRIDGE_PIN_NRST);
+	if (wifi_en == NULL || nrst == NULL) {
+		if (wifi_en != NULL) {
+			alp_gpio_close(wifi_en);
+		}
+		if (nrst != NULL) {
+			alp_gpio_close(nrst);
+		}
+		return ALP_ERR_NOT_PRESENT_ON_THIS_SOC;
+	}
+	aen_lp_pads_enable_output();
+	/* Sample the supply gate BEFORE touching its direction.  High is only a HINT
+	 * that the chip may be powered -- an external pull-up on WIFI_EN would make every
+	 * power-on read high (whether the module has one is an OPEN QUESTION; the
+	 * netlist has not been checked), so the decision below also needs a PING. */
+	bool wifi_was_high = false;
+	/* A failed read leaves the level unknown: never take the supply-cycling cold path
+	 * on that alone -- go through the PING path below, which still ends in
+	 * cc3501e_reset() if the chip turns out to be silent. */
+	const bool wifi_unknown = alp_gpio_read(wifi_en, &wifi_was_high) != ALP_OK;
+	if (wifi_was_high) {
+		/* Latch the level in DR first so the direction change cannot glitch it low. */
+		aen_wifi_en_latch_high();
+	}
+	(void)alp_gpio_configure(wifi_en, ALP_GPIO_OUTPUT, ALP_GPIO_PULL_NONE);
+	(void)alp_gpio_configure(nrst, ALP_GPIO_OUTPUT, ALP_GPIO_PULL_NONE);
+
+	/* 2. Inter-chip SPI (Alif = master).  CS is the dwc-ssi hardware SS0
+	 *    muxed on P14_7; the app passes ALP_SPI_NO_CS so no software GPIO CS
+	 *    is installed and the SPI controller drives SS0 per transfer.  Mode 0
+	 *    matches the CC3501E vendor image frameFormat. */
+	alp_spi_t *spi = alp_spi_open(&(alp_spi_config_t){
+	    .bus_id        = CC3501E_BRIDGE_SPI_BUS_ID,
+	    .freq_hz       = CC3501E_BRIDGE_SPI_FREQ_HZ,
+	    .mode          = ALP_SPI_MODE_0,
+	    .bits_per_word = 8u,
+	    .cs_pin_id     = ALP_SPI_NO_CS,
+	});
+	if (spi == NULL) {
+		alp_gpio_close(wifi_en);
+		alp_gpio_close(nrst);
+		return ALP_ERR_NOT_PRESENT_ON_THIS_SOC;
+	}
+
+#if CC3501E_BRIDGE_RX_SAMPLE_DLY > 0
+	/* Raise the SCLK past 1 MHz: the DW SSI RX_SAMPLE_DLY register (0xf0) delays
+	 * the MISO capture point by N ssi_clk cycles to cover the on-SoM trace + crossed
+	 * data round-trip.  Zephyr spi_dw never writes it (leaves 0), so without this
+	 * >1 MHz mis-samples MISO (cold reqhdr_rx=0xFFFFFFFF).  Written with SSI disabled
+	 * (SSIENR=0); persists across the driver's per-transfer configure.  Value is
+	 * silicon-tuned -- sweep CC3501E_BRIDGE_RX_SAMPLE_DLY at the target SCLK.
+	 *
+	 * SWEEP TRAP -- read before setting the constant to 0: the `#if > 0` above
+	 * compiles this block out, so 0 does not mean "no delay", it means the SPI
+	 * node's `rx-delay` devicetree value is left in place.  aen-cc3501e-bringup
+	 * and aen-evk-demo declare rx-delay = <2>, so a naive N=0 sweep point on
+	 * those two silently measures 2.  Read 0x481040F0 back to see what the link
+	 * is actually running at. */
+	{
+		volatile uint32_t *ssienr =
+		    (volatile uint32_t *)(uintptr_t)(CC3501E_BRIDGE_SPI1_BASE + 0x08u);
+		volatile uint32_t *rsd = (volatile uint32_t *)(uintptr_t)(CC3501E_BRIDGE_SPI1_BASE + 0xf0u);
+		uint32_t           en  = *ssienr;
+		*ssienr                = 0u;
+		*rsd                   = (uint32_t)CC3501E_BRIDGE_RX_SAMPLE_DLY;
+		*ssienr                = en;
+	}
+#endif
+
+	/* 3. Bind the bus + control pins; attach the GPIO proxy (proxied E1M IOs then
+	 *    route over the bridge); run the power + reset sequence (TI SWRU626 + the
+	 *    Puya cold-boot hard-reset workaround).  Leaves WIFI_EN HIGH. */
+	(void)cc3501e_init(fw, spi);
+	fw->enable_pin = wifi_en;
+	fw->reset_pin  = nrst;
+	/* READY (CC35 GPIO17) is NOT wired here by default on this R2 module --
+	 * see chips/cc3501e/cc3501e_core.c's cc3501e_reply_gate() comment for the
+	 * pin-routing fact, the bench evidence, and how a board that genuinely
+	 * wires it can opt back in via fw->ready_pin. */
+#ifdef CONFIG_ALP_SDK_GPIO_CC3501E_PROXY
+	(void)alp_gpio_cc3501e_attach(fw);
+#endif
+#ifdef CONFIG_ALP_SDK_WIFI_CC3501E
+	(void)alp_wifi_cc3501e_attach(fw);
+#endif
+#ifdef CONFIG_ALP_SDK_BLE_CC3501E
+	(void)alp_ble_cc3501e_attach(fw);
+#endif
+	/* One line naming the path taken, so a log shows whether the supply was cycled. */
+	if (!wifi_was_high && !wifi_unknown) {
+		printf("[cc3501e_bridge] WIFI_EN low: cold power-up (cc3501e_reset)\n");
+		return cc3501e_reset(fw); /* supply low: the full cold-boot sequence */
+	}
+	/* WIFI_EN reads high.  Warm = the chip ANSWERS a PING; a pull-up alone proves
+	 * nothing.  Warm: nRESET only, never a WIFI_EN toggle. */
+	if (cc3501e_ping(fw) == ALP_OK) {
+		printf("[cc3501e_bridge] WIFI_EN high, PING ok: warm, nRESET only\n");
+		return cc3501e_hard_reset(fw);
+	}
+	/* High but silent: powered-and-hung, or unpowered behind a pull-up.  Try the
+	 * nRESET-only reset first (safe for a powered chip); only if the chip still does
+	 * not answer is the supply cycled -- the last resort, taken from a chip that is
+	 * already unresponsive. */
+	if (cc3501e_hard_reset(fw) == ALP_OK && cc3501e_ping(fw) == ALP_OK) {
+		printf("[cc3501e_bridge] WIFI_EN high, silent: recovered by nRESET only\n");
+		return ALP_OK;
+	}
+	printf("[cc3501e_bridge] WIFI_EN high, silent after nRESET: supply cycle (cc3501e_reset)\n");
+	return cc3501e_reset(fw);
+}

tan/templates/vendored/iot/E1M-AEN801/src/cc3501e_bridge.h

@@ -0,0 +1,173 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ * Copyright 2026 Alp Lab AB
+ *
+ * One-call bring-up of the E1M-AEN SoM's CC3501E Wi-Fi 6 / BLE coprocessor over the
+ * inter-chip SPI bridge -- the SoM bring-up TEMPLATE for applications.
+ *
+ * The CC3501E is part of the SoM (module U4 = BDE-BW35N): the application does NOT
+ * touch the raw SPI bus or the WIFI_EN / nRESET control pins.  It calls
+ * cc3501e_bridge_bringup() once, gets a ready @ref cc3501e_t, and from there uses the
+ * portable surfaces:
+ *   - cc3501e_* (chips/cc3501e)            -- MAC / Wi-Fi / BLE / GPIO-proxy / OTA
+ *   - alp_gpio_open(ALP_E1M_GPIO_IOxx)         -- proxied E1M IOs (when the proxy is built)
+ *
+ * To reuse in your own AEN application: copy this pair (cc3501e_bridge.{c,h}) into your
+ * app, or call cc3501e_bridge_bringup() directly.  The bus / pins / clock are the
+ * E1M-AEN SoM defaults below; a board variant overrides only those macros -- the SoM
+ * stays swappable without touching application code.
+ */
+
+#ifndef CC3501E_BRIDGE_H
+#define CC3501E_BRIDGE_H
+
+#include <alp/peripheral.h>    /* alp_status_t */
+#include <alp/chips/cc3501e.h> /* cc3501e_t */
+
+/* ---- E1M-AEN SoM bridge defaults (override per board variant) ---------------- */
+
+/* Inter-chip SPI: Alif = master, CC3501E = slave.  P14_7 is muxed as the
+ * dwc-ssi hardware SS0 chip-select; ALP_SPI_NO_CS means "no software GPIO CS"
+ * here, so the controller frames each protocol phase.  Mode 0 matches the
+ * CC3501E vendor image frameFormat. */
+#ifndef CC3501E_BRIDGE_SPI_BUS_ID
+#define CC3501E_BRIDGE_SPI_BUS_ID 1u
+#endif
+#ifndef CC3501E_BRIDGE_SPI_FREQ_HZ
+/* 25 MHz = 200 MHz SSI functional clock / 8.
+ *
+ * The CC3501E peripheral-mode maximum is 30 MHz, NOT the 15 MHz this comment
+ * claimed for most of the bring-up: datasheet SWRS343A section 6.14.2.3.3,
+ * `fsclk SPI clock frequency, Peripheral Mode, MAX 30 MHz` (Controller Mode is
+ * 40 MHz).  Every earlier ceiling argument here was built on the wrong number.
+ *
+ * 25 MHz is the fastest LEGAL step available: the DW SSI BAUDR divisor must be
+ * EVEN, so from 200 MHz the neighbours are /8 = 25 MHz and /6 = 33.3 MHz, and
+ * 33.3 is 11% over the part's maximum.  Reaching exactly 30 MHz would require
+ * retargeting the SSI functional clock itself (AE822 HWRM section 8.3.5) --
+ * ALIF_SPI_CLK is a frequency-only dummy in the dtsi with no divider control,
+ * so there is no software knob for it here.
+ *
+ * REQUIRES an RX sample delay: at a 40 ns bit period the MISO capture does not
+ * land on its own.  That delay comes from CC3501E_BRIDGE_RX_SAMPLE_DLY below --
+ * NOT from the SPI node's `rx-delay` property, which the poke in
+ * cc3501e_bridge.c overwrites.  The measured working span is in that constant's
+ * comment.
+ *
+ * It does not raise throughput -- silicon-measured
+ * 2026-08-24: 682 kB/s at 25 MHz vs 678 kB/s at 14.29 MHz on PIO, 704 vs 701 on
+ * DMA, because wire time is only ~554 us of a ~2459 us transaction and the rest
+ * is per-frame protocol cost on both ends.  It is worth taking anyway: each
+ * transfer occupies the bus for ~44% less time, which is CPU and bus budget
+ * handed back to everything else on the SoM.
+ *
+ * The 14.29 MHz predecessor was scope-confirmed at 14.20-14.26 MHz, which is
+ * what validates the 200 MHz functional-clock figure the divider assumes.  A
+ * board with longer traces should re-check MISO capture before adopting 25 MHz.
+ *
+ * SEPARATE, PRE-EXISTING DEFECT (do not blame this clock for it): a bulk read
+ * intermittently desyncs partway through -- roughly 1 run in 2-3, at anywhere
+ * from 61 kB to 212 kB in -- and then never recovers for the caller's whole
+ * retry budget.  It reproduces at 14.29 MHz TOO, so it is not a clock artifact.
+ * Signature (host-side, request-header phase of CMD_SOCK_RECV 0x23): the
+ * slave's in-band idle marker reads [02 00 00 00] once and then [00 00 00 00]
+ * forever instead of A5 A5 A5 A5 -- i.e. the slave is stuck mid-reply on a
+ * transfer it armed earlier and never completed.  With
+ * SPI_TRANSFER_RETURN_PARTIAL deliberately off, a CS deassert does not complete
+ * it, and NEITHER slave self-heal fires (g_resync_count does not move -- the
+ * slave is not misframing; g_arm_fail_count does not move -- the arm succeeded).
+ * Clocking a full idle frame from the host to satisfy the outstanding count was
+ * tried and did NOT recover it.  The fix likely belongs on the slave: a
+ * stall watchdog that calls bridge_transport_spi_hw_reinit() when an armed
+ * transfer has not completed for N ms. */
+#define CC3501E_BRIDGE_SPI_FREQ_HZ 25000000u
+#endif
+
+/* CC3501E control pins on the Alif LP-GPIO island (NOT E1M edge pads):
+ * WIFI_EN = supply gate (P15_5), nRESET = reset (P15_1_FLEX). */
+#ifndef CC3501E_BRIDGE_PIN_WIFI_EN
+#define CC3501E_BRIDGE_PIN_WIFI_EN 0u
+#endif
+#ifndef CC3501E_BRIDGE_PIN_NRST
+#define CC3501E_BRIDGE_PIN_NRST 1u
+#endif
+/* OPTIONAL host-IRQ/READY input.  ready_pin has no fixed index or macro
+ * here on purpose: on a board where the CC3501E's GPIO17 READY net is
+ * actually routed to the host, set fw->ready_pin (in
+ * cc3501e_bridge_bringup() below) to whatever Alif pin that board wires it
+ * to.  When set, cc3501e_reply_gate() (chips/cc3501e/cc3501e_core.c) can
+ * only ever ADD delay to a reply phase, never remove it, so opting in on a
+ * board where the wiring is wrong costs up to 3 x 250 ms of busy-wait per
+ * latch cycle before the driver's own (recoverable) stuck-LOW latch gives up
+ * on it -- longer thresholds apply after each re-latch if the line flaps
+ * instead of staying cleanly stuck (chips/cc3501e/cc3501e_core.c's
+ * g_ready_stuck_low_threshold) -- it is always safe to try FOR LINK TIMING.
+ * It is not free, though: this
+ * wait runs while cc3501e_request() holds its internal transport lock, so
+ * a wrong or slow ready_pin can make another caller on the same ctx see
+ * ALP_ERR_BUSY after CONFIG_ALP_SDK_CC3501E_REQUEST_LOCK_TIMEOUT_MS -- see
+ * <alp/chips/cc3501e/core.h>'s ready_pin doc.
+ *
+ * NOT Alif P2_6 on an R2 AEN EVK bench module: P2_6 there is E1M pad AH7 /
+ * I2S1_SCLK (the EVK's Arduino CK_RST, metadata/boards/e1m-evk.yaml), and
+ * the CC3501E GPIO17 READY net lands on E1M pad G3 / IO16 instead
+ * (metadata/e1m_modules/aen/from-cc3501e.tsv).  cc3501e_bridge_bringup()
+ * below leaves ready_pin NULL by default on that module -- see
+ * cc3501e_reply_gate()'s own doc comment for the bench evidence. */
+
+/* DW SSI SPI1 base (0x48104000) + RX_SAMPLE_DLY to run the bridge SCLK above
+ * 1 MHz.  spi_dw_configure never writes RX_SAMPLE_DLY (0xf0), so without the
+ * poke in cc3501e_bridge.c the master samples MISO at the SCLK edge, before the
+ * on-SoM trace + crossed-data round-trip returns the CC35's bit, and anything
+ * above 1 MHz mis-samples.  Setting it delays the capture by N ssi_clk
+ * (200 MHz) cycles -- 5 ns per step.
+ *
+ * 4 is silicon-measured at the 25 MHz working point (40 ns bit period) on
+ * E1M-AEN803 serial 2026W36-0002.  N was swept 0..10 with 0x481040F0 read back
+ * each time to confirm the value took, using aen-evk-demo phase 8 as the
+ * workload:
+ *
+ *   N = 0..7   PASS, 2-3 runs each: bring-up 0, PING on attempt 1 of 25,
+ *              byte-exact MAC, scan 0, BLE 0.
+ *   N = 8      FAIL, 3 runs of 3: bring-up still returns 0, but the link never
+ *              answers -- PING -> -5 after all 25 attempts.
+ *   N = 9      PASS, 2 runs of 2.
+ *   N = 10     PASS, 3 runs of 3, but one run returned a MAC with a single bit
+ *              flipped in byte 0.
+ *
+ * 4 is the centre of the measured-good 0..7 span: +4 steps (20 ns, half a bit
+ * period) below the failure, and the low side is not a cliff at all since 0
+ * itself is clean.  Do NOT read 8/9/10 as a monotone upper boundary -- 8
+ * hard-fails while 9 and 10 pass, which this sweep did not explain.  Treat
+ * everything above 7 as unqualified, not as graded margin.
+ *
+ * The "4..8 all clean cold+warm" window this comment used to claim was taken on
+ * an earlier bench run at ~14.3 MHz -- a different board at roughly half the clock,
+ * so it is not comparable and is not evidence for 25 MHz on this one.
+ *
+ * 0 does NOT mean "no delay": it compiles the poke out, leaving whatever the
+ * SPI node's `rx-delay` property put there (see cc3501e_bridge.c).  Re-sweep if
+ * the SoM trace lengths or the SCLK change. */
+#ifndef CC3501E_BRIDGE_SPI1_BASE
+#define CC3501E_BRIDGE_SPI1_BASE 0x48104000u
+#endif
+#ifndef CC3501E_BRIDGE_RX_SAMPLE_DLY
+#define CC3501E_BRIDGE_RX_SAMPLE_DLY 4u
+#endif
+
+/**
+ * @brief Bring up the SoM's CC3501E coprocessor over the inter-chip bridge.
+ *
+ * Opens the hardware-SS0 bridge SPI + the WIFI_EN / nRESET control pins, binds
+ * them to @p fw, attaches the GPIO proxy (when CONFIG_ALP_SDK_GPIO_CC3501E_PROXY is
+ * built), and runs the power + reset sequence (TI SWRU626 + the Puya cold-boot
+ * hard-reset workaround).  Blocks ~900 ms for the boot budget; leaves WIFI_EN HIGH.
+ *
+ * @param fw  Caller-owned handle, populated on success.  Use it with cc3501e_*.
+ * @return ALP_OK with @p fw ready; ALP_ERR_NOT_PRESENT_ON_THIS_SOC if the SPI bus /
+ *         control pins are absent (check the board overlay); otherwise the reset
+ *         sequence status.  On any failure @p fw is left un-bound (do not use it).
+ */
+alp_status_t cc3501e_bridge_bringup(cc3501e_t *fw);
+
+#endif /* CC3501E_BRIDGE_H */

tan/templates/vendored/iot/E1M-AEN801/src/main.c

@@ -0,0 +1,262 @@
+/*
+ * Copyright 2026 Alp Lab AB
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * mqtt-telemetry -- publish a sensor reading over MQTT/TLS.
+ *
+ * The "connected device" starting point.  It shows the whole
+ * telemetry path a field device runs, all on the portable
+ * <alp/iot.h> surface:
+ *
+ *   1. Bring the Wi-Fi station up + associate.   (alp_wifi_*)
+ *   2. Open an mqtts:// (TLS) MQTT client.        (alp_mqtt_open)
+ *   3. Connect to the broker.                     (alp_mqtt_connect)
+ *   4. Publish a telemetry reading on a cadence.  (alp_mqtt_publish)
+ *   5. Disconnect cleanly.                        (alp_mqtt_close)
+ *
+ * Transport (E1M-AEN801): the CC3501E Wi-Fi6+BLE coprocessor bridge
+ * (https://github.com/alplabai/alp-sdk/blob/v0.17.0/docs/cc3501e-bridge.md), selected automatically by the AEN board
+ * emit from `iot.wifi: true` -- the app never names it, it just
+ * calls <alp/iot.h>.  The bridge is silicon-validated (2026-06-24);
+ * this is a real transport, not a stub.
+ *
+ * Bridge bring-up (#2112): alp_wifi_open() only resolves to the CC3501E
+ * backend once an application has attached a live bridge handle --
+ * cc3501e_bridge_bringup() (src/cc3501e_bridge.c, the same copyable
+ * template every https://github.com/alplabai/alp-sdk/tree/v0.17.0/examples/aen/aen-cc3501e-* app uses) does exactly that
+ * before this app calls alp_wifi_open() below.  On native_sim the bring-up
+ * fails fast (ALP_ERR_NOT_PRESENT_ON_THIS_SOC -- no SPI/GPIO backend
+ * matches that SoC ref) and this app falls through to the same
+ * NULL-with-NOT_READY framing path as before.
+ *
+ * The "sensor reading": to keep the focus on the transport, this
+ * template publishes a synthetic metric (device uptime).  Swap
+ * read_telemetry_value() for a real sensor read -- e.g. compose it
+ * with the `sensor` template (https://github.com/alplabai/alp-sdk/tree/v0.17.0/examples/peripheral-io/i2c-master,
+ * TMP112 over <alp/chips/tmp112.h>) -- and the publish path here is
+ * unchanged.
+ *
+ * TLS status (preview): the mqtts:// path is configured through the
+ * portable API (broker URI + pinned CA), but CONFIG_MBEDTLS is held
+ * OFF in the build today -- Zephyr v4.4's mbedtls 3.6 has an
+ * ssl_misc.h include-order bug; full tf-psa-crypto wiring is a v0.6
+ * work item (see prj.conf / native_sim.conf).  Real AEN silicon
+ * uses the TF-M stack.  This is why the catalog record is `preview`.
+ *
+ * What runs under native_sim (CI lane): there is no radio and no
+ * MQTT-capable net stack, so alp_wifi_open()/alp_mqtt_open() return
+ * NULL -- ALP_ERR_NOT_READY when a backend registered but its device
+ * isn't up, or ALP_ERR_NOSUPPORT when no backend is linked at all;
+ * both are the documented <alp/iot.h> NULL contract.  The app
+ * detects that, prints the telemetry payloads it WOULD publish (so
+ * the framing is CI-observable), and exits on the `[mqtt] done`
+ * marker.
+ *
+ * What runs on AEN HiL: real association through the CC3501E, real
+ * MQTT publish to the broker; the same source, no #ifdef in the
+ * telemetry logic.
+ */
+
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+
+#include "alp/iot.h"
+#include "cc3501e_bridge.h" /* cc3501e_bridge_bringup() -- the SoM bring-up template, #2112 */
+
+/* Broker + topic identity.  In a real fleet these come from the
+ * device's provisioning step; hardcoded here as documentation.
+ * mqtts:// selects the TLS path (see the TLS config below). */
+#define MQTT_BROKER_URI "mqtts://broker.example.alplab.ai:8883"
+#define MQTT_CLIENT_ID  "e1m-aen801-demo"
+#define MQTT_TOPIC      "alp/telemetry/e1m-aen801"
+
+/* Pin the broker's CA bundle.  NULL would fall back to the OS
+ * default trust store; a real deployment should pin a known-good
+ * CA, so we name the path a customer would provision. */
+#define MQTT_CA_FILE "/etc/ssl/certs/alp-broker-ca.pem"
+
+/* Wi-Fi credentials.  On real silicon these come from the EEPROM
+ * factory manifest or a provisioning blob so one binary serves a
+ * whole fleet; hardcoded for the demo. */
+#define WIFI_SSID "alp-demo-ap"
+#define WIFI_PSK  "changeme-in-provisioning"
+
+/* Publish a bounded number of readings so the native_sim run
+ * terminates and the twister harness latches.  Real firmware would
+ * publish forever on a timer. */
+#define PUBLISH_COUNT    3u
+#define PUBLISH_PERIOD_S 5u
+
+/* Handshake budgets.
+ *
+ * WIFI_CONNECT_TIMEOUT_MS: on E1M-AEN801 with the CC3501E bridge attached,
+ * alp_wifi_connect() routes to the CC3501E backend
+ * (src/backends/wifi/cc3501e.c), and the bridge's own worst case for one STA
+ * connect is 10s Wlan_RoleUp + 30s L2 association + a 30s DHCP-lease poll
+ * (hal/ti/cc3501e_hw_ti_wifi.c) = 70s. On other Wi-Fi backends this value is
+ * only an upper bound, not a derived worst case. */
+#define WIFI_CONNECT_TIMEOUT_MS 75000u
+#define MQTT_CONNECT_TIMEOUT_MS 10000u
+
+/* Read one telemetry value.
+ *
+ * PLACEHOLDER: returns a synthetic uptime-seconds counter so the
+ * template stays chip-free and focused on the transport.  On real
+ * hardware, replace the body with a sensor read -- e.g. a TMP112
+ * temperature via <alp/chips/tmp112.h> (see the `sensor` template)
+ * -- and return that value.  The publish path below does not change. */
+static uint32_t read_telemetry_value(uint32_t sample_index)
+{
+	/* Synthetic: seconds of "uptime" at this sample's cadence.
+	 * Deterministic so the native_sim framing output is stable. */
+	return sample_index * PUBLISH_PERIOD_S;
+}
+
+/* Format a telemetry sample as a compact JSON payload.  Returns the
+ * byte length written (excluding the NUL), or 0 on truncation. */
+static size_t build_payload(char *buf, size_t cap, uint32_t value)
+{
+	int n = snprintf(buf,
+	                 cap,
+	                 "{\"device\":\"%s\",\"metric\":\"uptime_s\",\"value\":%u}",
+	                 MQTT_CLIENT_ID,
+	                 value);
+	if (n < 0 || (size_t)n >= cap) {
+		return 0u; /* truncated -- caller skips the publish */
+	}
+	return (size_t)n;
+}
+
+/* Bring the Wi-Fi station up + associate.  Returns an open handle
+ * on success, or NULL (with the reason logged) when there is no
+ * Wi-Fi backend on this build -- the native_sim / sw_fallback path. */
+static alp_wifi_t *telemetry_wifi_up(void)
+{
+	/* STATIC, not a local -- cc3501e_t embeds several
+	 * ALP_CC3501E_MAX_PAYLOAD scratch buffers; see cc3501e_bridge.h. */
+	static cc3501e_t bridge = { 0 };
+
+	printf("[mqtt] wifi: bridge bring-up\n");
+	alp_status_t bridge_rc = cc3501e_bridge_bringup(&bridge);
+	printf("[mqtt] wifi: cc3501e_bridge_bringup -> %s\n", alp_status_name(bridge_rc));
+
+	printf("[mqtt] wifi: opening station\n");
+	alp_wifi_t *w = alp_wifi_open();
+	if (w == NULL) {
+		/* NOT_READY on native_sim (a Wi-Fi backend registered but no
+		 * device is up) or NOSUPPORT when no Wi-Fi backend is linked;
+		 * on HiL, NOT_READY before the CC3501E bridge has probed. */
+		printf("[mqtt] wifi: alp_wifi_open -> NULL (%s)\n", alp_status_name(alp_last_error()));
+		return NULL;
+	}
+	const alp_wifi_credentials_t creds = {
+		.ssid = WIFI_SSID,
+		.psk  = WIFI_PSK,
+	};
+	alp_status_t s = alp_wifi_connect(w, &creds, WIFI_CONNECT_TIMEOUT_MS);
+	if (s != ALP_OK) {
+		printf("[mqtt] wifi: connect -> %s\n", alp_status_name(s));
+		alp_wifi_close(w);
+		return NULL;
+	}
+	printf("[mqtt] wifi: associated to \"%s\"\n", WIFI_SSID);
+	return w;
+}
+
+/* Open + connect the TLS MQTT client.  Returns an open handle, or
+ * NULL when there is no MQTT backend on this build. */
+static alp_mqtt_t *telemetry_mqtt_up(void)
+{
+	printf("[mqtt] broker: opening %s (TLS, CA pinned)\n", MQTT_BROKER_URI);
+
+	/* Pin the broker CA for the mqtts:// handshake.  insecure
+	 * stays false -- a starter must not teach cert-skipping. */
+	static const alp_mqtt_tls_config_t tls = {
+		.ca_file  = MQTT_CA_FILE,
+		.insecure = false,
+	};
+	alp_mqtt_config_t cfg = ALP_MQTT_CONFIG_DEFAULT(MQTT_BROKER_URI);
+	cfg.client_id         = MQTT_CLIENT_ID;
+	cfg.tls               = &tls;
+
+	alp_mqtt_t *m = alp_mqtt_open(&cfg);
+	if (m == NULL) {
+		printf("[mqtt] broker: alp_mqtt_open -> NULL (%s)\n", alp_status_name(alp_last_error()));
+		return NULL;
+	}
+	alp_status_t s = alp_mqtt_connect(m, MQTT_CONNECT_TIMEOUT_MS);
+	if (s != ALP_OK) {
+		printf("[mqtt] broker: connect -> %s\n", alp_status_name(s));
+		alp_mqtt_close(m);
+		return NULL;
+	}
+	printf("[mqtt] broker: connected\n");
+	return m;
+}
+
+/* Publish PUBLISH_COUNT readings on the live client. */
+static void telemetry_publish_loop(alp_mqtt_t *m)
+{
+	for (uint32_t i = 0; i < PUBLISH_COUNT; i++) {
+		char   payload[96];
+		size_t len = build_payload(payload, sizeof(payload), read_telemetry_value(i));
+		if (len == 0u) {
+			printf("[mqtt] publish %u: payload truncated -- skipped\n", i);
+			continue;
+		}
+		alp_status_t s =
+		    alp_mqtt_publish(m, MQTT_TOPIC, (const uint8_t *)payload, len, ALP_MQTT_QOS_1, false);
+		printf("[mqtt] publish %u -> %s: %s\n", i, alp_status_name(s), payload);
+
+		/* Pace the publishes -- a real telemetry device sends on a
+		 * timer, not in a tight loop.  alp_delay_ms is portable
+		 * (<alp/peripheral.h>, reached via <alp/iot.h>). */
+		if (i + 1u < PUBLISH_COUNT) {
+			alp_delay_ms(PUBLISH_PERIOD_S * 1000u);
+		}
+	}
+}
+
+/* native_sim / no-backend path: there's no live client, but print
+ * the payloads the app WOULD publish so the framing is observable
+ * in CI (and so a customer sees the message shape without a broker). */
+static void telemetry_print_framing(void)
+{
+	printf("[mqtt] no transport on this build -- printing framing only\n");
+	for (uint32_t i = 0; i < PUBLISH_COUNT; i++) {
+		char   payload[96];
+		size_t len = build_payload(payload, sizeof(payload), read_telemetry_value(i));
+		if (len == 0u) {
+			continue;
+		}
+		printf("[mqtt] would publish to %s: %s\n", MQTT_TOPIC, payload);
+	}
+}
+
+int main(void)
+{
+	/* Bring up the SDK runtime before anything else. */
+	(void)alp_init();
+
+	printf("[mqtt] alp-sdk mqtt-telemetry demo (publish over MQTT/TLS)\n");
+	printf("[mqtt] transport: CC3501E Wi-Fi bridge (E1M-AEN801)\n");
+
+	alp_wifi_t *w = telemetry_wifi_up();
+	if (w != NULL) {
+		alp_mqtt_t *m = telemetry_mqtt_up();
+		if (m != NULL) {
+			telemetry_publish_loop(m);
+			alp_mqtt_close(m);
+		}
+		alp_wifi_disconnect(w);
+		alp_wifi_close(w);
+	} else {
+		/* No Wi-Fi backend (native_sim): show the framing so the
+		 * run is still meaningful + the harness has a marker. */
+		telemetry_print_framing();
+	}
+
+	printf("[mqtt] done\n");
+	return 0;
+}