Events & acks

Functions
int	nus_emit_event (const char *json)
	Send one JSON event frame (no trailing newline — the LF is appended); 0/-1 only.
void	nus_events_push_pending_ack (const char *id)
	Push a notification id onto the pending-ack FIFO; dedups, evicts oldest when full.
bool	nus_events_drain_pending_ack (const char *id)
	Remove an id from the FIFO; true if found — the CM55 tap's bento.user.ack path.
size_t	nus_events_pending_ack_count (void)
	Number of ids in the FIFO; telemetry and host unit tests. No caller anywhere.
void	nus_commands_emit_ack (const char *ack_cmd, size_t ack_cmd_len, const char *ok_true_or_null, const char *error_or_null, int n)
	Emit a command ack (verb hard-truncated at 32 chars); void — a send failure is invisible.
void	nus_commands_dispatch (const char *json, size_t json_len, const jsmntok_t *toks, int n_toks, const jsmntok_t *t_cmd)
	Route a top-level "cmd" frame to its handler; internal to the RX path.
void	nus_commands_handle_time_sync (const char *json, const jsmntok_t *toks, int n)
	Handle the one-shot {"time":[epoch,tz]} frame; no ack is emitted.

Detailed Description

Seven functions: nus_emit_event, the pending-ack FIFO, and the nus_commands_* dispatch. 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: nus_events.h (nus_emit_event, pending-ack FIFO) and nus_commands.h (nus_commands_*). nus_commands.h includes vendor/jsmn.h, which the dist include set does not carry (Header packaging note); the jsmntok_t parameters are described without relying on it. Implementation nus_events.c / nus_commands.c is archived in libbento_secure.a.

Variant

mtb-mpy and mtb-only

Function Documentation

nus_emit_event()

int nus_emit_event

(

const char *

json

)

Send one JSON event frame (no trailing newline — the LF is appended); 0/-1 only.

Contract

Pass a NUL-terminated JSON object with no trailing newline — the function appends the LF itself (nus_events.c:54). Payload must satisfy strlen(json) + 2 <= 256, else it returns -1 and drops rather than truncating. Returns 0/-1 only; -1 collapses oversized, NULL, and link-down (it delegates to ble_nus_send(), so a connected link with notifications enabled is required). Consumers in the mpy tree declare a local extern — nus_events.h is the only public declaration. Template call sites: 3.

Variant

mtb-mpy and mtb-only

Best template call site (mtb-mpy zip only, cited as text)

bento_libs/claw/common/mpy/mod_dualband.c:196-213 (local extern at :44-46), marker tag ble_nus_emit_event_contract — builds a bento.net.down object with snprintf into a 128-byte buffer, raises OSError("payload too large") if len <= 0 || len >= sizeof(json), then raises OSError("nus_emit_event failed (d)") on a non-zero return. Not rendered here because this topic is also part of the mtb-only doc set, which does not carry that file.

Archived exemplar

The radio-state emitter shows the same bounds-check-then-emit discipline with the (void) return convention:

Origin

Lifted from BENTO-TESAIoT-libraries/claw/common/ble_nus/nus_commands.c:1443-1469 (compiled into the prebuilt archive; not shipped as source).

nus_events_push_pending_ack()

void nus_events_push_pending_ack

(

const char *

id

)

Push a notification id onto the pending-ack FIFO; dedups, evicts oldest when full.

Contract

Pushes a notification id onto the pending-ack FIFO when a bento.notify.show with ack_required=true lands. Dedups; evicts the oldest when full. Runs on the NUS RX dispatch task. Template call sites: 0; archived call site nus_commands.c:326 (nus_events_push_pending_ack(slot->id); — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

nus_events_drain_pending_ack()

bool nus_events_drain_pending_ack

(

const char *

id

)

Remove an id from the FIFO; true if found — the CM55 tap's bento.user.ack path.

Contract

Removes an id from the FIFO; true if found and removed, false otherwise. Called when a CM55 LCD tap comes back as a bento.user.ack through the IPC bridge; the shipped caller (void)-casts the result. Template call sites: 0; archived call site ipc_bento_buddy_bridge.c:122 ((void)nus_events_drain_pending_ack(id); — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

nus_events_pending_ack_count()

size_t nus_events_pending_ack_count

(

void

)

Number of ids in the FIFO; telemetry and host unit tests. No caller anywhere.

Contract

Number of ids in the FIFO; telemetry and host unit tests. Bounded by the FIFO size (dedup + oldest eviction). No caller anywhere.

Variant

mtb-mpy and mtb-only

Example (authored — no shipped call site)

__attribute__((used))
static void bento_ex_nus_events_pending_ack_count(void)
{
    size_t pending = nus_events_pending_ack_count();
    if (pending > 0u) {
        /* e.g. keep the notification badge lit on the LCD topbar until
         * the FIFO drains back to zero. */
    }
}

nus_commands_emit_ack()

void nus_commands_emit_ack	(	const char *	ack_cmd,
		size_t	ack_cmd_len,
		const char *	ok_true_or_null,
		const char *	error_or_null,
		int	n )

Emit a command ack (verb hard-truncated at 32 chars); void — a send failure is invisible.

Contract

ack_cmd_len == 0 means "use `strlen`"; the verb is hard-truncated at 32 characters (nus_commands.c:152). ok is derived: both NULL gives ok:true; a non-NULL error_or_null flips it to false and appends "error":"...". n = 0 skips that field. Void — a send failure is invisible. Output goes through NUS_SEND to ble_nus_send(), so the same connected-link precondition applies. Runs on the NUS RX dispatch task (the task delivering nus_on_rx_bytes()), not arbitrary context. Template call sites: 0 (archived: 74 — the most-called symbol in the module).

Variant

mtb-mpy and mtb-only

Origin

Lifted from BENTO-TESAIoT-libraries/claw/common/ble_nus/nus_commands.c:770-784 (compiled into the prebuilt archive; not shipped as source).

nus_commands_dispatch()

void nus_commands_dispatch	(	const char *	json,
		size_t	json_len,
		const jsmntok_t *	toks,
		int	n_toks,
		const jsmntok_t *	t_cmd )

Route a top-level "cmd" frame to its handler; internal to the RX path.

Contract

Called by the protocol layer when the outer object carries a top-level "cmd" string; routes to the handler and emits the ack. t_cmd is the token of the verb string. Internal to the RX path — application code feeds bytes to nus_on_rx_bytes() and never dispatches itself. Template call sites: 0; archived call sites nus_protocol.c:307 and :326 (nus_commands_dispatch((const char *)json, len, ... — the frame-router hand-off; compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

nus_commands_handle_time_sync()

void nus_commands_handle_time_sync	(	const char *	json,
		const jsmntok_t *	toks,
		int	n )

Handle the one-shot {"time":[epoch,tz]} frame; no ack is emitted.

Contract

Handles the one-shot {"time":[epoch,tz]} frame; no ack is emitted. Internal to the RX path. Template call sites: 0; archived call site nus_protocol.c:319 (nus_commands_handle_time_sync((const char *)json, s_dispatch_tokens, n); — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only