Functions
bool	ai_engine_init (void)
	สร้าง inference task (idempotent); ต้องเรียกก่อน ai_engine_start()
bool	ai_engine_start (uint32_t index)
	เปิดใช้งานโมเดล (หรือ set) ด้วยดัชนี แล้วเริ่มการอนุมาน; ต้องตรวจค่าที่คืนมา
void	ai_engine_stop (void)
	หยุดโมเดลที่ active อยู่ (idempotent); ต้องจับคู่กับการลดอัตราเซนเซอร์ลง
int	ai_engine_active (void)
	โมเดลที่ LOADED แล้ว หรือ -1; ตามหลัง requested อยู่หนึ่งช่วง cold-init
int	ai_engine_requested (void)
	โมเดลที่ REQUESTED ไว้ หรือ -1; เป็นตัวกันที่ถูกต้องสำหรับ fallback
uint32_t	ai_engine_stack_words (void)
	ขนาด stack ที่ inference task ได้รับ หน่วยเป็นเวิร์ด; 0 = engine ไม่เคยเริ่มทำงาน — เป็น gate สากล
uint32_t	ai_engine_stack_free_words (void)
	ค่าต่ำสุดตลอดกาลของจำนวนเวิร์ดใน stack ที่ยังไม่ถูกใช้; เป็นการสแกนแบบ O(stack) — อ่านได้ไม่เกินประมาณ 1 Hz

Detailed Description

ฟังก์ชัน 7 ตัว: สร้าง inference task, start และ stop โมเดล, อ่านว่าโมเดลใดถูก requested เทียบกับที่ loaded แล้ว และค่าอ่าน 2 ค่าเรื่อง stack ที่เป็น gate ของทุกอย่างที่เหลือ ให้อ่าน วินัย select → confirm → start ก่อนใช้ฟังก์ชันใดก็ตามในกลุ่มนี้

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

Function Documentation

◆ ai_engine_init()

bool ai_engine_init ( void )

สร้าง inference task (idempotent); ต้องเรียกก่อน ai_engine_start()

Create the inference task (idle until ai_engine_start). Idempotent; must precede ai_engine_start(). If it fails, ai_engine_stack_words() returns 0.

ข้อกำหนดการเรียกใช้: สร้าง inference task ซึ่งจะอยู่เฉย ๆ จนกว่าจะเรียก ai_engine_start(); ให้เรียกหลังจากที่แหล่งข้อมูลเซนเซอร์มีอยู่แล้ว Idempotent — เรียกซ้ำได้โดยผลไม่เปลี่ยน ฟังก์ชันนี้ ต้องมาก่อน ai_engine_start() — หากเครื่องยนต์ยังไม่เคยเริ่มทำงาน start() จะคืนค่า false อย่างเงียบ ๆ และ ai_engine_active() จะค้างอยู่ที่ -1 ตลอดไป ซึ่งจะปรากฏออกมาเป็น edge_ai.select() ที่ล้มเหลวด้วยอาการ "not confirmed" ขั้นตอนเปิดใช้จอแสดงผลเรียกฟังก์ชันนี้หลังจากยืนยันแล้วว่าจอขึ้นเรียบร้อย ความผิดพลาดฝั่ง AI จึงไม่มีทางทำให้เสียหน้าจอไปได้ แต่การเรียกที่จุดนั้นเพียงจุดเดียวไม่พอสำหรับการบูตทุกเส้นทาง สำนวนที่ส่งมอบจริงจึงเรียกซ้ำก่อน start ทุกครั้ง เมื่อสร้าง task ไม่สำเร็จ ai_engine_stack_words() คืนค่า 0 — ซึ่งเป็น gate สากล

(void)ai_engine_init();                 /* idempotent: cheap when already up */
if (ai_engine_requested() < 0) {        /* guard on REQUESTED, never ACTIVE  */
    (void)ai_engine_start(0u);
}

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

◆ ai_engine_start()

bool ai_engine_start ( uint32_t index )

เปิดใช้งานโมเดล (หรือ set) ด้วยดัชนี แล้วเริ่มการอนุมาน; ต้องตรวจค่าที่คืนมา

Activate a model by registry index, or a set by set index, and begin inferring. Stops whatever was running first. Returns false on a bad index, a set index in an image built without a microphone model, or an engine that never started (see ai_engine_init). A model whose own init() fails is reported later: ai_engine_requested() drops back to -1.

ข้อกำหนดการเรียกใช้: เปิดใช้งานโมเดลด้วยดัชนีใน registry (หรือดัชนีเทียมของ set, ดัชนีเทียมของ set และการแปลงค่ารูปเดิม) แล้วเริ่มการอนุมาน (inference); โดยหยุดสิ่งที่กำลังทำงานอยู่ก่อนเป็นอันดับแรก ให้เรียก ai_engine_init() ก่อน — การเรียกซ้ำแบบ idempotent ทันทีก่อน start คือสำนวนที่ส่งมอบจริง ดัชนีเทียมของ set 252..255 จะรับเฉพาะในอิมเมจที่ build พร้อมโมเดลไมโครโฟนอย่างน้อยหนึ่งตัว ในอิมเมจที่มีแต่ motion ดัชนีของ set จะถูกปฏิเสธ ต้องตรวจค่าที่คืนมาก่อนจะไปแตะอัตราหรือสถานะใด ๆ: false = ดัชนีผิด, ดัชนีของ set ในอิมเมจที่ไม่มีโมเดลไมโครโฟน หรือเครื่องยนต์ไม่เคยเริ่มทำงาน ให้ตั้งอัตราเซนเซอร์หลังจากที่ start() คืนค่า true แล้วเท่านั้น; เมื่อล้มเหลว ให้ปล่อยสถานะไว้ตามเดิม แล้วให้การยืนยันด้วย Q_ACTIVE เป็นตัวเปิดเผยเรื่องนี้ start() เปลี่ยนเฉพาะโมเดลที่ requested; โมเดลที่ active จะเปลี่ยนหลังจาก init() แบบเย็นของโมเดลคืนค่ากลับมาแล้ว — ดู วินัย select → confirm → start

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

◆ ai_engine_stop()

void ai_engine_stop ( void )

หยุดโมเดลที่ active อยู่ (idempotent); ต้องจับคู่กับการลดอัตราเซนเซอร์ลง

Stop the active model (idempotent).

ข้อกำหนดการเรียกใช้: เป็น idempotent และเป็นคำขอ: ai_engine_active() ที่กลายเป็น -1 คือการยืนยัน ฟังก์ชันนี้ไม่แตะอัตราเซนเซอร์ — ทุกครั้งที่ stop ต้องจับคู่กับการลดอัตราเซนเซอร์ลง (เช่น ai_engine_set_sensor_rate(100u) เพื่อกลับสู่จังหวะของ dashboard) มิฉะนั้นเซนเซอร์วัดความเร่ง (accelerometer) จะถูกตรึงไว้ที่ 50 Hz และแย่งทรัพยากรจนเซนเซอร์ของ dashboard อดอยาก ปุ่ม Load บนหน้า Edge AI เป็นปุ่มแบบ 3 สถานะ: ปุ่มจะปฏิเสธก่อนเป็นอันดับแรกเมื่อ ai_engine_stack_words() เป็น 0 จากนั้นอ่าน ai_engine_active() หนึ่งครั้ง แล้วเรียก stop() เมื่อโมเดลที่เลือกไว้เป็นตัวเดียวกับที่ active อยู่

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

◆ ai_engine_active()

int ai_engine_active ( void )

โมเดลที่ LOADED แล้ว หรือ -1; ตามหลัง requested อยู่หนึ่งช่วง cold-init

Index of the active model, or -1 when idle.

ข้อกำหนดการเรียกใช้: คืนค่าโมเดลที่ LOADED แล้ว หรือ -1 เมื่อไม่มีโมเดลทำงานอยู่ ค่านี้ตามหลัง ai_engine_requested() อยู่เต็มหนึ่งช่วง cold-init ห้ามใช้ค่านี้เป็น gate ของ fallback: อาการที่บันทึกไว้คือ "select Radar, Load, get Motion" — ตัวกัน (guard) ที่อ่าน active() ระหว่างช่วง cold-load ได้ยิง ai_engine_start(0) ออกไปและเขียนทับสิ่งที่ผู้ใช้เลือกไว้ สำหรับ set ค่านี้จะรายงานเป็นค่าคงที่ของ set (ผู้เรียกที่ส่ง 13 เข้าไปจะได้รับคำตอบเป็น 253 — ดัชนีเทียมของ set และการแปลงค่ารูปเดิม) ภายในหนึ่งรอบเรนเดอร์ ให้อ่านค่านี้เพียงครั้งเดียว (ดู ai_engine_set_models()): task อื่นอาจสั่ง start/stop กลางรอบเรนเดอร์ได้ เปิดให้ MicroPython ใช้ในชื่อ MODEL_LINK_Q_ACTIVE

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

◆ ai_engine_requested()

int ai_engine_requested ( void )

โมเดลที่ REQUESTED ไว้ หรือ -1; เป็นตัวกันที่ถูกต้องสำหรับ fallback

Index of the REQUESTED model (last ai_engine_start), or -1 when stopped. Leads ai_engine_active() until the requested model has finished loading, and drops to -1 if its init() fails. Guard a default-model fallback on this, never on ai_engine_active().

ข้อกำหนดการเรียกใช้: คืนค่าโมเดลที่ ai_engine_start() ครั้งล่าสุด REQUESTED ไว้ หรือ -1 เมื่อหยุดแล้ว ค่านี้คือตัวกันที่ถูกต้องสำหรับ fallback ไปยังโมเดลค่าเริ่มต้น (สำนวน if (ai_engine_requested() < 0) ai_engine_start(0) ที่แสดงไว้ใต้ ai_engine_init()) ค่านี้นำหน้า Q_ACTIVE อยู่หนึ่งช่วง cold-init และ ตกกลับไปเป็น -1 เมื่อ init() นั้นล้มเหลว ลูปยืนยันที่เคยเห็น requested == want มาแล้วจึงล้มเหลวได้เร็วเมื่อเห็น requested < 0 ในภายหลัง แทนที่จะรอจนครบเพดาน 15 s เปิดให้ MicroPython ใช้ในชื่อ MODEL_LINK_Q_REQUESTED

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

◆ ai_engine_stack_words()

uint32_t ai_engine_stack_words ( void )

ขนาด stack ที่ inference task ได้รับ หน่วยเป็นเวิร์ด; 0 = engine ไม่เคยเริ่มทำงาน — เป็น gate สากล

Stack the inference task actually got, in words; 0 if it was never created. Reported on the Edge AI page so a heap squeeze is visible, not silent.

ข้อกำหนดการเรียกใช้: ขนาด stack ที่ inference task ได้รับมาจริง หน่วยเป็นเวิร์ด; 0 หมายความว่า task ไม่เคยถูกสร้างขึ้น — engine ไม่เคยเริ่มทำงาน ให้ใช้ค่านี้เป็น gate ของตัวควบคุมทุกตัว: หน้า Edge AI ใช้ค่านี้ทำให้ปุ่ม Load เป็น no-op แสดงป้าย "engine failed to start" และเลือกระหว่าง Failed กับ Stopped ตัวนับอื่นทุกตัวในหน้าเหล่านี้ไม่มีความหมายตราบใดที่ค่านี้ยังเป็น 0 เป็นการอ่านที่ต้นทุนต่ำ เรียกได้จาก CM55 context ใด ๆ

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

◆ ai_engine_stack_free_words()

uint32_t ai_engine_stack_free_words ( void )

ค่าต่ำสุดตลอดกาลของจำนวนเวิร์ดใน stack ที่ยังไม่ถูกใช้; เป็นการสแกนแบบ O(stack) — อ่านได้ไม่เกินประมาณ 1 Hz

Unused words left in the inference task's stack (all-time minimum); 0 if the task was never created. Read at about 1 Hz — the call scans the stack.

ข้อกำหนดการเรียกใช้: ค่าต่ำสุดตลอดกาลของจำนวนเวิร์ดที่ยังไม่ถูกใช้ใน stack ของ inference task; ได้ 0 หาก task ไม่เคยถูกสร้างขึ้น การเรียกนี้สแกน stack ทั้งก้อน — O(stack) ให้อ่านไม่เกินประมาณ 1 Hz และห้ามอ่านทุกเฟรม; หน้า Edge AI อ่านค่านี้เฉพาะในบรรทัดสถิติที่ออกวินาทีละครั้งเท่านั้น

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

Functions