Radio scheduler

Functions
void	radio_scheduler_set_on_state (radio_scheduler_on_state_fn_t cb)
	ติดตั้ง hook ของสถานะ ต้องเรียกก่อน radio_scheduler_init() มิฉะนั้นจะพลาดการเปลี่ยนสถานะครั้งแรก
bool	radio_scheduler_init (const radio_scheduler_config_t *cfg)
	สร้างตัวชี้ขาด (arbiter) เรียกก่อน scheduler เริ่มทำงานได้ คืน true ทั้งเมื่อสำเร็จและเมื่อ init ซ้ำ
void	nus_radio_emit_state_event (const struct radio_status_s *st)
	hook on_state ที่ส่งมอบจริง — ใช้เป็นพอยน์เตอร์ฟังก์ชันเท่านั้น ห้ามเรียกโดยตรง
radio_mode_t	radio_scheduler_get_mode (void)
	อ่านโหมดโดยไม่ต้องจับ lock — เป็นตัวกัน (guard) มาตรฐานของความเป็นเอกสิทธิ์ระหว่าง Wi-Fi กับ BLE บน RF เดียว
void	radio_scheduler_get_status (radio_status_t *out)
	snapshot สถานะเต็มชุดภายใต้ mutex ของ scheduler มี timeout 50 ms ต้องคัดลอก ssid ออกมา
bool	radio_scheduler_request_mode (radio_mode_t target)
	จัดคิวการเปลี่ยนโหมดแบบอะซิงโครนัส ให้ยืนยันผลผ่าน hook หรือด้วยการวนถามค่าโหมด
bool	radio_scheduler_set_wifi_creds (const char *ssid, const char *password, const char *security, bool auto_switch)
	บันทึกข้อมูลรับรอง Wi-Fi ผ่าน hook LFS ของผู้ใช้ไลบรารี และจัดคิวการสลับโหมดต่อไปด้วยก็ได้
void	radio_scheduler_set_boot_mode (radio_boot_mode_t mode)
	คงค่าโหมดบูตที่ต้องการไว้ผ่าน hook สำหรับการคงค่า ถ้า hook เป็น NULL จะไม่มีอะไรรอดข้ามการบูตใหม่
radio_boot_mode_t	radio_scheduler_get_boot_mode (void)
	โหมดบูตที่คงค่าไว้ เมื่อ hook เป็น NULL ตามที่ส่งมอบจริง ทุกการบูตจะโหลดเป็น AUTO
const char *	radio_mode_str (radio_mode_t m)
	ตารางแปลงโหมดเป็นสตริงล้วน ๆ คืน literal แบบ static ค่านอกช่วงคืน "invalid" — ใช้กับ s ได้อย่างปลอดภัย

Detailed Description

สิบ symbol: ตัวชี้ขาด (arbiter) ระหว่าง BLE กับ Wi-Fi บน RF เดียว (radio_scheduler_*, radio_mode_str) และตัวส่ง event สถานะของมัน (nus_radio_emit_state_event) คอมไพล์เฉพาะเมื่อ ENABLE_PAGE_BENTO_BUDDY=1 (ค่าตั้งต้นคือ 0, proj_cm33_ns/Makefile:64, :305) ให้ build ใหม่หลังจาก make getlibs — ดู Flag gate (อ่านก่อน)

การประกาศ: radio_scheduler.h (radio_scheduler_* ทั้งหมด, radio_mode_str และชนิด radio_status_t / radio_scheduler_config_t) กับ nus_commands.h (nus_radio_emit_state_event) ส่วนการนำไปสร้างจริงใน radio_scheduler.c / nus_commands.c ถูกเก็บไว้ใน libbento_secure.a

symbol 3 ตัวคือ radio_scheduler_set_on_state(), radio_scheduler_init() และ nus_radio_emit_state_event() ปรากฏอยู่ในบล็อกเดียวกันของที่ส่งมอบจริง (proj_cm33_ns/main.c:325-357) การบันทึกทั้งสามไว้ด้วยกันจึงตรงกับสิ่งที่เฟิร์มแวร์ทำ บล็อกนั้นเรนเดอร์ไว้ครั้งเดียวดังนี้:

#if ENABLE_PAGE_BENTO_BUDDY
    /* Two-layer BLE bring-up:
     *
     *   1. bento_buddy_auto_start_install — the legacy 3-s-delayed task
     *      that brings up the AIROC BLE host stack. Proven path: kept as
     *      the boot-time owner of ble_nus_init. Smoke tests showed that
     *      calling ble_nus_init from any other context (notably the
     *      radio_scheduler worker) fails with state=ERROR even with the
     *      same 3-s delay — the original task's stack/priority is what
     *      the AIROC HCI bring-up actually needs.
     *
     *   2. radio_scheduler — runtime arbiter for BLE↔Wi-Fi mode switches.
     *      Initialised AFTER auto_start so it doesn't race the AIROC init.
     *      Phase 1 only services the verbs (radio.status / radio.switch /
     *      wifi.set_creds) and persists creds; the actual swap-radio path
     *      is exercised by user action, not at boot. Saved-creds auto-Wi-Fi
     *      moves to Phase 2 once the persistence hooks (LFS boot_mode +
     *      LCD long-press) are wired. */
    {
        /* Replace bento_buddy_auto_start_install with our chip-power-then-BLE
         * variant — the legacy task skipped the WL_REG_ON / WCM init step,
         * which CYW55513 needs for BLE controller bring-up. */
        install_chip_power_then_ble();
 
        extern void nus_radio_emit_state_event(const struct radio_status_s *st);
        radio_scheduler_config_t cfg = {
            .persist_boot_mode = NULL,
            .load_boot_mode    = NULL,
        };
        radio_scheduler_set_on_state(nus_radio_emit_state_event);
        (void)radio_scheduler_init(&cfg);
    }
#endif

variant ที่ใช้ได้

mtb-mpy และ mtb-only

Function Documentation

radio_scheduler_set_on_state()

void radio_scheduler_set_on_state

(

radio_scheduler_on_state_fn_t

cb

)

ติดตั้ง hook ของสถานะ ต้องเรียกก่อน radio_scheduler_init() มิฉะนั้นจะพลาดการเปลี่ยนสถานะครั้งแรก

ข้อกำหนดการเรียกใช้

ต้องเรียกก่อน radio_scheduler_init() — ฟังก์ชันนี้เป็นเพียงการกำหนดค่าตรง ๆ โดยไม่มีการจับ lock (radio_scheduler.c:418-421) และ radio_scheduler_init() ทำให้เกิดการเปลี่ยนสถานะครั้งแรกที่ radio_scheduler.c:319 hook ที่ตั้งภายหลังจึงพลาดการเปลี่ยนสถานะครั้งนั้นไป เฟิร์มแวร์ที่ส่งมอบจริงต่อ hook นี้ไว้กับ nus_radio_emit_state_event() call site ในเทมเพลต: 1 (บล็อกที่เรนเดอร์ไว้ใน Radio scheduler)

variant ที่ใช้ได้

mtb-mpy และ mtb-only

radio_scheduler_init()

bool radio_scheduler_init

(

const radio_scheduler_config_t *

cfg

)

สร้างตัวชี้ขาด (arbiter) เรียกก่อน scheduler เริ่มทำงานได้ คืน true ทั้งเมื่อสำเร็จและเมื่อ init ซ้ำ

ข้อกำหนดการเรียกใช้

เรียกก่อน scheduler เริ่มทำงานได้ — ฟังก์ชันนี้ใช้ xSemaphoreCreateMutexStatic, xQueueCreateStatic และ xTaskCreate (radio_scheduler.c:279-287) และการเรียกที่ส่งมอบจริงอยู่ใน main() ก่อน vTaskStartScheduler() ให้ init หลังจากที่ auto-start ของ BLE ถูกจัดเข้าคิวไว้แล้ว เพื่อไม่ให้ชิงกับ init ของ AIROC (main.c:336-337) คืนค่า true ทั้งเมื่อสำเร็จ และ เมื่อ init ซ้ำ (เป็นตัวกันการเข้าซ้ำโดยเจตนา :271-275) คืน false เฉพาะเมื่อ xTaskCreate ล้มเหลว cfg.persist_boot_mode / cfg.load_boot_mode เป็น NULL ได้โดยชอบ (:291-294, :403-416 ตรวจค่า null ให้แล้วถอยไปใช้ RADIO_BOOT_AUTO) task ที่ทำงานเบื้องหลังหน่วง 3000 ms ก่อนเริ่มให้บริการคิว (radio_scheduler.c:238) ด้วยเหตุผลเรื่องการตั้งตัวของ AIROC ผู้เรียกที่มีอยู่จริงในของที่ส่งมอบแคสต์ค่าที่คืนทิ้งด้วย (void) call site ในเทมเพลต: 1 (บล็อกที่เรนเดอร์ไว้ใน Radio scheduler)

variant ที่ใช้ได้

mtb-mpy และ mtb-only

nus_radio_emit_state_event()

void nus_radio_emit_state_event

(

const struct radio_status_s *

st

)

hook on_state ที่ส่งมอบจริง — ใช้เป็นพอยน์เตอร์ฟังก์ชันเท่านั้น ห้ามเรียกโดยตรง

ข้อกำหนดการเรียกใช้

ใช้เป็น พอยน์เตอร์ฟังก์ชัน เท่านั้น — ส่งเข้าไปให้ radio_scheduler_set_on_state() ห้ามเรียกโดยตรง ตัวฟังก์ชัน (nus_commands.c:1443-1469) ตรวจค่า null ของ st จัดรูป event bento.radio.state แล้วเรียก nus_emit_event() ฟังก์ชันนี้อยู่ใน nus_commands.c เพื่อให้ radio_scheduler.c ไม่ต้องพึ่งตัวประกอบเฟรมของ NUS call site ในเทมเพลต: 1 (บล็อกที่เรนเดอร์ไว้ใน Radio scheduler ในรูปพอยน์เตอร์ ส่วน extern ที่ประกาศไว้เองที่ main.c:349 ใช้ struct tag ที่ประกาศล่วงหน้าไว้)

variant ที่ใช้ได้

mtb-mpy และ mtb-only

ที่มา

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

radio_scheduler_get_mode()

radio_mode_t radio_scheduler_get_mode

(

void

)

อ่านโหมดโดยไม่ต้องจับ lock — เป็นตัวกัน (guard) มาตรฐานของความเป็นเอกสิทธิ์ระหว่าง Wi-Fi กับ BLE บน RF เดียว

ข้อกำหนดการเรียกใช้

ไม่ต้องจับ lock — "Reads of a single enum are atomic on Cortex-M33; skip the mutex" (radio_scheduler.c:387) เรียกได้จากทุก context รวมทั้ง REPL ของ MicroPython คืน RADIO_MODE_UNKNOWN ก่อนที่ radio_scheduler_init() จะทำงาน ฟังก์ชันนี้คือตัวกันมาตรฐานของความเป็นเอกสิทธิ์ระหว่าง Wi-Fi กับ BLE บน RF เดียว และตัวกันนั้น ขึ้นกับเงื่อนไขตอน build: ถูกข้ามไปเมื่อ BENTO_HAS_DUAL_BAND == 1 เพราะ COEX บนไดของ CYW55513 แบ่งเวลาให้ Wi-Fi กับ BLE ได้ Wi-Fi ได้รับอนุญาตเฉพาะใน RADIO_MODE_WIFI_ACTIVE, RADIO_MODE_SWITCHING_TO_WIFI และ RADIO_MODE_WIFI_FAILED (เส้นทาง retry) เท่านั้น ถ้าต้องการ snapshot ครบทั้งชุดให้ใช้ radio_scheduler_get_status() (มี mutex, timeout 50 ms) call site ในเทมเพลต: 1

variant ที่ใช้ได้

mtb-mpy และ mtb-only

call site ในเทมเพลตแห่งเดียว (มีเฉพาะใน zip ของ mtb-mpy ยกมาเป็นข้อความ)

bento_libs/claw/common/mpy/modwifi.c:52-79 marker tag ble_radio_scheduler_single_rf_guard — ภายใต้ BENTO_HAS_BLE_NUS == 1 && !BENTO_HAS_DUAL_BAND wifi.connect() อ่านค่าโหมดแล้ว raise OSError("WiFi unavailable: BLE is active. Use the Desktop Buddy or call bento_buddy.stop() to switch radio mode first.") เว้นแต่โหมดปัจจุบันเป็นหนึ่งใน 3 โหมดของ Wi-Fi

ตัวนิยามที่อยู่ใน archive (เรนเดอร์ไว้พร้อมกับ radio_scheduler_get_status()) แสดงการอ่านที่ไม่ต้องใช้ mutex

radio_scheduler_get_status()

void radio_scheduler_get_status

(

radio_status_t *

out

)

snapshot สถานะเต็มชุดภายใต้ mutex ของ scheduler มี timeout 50 ms ต้องคัดลอก ssid ออกมา

ข้อกำหนดการเรียกใช้

จับ mutex ของ scheduler ด้วย timeout 50 ms เมื่อหมดเวลาจะล้าง *out เป็นศูนย์แล้วเติมเฉพาะ mode (radio_scheduler.c:391-401) ฟิลด์ ssid ชี้ไปยังที่เก็บซึ่ง scheduler เป็นเจ้าของ ใช้ได้จนถึงการเปลี่ยนโหมดครั้งถัดไป — ต้องคัดลอกออกมาก่อนออกจาก context ที่เรียก ค่า out ที่เป็น NULL จะถูกละเลย ต้องอยู่ใน task context (mutex) call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ nus_commands.c:1349 (radio_scheduler_get_status(&st); คือ verb สถานะ คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

variant ที่ใช้ได้

mtb-mpy และ mtb-only

ที่มา

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

radio_scheduler_request_mode()

bool radio_scheduler_request_mode

(

radio_mode_t

target

)

จัดคิวการเปลี่ยนโหมดแบบอะซิงโครนัส ให้ยืนยันผลผ่าน hook หรือด้วยการวนถามค่าโหมด

ข้อกำหนดการเรียกใช้

เป็น idempotent (เรียกซ้ำแล้วผลเหมือนเดิม) — การขอโหมดที่เป็นอยู่แล้วเป็น no-op คืน true เมื่อการเปลี่ยนโหมดถูก จัดเข้าคิว แล้ว คืน false เมื่อถูกปฏิเสธ (เช่น ขอ Wi-Fi ทั้งที่ไม่มีข้อมูลรับรองบันทึกไว้) การเปลี่ยนเป็นแบบอะซิงโครนัส: ให้ยืนยันผลผ่าน hook on_state หรือด้วยการวนถาม radio_scheduler_get_mode() call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ nus_commands.c:1389 (if (!radio_scheduler_request_mode(want)) { — verb bento.radio.set ตอบ nack เมื่อได้ false คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

variant ที่ใช้ได้

mtb-mpy และ mtb-only

radio_scheduler_set_wifi_creds()

bool radio_scheduler_set_wifi_creds	(	const char *	ssid,
		const char *	password,
		const char *	security,
		bool	auto_switch )

บันทึกข้อมูลรับรอง Wi-Fi ผ่าน hook LFS ของผู้ใช้ไลบรารี และจัดคิวการสลับโหมดต่อไปด้วยก็ได้

ข้อกำหนดการเรียกใช้

บันทึกข้อมูลรับรองผ่าน hook lfs_save_wifi_creds ของผู้ใช้ไลบรารี (WiFi overridables (นิยามเอง ห้ามเรียก)) เมื่อ auto_switch = true จะจัดคิวการเปลี่ยนไปยัง Wi-Fi ต่อจากการบันทึกด้วย คืน false เมื่อการตรวจความถูกต้องไม่ผ่าน (SSID ยาวเกินไป และอื่น ๆ) หรือเมื่อการเขียน LFS ล้มเหลว ต้องอยู่ใน task context (hook เขียนลงหน่วยความจำแฟลช) call site ในเทมเพลต: 0 call site ใน archive อยู่ที่ nus_commands.c:1429 (if (!radio_scheduler_set_wifi_creds(ssid, pass, sec[0] ? sec : NULL, ... — สตริง security ที่ว่างเปล่าถูกส่งเป็น NULL คอมไพล์รวมอยู่ใน libbento_secure.a ไม่ได้ส่งมอบมาเป็นซอร์ส)

variant ที่ใช้ได้

mtb-mpy และ mtb-only

radio_scheduler_set_boot_mode()

void radio_scheduler_set_boot_mode

(

radio_boot_mode_t

mode

)

คงค่าโหมดบูตที่ต้องการไว้ผ่าน hook สำหรับการคงค่า ถ้า hook เป็น NULL จะไม่มีอะไรรอดข้ามการบูตใหม่

ข้อกำหนดการเรียกใช้

คงค่าโหมดบูตที่ต้องการไว้ผ่าน hook persist_boot_mode ที่ให้ไว้ตอน init เมื่อ hook เป็น NULL ซึ่งเป็นค่าตั้งต้นที่ส่งมอบจริง (main.c:350-353) จะไม่มีอะไรรอดข้ามการบูตใหม่ และการบูตครั้งถัดไปจะตัดสินเป็น RADIO_BOOT_AUTO ฟังก์ชันนี้ไม่ได้สลับ radio การสลับเป็นหน้าที่ของ radio_scheduler_request_mode() ไม่มีผู้เรียกที่ใดเลย

variant ที่ใช้ได้

mtb-mpy และ mtb-only

ตัวอย่าง (เขียนขึ้นเอง — ไม่มี call site ในของที่ส่งมอบจริง)

__attribute__((used))
static void bento_ex_radio_scheduler_set_boot_mode(void)
{
    /* LCD long-press handler: pin this board to BLE across reboots
     * (takes effect only if persistence hooks were supplied at init): */
    radio_scheduler_set_boot_mode(RADIO_BOOT_FORCE_BLE);
 
    /* Escape hatch after a router move — force the next boot to try
     * Wi-Fi even though the last three connects failed:
     *   radio_scheduler_set_boot_mode(RADIO_BOOT_FORCE_WIFI);
     */
}

radio_scheduler_get_boot_mode()

radio_boot_mode_t radio_scheduler_get_boot_mode

(

void

)

โหมดบูตที่คงค่าไว้ เมื่อ hook เป็น NULL ตามที่ส่งมอบจริง ทุกการบูตจะโหลดเป็น AUTO

ข้อกำหนดการเรียกใช้

คืนโหมดบูตที่คงค่าไว้ (AUTO / FORCE_BLE / FORCE_WIFI) เรื่อง hook ที่เป็น NULL เป็นแบบเดียวกับ radio_scheduler_set_boot_mode(): เมื่อใช้การตั้งค่าที่ส่งมอบจริง ทุกการบูตจะโหลดเป็น RADIO_BOOT_AUTO ไม่มีผู้เรียกที่ใดเลย

variant ที่ใช้ได้

mtb-mpy และ mtb-only

ตัวอย่าง (เขียนขึ้นเอง — ไม่มี call site ในของที่ส่งมอบจริง)

__attribute__((used))
static void bento_ex_radio_scheduler_get_boot_mode(void)
{
    radio_boot_mode_t bm = radio_scheduler_get_boot_mode();
    if (bm != RADIO_BOOT_AUTO) {
        /* User override in force (FORCE_BLE / FORCE_WIFI) — render the
         * "override" badge. With NULL persistence hooks this branch is
         * unreachable across reboots: everything loads as AUTO. */
    }
}

radio_mode_str()

const char * radio_mode_str

(

radio_mode_t

m

)

ตารางแปลงโหมดเป็นสตริงล้วน ๆ คืน literal แบบ static ค่านอกช่วงคืน "invalid" — ใช้กับ s ได้อย่างปลอดภัย

ข้อกำหนดการเรียกใช้

เป็นฟังก์ชันล้วน reentrant ไม่ต้อง init คืนค่าเป็น string literal แบบ static — ห้าม free และห้ามแก้ค่านั้น ค่านอกช่วงคืน "invalid" (radio_scheduler.c:116) การใช้กับ s จึงปลอดภัยโดยไม่มีเงื่อนไข คำศัพท์ที่ใช้บนสาย: unknown | ble_adv | ble_paired | switching_to_wifi | wifi_active | switching_to_ble | wifi_failed call site ในเทมเพลต: 0 (ใน archive: 3)

variant ที่ใช้ได้

mtb-mpy และ mtb-only

ที่มา

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