Samples: SMF: Add sample for SMF framework

This PR adds a sample demonstrating the use of the
State Machine Framework (SMF)

Instructions are in the README.rst for the sample.

Miro Samek was contacted and gave approval to use the state
diagram in this demo.

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

Author: glenn-andrews

samples/subsys/smf/hsm_psicc2/CMakeLists.txt

@@ -0,0 +1,12 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(smf_hsm_psicc2)
+
+target_sources(app PRIVATE
+  src/main.c
+  src/hsm_psicc2_console_cmds.c
+  src/hsm_psicc2_thread.c
+)

samples/subsys/smf/hsm_psicc2/README.rst

@@ -0,0 +1,51 @@
+.. zephyr:code-sample:: smf_hsm_psicc2
+   :name: Hierarchical State Machine Demo based on example from PSiCC2
+   :relevant-api: smf
+
+   Implement an event-driven hierarchical state machine using State Machine Framework (SMF).
+
+Overview
+********
+
+This sample demonstrates the :ref:`State Machine Framework <smf>` subsystem.
+
+Building and Running
+********************
+
+It should be possible to build and run this sample on almost any board or emulator.
+
+Building and Running for ST Disco L475 IOT01 (B-L475E-IOT01A)
+=============================================================
+The sample can be built and executed for the :ref:`disco_l475_iot1_board` as follows:
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/subsys/smf/psicc2
+   :board: disco_l475_iot1
+   :goals: build flash
+   :compact:
+
+For other boards just replace the board name.
+
+Instructions for Use
+====================
+This application implements the statechart shown in Figure 2.11 of
+Practical UML Statecharts in C/C++, 2nd Edition, by Miro Samek (PSiCC2). Ebook available from
+https://www.state-machine.com/psicc2 This demo was chosen as it contains all possible transition
+topologies up to four levels of state nesting and is used with permission of the author.
+
+For each state, the entry, run, and exit actions are logged to the console, as well as logging
+when a state handles an event, or explicitly ignores it and passes it up to the parent state.
+
+There are two shell commands defined for controlling the operation.
+
+* ``psicc2 event <event>`` sends the event (from A to I) to the state machine. These correspond to
+  events A through I in PSiCC2 Figure 2.11
+* ``psicc2 terminate`` sends the ``EVENT_TERMINATE`` event to terminate the state machine. There
+  is no way to restart the state machine once terminated, and future events are ignored.
+
+Comparison to PSiCC2 Output
+===========================
+Not all transitions modelled in UML may be supported by the :ref:`State Machine Framework <smf>`.
+Unsupported transitions may lead to results different to the example run of the application in
+PSiCC2 Section 2.3.15. The differences will not be listed here as it is hoped :ref:`SMF <smf>`
+will support these transitions in the future and the list would become outdated.

samples/subsys/smf/hsm_psicc2/prj.conf

@@ -0,0 +1,11 @@
+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

samples/subsys/smf/hsm_psicc2/sample.yaml

@@ -0,0 +1,19 @@
+sample:
+  name: SMF HSM PSiCC2 Demo
+common:
+  tags:
+    - smf
+  integration_platforms:
+    - native_sim
+  harness: console
+  harness_config:
+    type: multi_line
+    ordered: true
+    regex:
+      - ".*<inf> hsm_psicc2_thread: initial_entry.*"
+      - ".*<inf> hsm_psicc2_thread: s_entry.*"
+      - ".*<inf> hsm_psicc2_thread: s2_entry.*"
+      - ".*<inf> hsm_psicc2_thread: s21_entry.*"
+      - ".*<inf> hsm_psicc2_thread: s211_entry.*"
+tests:
+  sample.smf.hsm_psicc2: {}

samples/subsys/smf/hsm_psicc2/src/hsm_psicc2_console_cmds.c

@@ -0,0 +1,91 @@
+/*
+ * Copyright (c) 2023 Glenn Andrews
+ * State Machine example copyright (c) Miro Samek
+ *
+ * Implementation of the statechart in Figure 2.11 of
+ * Practical UML Statecharts in C/C++, 2nd Edition by Miro Samek
+ * https://www.state-machine.com/psicc2
+ * Used with permission of the author.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/kernel.h>
+#include <zephyr/shell/shell.h>
+#include "hsm_psicc2_thread.h"
+#include <stdlib.h>
+#include <ctype.h>
+
+static int cmd_hsm_psicc2_event(const struct shell *sh, size_t argc, char **argv)
+{
+	struct hsm_psicc2_event event;
+	int event_id = toupper(argv[1][0]);
+
+	switch (event_id) {
+	case 'A':
+		event.event_id = EVENT_A;
+		break;
+	case 'B':
+		event.event_id = EVENT_B;
+		break;
+	case 'C':
+		event.event_id = EVENT_C;
+		break;
+	case 'D':
+		event.event_id = EVENT_D;
+		break;
+	case 'E':
+		event.event_id = EVENT_E;
+		break;
+	case 'F':
+		event.event_id = EVENT_F;
+		break;
+	case 'G':
+		event.event_id = EVENT_G;
+		break;
+	case 'H':
+		event.event_id = EVENT_H;
+		break;
+	case 'I':
+		event.event_id = EVENT_I;
+		break;
+	default:
+		shell_error(sh, "Invalid argument %s", argv[1]);
+		return -1;
+	}
+
+	int rc = k_msgq_put(&hsm_psicc2_msgq, &event, K_NO_WAIT);
+
+	if (rc == 0) {
+		shell_print(sh, "Event %c posted", event_id);
+	} else {
+		shell_error(sh, "error posting event: %d", rc);
+	}
+	return rc;
+}
+
+static int cmd_hsm_psicc2_terminate(const struct shell *sh, size_t argc, char **argv)
+{
+	struct hsm_psicc2_event event = {.event_id = EVENT_TERMINATE};
+	int rc = k_msgq_put(&hsm_psicc2_msgq, &event, K_NO_WAIT);
+
+	if (rc == 0) {
+		shell_print(sh, "Terminate event posted");
+	} else {
+		shell_error(sh, "error posting terminate event: %d", rc);
+	}
+	return rc;
+}
+
+/* Creating subcommands (level 1 command) array for command "demo". */
+SHELL_STATIC_SUBCMD_SET_CREATE(sub_hsm_psicc2,
+			       SHELL_CMD_ARG(event, NULL, "Send event to State Machine",
+					     cmd_hsm_psicc2_event, 2, 0),
+			       SHELL_CMD_ARG(terminate, NULL,
+					     "Send terminate event to State Machine",
+					     cmd_hsm_psicc2_terminate, 1, 0),
+			       SHELL_SUBCMD_SET_END);
+
+/* Creating root (level 0) command "demo" */
+SHELL_CMD_REGISTER(hsm_psicc2, &sub_hsm_psicc2, "PSICC2 demo hierarchical state machine commands",
+		   NULL);