samples: SMF: LVGL: SMF-based Calculator

This sample crates a touchscreen desk calculator based on
the sample state machine in _Practical UML Statecharts in
C/C++_ by Miro Samek.

Sample should build and run on any touchscreen-enabled
board with sufficient resources.

Tested on `disco_l475_iot1` board with
`adafruit_2_8_tft_touch_v2` touchscreen.

Signed-off-by: Glenn Andrews <[email protected]>

Author: glenn-andrews

samples/subsys/smf/smf_calculator/CMakeLists.txt

@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: Apache-2.0
+
+set(CMAKE_CXX_FLAGS "-fstack-usage")
+cmake_minimum_required(VERSION 3.20.0)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(smf_calculator_demo)
+
+target_sources(app PRIVATE src/main.c)
+target_sources(app PRIVATE src/smf_console_cmds.c)
+target_sources(app PRIVATE src/smf_calculator_thread.c)

samples/subsys/smf/smf_calculator/README.rst

@@ -0,0 +1,100 @@
+.. zephyr:code-sample:: smf_calculator
+   :name: SMF Calculator
+   :relevant-api: smf
+
+   Create a simple desk calculator using the State Machine Framework.
+
+Overview
+********
+
+This sample creates a basic desk calculator driven by a state machine written
+with the :ref:`State Machine Framework <smf>`.
+
+The 'business logic' of the calculator is based on the statechart given in
+Fig 2.18 of *Practical UML Statecharts in C/C++* 2nd Edition by Miro Samek.
+This uses a three-layer hierarchical statechart to handle situations such as
+ignoring leading zeroes, and disallowing multiple decimal points.
+
+The statechart has been slightly modified to display different output on the
+screen in the ``op_entered`` state depending on if a previous result is
+available or not.
+
+.. figure:: img/smf_calculator.svg
+    :align: center
+    :alt: SMF Calculator Statechart
+    :figclass: align-center
+
+    Statechart for the SMF Calculator business logic.
+
+The graphical interface uses an LVGL button matrix for input and text label for
+output, based on the sample in samples/drivers/display. The state machine updates
+the output text label after every call to :c:func:`smf_run_state`.
+
+:kconfig:option:`CONFIG_LV_Z_VDB_SIZE` has been reduced to 14% to allow it to run
+on RAM-constrained boards like the :ref:`disco_l475_iot1_board`.
+
+Requirements
+************
+
+The GUI should work with any touchscreen display supported by Zephyr. The shield
+must be passed to ``west build`` using the ``--shield`` option, e.g.
+``--shield adafruit_2_8_tft_touch_v2``
+
+List of Arduino-based touchscreen shields:
+
+- :ref:`adafruit_2_8_tft_touch_v2`
+- :ref:`buydisplay_2_8_tft_touch_arduino`
+- :ref:`buydisplay_3_5_tft_touch_arduino`
+
+The demo should also work on STM32 Discovery Kits with built-in touchscreens e.g.
+
+- :ref:`stm32f412g_disco_board`
+- :ref:`st25dv_mb1283_disco_board`
+- :ref:`stm32f7508_dk_board`
+- :ref:`stm32f769i_disco_board`
+
+etc. These will not need a shield defined as the touchscreen is built-in.
+
+
+Building and Running
+********************
+
+Below is an example on how to build for a :ref:`disco_l475_iot1_board` board with
+a :ref:`adafruit_2_8_tft_touch_v2`.
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/subsys/smf/smf_calculator
+   :board: disco_l475_iot1
+   :goals: build
+   :shield: adafruit_2_8_tft_touch_v2
+   :compact:
+
+For testing purpose without the need of any hardware, the :ref:`native_sim <native_sim>`
+board is also supported and can be built as follows;
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/subsys/smf/smf_calculator
+   :board: native_sim
+   :goals: build
+   :compact:
+
+CLI control
+===========
+
+As well as control through the GUI, the calculator can be controlled through the shell,
+demonstrating a state machine can receive inputs from multiple sources.
+The ``key <key>`` command sends a keypress to the state machine. Valid keys are
+``0`` through ``9`` for numbers, ``.``, ``+``, ``-``, ``*``, ``/`` and ``=`` to
+perform the expected function, ``C`` for Cancel, and ``E`` for Cancel Entry.
+
+GUI update speed on the :ref:`disco_l475_iot1_board` with :ref:`adafruit_2_8_tft_touch_v2`
+touchscreen is of the order of 0.8s due to button matrices invalidating the entire
+matrix area when pressed, rather than just the button that was selected. This could
+be sped up by using 18 individual buttons rather than a single matrix, but is sufficient
+for this demo.
+
+References
+**********
+
+*Practical UML Statecharts in C/C++* 2nd Edition by Miro Samek
+https://www.state-machine.com/psicc2

samples/subsys/smf/smf_calculator/img/smf_calculator.svg

@@ -0,0 +1,37 @@
+CONFIG_DEBUG=y
+CONFIG_LOG=y
+CONFIG_SHELL=y
+
+# Needed for boards that enable RTT backends for logging
+# e.g. nrf52840dk/nrf52840 and any others that enable it
+CONFIG_LOG_BACKEND_RTT=n
+
+# Enable the state machine framework
+CONFIG_SMF=y
+CONFIG_SMF_ANCESTOR_SUPPORT=y
+CONFIG_SMF_INITIAL_TRANSITION=y
+
+# Enable floating point support
+CONFIG_REQUIRES_FLOAT_PRINTF=y
+
+# Enable thread awareness for debugging tools supporting it
+CONFIG_DEBUG_THREAD_INFO=y
+
+# enable to use thread names
+CONFIG_THREAD_NAME=y
+
+# Display Options
+CONFIG_DISPLAY=y
+CONFIG_DISPLAY_LOG_LEVEL_ERR=y
+
+# LVGL Options
+CONFIG_LVGL=y
+CONFIG_LV_Z_MEM_POOL_SIZE=16384
+CONFIG_LV_Z_SHELL=y
+# Percentage of screen size for a video buffer
+# LVGL defaults sets this too high for resource-constrained boards.
+# 14% ~= 32KB RAM on adafruit_2_8_tft_touch_v2
+CONFIG_LV_Z_VDB_SIZE=14
+
+# extra large in case you want to enable LV_USE_REFR_DEBUG
+CONFIG_MAIN_STACK_SIZE=4096

samples/subsys/smf/smf_calculator/prj.conf

@@ -0,0 +1,23 @@
+sample:
+  description: SMF Calculator GUI Application
+  name: smf_calculator
+tests:
+  sample.smf.smf_calculator:
+    filter: dt_chosen_enabled("zephyr,display")
+    # Sample takes ~300k on disco_l475_iot1 board, add 50k just in case.
+    # Ram usage is 70k on disco_l475_iot1 board with adafruit_2_8_tft_touch_v2.
+    # Can be reduced by changing CONFIG_LV_Z_VDB_SIZE,
+    # CONFIG_LV_Z_MEM_POOL_SIZE and CONFIG_MAIN_STACK_SIZE.
+    min_flash: 350
+    min_ram: 75
+    harness: none
+    tags:
+      - samples
+      - display
+      - gui
+      - lvgl
+      - smf
+    modules:
+      - lvgl
+    integration_platforms:
+      - native_sim/native/64

samples/subsys/smf/smf_calculator/sample.yaml

@@ -0,0 +1,193 @@
+/*
+ * Copyright (c) 2024 Glenn Andrews
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "main.h"
+#include <zephyr/kernel.h>
+#include "smf_calculator_thread.h"
+#include <zephyr/drivers/display.h>
+#include <lvgl.h>
+#include <stdio.h>
+#include <string.h>
+#include <lvgl_input_device.h>
+#include <zephyr/logging/log.h>
+
+#define LOG_LEVEL CONFIG_LOG_DEFAULT_LEVEL
+LOG_MODULE_REGISTER(main_app);
+
+K_MSGQ_DEFINE(output_msgq, CALCULATOR_STRING_LENGTH, 2, 1);
+
+#define CALCULATOR_BUTTON_LABEL_LENGTH 4
+struct calculator_button {
+	char label[CALCULATOR_BUTTON_LABEL_LENGTH];
+	struct calculator_event event;
+};
+
+/**
+ * Important: this enum MUST be in the order of the buttons on the screen
+ * otherwise the mapping from button index to function will break
+ */
+enum calculator_ui_buttons {
+	BUTTON_CANCEL_ENTRY = 0,
+	BUTTON_CANCEL,
+	BUTTON_7,
+	BUTTON_8,
+	BUTTON_9,
+	BUTTON_DIVIDE,
+	BUTTON_4,
+	BUTTON_5,
+	BUTTON_6,
+	BUTTON_MULTIPLY,
+	BUTTON_1,
+	BUTTON_2,
+	BUTTON_3,
+	BUTTON_SUBTRACT,
+	BUTTON_0,
+	BUTTON_DECIMAL_POINT,
+	BUTTON_EQUALS,
+	BUTTON_ADD,
+};
+
+struct calculator_button buttons[] = {
+	[BUTTON_CANCEL_ENTRY] = {.label = "CE",
+				 .event = {.event_id = CANCEL_ENTRY, .operand = 'E'}},
+	[BUTTON_CANCEL] = {.label = "C", .event = {.event_id = CANCEL_BUTTON, .operand = 'C'}},
+	[BUTTON_ADD] = {.label = "+", .event = {.event_id = OPERATOR, .operand = '+'}},
+	[BUTTON_SUBTRACT] = {.label = "-", .event = {.event_id = OPERATOR, .operand = '-'}},
+	[BUTTON_MULTIPLY] = {.label = "*", .event = {.event_id = OPERATOR, .operand = '*'}},
+	[BUTTON_DIVIDE] = {.label = "/", .event = {.event_id = OPERATOR, .operand = '/'}},
+	[BUTTON_DECIMAL_POINT] = {.label = ".",
+				  .event = {.event_id = DECIMAL_POINT, .operand = '.'}},
+	[BUTTON_EQUALS] = {.label = "=", .event = {.event_id = EQUALS, .operand = '='}},
+	[BUTTON_0] = {.label = "0", .event = {.event_id = DIGIT_0, .operand = '0'}},
+	[BUTTON_1] = {.label = "1", .event = {.event_id = DIGIT_1_9, .operand = '1'}},
+	[BUTTON_2] = {.label = "2", .event = {.event_id = DIGIT_1_9, .operand = '2'}},
+	[BUTTON_3] = {.label = "3", .event = {.event_id = DIGIT_1_9, .operand = '3'}},
+	[BUTTON_4] = {.label = "4", .event = {.event_id = DIGIT_1_9, .operand = '4'}},
+	[BUTTON_5] = {.label = "5", .event = {.event_id = DIGIT_1_9, .operand = '5'}},
+	[BUTTON_6] = {.label = "6", .event = {.event_id = DIGIT_1_9, .operand = '6'}},
+	[BUTTON_7] = {.label = "7", .event = {.event_id = DIGIT_1_9, .operand = '7'}},
+	[BUTTON_8] = {.label = "8", .event = {.event_id = DIGIT_1_9, .operand = '8'}},
+	[BUTTON_9] = {.label = "9", .event = {.event_id = DIGIT_1_9, .operand = '9'}},
+};
+
+/* Where the result is printed */
+static lv_obj_t *result_label;
+
+/**
+ * LVGL v8.4 is not thread safe, so use a msgq to pass updates back
+ * to the thread that calls lv_task_handler()
+ */
+void update_display(const char *output)
+{
+	while (k_msgq_put(&output_msgq, output, K_NO_WAIT) != 0) {
+		k_msgq_purge(&output_msgq);
+	}
+}
+
+static void lv_btn_matrix_click_callback(lv_event_t *e)
+{
+	lv_event_code_t code = lv_event_get_code(e);
+	lv_obj_t *obj = lv_event_get_target(e);
+
+	if (code == LV_EVENT_PRESSED) {
+		uint32_t id;
+		int rc;
+
+		id = lv_btnmatrix_get_selected_btn(obj);
+		if (id >= ARRAY_SIZE(buttons)) {
+			LOG_ERR("Invalid button: %d", id);
+			return;
+		}
+
+		rc = post_calculator_event(&buttons[id].event, K_FOREVER);
+		if (rc != 0) {
+			LOG_ERR("could not post to msgq: %d", rc);
+		}
+	}
+}
+
+static int setup_display(void)
+{
+	const struct device *display_dev = DEVICE_DT_GET(DT_CHOSEN(zephyr_display));
+
+	if (!device_is_ready(display_dev)) {
+		LOG_ERR("Device not ready, aborting setup");
+		return -ENODEV;
+	}
+
+	static const char *const btnm_map[] = {buttons[BUTTON_CANCEL_ENTRY].label,
+					       buttons[BUTTON_CANCEL].label,
+					       "\n",
+					       buttons[BUTTON_7].label,
+					       buttons[BUTTON_8].label,
+					       buttons[BUTTON_9].label,
+					       buttons[BUTTON_DIVIDE].label,
+					       "\n",
+					       buttons[BUTTON_4].label,
+					       buttons[BUTTON_5].label,
+					       buttons[BUTTON_6].label,
+					       buttons[BUTTON_MULTIPLY].label,
+					       "\n",
+					       buttons[BUTTON_1].label,
+					       buttons[BUTTON_2].label,
+					       buttons[BUTTON_3].label,
+					       buttons[BUTTON_SUBTRACT].label,
+					       "\n",
+					       buttons[BUTTON_0].label,
+					       buttons[BUTTON_DECIMAL_POINT].label,
+					       buttons[BUTTON_EQUALS].label,
+					       buttons[BUTTON_ADD].label,
+					       "\n",
+					       ""};
+
+	lv_obj_t *btn_matrix = lv_btnmatrix_create(lv_scr_act());
+
+	lv_btnmatrix_set_map(btn_matrix, (const char **)btnm_map);
+	lv_obj_align(btn_matrix, LV_ALIGN_BOTTOM_MID, 0, 0);
+	lv_obj_set_size(btn_matrix, lv_pct(CALC_BTN_WIDTH_PCT), lv_pct(CALC_BTN_HEIGHT_PCT));
+	lv_obj_add_event_cb(btn_matrix, lv_btn_matrix_click_callback, LV_EVENT_ALL, NULL);
+
+	result_label = lv_label_create(lv_scr_act());
+	lv_obj_set_width(result_label, lv_pct(CALC_RESULT_WIDTH_PCT));
+	lv_obj_set_style_text_align(result_label, LV_TEXT_ALIGN_RIGHT, 0);
+	lv_obj_align(result_label, LV_ALIGN_TOP_MID, 0, lv_pct(CALC_RESULT_OFFSET_PCT));
+
+	static lv_style_t style_shadow;
+
+	lv_style_init(&style_shadow);
+	lv_style_set_shadow_width(&style_shadow, 5);
+	lv_style_set_shadow_spread(&style_shadow, 2);
+	lv_style_set_shadow_color(&style_shadow, lv_palette_main(LV_PALETTE_GREY));
+	lv_obj_add_style(result_label, &style_shadow, 0);
+	update_display("0");
+
+	lv_task_handler();
+	display_blanking_off(display_dev);
+
+	return 0;
+}
+
+int main(void)
+{
+	printk("SMF Desk Calculator Demo\n");
+
+	int rc = setup_display();
+
+	if (rc != 0) {
+		return rc;
+	}
+
+	while (1) {
+		char output[CALCULATOR_STRING_LENGTH];
+
+		if (k_msgq_get(&output_msgq, output, K_MSEC(50)) == 0) {
+			lv_label_set_text(result_label, output);
+		}
+
+		lv_task_handler();
+	}
+	return 0;
+}

samples/subsys/smf/smf_calculator/src/main.c

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) 2024 Glenn Andrews
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/* Constants for control sizes as a percentage of screen size. */
+#define CALC_BTN_WIDTH_PCT     90
+#define CALC_BTN_HEIGHT_PCT    80
+#define CALC_RESULT_WIDTH_PCT  70
+#define CALC_RESULT_OFFSET_PCT 10
+
+void update_display(const char *output);