Functions
void	nus_protocol_init (void)
	init ครั้งเดียวสำหรับใช้ภายใน — ble_nus_init() ทำให้แล้ว ห้ามเรียกโดยตรง
void	nus_on_rx_bytes (const uint8_t *buf, size_t len)
	ป้อนไบต์จาก NUS RX ให้ตัวประกอบเฟรม ใช้ newline คั่นเฟรม ล้นที่ 4 KB แล้ว RESYNC
void	nus_protocol_tick (uint32_t now_ms)
	watchdog แบบ keepalive 30 s ที่ทำงานเชิงรับ ให้เรียกที่ราว 10 Hz ไม่มีผู้เรียกที่ใดเลย
void	nus_protocol_send_permission (const char *id, size_t id_len, int decision_approve)
	ส่งเฟรม permission ของ id คำถามยืนยันที่เก็บไว้ หลังจากมีการตัดสินใจของมนุษย์แล้ว ไม่มีผู้เรียกที่ใดเลย
void	nus_protocol_set_link_encrypted (int encrypted)
	เป็นของภายใน stack: ถูกตั้งค่าจาก handler ของ BTM_ENCRYPTION_STATUS_EVT
int	nus_protocol_get_link_encrypted (void)
	อ่าน flag ว่า link เข้ารหัสอยู่หรือไม่ เป็น prototype ที่กู้กลับมา — อยู่ใน bento_secure_undeclared.h
void	nus_fp_char_begin (const char json, const jsmntok_t toks, int n)
	verb char_begin ของ folder-push: เปิดโฟลเดอร์ staging เรียกจาก dispatcher เท่านั้น
void	nus_fp_file (const char json, const jsmntok_t toks, int n)
	verb file: เริ่มไฟล์ใหม่ในโฟลเดอร์ staging การตรวจพาธปฏิเสธการไต่ไดเรกทอรี
void	nus_fp_chunk (const char json, const jsmntok_t toks, int n)
	verb chunk: สตรีมฟิลด์ base64 "d" ลง LittleFS ผ่าน decoder ที่เก็บสถานะไว้
void	nus_fp_file_end (const char json, const jsmntok_t toks, int n)
	verb file_end: เขียนค่าที่ decoder ค้างไว้ลงจริงแล้วปิดไฟล์
void	nus_fp_char_end (const char json, const jsmntok_t toks, int n)
	verb char_end: commit แบบอะตอมิก — เปลี่ยนชื่อ staging เป็น /buddy/<name>/ หรือลบทิ้ง
int	nus_fp_is_active (void)
	คืนค่าที่ไม่ใช่ศูนย์ในช่วงระหว่าง char_begin กับ char_end ใช้เลื่อนงานหนักอื่นออกไประหว่างการโอนข้อมูล
int	nus_fp_device_write_bytes (const uint8_t *b, size_t n)
	sink ของ decoder ที่เขียนลงไฟล์ staging ที่เปิดอยู่ เป็น prototype ที่กู้กลับมา ไม่ใช่จุดเข้าใช้งาน
void	nus_b64_init (nus_b64_state_t s, nus_b64_sink_t sink, void ctx)
	รีเซ็ตสถานะ decoder ที่ผู้เรียกเป็นเจ้าของแล้วต่อ sink เข้าไป ไม่มีการพักข้อมูลทั้งก้อนไว้ใน RAM
int	nus_b64_feed (nus_b64_state_t s, const uint8_t b64, size_t len)
	ป้อนข้อความ base64 ทีละ chunk สถานะจะพา quantum ขนาด 4 อักขระที่ถูกแบ่งข้าม chunk ไปด้วย
int	nus_b64_flush (nus_b64_state_t *s)
	เขียนค่าที่ค้างท้ายลงจริง ให้เรียกตอน file_end

Detailed Description

16 ฟังก์ชัน: nus_protocol_* กับ nus_on_rx_bytes verb ของ folder-push ในกลุ่ม nus_fp_* และตัวถอดรหัส base64 nus_b64_* คอมไพล์เฉพาะเมื่อ ENABLE_PAGE_BENTO_BUDDY=1 (ค่าตั้งต้นคือ 0, proj_cm33_ns/Makefile:64, :305) ให้ build ใหม่หลังจาก make getlibs — ดู Flag gate (อ่านก่อน)

การประกาศ: nus_protocol.h, nus_folder_push.h (มี #include "vendor/jsmn.h" ซึ่งไม่มีอยู่ในชุด include ของ dist — หมายเหตุเรื่องการแพ็กเกจ header), nus_base64.h และ bento_secure_undeclared.h สำหรับ prototype ที่กู้กลับมา 2 ตัว (nus_protocol_get_link_encrypted, nus_fp_device_write_bytes) ส่วนการนำไปสร้างจริงใน nus_protocol.c / nus_folder_push.c / nus_base64.c ถูกเก็บไว้ใน libbento_secure.a เกือบทั้งหมดในกลุ่มนี้เป็นกลไกภายในของเส้นทาง RX เอง: ble_nus.c ป้อนไบต์เข้าสู่ nus_on_rx_bytes() ชั้น protocol แจงข้อมูลแล้วส่งเฟรมที่มี "cmd" ต่อให้ nus_commands_dispatch() และ verb ของ folder-push เข้าถึงได้จาก dispatcher นั้นเท่านั้น

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

Function Documentation

◆ nus_protocol_init()

void nus_protocol_init ( void )

init ครั้งเดียวสำหรับใช้ภายใน — ble_nus_init() ทำให้แล้ว ห้ามเรียกโดยตรง

ข้อกำหนดการเรียกใช้: ถูกเรียกครั้งเดียวในช่วงที่ ble_nus_init() ทำงาน หลังจาก stack ขึ้นมาแล้ว เป็นของภายใน — ห้ามเรียกโดยตรง ble_nus_init() ทำให้แล้ว call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ ble_nus.c:860 (nus_protocol_init(); ภายใน ble_nus_init คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

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

◆ nus_on_rx_bytes()

void nus_on_rx_bytes	(	const uint8_t *	buf,
		size_t	len )

ป้อนไบต์จาก NUS RX ให้ตัวประกอบเฟรม ใช้ newline คั่นเฟรม ล้นที่ 4 KB แล้ว RESYNC

ข้อกำหนดการเรียกใช้: ป้อนไบต์ที่ถูกเขียนเข้ามาที่ characteristic RX ของ NUS อาจส่งออกมาเป็นเฟรมเต็มหนึ่งเฟรม เฟรมที่ยังไม่ครบ หรือหลายเฟรมที่ต่อกันมาก็ได้ ใช้ newline คั่นเฟรม ล้นที่ 4 KB แล้ว RESYNC แจงด้วย jsmn โดยมีเพดาน 256 token ไม่บล็อก ทำงานใน task context ของ BLE ที่ส่ง GATT write เข้ามา call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ ble_nus.c:432 (nus_on_rx_bytes(p->p_val, p->val_len); คือจุดป้อนจาก GATT write เข้าสู่ชั้น protocol คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

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

◆ nus_protocol_tick()

void nus_protocol_tick ( uint32_t now_ms )

watchdog แบบ keepalive 30 s ที่ทำงานเชิงรับ ให้เรียกที่ราว 10 Hz ไม่มีผู้เรียกที่ใดเลย

ข้อกำหนดการเรียกใช้: watchdog แบบ keepalive 30 s ที่ทำงานเชิงรับ: ให้เรียกเป็นระยะ (ราว 10 Hz) พร้อมค่านาฬิกาหน่วยมิลลิวินาทีแบบ monotonic ส่ง BUDDY_UI_STATE=SLEEP ออกทาง IPC เมื่อผ่านไป 30 s โดยไม่มีเฟรมที่แจงได้เข้ามา ทั้งที่ link ยังนับว่าเชื่อมต่ออยู่ ฟังก์ชันนี้ไม่แตะตัว link เลย ไม่มีผู้เรียกที่ใดเลย

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

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

ส่งเฟรม permission ของ id คำถามยืนยันที่เก็บไว้ หลังจากมีการตัดสินใจของมนุษย์แล้ว ไม่มีผู้เรียกที่ใดเลย

ข้อกำหนดการเรียกใช้: ส่งเฟรม permission แบบ JSON ออกทาง NUS TX สำหรับ id ของคำถามยืนยันที่เก็บไว้ decision_approve ที่ไม่ใช่ศูนย์หมายถึง "once" (อนุมัติ) ศูนย์หมายถึง "deny" id ไม่จำเป็นต้องปิดท้ายด้วย NUL (id_len คือจำนวนไบต์ของมัน) ตั้งใจไว้สำหรับเส้นทางปุ่ม Approve/Deny — หลังจากมีการตัดสินใจของมนุษย์แล้ว ไม่มีผู้เรียกที่ใดเลย

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

ตัวอย่าง (เขียนขึ้นเอง — ไม่มี 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: ถูกตั้งค่าจาก handler ของ BTM_ENCRYPTION_STATUS_EVT

ข้อกำหนดการเรียกใช้: ถูกเรียกจาก handler ของ BTM_ENCRYPTION_STATUS_EVT เมื่อค่าถูกตั้งไว้ ack สถานะจะรายงาน "sec":true เป็นของภายใน stack call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ ble_nus.c:770 (nus_protocol_set_link_encrypted( คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

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

◆ nus_protocol_get_link_encrypted()

int nus_protocol_get_link_encrypted ( void )

extern

อ่าน flag ว่า link เข้ารหัสอยู่หรือไม่ เป็น prototype ที่กู้กลับมา — อยู่ใน bento_secure_undeclared.h

ข้อกำหนดการเรียกใช้: อ่านค่า flag ว่า link เข้ารหัสอยู่หรือไม่ ไม่มี header สาธารณะตัวใดประกาศฟังก์ชันนี้ ผู้ใช้ไลบรารีที่ส่งมอบจริงใช้ extern ที่ประกาศในไฟล์ของตนเอง (nus_commands.c:85) — prototype ใน bento_secure_undeclared.h คือการประกาศนั้นที่กู้กลับมา call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ nus_commands.c:190 (nus_protocol_get_link_encrypted() ? "true" : "false", ใน JSON สถานะ คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

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

◆ nus_fp_char_begin()

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

verb char_begin ของ folder-push: เปิดโฟลเดอร์ staging เรียกจาก dispatcher เท่านั้น

ข้อกำหนดการเรียกใช้: verb char_begin ของ folder-push: เปิดโฟลเดอร์ staging /buddy/.staging/<name>/ ส่ง ack ของตัวเอง เรียกจาก dispatcher เท่านั้น — เข้าถึงผ่านตาราง verb ใน nus_commands.c ห้ามเรียกจากโค้ดของแอปพลิเคชัน call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ nus_commands.c:1897 (if (jsonstr_eq(json, t_cmd, "char_begin")) { nus_fp_char_begin(json, toks, n_toks); return; } คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

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

◆ nus_fp_file()

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

verb file: เริ่มไฟล์ใหม่ในโฟลเดอร์ staging การตรวจพาธปฏิเสธการไต่ไดเรกทอรี

ข้อกำหนดการเรียกใช้: verb file: เริ่มไฟล์ใหม่ในโฟลเดอร์ staging การตรวจความถูกต้องของพาธปฏิเสธ .. พาธสัมบูรณ์ และอักขระควบคุม ส่ง ack ของตัวเอง เรียกจาก dispatcher เท่านั้น call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ nus_commands.c:1898 (การ dispatch ผ่านตาราง verb คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

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

◆ nus_fp_chunk()

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

verb chunk: สตรีมฟิลด์ base64 "d" ลง LittleFS ผ่าน decoder ที่เก็บสถานะไว้

ข้อกำหนดการเรียกใช้: verb chunk: ป้อนฟิลด์ base64 "d" ผ่าน decoder ที่เก็บสถานะไว้ (nus_b64_feed()) ลง LittleFS โดยไม่ต้องพักทั้งไฟล์ไว้ในบัฟเฟอร์ ส่ง ack ของตัวเอง เรียกจาก dispatcher เท่านั้น call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ nus_commands.c:1899 (การ dispatch ผ่านตาราง verb คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

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

◆ nus_fp_file_end()

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

verb file_end: เขียนค่าที่ decoder ค้างไว้ลงจริงแล้วปิดไฟล์

ข้อกำหนดการเรียกใช้: verb file_end: เขียนค่าที่ decoder ค้างไว้ลงจริง (nus_b64_flush()) แล้วปิดไฟล์ ส่ง ack ของตัวเอง เรียกจาก dispatcher เท่านั้น call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ nus_commands.c:1900 (การ dispatch ผ่านตาราง verb คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

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

◆ nus_fp_char_end()

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

verb char_end: commit แบบอะตอมิก — เปลี่ยนชื่อ staging เป็น /buddy/<name>/ หรือลบทิ้ง

ข้อกำหนดการเรียกใช้: verb char_end: commit แบบอะตอมิก — เปลี่ยนชื่อโฟลเดอร์ staging เป็น /buddy/<name>/ ความล้มเหลวใด ๆ จะลบ staging ทิ้งแล้วตอบ ack เป็น {ok:false} เรียกจาก dispatcher เท่านั้น call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ nus_commands.c:1901 (การ dispatch ผ่านตาราง verb คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

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

◆ nus_fp_is_active()

int nus_fp_is_active ( void )

คืนค่าที่ไม่ใช่ศูนย์ในช่วงระหว่าง char_begin กับ char_end ใช้เลื่อนงานหนักอื่นออกไประหว่างการโอนข้อมูล

ข้อกำหนดการเรียกใช้: คืนค่าที่ไม่ใช่ศูนย์ในช่วงระหว่าง char_begin กับ char_end เป็นการอ่านค่าตรง ๆ ใช้เพื่อเลื่อนงานอื่นที่กินระบบไฟล์หรือกิน link ออกไประหว่างการโอนข้อมูล ไม่มีผู้เรียกที่ใดเลย

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

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

sink ของ decoder ที่เขียนลงไฟล์ staging ที่เปิดอยู่ เป็น prototype ที่กู้กลับมา ไม่ใช่จุดเข้าใช้งาน

ข้อกำหนดการเรียกใช้: เป็น sink ของ decoder: เขียนไบต์ที่ถอดรหัสแล้วลงไฟล์ staging ที่เปิดอยู่ ประกาศไว้ด้วย extern ในไฟล์ของผู้เรียกเองเท่านั้น (nus_folder_push.c:52) ตัวนิยามจริงอยู่ที่ nus_folder_push.c:215 และมี stub คู่กันที่ :266 ({ (void)b; (void)n; return 0; }) สำหรับ build ที่ไม่มีระบบไฟล์ ไม่ใช่จุดเข้าใช้งานของแอปพลิเคชัน call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ nus_folder_push.c:55 (return nus_fp_device_write_bytes(b, n); คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

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

◆ nus_b64_init()

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

รีเซ็ตสถานะ decoder ที่ผู้เรียกเป็นเจ้าของแล้วต่อ sink เข้าไป ไม่มีการพักข้อมูลทั้งก้อนไว้ใน RAM

ข้อกำหนดการเรียกใช้: รีเซ็ต nus_b64_state_t ที่ผู้เรียกเป็นเจ้าของ แล้วต่อ callback ของ sink เข้าไป ผลลัพธ์ที่ถอดรหัสแล้วไหลออกผ่าน sink จึงไม่มีการพักข้อมูลทั้งก้อนไว้ใน RAM call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ nus_folder_push.c:358 (nus_b64_init(&s_b64, คือจุดต่อ callback ของ sink คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

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

◆ nus_b64_feed()

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

ป้อนข้อความ base64 ทีละ chunk สถานะจะพา quantum ขนาด 4 อักขระที่ถูกแบ่งข้าม chunk ไปด้วย

ข้อกำหนดการเรียกใช้: ป้อนข้อความ base64 ทีละ chunk quantum ขนาด 4 อักขระอาจถูกแบ่งข้าม chunk ได้ — สถานะจะเก็บไบต์ที่เหลือ 1..3 ไบต์ไว้ คืน 0 เมื่อสำเร็จ คืนค่าติดลบเมื่อพบอักขระที่ไม่ถูกต้อง เมื่อ sink ล้มเหลว หรือเมื่อมีข้อมูลตามหลัง padding call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ nus_folder_push.c:383 (int r = nus_b64_feed(&s_b64, b64, b64_len); คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

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

◆ nus_b64_flush()

int nus_b64_flush ( nus_b64_state_t * s )

เขียนค่าที่ค้างท้ายลงจริง ให้เรียกตอน file_end

ข้อกำหนดการเรียกใช้: เขียนค่าที่ค้างท้ายทั้งหมดลงจริง ให้เรียกตอน file_end call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ nus_folder_push.c:407 (nus_b64_flush(&s_b64); คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

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

Functions