1.. zephyr:code-sample:: smf_hsm_psicc2
2   :name: Hierarchical State Machine Demo based on example from PSiCC2
3   :relevant-api: smf
4
5   Implement an event-driven hierarchical state machine using State Machine Framework (SMF).
6
7Overview
8********
9
10This sample demonstrates the :ref:`State Machine Framework <smf>` subsystem.
11
12Building and Running
13********************
14
15It should be possible to build and run this sample on almost any board or emulator.
16
17Building and Running for ST Disco L475 IOT01 (B-L475E-IOT01A)
18=============================================================
19The sample can be built and executed for the :zephyr:board:`disco_l475_iot1` as follows:
20
21.. zephyr-app-commands::
22   :zephyr-app: samples/subsys/smf/hsm_psicc2
23   :board: disco_l475_iot1
24   :goals: build flash
25   :compact:
26
27For other boards just replace the board name.
28
29Instructions for Use
30====================
31This application implements the statechart shown in Figure 2.11 of
32Practical UML Statecharts in C/C++, 2nd Edition, by Miro Samek (PSiCC2). Ebook available from
33https://www.state-machine.com/psicc2 This demo was chosen as it contains all possible transition
34topologies up to four levels of state nesting and is used with permission of the author.
35
36For each state, the entry, run, and exit actions are logged to the console, as well as logging
37when a state handles an event, or explicitly ignores it and passes it up to the parent state.
38
39There are two shell commands defined for controlling the operation.
40
41* ``psicc2 event <event>`` sends the event (from A to I) to the state machine. These correspond to
42  events A through I in PSiCC2 Figure 2.11
43* ``psicc2 terminate`` sends the ``EVENT_TERMINATE`` event to terminate the state machine. There
44  is no way to restart the state machine once terminated, and future events are ignored.
45
46Comparison to PSiCC2 Output
47===========================
48Not all transitions modelled in UML may be supported by the :ref:`State Machine Framework <smf>`.
49Unsupported transitions may lead to results different to the example run of the application in
50PSiCC2 Section 2.3.15. The differences will not be listed here as it is hoped :ref:`SMF <smf>`
51will support these transitions in the future and the list would become outdated.
52