Protocol, folder-push & base64

Functions
void	nus_protocol_init (void)
	Internal one-time init — ble_nus_init() does it; never call directly.
void	nus_on_rx_bytes (const uint8_t *buf, size_t len)
	Feed NUS RX bytes to the framer; newline framed, 4 KB overflow with RESYNC.
void	nus_protocol_tick (uint32_t now_ms)
	Passive 30 s keepalive watchdog; call at about 10 Hz. No caller anywhere.
void	nus_protocol_send_permission (const char *id, size_t id_len, int decision_approve)
	Emit the permission frame for a stored prompt id after a human decision. No caller anywhere.
void	nus_protocol_set_link_encrypted (int encrypted)
	Stack-internal: set from the BTM_ENCRYPTION_STATUS_EVT handler.
int	nus_protocol_get_link_encrypted (void)
	Read the encrypted-link flag; recovered prototype — bento_secure_undeclared.h.
void	nus_fp_char_begin (const char *json, const jsmntok_t *toks, int n)
	Folder-push verb char_begin: open the staging folder. Dispatcher-only.
void	nus_fp_file (const char *json, const jsmntok_t *toks, int n)
	Verb file: start a file inside the staging folder; path validation rejects traversal.
void	nus_fp_chunk (const char *json, const jsmntok_t *toks, int n)
	Verb chunk: stream the "d" base64 field into LittleFS via the stateful decoder.
void	nus_fp_file_end (const char *json, const jsmntok_t *toks, int n)
	Verb file_end: flush the decoder carry and close the file.
void	nus_fp_char_end (const char *json, const jsmntok_t *toks, int n)
	Verb char_end: atomic commit — rename staging to /buddy/<name>/ or delete it.
int	nus_fp_is_active (void)
	Non-zero between char_begin and char_end; defer heavy side work during a transfer.
int	nus_fp_device_write_bytes (const uint8_t *b, size_t n)
	The decoder's sink into the open staging file; recovered prototype, not an entry point.
void	nus_b64_init (nus_b64_state_t *s, nus_b64_sink_t sink, void *ctx)
	Reset a caller-owned decoder state and wire the sink; nothing is buffered whole in RAM.
int	nus_b64_feed (nus_b64_state_t *s, const uint8_t *b64, size_t len)
	Feed one chunk of base64 text; the state carries a split 4-char quantum across chunks.
int	nus_b64_flush (nus_b64_state_t *s)
	Flush any trailing carry; call at file_end.

Detailed Description

Sixteen functions: nus_protocol_* and nus_on_rx_bytes, the folder-push verbs nus_fp_*, and the base64 decoder nus_b64_*. 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_protocol.h, nus_folder_push.h (includes vendor/jsmn.h, absent from the dist include set — Header packaging note), nus_base64.h, and bento_secure_undeclared.h for the two recovered prototypes (nus_protocol_get_link_encrypted, nus_fp_device_write_bytes). Implementation nus_protocol.c / nus_folder_push.c / nus_base64.c is archived in libbento_secure.a. Nearly everything here is the RX pipeline's own plumbing: ble_nus.c feeds bytes into nus_on_rx_bytes(), the protocol layer parses and hands "cmd" frames to nus_commands_dispatch(), and the folder-push verbs are reached only from that dispatcher.

Variant

mtb-mpy and mtb-only

Function Documentation

nus_protocol_init()

void nus_protocol_init

(

void

)

Internal one-time init — ble_nus_init() does it; never call directly.

Contract

Called once at ble_nus_init() time, after the stack is up. Internal — never call directly; ble_nus_init() does it. Template call sites: 0; archived call site ble_nus.c:860 (nus_protocol_init(); inside ble_nus_init — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

nus_on_rx_bytes()

void nus_on_rx_bytes	(	const uint8_t *	buf,
		size_t	len )

Feed NUS RX bytes to the framer; newline framed, 4 KB overflow with RESYNC.

Contract

Feed bytes written to the NUS RX characteristic; may deliver one full frame, a partial frame or several concatenated frames. Newline framed, 4 KB overflow with RESYNC, jsmn parse with a 256-token ceiling. Non-blocking; runs in the BLE task context that delivers the GATT write. Template call sites: 0; archived call site ble_nus.c:432 (nus_on_rx_bytes(p->p_val, p->val_len); — the GATT write to protocol feed; compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

nus_protocol_tick()

void nus_protocol_tick

(

uint32_t

now_ms

)

Passive 30 s keepalive watchdog; call at about 10 Hz. No caller anywhere.

Contract

Passive 30 s keepalive watchdog: call periodically (about 10 Hz) with a monotonic millisecond clock; emits BUDDY_UI_STATE=SLEEP over IPC when 30 s pass without a parseable frame while the link still counts as connected. It never touches the link. No caller anywhere.

Variant

mtb-mpy and mtb-only

Example (authored — no shipped call site)

__attribute__((used))
static void bento_ex_nus_protocol_tick(void)
{
    /* From a ~10 Hz periodic task: */
    uint32_t now_ms = (uint32_t)(xTaskGetTickCount() * portTICK_PERIOD_MS);
    nus_protocol_tick(now_ms);
}

nus_protocol_send_permission()

void nus_protocol_send_permission	(	const char *	id,
		size_t	id_len,
		int	decision_approve )

Emit the permission frame for a stored prompt id after a human decision. No caller anywhere.

Contract

Emits the permission JSON frame on NUS TX for the stored prompt id; decision_approve non-zero = "once" (approve), zero = "deny". id need not be NUL-terminated (id_len is its byte length). Intended for the Approve/Deny button path — after a human decision. No caller anywhere.

Variant

mtb-mpy and mtb-only

Example (authored — no shipped call site)

__attribute__((used))
static void bento_ex_nus_protocol_send_permission(void)
{
    /* The prompt id as stored when the permission request arrived: */
    const char *prompt_id = "perm-7";
 
    /* Operator pressed Approve ("once"): */
    nus_protocol_send_permission(prompt_id, strlen(prompt_id), 1);
 
    /* Operator pressed Deny:
     *   nus_protocol_send_permission(prompt_id, strlen(prompt_id), 0);
     */
}

nus_protocol_set_link_encrypted()

void nus_protocol_set_link_encrypted

(

int

encrypted

)

Stack-internal: set from the BTM_ENCRYPTION_STATUS_EVT handler.

Contract

Called from the BTM_ENCRYPTION_STATUS_EVT handler; when set, the status ack reports "sec":true. Stack-internal. Template call sites: 0; archived call site ble_nus.c:770 (nus_protocol_set_link_encrypted( — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

nus_protocol_get_link_encrypted()

int nus_protocol_get_link_encrypted ( void )

extern

Read the encrypted-link flag; recovered prototype — bento_secure_undeclared.h.

Contract

Read of the encrypted-link flag. No public header declares it; the shipped consumer uses a local extern (nus_commands.c:85) — the bento_secure_undeclared.h prototype is that declaration, recovered. Template call sites: 0; archived call site nus_commands.c:190 (nus_protocol_get_link_encrypted() ? "true" : "false", in the status JSON — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

nus_fp_char_begin()

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

Folder-push verb char_begin: open the staging folder. Dispatcher-only.

Contract

Folder-push verb char_begin: opens the staging folder /buddy/.staging/<name>/. Emits its own ack. Dispatcher-only — reached by the verb table in nus_commands.c, never from application code. Template call sites: 0; archived call site nus_commands.c:1897 (if (jsonstr_eq(json, t_cmd, "char_begin")) { nus_fp_char_begin(json, toks, n_toks); return; } — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

nus_fp_file()

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

Verb file: start a file inside the staging folder; path validation rejects traversal.

Contract

Verb file: starts a file inside the staging folder; path validation rejects .., absolute paths and control characters. Emits its own ack. Dispatcher-only. Template call sites: 0; archived call site nus_commands.c:1898 (verb-table dispatch — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

nus_fp_chunk()

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

Verb chunk: stream the "d" base64 field into LittleFS via the stateful decoder.

Contract

Verb chunk: feeds the "d" base64 field through the stateful decoder (nus_b64_feed()) into LittleFS without buffering the whole file. Emits its own ack. Dispatcher-only. Template call sites: 0; archived call site nus_commands.c:1899 (verb-table dispatch — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

nus_fp_file_end()

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

Verb file_end: flush the decoder carry and close the file.

Contract

Verb file_end: flushes the decoder carry (nus_b64_flush()) and closes the file. Emits its own ack. Dispatcher-only. Template call sites: 0; archived call site nus_commands.c:1900 (verb-table dispatch — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

nus_fp_char_end()

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

Verb char_end: atomic commit — rename staging to /buddy/<name>/ or delete it.

Contract

Verb char_end: atomic commit — renames the staging folder to /buddy/<name>/; any failure deletes staging and acks {ok:false}. Dispatcher-only. Template call sites: 0; archived call site nus_commands.c:1901 (verb-table dispatch — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

nus_fp_is_active()

int nus_fp_is_active

(

void

)

Non-zero between char_begin and char_end; defer heavy side work during a transfer.

Contract

Non-zero between char_begin and char_end. Plain read; use it to defer filesystem- or link-heavy side work during a transfer. No caller anywhere.

Variant

mtb-mpy and mtb-only

Example (authored — no shipped call site)

__attribute__((used))
static void bento_ex_nus_fp_is_active(void)
{
    if (nus_fp_is_active()) {
        return;                        /* transfer in flight — defer       */
    }
    /* Safe window for filesystem/link-heavy side work. */
}

nus_fp_device_write_bytes()

int nus_fp_device_write_bytes ( const uint8_t * b, size_t n )

extern

The decoder's sink into the open staging file; recovered prototype, not an entry point.

Contract

The decoder's sink: writes decoded bytes to the open staging file. Declared only by a local extern in its caller (nus_folder_push.c:52); the real definition is nus_folder_push.c:215 with a paired stub at :266 ({ (void)b; (void)n; return 0; }) for builds without a filesystem. Not an application entry point. Template call sites: 0; archived call site nus_folder_push.c:55 (return nus_fp_device_write_bytes(b, n); — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

nus_b64_init()

void nus_b64_init	(	nus_b64_state_t *	s,
		nus_b64_sink_t	sink,
		void *	ctx )

Reset a caller-owned decoder state and wire the sink; nothing is buffered whole in RAM.

Contract

Resets a caller-owned nus_b64_state_t and wires the sink callback; decoded output streams through the sink so nothing is buffered whole in RAM. Template call sites: 0; archived call site nus_folder_push.c:358 (nus_b64_init(&s_b64, — sink-callback wiring; compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

nus_b64_feed()

int nus_b64_feed	(	nus_b64_state_t *	s,
		const uint8_t *	b64,
		size_t	len )

Feed one chunk of base64 text; the state carries a split 4-char quantum across chunks.

Contract

Feed one chunk of base64 text; a 4-character quantum may be split across chunks — the state keeps the 1..3 leftover bytes. Returns 0 on success, negative on invalid character, sink failure, or data after padding. Template call sites: 0; archived call site nus_folder_push.c:383 (int r = nus_b64_feed(&s_b64, b64, b64_len); — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only

nus_b64_flush()

int nus_b64_flush

(

nus_b64_state_t *

s

)

Flush any trailing carry; call at file_end.

Contract

Flushes any trailing carry; call at file_end. Template call sites: 0; archived call site nus_folder_push.c:407 (nus_b64_flush(&s_b64); — compiled into libbento_secure.a, not shipped as source).

Variant

mtb-mpy and mtb-only