Each state gets its own handler function. The dispatcher is a pure switch(state). A unified fault-threshold check runs after all state handlers — no handler triggers the error transition itself. This keeps handlers simple and fault logic centralized.
// === State enum: exactly one valid state at all times ===\ntypedef enum {\n COMM_STATE_INIT,\n COMM_STATE_IDLE,\n COMM_STATE_SAMPLE_STARTING,\n COMM_STATE_SAMPLING,\n COMM_STATE_ERROR,\n COMM_STATE_RECOVERING,\n} comm_state_t;\n\n// === Runtime context: all flags explicit in one struct ===\ntypedef struct {\n comm_state_t state;\n uint32_t command_fail_count;\n bool data_ready;\n bool communication_lost;\n} comm_runtime_t;\n\n// === Per-state handlers: each reads only what it needs ===\nstatic void comm_handle_idle(comm_runtime_t *rt) {\n rt->warmup_start_time = sys_tick();\n comm_start_sample();\n rt->state = COMM_STATE_SAMPLE_STARTING;\n}\n\nstatic void comm_handle_error(comm_runtime_t *rt) {\n static uint32_t retry_tick = 0;\n if (retry_tick == 0) {\n retry_tick = sys_tick();\n rt->data_ready = false;\n }\n comm_power_off();\n if (sys_tick() - retry_tick < 500) return; // 500ms cooldown\n retry_tick = 0;\n rt->state = COMM_STATE_RECOVERING;\n}\n\nstatic void comm_handle_recovering(comm_runtime_t *rt) {\n comm_handle_initializing(rt); // Recovery RE-USES init — no duplicated paths\n}\n\n// === Dispatcher: pure switch, single exit ===\nstatic void comm_state_process(comm_runtime_t *rt) {\n switch (rt->state) {\n case COMM_STATE_INIT: comm_handle_initializing(rt); break;\n case COMM_STATE_IDLE: comm_handle_idle(rt); break;\n case COMM_STATE_SAMPLE_STARTING: comm_handle_sample_starting(rt);break;\n case COMM_STATE_SAMPLING: comm_handle_sampling(rt); break;\n case COMM_STATE_ERROR: comm_handle_error(rt); break;\n case COMM_STATE_RECOVERING: comm_handle_recovering(rt); break;\n default:\n rt->state = COMM_STATE_INIT; // Unknown state → safe fallback\n break;\n }\n\n // Unified error gate: checked AFTER every state, not buried inside handlers.\n // A new state cannot accidentally bypass this check.\n if (rt->command_fail_count >= COMM_MAX_FAILS) {\n rt->state = COMM_STATE_ERROR;\n rt->command_fail_count = 0;\n rt->communication_lost = true;\n }\n}\nKey properties:
\ncomm_handle_recovering() calls comm_handle_initializing(). No duplicated paths to drift apart.Error has a cooldown period (500ms), then transitions to Recovering. No fall-through, no implicit assumption.default case resets to Init.Heavier than switch-case, but useful when states are added/removed frequently or handlers need different signatures.
\nstatic const struct {\n comm_state_t state;\n void (*process)(void);\n} comm_state_table[] = {\n {COMM_STATE_INIT, comm_init_process},\n {COMM_STATE_IDLE, comm_idle_process},\n {COMM_STATE_CONNECTED, comm_connected_process},\n {COMM_STATE_ERROR, comm_error_process},\n {COMM_STATE_RECOVERING, comm_recovering_process},\n};\n\nvoid comm_state_dispatch(void) {\n for (size_t i = 0; i < ARRAY_LEN(comm_state_table); i++) {\n if (g_comm_runtime.state == comm_state_table[i].state\n && comm_state_table[i].process != NULL) {\n comm_state_table[i].process();\n return;\n }\n }\n // Unknown state: reset to safe default\n g_comm_runtime.state = COMM_STATE_INIT;\n}\nAll core rules in one function: timeout gated only when work is pending, explicit retry count, predefined max retries, all exits defined.
\nstatic void comm_ack_check(uint32_t now_sec) {\n // GUARD: timeout logic only runs when there is real pending work\n if (!g_comm.report_in_progress) return;\n\n // GUARD: timeout hasn't expired yet\n if (elapsed_sec(g_comm.send_time, now_sec) < COMM_ACK_TIMEOUT_S) return;\n\n // Timeout fired. Explicit retry branch:\n if (g_comm.retry_count == 0) {\n g_comm.retry_count++;\n g_comm.send_time = now_sec;\n comm_send_report(); // One automatic retry\n return;\n }\n // All retries exhausted → terminal exit\n g_comm.report_in_progress = false;\n g_comm.retry_count = 0; // Reset for next cycle\n comm_report_result(false); // Notify caller: failed\n}\n// BAD: implicit state via flags — new flag creates untested state combinations\nif (g_flags.busy && !g_flags.paused && g_flags.online) { ... }\n// Fix: use explicit enum — exactly one valid state at all times\n\n// BAD: idle state triggers timeout — retry fires with nothing pending\nif (elapsed_ms(t0, now) > TIMEOUT) { retry(); }\n// t0 is always running, even when no work is in flight\n\n// BAD: retry loop with no exit condition\nvoid retry_forever(void) {\n while (!send_packet()) { delay(100); } // Will lock up if HW is dead\n}\n\n// BAD: recovery path duplicates init logic instead of reusing it.\n// The copy drifts over time — one path gets a fix, the other doesn't.\n\n// BAD: Error handler directly calls power_off() without cooldown period.\n// Power-cycling faster than the hardware spec causes unpredictable state.\nREQUIRED SUB-SKILL: If you find a state machine bug, also load Skill(\"debug-methodology\") to apply structured root-cause analysis. If the bug involves async lifecycle flags or hardware events, load Skill(\"embedded-firmware-dev\"). If the state machine lockup triggers a watchdog reset or HardFault, load Skill(\"hardfault-triage\").