README.rst
1.. zephyr:code-sample:: smf_calculator
2 :name: SMF Calculator
3 :relevant-api: smf
4
5 Create a simple desk calculator using the State Machine Framework.
6
7Overview
8********
9
10This sample creates a basic desk calculator driven by a state machine written
11with the :ref:`State Machine Framework <smf>`.
12
13The 'business logic' of the calculator is based on the statechart given in
14Fig 2.18 of *Practical UML Statecharts in C/C++* 2nd Edition by Miro Samek.
15This uses a three-layer hierarchical statechart to handle situations such as
16ignoring leading zeroes, and disallowing multiple decimal points.
17
18The statechart has been slightly modified to display different output on the
19screen in the ``op_entered`` state depending on if a previous result is
20available or not.
21
22.. figure:: img/smf_calculator.svg
23 :align: center
24 :alt: SMF Calculator Statechart
25 :figclass: align-center
26
27 Statechart for the SMF Calculator business logic.
28
29The graphical interface uses an LVGL button matrix for input and text label for
30output, based on the sample in samples/drivers/display. The state machine updates
31the output text label after every call to :c:func:`smf_run_state`.
32
33:kconfig:option:`CONFIG_LV_Z_VDB_SIZE` has been reduced to 14% to allow it to run
34on RAM-constrained boards like the :zephyr:board:`disco_l475_iot1`.
35
36Requirements
37************
38
39The GUI should work with any touchscreen display supported by Zephyr. The shield
40must be passed to ``west build`` using the ``--shield`` option, e.g.
41``--shield adafruit_2_8_tft_touch_v2``
42
43List of Arduino-based touchscreen shields:
44
45- :ref:`adafruit_2_8_tft_touch_v2`
46- :ref:`buydisplay_2_8_tft_touch_arduino`
47- :ref:`buydisplay_3_5_tft_touch_arduino`
48
49The demo should also work on STM32 Discovery Kits with built-in touchscreens e.g.
50
51- :zephyr:board:`stm32f412g_disco`
52- :zephyr:board:`st25dv_mb1283_disco`
53- :zephyr:board:`stm32f7508_dk`
54- :zephyr:board:`stm32f769i_disco`
55
56etc. These will not need a shield defined as the touchscreen is built-in.
57
58
59Building and Running
60********************
61
62Below is an example on how to build for a :zephyr:board:`disco_l475_iot1` board with
63a :ref:`adafruit_2_8_tft_touch_v2`.
64
65.. zephyr-app-commands::
66 :zephyr-app: samples/subsys/smf/smf_calculator
67 :board: disco_l475_iot1
68 :goals: build
69 :shield: adafruit_2_8_tft_touch_v2
70 :compact:
71
72For testing purpose without the need of any hardware, the :ref:`native_sim <native_sim>`
73board is also supported and can be built as follows;
74
75.. zephyr-app-commands::
76 :zephyr-app: samples/subsys/smf/smf_calculator
77 :board: native_sim
78 :goals: build
79 :compact:
80
81CLI control
82===========
83
84As well as control through the GUI, the calculator can be controlled through the shell,
85demonstrating a state machine can receive inputs from multiple sources.
86The ``key <key>`` command sends a keypress to the state machine. Valid keys are
87``0`` through ``9`` for numbers, ``.``, ``+``, ``-``, ``*``, ``/`` and ``=`` to
88perform the expected function, ``C`` for Cancel, and ``E`` for Cancel Entry.
89
90GUI update speed on the :zephyr:board:`disco_l475_iot1` with :ref:`adafruit_2_8_tft_touch_v2`
91touchscreen is of the order of 0.8s due to button matrices invalidating the entire
92matrix area when pressed, rather than just the button that was selected. This could
93be sped up by using 18 individual buttons rather than a single matrix, but is sufficient
94for this demo.
95
96References
97**********
98
99*Practical UML Statecharts in C/C++* 2nd Edition by Miro Samek
100https://www.state-machine.com/psicc2
101
