12 Device State Machines: Transition Contracts

12.1 Start With the Decision

A transition contract connects current state, event, guard, action, target state, timeout, and log output

12.2 Route Overview

This is part 2 of 2. Review Device State Machines: Modes and Safety for the preceding evidence.

12.3 Learning Objectives

• Define transition contract with explicit inputs, errors, and change rules.
• Validate references with a concrete scenario and pass criteria.

12.4 Chapter Roadmap

• Transition Contract
• Knowledge Check: Transition Review
• Pattern 1: Connection Lifecycle
• Knowledge Check: Connection Lifecycle
• Pattern 2: Sampling and Power
• Pattern 3: Actuator Safety
• Safety Review Rule
• Knowledge Check: Safety Recovery
• Pattern 4: Cloud Shadow Reconciliation
• Checkpoint: Reusable IoT Patterns
• Hierarchical and Parallel State Machines
• Knowledge Check: State Explosion
• Implementation Pattern
• Knowledge Check: Rejected Events
• Architecture Review Checklist
• Checkpoint: Implementation and Review
• Common Pitfalls
• Label the Diagram
• Code Challenge
• Summary
• Key Takeaway
• Knowledge Check
• Quiz: State Machine Patterns
• Interactive Quiz: Match State Machine Pattern Concepts
• Interactive Quiz: Sequence the Steps
• Try It Yourself: State Machine Design Record
• References
• What’s Next
• Navigation

12.5 Transition Contract

Every transition should be readable enough that firmware, cloud, QA, and operations teams can review it together.

Before writing a transition table, inspect Figure 12.1 to see where eligibility, side effects, and evidence belong. The visual matters because mixing those responsibilities makes retries unsafe and field failures difficult to reconstruct.

In Figure 12.1, Current state and Event select a candidate transition; Guard decides whether that event is permitted before Action performs work. Only then does Target name the new stable state. Check Timeout for the missing-event path and Log for the record of what occurred. That ordering supplies the test structure used throughout the chapter: given a state and event, assert the guard result, action, target, timer behavior, and audit output. The diagram completes the evidence for Transition Contract.

TRANSITIONS = {
    ("IDLE", "sample_timer", "battery_ok"): ("WAKE_SENSOR", "power_sensor"),
    ("WAKE_SENSOR", "sensor_ready", "within_deadline"): ("SAMPLE", "read_sensor"),
    ("SAMPLE", "sample_ok", "network_available"): ("TRANSMIT", "send_message"),
    ("SAMPLE", "sample_ok", "network_unavailable"): ("BUFFER", "store_locally"),
    ("TRANSMIT", "ack_received", "always"): ("SLEEP", "schedule_next_wake"),
    ("TRANSMIT", "deadline_expired", "always"): ("BUFFER", "store_locally"),
    ("ANY", "watchdog_warning", "always"): ("SAFE_OFF", "disable_outputs"),
}

12.6 Pattern 1: Connection Lifecycle

A connection state machine protects the device from chaotic reconnect behavior and gives the cloud a clear view of whether the device is online, degraded, or intentionally disabled.

12.7 Pattern 2: Sampling and Power

Sampling state machines keep energy, latency, and data quality decisions visible. They also prevent work from happening in the wrong power mode.

Energy claims need a time sequence, not just a list of modes. Consult Figure 12.2 to see when the radio leaves Low Power, how long it waits for traffic or acknowledgement, and where it returns to sleep. This diagram tests Pattern 2: Sampling and Power.

Trace Figure 12.2 from Sleep (Low Power) through Listen. A received packet moves into Receive, whereas local data takes the Transmit path and waits at Wait ACK before the cycle can close. Compare that active interval with the Energy Savings timeline below it: the long sleep band, not the mere presence of a sleep state, is what reduces average power. The pattern therefore connects transition timing and acknowledgement policy to the battery-life claim.

12.8 Pattern 3: Actuator Safety

Actuator state machines need stricter recovery rules than telemetry workflows. The safe state should be easy to enter, and dangerous states should be hard to re-enter accidentally.

12.9 Pattern 4: Cloud Shadow Reconciliation

Cloud shadows, device twins, and desired-reported property models are state reconciliation patterns. They work best when the device treats cloud instructions as events and reports its actual state honestly.

Cloud reconciliation becomes unsafe when desired and observed state are treated as one value. Use Figure 12.3 to separate the application’s request from the device’s report and to locate the delta that drives a legitimate transition. This diagram tests Pattern 4: Cloud Shadow Reconciliation.

In Figure 12.3, the Application writes a desired value such as Set Temperature, while the Physical Device publishes reported state through the named MQTT Topics. The delta exists only while those values differ; it is not proof that the actuator already changed. This distinction carries the running transition contract into the cloud: version the request, apply it idempotently on the device, and acknowledge the resulting reported state before declaring reconciliation complete. The diagram completes the evidence for Pattern 4: Cloud Shadow Reconciliation.

12.10 Hierarchical and Parallel State Machines

Simple FSMs are enough for many devices. When the state count grows, use hierarchy or parallel regions rather than multiplying every combination into a new flat state.

One flat machine would multiply every link, buffer, command, and service mode into an unmanageable cross-product. Inspect Figure 12.4 to see how independent machines retain their own states while exchanging a small set of explicit events.

Read Figure 12.4 across the Link machine, Buffer machine, Command machine, and Service machine rather than inventing one combined state. When the link changes from offline to online, it can emit an event that lets the buffer flush without rewriting command logic. A separate command_expired event allows the command machine to reject stale work even if the service is otherwise healthy. The event contracts preserve coordination while keeping each machine testable, which is the reason to introduce parallel state machines here.

12.11 Implementation Pattern

A table-driven state machine is often easier to review and test than a long chain of conditional branches.

from dataclasses import dataclass


@dataclass(frozen=True)
class Transition:
    source: str
    event: str
    guard: str
    target: str
    action: str


class DeviceStateMachine:
    def __init__(self, initial_state, transitions, actions, guards):
        self.state = initial_state
        self.transitions = transitions
        self.actions = actions
        self.guards = guards

    def dispatch(self, event, context):
        candidates = [
            t for t in self.transitions
            if t.event == event and t.source in (self.state, "ANY")
        ]
        for transition in candidates:
            guard = self.guards.get(transition.guard, lambda _: False)
            if guard(context):
                previous = self.state
                self.actions[transition.action](context)
                self.state = transition.target
                context.log_transition(previous, event, self.state)
                return self.state
        context.log_rejected_event(self.state, event)
        return self.state

12.12 Architecture Review Checklist

Use this checklist before implementing firmware, cloud workflows, or device-twin reconciliation.

12.13 Common Pitfalls

12.14 Summary

Taken together, these checks make the section reviewable. That order makes timing, persistence, and recovery part of the behaviour contract, so the later implementation and test record can prove deterministic outcomes.

12.15 Key Takeaway

Use a state machine whenever device behavior depends on mode, history, safety, or connectivity. Explicit states, events, guards, actions, timeouts, and rejected-event logs make field failures easier to prevent and diagnose.

12.16 Knowledge Check

12.17 Try It Yourself: State Machine Design Record

Choose one IoT workflow and complete a design record before coding.

state_machine: device-command-lifecycle
initial_state: SAFE_OFF
states:
  - SAFE_OFF
  - ARMED
  - ACTIVE
  - LIMITED
  - EMERGENCY_STOP
  - LOCKOUT
events:
  - arm_requested
  - start_requested
  - stop_requested
  - limit_exceeded
  - watchdog_warning
  - inspected_reset
transition_example:
  source: ACTIVE
  event: limit_exceeded
  guard: sensor_reading_is_valid
  action: reduce_output_and_log_fault
  target: LIMITED
  timeout: move_to_emergency_stop
invalid_event_policy:
  in_lockout: reject_and_log
observability:
  transition_log_fields:
    - previous_state
    - event
    - guard_result
    - target_state
    - timestamp
    - firmware_version
tests:
  - invalid_event_in_each_state
  - timeout_from_each_waiting_state
  - reboot_from_each_persisted_state
  - emergency_stop_priority

Review the record with someone who owns operations or safety. The best state-machine reviews find missing events before they become field failures.

12.18 References

Taken together, these checks make the section reviewable. That order makes timing, persistence, and recovery part of the behaviour contract, so the later implementation and test record can prove deterministic outcomes.

12.19 What’s Next

12.20 Navigation

12.21 Continue Your Route

This final part closes the route from Transition Contract through Navigation. Return to Device State Machines: Modes and Safety or continue from the design-patterns module index.