Functions
int	bento_buddy_request_start (void)
	Bring up the AIROC BLE host stack and NUS advertising on demand; task context only.
void	bento_buddy_request_stop (void)
	Soft stop — drops advertising and the link, keeps the AIROC stack resident; no error signal.
void	bento_buddy_auto_start_install (void)
	Legacy one-shot auto-start task; no caller anywhere — replaced by the chip-power pattern.
int	ipc_bento_buddy_rx_init (void)
	Arm the CM33_NS IPC receiver before the first CM55 tap can arrive; double registration tolerated.

Detailed Description

Five symbols: the on-demand BLE bring-up and soft stop, the legacy auto-start helper, and the CM33–CM55 IPC bridge pair. Compiled only with ENABLE_PAGE_BENTO_BUDDY=1 (default 0, proj_cm33_ns/Makefile:64, :305); rebuild after make getlibs — Flag gate (read first).

Declarations: ble_nus_lazy.h (start/stop/auto_start_install); bento_secure_undeclared.h (ipc_bento_buddy_rx_init — recovered prototype). ipc_bento_buddy_send has no declaration in any shipped header (recorded in bento_secure_undeclared.h); its entry below quotes the archive definition.

Variant: mtb-mpy and mtb-only

ipc_bento_buddy_send

/* No shipped header declares this; archive definition, ipc_bento_buddy_bridge.c:45 */
int ipc_bento_buddy_send(uint8_t cmd, uint16_t value,
                         const uint8_t *data, size_t data_len);

Contract. Writes into a single static shared-memory message (CY_SECTION(".cy_shared_socmem") static ipc_msg_t s_buddy_msg, ipc_bento_buddy_bridge.c:43) — therefore not reentrant; two concurrent callers corrupt each other. data_len is silently clamped to IPC_DATA_MAX_LEN (:55). The retry loop is bounded: 50 iterations of vTaskDelay(pdMS_TO_TICKS(1)) (:61-68), so it may block up to 50 ms and must be called from a FreeRTOS task, never an ISR. Returns 0/-1; every shipped caller (void)-casts it. Convention: pass len + 1 so the receiver gets the NUL, and put the excl-NUL byte count in value. Also reached through the IPC_SEND macro (nus_protocol.c:37, :49-50) — macro-expanded sites are not in the caller counts. Template call sites: 0 (archived: 10).

Origin: Lifted from BENTO-TESAIoT-libraries/claw/common/ble_nus/nus_agent.c:189-204 (compiled into the prebuilt archive; not shipped as source).

Origin: Lifted from BENTO-TESAIoT-libraries/claw/common/ble_nus/ipc_bento_buddy_bridge.c:43-70 (compiled into the prebuilt archive; not shipped as source).

Function Documentation

◆ bento_buddy_request_start()

int bento_buddy_request_start ( void )

Bring up the AIROC BLE host stack and NUS advertising on demand; task context only.

Contract: Brings up the AIROC BLE host stack and NUS advertising on demand. Return: 0 = newly started, 1 = already running, -1 = init failed or mutex timeout (ble_nus_lazy.c:152-156). FreeRTOS task context only — never main() and never an ISR: it takes a mutex with a 1000 ms timeout (ble_nus_lazy.c:161). WL_REG_ON must already be asserted and about 1.5 s of system settle elapsed (main.c:58, :62, :65); the boot-time owner must be the dedicated chip-power task — calling ble_nus_init from any other context fails with state=ERROR (main.c:326-334). On a soft-stopped stack it takes the ble_nus_rearm_advertising() path instead of re-running init (ble_nus_lazy.c:176). It also lazily registers the IPC receiver (ipc_bento_buddy_rx_init(), ble_nus_lazy.c:183-186). Template call sites: 2.

Variant: mtb-mpy and mtb-only

Template call site — boot path: (proj_cm33_ns/main.c:55-73, ships in both zips):
static void chip_power_then_ble_task(void *arg)

{

(void)arg;

vTaskDelay(pdMS_TO_TICKS(1500));

printf("[boot] Asserting WL_REG_ON (P%u.%u) for CYW55513...\r\n",

CYBSP_WIFI_WL_REG_ON_PORT_NUM, (unsigned)CYBSP_WIFI_WL_REG_ON_PIN);

Cy_GPIO_Write(CYBSP_WIFI_WL_REG_ON_PORT, CYBSP_WIFI_WL_REG_ON_PIN, 1U);

/* Murata 2FY datasheet: WL_REG_ON to module-ready ≈ 5 ms. Give 50 ms

* for the HCI controller firmware to finish its internal power-up. */

vTaskDelay(pdMS_TO_TICKS(50));

printf("[boot] WL_REG_ON asserted — bringing up BLE NUS stack\r\n");

extern int bento_buddy_request_start(void);

int rc = bento_buddy_request_start();

printf("[boot] bento_buddy_request_start rc=%d\r\n", rc);

vTaskDelete(NULL);

}

Second template call site (mtb-mpy zip only, cited as text): bento_libs/claw/common/mpy/modbentobuddy.c:29-36, marker tag ble_bento_buddy_start_stop_mpy — the MicroPython binding maps rc < 0 to OSError(EIO) and returns rc (0 or 1) otherwise. Not rendered here because this topic is also part of the mtb-only doc set, which does not carry that file.

◆ bento_buddy_request_stop()

void bento_buddy_request_stop ( void )

Soft stop — drops advertising and the link, keeps the AIROC stack resident; no error signal.

Contract: Void — no error signal at all; a mutex timeout is silently swallowed (ble_nus_lazy.c:231-234). Idempotent, safe when already off. Task context (mutex). It is a soft stop: ble_nus_deinit() drops advertising and the link but the AIROC stack stays resident and s_init_done stays 1 (ble_nus_lazy.c:227-245), so the next bento_buddy_request_start() re-arms advertising rather than re-initialising. Template call sites: 1.

Variant: mtb-mpy and mtb-only

Only template call site (mtb-mpy zip only, cited as text): bento_libs/claw/common/mpy/modbentobuddy.c:39-44, marker tag ble_bento_buddy_start_stop_mpy — mp_bento_buddy_stop() calls it and returns None; there is nothing to check because nothing is returned.

◆ bento_buddy_auto_start_install()

void bento_buddy_auto_start_install ( void )

Legacy one-shot auto-start task; no caller anywhere — replaced by the chip-power pattern.

Contract: Spawns a one-shot task that brings BLE up about 3 s after the scheduler starts; legal from main() before vTaskStartScheduler. No caller anywhere. The shipped boot path explicitly replaced it (proj_cm33_ns/main.c:344-347): "the legacy task skipped the WL_REG_ON / WCM init step, which CYW55513 needs for BLE controller bring-up" — the helper brings the host stack up against an unpowered controller. Use install_chip_power_then_ble() (the pattern shown under bento_buddy_request_start()) instead.

Variant: mtb-mpy and mtb-only

Example (authored — no shipped call site)

static void bento_ex_chip_power_then_ble_task(void *arg)
{
    (void)arg;
    vTaskDelay(pdMS_TO_TICKS(1500));   /* let the rest of boot settle      */
 
    /* Power the CYW55513 first — the step the legacy helper skipped. */
    Cy_GPIO_Write(CYBSP_WIFI_WL_REG_ON_PORT, CYBSP_WIFI_WL_REG_ON_PIN, 1U);
    /* WL_REG_ON to module-ready ≈ 5 ms; give the HCI controller firmware
     * 50 ms to finish its internal power-up. */
    vTaskDelay(pdMS_TO_TICKS(50));
 
    int rc = bento_buddy_request_start();  /* 0 new, 1 running, -1 failed  */
    (void)rc;
 
    vTaskDelete(NULL);                 /* one-shot                          */
}
 
__attribute__((used))
static void bento_ex_bento_buddy_auto_start_install(void)
{
    /* DO NOT: bento_buddy_auto_start_install();
     * (superseded — no WL_REG_ON, controller never powered)
     *
     * DO — install the chip-power-then-BLE one-shot, pre-scheduler: */
    static StackType_t  task_stack[1536];
    static StaticTask_t task_tcb;
    (void)xTaskCreateStatic(bento_ex_chip_power_then_ble_task,
                            "bento_chip_pwr",
                            (uint16_t)(sizeof(task_stack) /
                                       sizeof(task_stack[0])),
                            NULL, tskIDLE_PRIORITY + 1,
                            task_stack, &task_tcb);
}

◆ ipc_bento_buddy_rx_init()

int ipc_bento_buddy_rx_init ( void )

extern

Arm the CM33_NS IPC receiver before the first CM55 tap can arrive; double registration tolerated.

Contract: CM33_NS side. Thin wrapper over Cy_IPC_Pipe_RegisterCallback(CM33_IPC_PIPE_EP_ADDR, ..., CM33_IPC_BENTO_BUDDY_CLIENT_ID); returns 0/-1 (ipc_bento_buddy_bridge.c:166-173). Must run before the first CM55 tap can arrive and after the IPC pipe endpoint exists — the receiver translates the CM55 Start/Stop button into bento_buddy_request_start(), so an unarmed receiver means the tap "falls on deaf ears" (chicken-and-egg comment, mpy_main.c:572-576). It is also lazily self-registered inside bento_buddy_request_start() (ble_nus_lazy.c:183-186, guarded by static bool s_rx_registered), so double registration from the boot path is documented and tolerated. Consumers declare a local extern — no shipped header beyond bento_secure_undeclared.h declares it. Template call sites: 1.

Variant: mtb-mpy and mtb-only

Only template call site (mtb-mpy zip only, cited as text): bento_libs/claw/common/mpy/mpy_main.c:564-583, marker tag ble_ipc_bento_buddy_rx_init_boot — under BENTO_HAS_BLE_NUS == 1, a local extern int ipc_bento_buddy_rx_init(void);, the call, and printf("[MPY] bento_buddy IPC RX init: s\r\n", rc == 0 ? "OK" : "FAIL"). The [MPY] prefix is a live observable (unmuted file).