Event และ ack

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 นั้น ส่วนการนำไปสร้างจริงถูกเก็บไว้ใน 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 ให้เอง 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 ด้วย ซึ่งไม่มีไฟล์นั้นอยู่

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

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 ถูกเรียกภายใน archive เท่านั้น (จาก handler ของคำสั่ง bento.notify.show)

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 ถูกเรียกภายใน archive เท่านั้น (จาก callback รับ IPC ขาเข้าจาก CM55 ที่ ipc_bento_buddy_rx_init() ลงทะเบียนไว้)

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 อักขระ ค่า ok เป็นค่าที่คำนวณมา: ถ้าเป็น NULL ทั้งคู่จะได้ ok:true ถ้า error_or_null ไม่ใช่ NULL จะพลิกเป็น false และต่อท้ายด้วย "error":"..." n = 0 จะข้ามฟิลด์นั้นไป คืนค่า void — ความล้มเหลวในการส่งจึงมองไม่เห็น ผลลัพธ์ออกไปผ่านมาโครส่งข้อมูลไปยัง 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

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 ถูกเรียกภายใน archive เท่านั้น (จาก 2 จุดในตัวจัดเส้นทางเฟรมของชั้น protocol ซึ่งรับไบต์ต่อมาจาก nus_on_rx_bytes())

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 ถูกเรียกภายใน archive เท่านั้น (จากตัวจัดเส้นทางเฟรมของชั้น protocol)

variant ที่ใช้ได้

mtb-mpy และ mtb-only