zephyr-smf

Zephyr State Machine Framework (SMF)

Overview

SMF is an application-agnostic framework for integrating state machines into Zephyr applications. Enable with CONFIG_SMF=y.

Core Concepts

State Structure

Every state has three optional actions:

• Entry: Executes when entering the state
• Run: Executes on each smf_run_state() call
• Exit: Executes when leaving the state

// User object MUST have smf_ctx as FIRST member
struct s_object {
    struct smf_ctx ctx;  // MUST be first
    /* application-specific data */
};

State Definition

enum app_state { STATE_IDLE, STATE_ACTIVE, STATE_ERROR };

static const struct smf_state app_states[] = {
    [STATE_IDLE]   = SMF_CREATE_STATE(idle_entry, idle_run, idle_exit, NULL, NULL),
    [STATE_ACTIVE] = SMF_CREATE_STATE(active_entry, active_run, NULL, NULL, NULL),
    [STATE_ERROR]  = SMF_CREATE_STATE(NULL, error_run, error_exit, NULL, NULL),
};

SMF_CREATE_STATE parameters: (entry, run, exit, parent, initial)

• Set unused actions to NULL
• parent: For hierarchical states (requires CONFIG_SMF_ANCESTOR_SUPPORT)
• initial: Initial child state (requires CONFIG_SMF_INITIAL_TRANSITION)

Action Signatures

// Entry and exit actions
static void state_entry(void *o) { /* ... */ }
static void state_exit(void *o) { /* ... */ }

// Run action - returns event handling result
static enum smf_state_result state_run(void *o) {
    struct s_object *s = (struct s_object *)o;
    // Process events, trigger transitions
    return SMF_EVENT_HANDLED;  // or SMF_EVENT_PROPAGATE for HSM
}

Workflow

1. Determine State Machine Type

Type	Use Case	Kconfig
Flat	Simple sequential states, no nesting	CONFIG_SMF=y
Hierarchical (HSM)	Shared behavior, nested states	Add CONFIG_SMF_ANCESTOR_SUPPORT=y
HSM + Initial Transitions	Auto-transition to child states	Add CONFIG_SMF_INITIAL_TRANSITION=y

Step 1a: For flat state machines, proceed to step 2.