samples: boards: stm32: exit Poweroff using wkup pins & gpios

This sample demonstrates how gpio pins can be used to power on
the system after a Poweroff, just like a reset pin.
The user only needs to add the STM32_GPIO_WKUP flag to the gpio pin
in "gpios" property of a DT device such a button or a sensor.
The samples Powers off the system after a delay then the user can power it
on with the user button that has the STM32_GPIO_WKUP flag in DT.
Only works on STM32 boards that support Zephyr POWEROFF
(U5, WL, WB, & L4 SoC series), & also have a user button whose GPIO pin
is associated with a wake-up pin (see PWR node in SoC dtsi file).

Signed-off-by: Abderrahmane Jarmouni <abderrahmane.jarmouni-ext@st.com>

samples/boards/stm32/power_mgmt/wkup_pins/CMakeLists.txt

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

samples/boards/stm32/power_mgmt/wkup_pins/README.rst

@@ -0,0 +1,38 @@
+.. _gpio-as-a-wkup-pin-src-sample:
+
+GPIO As A Wake-up Pin Source
+############################
+
+Overview
+********
+
+This sample is a minimum application to demonstrate using a wake-up pin with a GPIO as
+a source to power on an STM32 SoC after Poweroff.
+
+The system will power off automatically ``WAIT_TIME_US`` us after boot.
+Press the user button designated in boards's devicetree overlay as "wkup-src" to power it on again.
+
+.. _gpio-as-a-wkup-pin-src-sample-requirements:
+
+Requirements
+************
+
+The SoC should support POWEROFF functionality & have a wake-up pin that corresponds
+to the GPIO pin of a user button.
+To support another board, add an overlay in boards folder.
+Make sure that wake-up pins are configured in SoC dtsi file.
+
+Building and Running
+********************
+
+Build and flash wkup_pins as follows, changing ``nucleo_u5a5zj_q`` for your board:
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/boards/stm32/power_mgmt/wkup_pins
+   :board: nucleo_u5a5zj_q
+   :goals: build flash
+   :compact:
+
+After flashing, the LED in ON.
+The LED will be turned off when the system is powered off.
+Press the user button to power on the system again.

samples/boards/stm32/power_mgmt/wkup_pins/boards/nucleo_l4r5zi.overlay

@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) 2024 STMicroelectronics
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/dt-bindings/gpio/stm32-gpio.h>
+
+/ {
+	aliases {
+		wkup-src = &user_button;
+	};
+};
+
+&user_button {
+	gpios = <&gpioc 13 (GPIO_ACTIVE_HIGH | STM32_GPIO_WKUP)>;
+};
+
+&pwr {
+	status = "okay";
+};

samples/boards/stm32/power_mgmt/wkup_pins/boards/nucleo_u575zi_q.overlay

@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) 2024 STMicroelectronics
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/dt-bindings/gpio/stm32-gpio.h>
+
+/ {
+	aliases {
+		wkup-src = &user_button;
+	};
+};
+
+&user_button {
+	gpios = <&gpioc 13 (GPIO_ACTIVE_HIGH | STM32_GPIO_WKUP)>;
+};
+
+&pwr {
+	status = "okay";
+};

samples/boards/stm32/power_mgmt/wkup_pins/boards/nucleo_u5a5zj_q.overlay

@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) 2024 STMicroelectronics
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/dt-bindings/gpio/stm32-gpio.h>
+
+/ {
+	aliases {
+		wkup-src = &user_button;
+	};
+};
+
+&user_button {
+	gpios = <&gpioc 13 (GPIO_ACTIVE_HIGH | STM32_GPIO_WKUP)>;
+};
+
+&pwr {
+	status = "okay";
+};

samples/boards/stm32/power_mgmt/wkup_pins/boards/nucleo_wl55jc.overlay

@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) 2024 STMicroelectronics
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/dt-bindings/gpio/stm32-gpio.h>
+
+/ {
+	aliases {
+		wkup-src = &user_button_1;
+	};
+};
+
+&user_button_1 {
+	gpios = <&gpioa 0 (GPIO_ACTIVE_LOW | GPIO_PULL_UP | STM32_GPIO_WKUP)>;
+};
+
+&pwr {
+	status = "okay";
+};

samples/boards/stm32/power_mgmt/wkup_pins/prj.conf

@@ -0,0 +1,7 @@
+CONFIG_POWEROFF=y
+CONFIG_STM32_WKUP_PINS=y
+CONFIG_INPUT=y
+CONFIG_INPUT_GPIO_KEYS=y
+CONFIG_PM=n
+CONFIG_PM_DEVICE=n
+CONFIG_PM_DEVICE_RUNTIME=n

samples/boards/stm32/power_mgmt/wkup_pins/sample.yaml

@@ -0,0 +1,12 @@
+sample:
+  name: GPIO As A Wake-up Pin Source
+tests:
+  sample.boards.stm32.power_mgmt.wkup_pins:
+    build_only: true
+    filter: dt_enabled_alias_with_parent_compat("wkup-src",
+      "gpio-keys") and dt_compat_enabled("st,stm32-pwr")
+    platform_allow:
+      - nucleo_l4r5zi
+      - nucleo_u575zi_q
+      - nucleo_u5a5zj_q
+      - nucleo_wl55jc

samples/boards/stm32/power_mgmt/wkup_pins/src/main.c

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2024 STMicroelectronics
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/kernel.h>
+#include <zephyr/device.h>
+#include <zephyr/devicetree.h>
+#include <zephyr/drivers/gpio.h>
+#include <zephyr/sys/printk.h>
+#include <zephyr/sys/poweroff.h>
+
+#define WAIT_TIME_US 4000000
+
+#define WKUP_SRC_NODE DT_ALIAS(wkup_src)
+#if !DT_NODE_HAS_STATUS(WKUP_SRC_NODE, okay)
+#error "Unsupported board: wkup_src devicetree alias is not defined"
+#endif
+
+static const struct gpio_dt_spec button = GPIO_DT_SPEC_GET(WKUP_SRC_NODE, gpios);
+
+static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(DT_ALIAS(led0), gpios);
+
+int main(void)
+{
+	__ASSERT_NO_MSG(gpio_is_ready_dt(&button));
+	printk("\nWake-up button set up at %s pin %d\n", button.port->name, button.pin);
+
+	__ASSERT_NO_MSG(gpio_is_ready_dt(&led));
+	gpio_pin_configure_dt(&led, GPIO_OUTPUT_ACTIVE);
+	gpio_pin_set(led.port, led.pin, 1);
+
+	printk("Device is ready\n");
+
+	printk("Will wait %ds before powering the system off\n", (WAIT_TIME_US / 1000000));
+	k_busy_wait(WAIT_TIME_US);
+
+	printk("Powering off\n");
+	printk("Press the user button to power the system on\n\n");
+
+	sys_poweroff();
+	/* Will remain powered off until wake-up or reset button is pressed */
+
+	return 0;
+}