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 แล้ว (s_current) หรือ -1; ตามหลัง requested อยู่หนึ่งช่วง cold-init
int	ai_engine_requested (void)
	โมเดลที่ REQUESTED ไว้ (s_active) หรือ -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). Call after the sensor sources exist; safe to call once from the display bring-up.

ข้อกำหนดการเรียกใช้: สร้าง inference task ซึ่งจะอยู่เฉย ๆ จนกว่าจะเรียก ai_engine_start(); ให้เรียกหลังจากที่แหล่งข้อมูลเซนเซอร์มีอยู่แล้ว Idempotent (ai_engine.c:1735-1738: if (s_task != NULL) return true;) ฟังก์ชันนี้ ต้องมาก่อน ai_engine_start() — ถ้า s_task == NULL start() จะคืนค่า false อย่างเงียบ ๆ และ ai_engine_active() จะค้างอยู่ที่ -1 ตลอดไป ซึ่งจะปรากฏออกมาเป็น edge_ai.select() ที่ล้มเหลวด้วยอาการ "not confirmed" ขั้นตอนเปิดใช้จอแสดงผลเรียกฟังก์ชันนี้หลัง display_ok = true และก่อนป้าย ipc_only: (tesaiot_display.c:467) ความผิดพลาดฝั่ง AI จึงไม่มีทางทำให้เสียหน้าจอไปได้; deepcraft_task.c:617-630 บันทึกไว้ว่าเหตุใดการเรียกที่จุดนั้นเพียงจุดเดียวจึงไม่พอ (การบูตที่เส้นทางจอแสดงผลลัดวงจรไปจะไม่สร้าง ai_task ขึ้นมา) ด้วยเหตุนี้สำนวนที่ส่งมอบจริงจึงเรียกซ้ำก่อน start ทุกครั้ง บันไดขนาด stack {2048, 1536} เวิร์ด (ai_engine.c:1774-1783); เมื่อล้มเหลวทั้งหมด s_task จะยังเป็น NULL และ ai_engine_stack_words() คืนค่า 0 — ซึ่งเป็น gate สากล

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

ที่มา: ยกมาจาก TESAIoT_KIT_PSE84_AI-Micropython-BentoClaw/proj_cm55/modules/deepcraft_task/deepcraft_task.c:631-641 (creator: tesaiot_display.c:467) (คอมไพล์รวมอยู่ใน archive สำเร็จรูป ไม่ได้ส่งมอบมาเป็นซอร์ส)

◆ ai_engine_start()

bool ai_engine_start ( uint32_t index )

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

Activate a model by registry index and begin inferring. Stops any model already running first. Returns false on a bad index or init failure.

ข้อกำหนดการเรียกใช้: เปิดใช้งานโมเดลด้วยดัชนีใน registry (หรือดัชนีเทียมของ set, ดัชนีเทียมของ set และการแปลงค่ารูปเดิม) แล้วเริ่มการอนุมาน (inference); โดยหยุดโมเดลที่กำลังทำงานอยู่ก่อนเป็นอันดับแรก ให้เรียก ai_engine_init() ก่อน — การเรียกซ้ำแบบ idempotent ทันทีก่อน start คือสำนวนที่ส่งมอบจริง ดัชนีเทียมของ set 252..255 จะรับเฉพาะในอิมเมจที่สร้างด้วย EDGE_AI_HAS_MIC เท่านั้น (ai_engine.c:1835-1861); ai_engine.c:1843-1849 บันทึกรูปแบบความล้มเหลวของการรับดัชนี set ในอิมเมจที่มีแต่ motion ไว้ — s_active ค้างอยู่กับที่ s_current ติดอยู่ที่ -1 และงบเวลา select 15 s ถูกเผาไป 2 รอบ ต้องตรวจค่าที่คืนมาก่อนจะไปแตะอัตราหรือสถานะใด ๆ: false = ดัชนีผิด หรือ s_task == NULL อัตราเซนเซอร์ถูกยืนยันเฉพาะภายในสาขาที่สำเร็จเท่านั้น (deepcraft_task.c:804-806); เมื่อล้มเหลว โค้ดที่ส่งมอบจริงจะปล่อยสถานะไว้ตามเดิม และให้การยืนยันด้วย Q_ACTIVE เป็นตัวเปิดเผยเรื่องนี้ (:807) start() ตั้งค่าเฉพาะ s_active (ai_engine.c:1860); ส่วน s_current จะถูกสลับโดย inference task หลังจาก init() แบบเย็นคืนค่ากลับมาแล้ว — ดู วินัย select → confirm → start

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

ที่มา: ยกมาจาก deepcraft_task.c:790-807 (คอมไพล์รวมอยู่ใน archive สำเร็จรูป ไม่ได้ส่งมอบมาเป็นซอร์ส)

◆ ai_engine_stop()

void ai_engine_stop ( void )

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

Stop the active model (idempotent).

ข้อกำหนดการเรียกใช้: เป็น idempotent; เนื้อในของฟังก์ชันคือ s_active = -1 เท่านั้น ไม่มีอย่างอื่น (ai_engine.c:1864) ฟังก์ชันนี้ไม่แตะอัตราเซนเซอร์ — ทุกครั้งที่ stop ต้องจับคู่กับการลดอัตราเซนเซอร์ลง ซึ่งในโค้ดที่ส่งมอบจริงคือ ai_engine_set_sensor_rate(dc_desired_sensor_rate()) มิฉะนั้นเซนเซอร์วัดความเร่ง (accelerometer) จะถูกตรึงไว้ที่ 50 Hz และแย่งทรัพยากรจนเซนเซอร์ของ dashboard อดอยาก (deepcraft_task.c:682-686) ฉบับที่ใช้ฝั่ง UI (page_edge_ai.c:353-368) คือปุ่ม Load แบบ 3 สถานะ: ปุ่มจะปฏิเสธก่อนเป็นอันดับแรกเมื่อ ai_engine_stack_words() เป็น 0 จากนั้นอ่าน ai_engine_active() หนึ่งครั้ง แล้วเรียก stop() เมื่อโมเดลที่เลือกไว้เป็นตัวเดียวกับที่ active อยู่

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

ที่มา: ยกมาจาก deepcraft_task.c:687-688; UI variant page_edge_ai.c:353-368 (คอมไพล์รวมอยู่ใน archive สำเร็จรูป ไม่ได้ส่งมอบมาเป็นซอร์ส)

◆ ai_engine_active()

int ai_engine_active ( void )

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

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

ข้อกำหนดการเรียกใช้: คืนค่า s_current — คือโมเดลที่ LOADED แล้ว หรือ -1 เมื่อไม่มีโมเดลทำงานอยู่ (ai_engine.c:1866) ค่านี้ตามหลัง ai_engine_requested() อยู่เต็มหนึ่งช่วง cold-init ห้ามใช้ค่านี้เป็น gate ของ fallback: ข้อบกพร่องที่บันทึกไว้คือ "select Radar, Load, get Motion" (ai_engine.c:1868-1873, deepcraft_task.c:634-640) — ตัวกัน (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

ที่มา: ยกมาจาก deepcraft_task.c:301-311 (wire exposure) and :437 (คอมไพล์รวมอยู่ใน archive สำเร็จรูป ไม่ได้ส่งมอบมาเป็นซอร์ส)

◆ ai_engine_requested()

int ai_engine_requested ( void )

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

Index of the REQUESTED model (last ai_engine_start), or -1 when stopped. Leads ai_engine_active() by up to one inference-task tick. Guard a default-model fallback on this, never on ai_engine_active().

ข้อกำหนดการเรียกใช้: คืนค่า s_active — คือโมเดลที่ ai_engine_start() ครั้งล่าสุด REQUESTED ไว้ หรือ -1 เมื่อหยุดแล้ว (ai_engine.c:1874) ค่านี้คือตัวกันที่ถูกต้องสำหรับ 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

ที่มา: ยกมาจาก deepcraft_task.c:632 and :305-310 (คอมไพล์รวมอยู่ใน archive สำเร็จรูป ไม่ได้ส่งมอบมาเป็นซอร์ส)

◆ 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 ของตัวควบคุมทุกตัว: หน้านี้ใช้ค่านี้ 6 ครั้ง (page_edge_ai.c:353 ทำให้ปุ่มเป็น no-op, :1261/:1265 ป้าย "engine failed to start", :1338 เลือกระหว่าง CHIP_FAIL กับ CHIP_STOPPED, :895, :1466) ตัวนับอื่นทุกตัวในหน้าเหล่านี้ไม่มีความหมายตราบใดที่ค่านี้ยังเป็น 0 เป็นการอ่านที่ต้นทุนต่ำ เรียกได้จาก CM55 context ใด ๆ

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

ที่มา: ยกมาจาก page_edge_ai.c:353 (คอมไพล์รวมอยู่ใน archive สำเร็จรูป ไม่ได้ส่งมอบมาเป็นซอร์ส)

◆ 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 และห้ามอ่านทุกเฟรม; หน้านี้อ่านค่านี้เฉพาะในบรรทัดสถิติที่ออกวินาทีละครั้งเท่านั้น

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

ที่มา: ยกมาจาก page_edge_ai.c:1465 (คอมไพล์รวมอยู่ใน archive สำเร็จรูป ไม่ได้ส่งมอบมาเป็นซอร์ส)

Functions