Functions
int	nus_emit_event (const char *json)
	ส่งเฟรม event แบบ JSON หนึ่งเฟรม (ห้ามใส่ newline ปิดท้าย — ฟังก์ชันเติม LF ให้เอง) คืนค่า 0/-1 เท่านั้น
void	nus_events_push_pending_ack (const char *id)
	ใส่ id ของ notification ลงใน FIFO ของ ack ที่ค้างอยู่ ตัดรายการซ้ำ และนำรายการเก่าสุดออกเมื่อเต็ม
bool	nus_events_drain_pending_ack (const char *id)
	เอา id ออกจาก FIFO คืน true เมื่อพบ — เป็นเส้นทาง bento.user.ack ของการแตะบน CM55
size_t	nus_events_pending_ack_count (void)
	จำนวน id ที่อยู่ใน FIFO ใช้กับ telemetry และ unit test บนเครื่อง host ไม่มีผู้เรียกที่ใดเลย
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)
	ส่ง ack ของคำสั่ง (ชื่อ verb ถูกตัดตายตัวที่ 32 อักขระ) คืนค่า void — ความล้มเหลวในการส่งจึงมองไม่เห็น
void	nus_commands_dispatch (const char json, size_t json_len, const jsmntok_t toks, int n_toks, const jsmntok_t *t_cmd)
	ส่งเฟรมที่มี "cmd" ระดับบนสุดต่อไปยัง handler ของมัน เป็นเรื่องภายในของเส้นทาง RX
void	nus_commands_handle_time_sync (const char json, const jsmntok_t toks, int n)
	จัดการเฟรม {"time":[epoch,tz]} แบบครั้งเดียว ไม่มีการส่ง ack ออกไป

Detailed Description

7 ฟังก์ชัน: nus_emit_event FIFO ของ ack ที่ค้างอยู่ และการ dispatch ของ nus_commands_* คอมไพล์เฉพาะเมื่อ ENABLE_PAGE_BENTO_BUDDY=1 (ค่าตั้งต้นคือ 0, proj_cm33_ns/Makefile:64, :305) ให้ build ใหม่หลังจาก make getlibs — ดู Flag gate (อ่านก่อน)

การประกาศ: nus_events.h (nus_emit_event และ FIFO ของ ack ที่ค้างอยู่) กับ nus_commands.h (nus_commands_*) โดย nus_commands.h มี #include "vendor/jsmn.h" ซึ่งชุด include ของ dist ไม่ได้มีมาให้ (หมายเหตุเรื่องการแพ็กเกจ header) พารามิเตอร์ชนิด jsmntok_t จึงถูกอธิบายไว้โดยไม่ต้องพึ่ง header นั้น ส่วนการนำไปสร้างจริงใน nus_events.c / nus_commands.c ถูกเก็บไว้ใน libbento_secure.a

variant ที่ใช้ได้: mtb-mpy และ mtb-only

Function Documentation

◆ nus_emit_event()

int nus_emit_event ( const char * json )

ส่งเฟรม event แบบ JSON หนึ่งเฟรม (ห้ามใส่ newline ปิดท้าย — ฟังก์ชันเติม LF ให้เอง) คืนค่า 0/-1 เท่านั้น

ข้อกำหนดการเรียกใช้: ให้ส่งอ็อบเจ็กต์ JSON ที่ปิดท้ายด้วย NUL และ ไม่มี newline ปิดท้าย — ฟังก์ชันเติม LF ให้เอง (nus_events.c:54) payload ต้องเป็นไปตาม strlen(json) + 2 <= 256 มิฉะนั้นคืนค่า -1 แล้ว ทิ้ง ข้อมูลไป ไม่ใช่ตัดให้สั้นลง คืนค่า 0/-1 เท่านั้น โดย -1 รวมกรณีขนาดเกิน กรณี NULL และกรณี link หลุดไว้ด้วยกัน (ฟังก์ชันนี้ส่งต่อให้ ble_nus_send() จึงต้องมี link ที่เชื่อมต่ออยู่และเปิด notification ไว้) ผู้ใช้ไลบรารีในทรี mpy ประกาศ extern ไว้ในไฟล์ของตนเอง — nus_events.h เป็นการประกาศแบบสาธารณะเพียงแห่งเดียว call site ในเทมเพลต: 3

variant ที่ใช้ได้: mtb-mpy และ mtb-only

call site ในเทมเพลตที่ดีที่สุด (มีเฉพาะใน zip ของ mtb-mpy ยกมาเป็นข้อความ): bento_libs/claw/common/mpy/mod_dualband.c:196-213 (มี extern ประกาศในไฟล์นั้นเองที่ :44-46) marker tag ble_nus_emit_event_contract — ประกอบอ็อบเจ็กต์ bento.net.down ด้วย snprintf ลงในบัฟเฟอร์ขนาด 128 ไบต์ แล้ว raise OSError("payload too large") เมื่อ len <= 0 || len >= sizeof(json) จากนั้น raise OSError("nus_emit_event failed (d)") เมื่อค่าที่คืนไม่ใช่ศูนย์ ไม่ได้เรนเดอร์ไว้ที่นี่เพราะหัวข้อนี้เป็นส่วนหนึ่งของชุดเอกสาร mtb-only ด้วย ซึ่งไม่มีไฟล์นั้นอยู่

ตัวอย่างจาก archive: ตัวส่ง event สถานะของ radio แสดงระเบียบเดียวกันคือตรวจขอบเขตก่อนแล้วจึงส่ง พร้อมธรรมเนียมการแคสต์ค่าที่คืนทิ้งด้วย (void):

ที่มา: ยกมาจาก BENTO-TESAIoT-libraries/claw/common/ble_nus/nus_commands.c:1443-1469 (คอมไพล์รวมอยู่ใน archive สำเร็จรูป ไม่ได้ส่งมอบมาเป็นซอร์ส)

◆ nus_events_push_pending_ack()

void nus_events_push_pending_ack ( const char * id )

ใส่ id ของ notification ลงใน FIFO ของ ack ที่ค้างอยู่ ตัดรายการซ้ำ และนำรายการเก่าสุดออกเมื่อเต็ม

ข้อกำหนดการเรียกใช้: ใส่ id ของ notification ลงใน FIFO ของ ack ที่ค้างอยู่ เมื่อมี bento.notify.show ที่มี ack_required=true เข้ามา ตัดรายการซ้ำ และนำรายการเก่าสุดออกเมื่อเต็ม ทำงานบน task ที่ทำหน้าที่ dispatch ของ NUS RX call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ nus_commands.c:326 (nus_events_push_pending_ack(slot->id); คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

variant ที่ใช้ได้: mtb-mpy และ mtb-only

◆ nus_events_drain_pending_ack()

bool nus_events_drain_pending_ack ( const char * id )

เอา id ออกจาก FIFO คืน true เมื่อพบ — เป็นเส้นทาง bento.user.ack ของการแตะบน CM55

ข้อกำหนดการเรียกใช้: เอา id ออกจาก FIFO คืน true เมื่อพบและเอาออกได้ คืน false ในกรณีอื่น ถูกเรียกเมื่อการแตะบนจอ LCD ของ CM55 ย้อนกลับมาเป็น bento.user.ack ผ่านสะพาน IPC ผู้เรียกที่มีอยู่จริงในของที่ส่งมอบแคสต์ผลลัพธ์ทิ้งด้วย (void) call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ ipc_bento_buddy_bridge.c:122 ((void)nus_events_drain_pending_ack(id); คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

variant ที่ใช้ได้: mtb-mpy และ mtb-only

◆ nus_events_pending_ack_count()

size_t nus_events_pending_ack_count ( void )

จำนวน id ที่อยู่ใน FIFO ใช้กับ telemetry และ unit test บนเครื่อง host ไม่มีผู้เรียกที่ใดเลย

ข้อกำหนดการเรียกใช้: จำนวน id ที่อยู่ใน FIFO ใช้กับ telemetry และ unit test บนเครื่อง host มีขอบเขตจำกัดตามขนาดของ FIFO (ตัดรายการซ้ำและนำรายการเก่าสุดออก) ไม่มีผู้เรียกที่ใดเลย

variant ที่ใช้ได้: mtb-mpy และ mtb-only

ตัวอย่าง (เขียนขึ้นเอง — ไม่มี 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 )

ส่ง ack ของคำสั่ง (ชื่อ verb ถูกตัดตายตัวที่ 32 อักขระ) คืนค่า void — ความล้มเหลวในการส่งจึงมองไม่เห็น

ข้อกำหนดการเรียกใช้: ack_cmd_len == 0 หมายถึงให้ใช้ strlen ชื่อ verb ถูก ตัดตายตัวที่ 32 อักขระ (nus_commands.c:152) ค่า ok เป็นค่าที่คำนวณมา: ถ้าเป็น NULL ทั้งคู่จะได้ ok:true ถ้า error_or_null ไม่ใช่ NULL จะพลิกเป็น false และต่อท้ายด้วย "error":"..." n = 0 จะข้ามฟิลด์นั้นไป คืนค่า void — ความล้มเหลวในการส่งจึงมองไม่เห็น ผลลัพธ์ออกไปผ่าน NUS_SEND ไปยัง ble_nus_send() เงื่อนไขที่ต้องมี link เชื่อมต่ออยู่จึงเป็นแบบเดียวกัน ทำงานบน task ที่ทำหน้าที่ dispatch ของ NUS RX (task ที่ส่ง nus_on_rx_bytes()) ไม่ใช่ context ใดก็ได้ call site ในเทมเพลต: 0 (ใน archive: 74 — เป็น symbol ที่ถูกเรียกมากที่สุดในโมดูลนี้)

variant ที่ใช้ได้: mtb-mpy และ mtb-only

ที่มา: ยกมาจาก BENTO-TESAIoT-libraries/claw/common/ble_nus/nus_commands.c:770-784 (คอมไพล์รวมอยู่ใน archive สำเร็จรูป ไม่ได้ส่งมอบมาเป็นซอร์ส)

◆ 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 )

ส่งเฟรมที่มี "cmd" ระดับบนสุดต่อไปยัง handler ของมัน เป็นเรื่องภายในของเส้นทาง RX

ข้อกำหนดการเรียกใช้: ชั้น protocol เรียกฟังก์ชันนี้เมื่ออ็อบเจ็กต์ชั้นนอกมีสตริง "cmd" อยู่ระดับบนสุด ฟังก์ชันจะส่งต่อไปยัง handler แล้วส่ง ack ออกไป t_cmd คือ token ของสตริง verb เป็นเรื่องภายในของเส้นทาง RX — โค้ดของแอปพลิเคชันป้อนไบต์ให้ nus_on_rx_bytes() และห้าม dispatch เอง call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ nus_protocol.c:307 และ :326 (nus_commands_dispatch((const char *)json, len, ... คือจุดส่งต่อของตัวจัดเส้นทางเฟรม คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

variant ที่ใช้ได้: mtb-mpy และ mtb-only

◆ nus_commands_handle_time_sync()

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

จัดการเฟรม {"time":[epoch,tz]} แบบครั้งเดียว ไม่มีการส่ง ack ออกไป

ข้อกำหนดการเรียกใช้: จัดการเฟรม {"time":[epoch,tz]} แบบครั้งเดียว ไม่มีการส่ง ack ออกไป เป็นเรื่องภายในของเส้นทาง RX call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ nus_protocol.c:319 (nus_commands_handle_time_sync((const char *)json, s_dispatch_tokens, n); คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

variant ที่ใช้ได้: mtb-mpy และ mtb-only

Functions