Button press callback sample module

YHusain1 · YHusain1 · commit fd48bd5222f6 · 2023-04-14T12:38:43.000-05:00
This commit pushes a new sample module that demonstrates to use a
callback mechanism when user presses the button.

The callback should be implemented in the user application code, the
callback's 3 parameters would represent the timestamp when the button
was pressed (in millisecs), the duration of how long the button was held
(also in millisecs) and the type of the button press as an enum value:
normal or timeout.

The 'timeout' button type indicates that the user had held the button
down for longer than a pre-configured duration (e.g, to factory reset
the board).

This module also has implementation that the user can de-init and
re-configure the tiemout duration and/or the callback function address.

Signed-off-by: YHusain1 &lt;yusuf.husainy1@t-mobile.com&gt;
diff --git a/samples/button_press_cb/CMakeLists.txt b/samples/button_press_cb/CMakeLists.txt
@@ -0,0 +1,11 @@
+# Copyright (c) 2023 T-Mobile USA, Inc.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(button_press_cb)
+
+target_sources(app PRIVATE src/main.c)
+target_sources(app PRIVATE src/button.c)
diff --git a/samples/button_press_cb/Kconfig b/samples/button_press_cb/Kconfig
@@ -0,0 +1,15 @@
+# Copyright (c) 2022 T-Mobile USA, Inc.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+mainmenu "Button Sample DevEdge board V04 Production"
+
+config BUTTON_DEBOUNCE_TIMEOUT_MS
+    int "Debounce filter timeout for button press in millisec"
+    range 0 100
+    default 50
+    help
+        Set this to configure timer value in order to debounce button press
+        and unpress.
+
+source "Kconfig.zephyr"
diff --git a/samples/button_press_cb/README.txt b/samples/button_press_cb/README.txt
@@ -0,0 +1,76 @@
+Title: button_press_cb
+
+Description:
+
+A sample to demonstrate a callback feature of the user push button on the DevEdge kit
+The user will implement the Button callback function in the application code.
+It gives the timestamp of the button pressed (from system uptime in millisecs), the duration of
+how long the button was pressed (also in millisecs), and the type of button press, whether a normal or a timeout.
+
+The duration parameter will be the max timeout value when a timeout occurs, this won't represent
+the real physical button press duration though. The callback will be invoked as soon as the
+timeout reaches even if the user has not release the button.
+
+--------------------------------------------------------------------------------
+
+Requirements
+************
+
+-A T-Mobile DevEdge dev kit (https://devedge.t-mobile.com/)
+-A Zephyr build environment (https://docs.zephyrproject.org/latest/develop/getting_started/index.html)
+
+Building and Running Project:
+
+How this project can be built:
+
+-Checkout the T-Mobile downstream zephyr repo:
+	cd ~/zephyrproject
+	git clone https://github.com/tmobile/DevEdge-IoTDevKit-ZephyrRTOS zephyr
+
+-Checkout the T-Mobile zephyr-tmo-sdk repo:
+	cd ~/zephyrproject
+	git clone https://github.com/tmobile/DevEdge-IoTDevKit-ZephyrSDK tmo-zephyr-sdk
+
+-Run 'west update'
+	cd ~/zephyrproject
+	west update
+
+-Build button_press_cb:
+	cd ~/zephyrproject
+	west build ~/zephyrproject/tmo-zephyr-sdk/samples/button_press_cb -p -b tmo_dev_edge -- -DBOARD_ROOT=<home folder>/zephyrproject/tmo-zephyr-sdk
+	(substitute your home folder for '<home folder>' in the command above)
+
+-Connect DevEdge dev kit:
+	For DevEdge dev kits running tmo_shell built with DevEdge SDK v1.9.1 or earlier:
+		connect BOTH USB-C ports to your computer or wall power
+	For DevEdge dev kits running tmo_shell built with DevEdge SDK v1.10.0 or later:
+		connect only the USB-C port furthest from the button to your computer
+		(both USB-C ports can be connected, but only one needs to be connected)
+
+-Flash button_press_cb:
+	cd ~/zephyrproject
+	west flash
+
+Sample output:
+```
+*** Booting Zephyr OS build ccdf94636486 ***
+
+
+                        Welcome to T-Mobile DevEdge!
+
+This application aims to demonstrate the button press callback sample module which
+uses SW0 interrupt pin, which is connected to the user pushbutton switch of the
+DevEdge module.
+
+Set up button at gpio@4000a030 pin 13
+
+factory_reset_callback: Button pressed: timestamp: 2562; duration: 10000, button press type: BUTTON_PRESS_TIMEOUT
+Set up button at gpio@4000a030 pin 13
+
+factory_reset_callback: Button pressed: timestamp: 14983; duration: 159, button press type: BUTTON_PRESS_NORMAL
+factory_reset_callback: Button pressed: timestamp: 15920; duration: 137, button press type: BUTTON_PRESS_NORMAL
+factory_reset_callback: Button pressed: timestamp: 16690; duration: 5000, button press type: BUTTON_PRESS_TIMEOUT
+factory_reset_callback: Button pressed: timestamp: 22771; duration: 139, button press type: BUTTON_PRESS_NORMAL
+factory_reset_callback: Button pressed: timestamp: 23757; duration: 179, button press type: BUTTON_PRESS_NORMAL
+```
+
diff --git a/samples/button_press_cb/prj.conf b/samples/button_press_cb/prj.conf
@@ -0,0 +1,9 @@
+# Copyright (c) 2022 T-Mobile USA, Inc.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# Required to disable default behavior of deep sleep on timeout
+CONFIG_GPIO=y
+
+# Stack sizes
+CONFIG_MAIN_STACK_SIZE=4096
diff --git a/samples/button_press_cb/src/button.c b/samples/button_press_cb/src/button.c
@@ -0,0 +1,191 @@
+/*
+ * Copyright (c) 2023 T-Mobile USA, Inc.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/device.h>
+#include <zephyr/drivers/gpio.h>
+#include <zephyr/kernel.h>
+#include <zephyr/sys/printk.h>
+
+#include "button.h"
+
+#define SW0_NODE DT_ALIAS(sw0)
+
+static const struct gpio_dt_spec button = GPIO_DT_SPEC_GET_OR(SW0_NODE, gpios, {0});
+static struct gpio_callback button_cb_data;
+static button_press_callback_t registered_callback;
+static struct gpio_callback button_cb_data;
+button_press_state button_state = BUTTON_STATE_DEINIT;
+struct k_timer debounce_timer;
+struct k_timer timeout_timer;
+static int64_t last_button_press_time;
+static int64_t button_press_duration;
+static int64_t max_button_press_timeout;
+
+/* button GPIO interrupt handler */
+static void button_press_handler(const struct device *port, struct gpio_callback *cb,
+				 gpio_port_pins_t pins)
+{
+	k_timer_stop(&debounce_timer);
+	k_timer_start(&debounce_timer, K_MSEC(50), K_NO_WAIT);
+	button_state = BUTTON_STATE_DEBOUNCING;
+}
+
+static void button_timeout_handler(struct k_timer *p_timeout_timer)
+{
+	button_state = BUTTON_STATE_TIMEOUT;
+	if (NULL != registered_callback) {
+		/* saving the last button press time, since k_uptime_delta updates it with current
+		 * system uptime, which is undesired behavior in the context of measuring the real
+		 * button press duration even if timeout has occurred */
+		int64_t save_last_button_press = last_button_press_time;
+
+		button_press_duration = k_uptime_delta(&last_button_press_time);
+		last_button_press_time = save_last_button_press;
+		/* Invoke the registered user callback handler */
+		registered_callback(last_button_press_time, button_press_duration,
+				    BUTTON_PRESS_TIMEOUT);
+	}
+	k_timer_stop(p_timeout_timer);
+}
+
+/* debounce timer handler */
+static void button_debounce_timer_handler(struct k_timer *p_debounce_timer)
+{
+	/* As soon as a button press action (hold or release) has occurred, we don't need the
+	 * timeout timer enabled anymore, until the next button event */
+	k_timer_stop(&timeout_timer);
+
+	if (BUTTON_STATE_DEINIT == button_state) {
+		return;
+	}
+	button_state = BUTTON_STATE_DEBOUNCED;
+	/* Each the button is pressed, last_button_press_time will be 0, indicating a new action on
+	 * user button */
+	if (last_button_press_time == 0) {
+		/* button press detected */
+		last_button_press_time = k_uptime_get();
+		k_timer_start(&timeout_timer, K_MSEC(max_button_press_timeout), K_NO_WAIT);
+	} else if (registered_callback != NULL) {
+		/* button release detected */
+
+		/* This basically compares the timestamps of each time the timer handler is called
+		 * (one on button press, another on button release )*/
+		button_press_duration = k_uptime_delta(&last_button_press_time);
+
+		/* Depending on whether the time delta exceeds the configured max timeout value set
+		 * during init function, the button press type is evaluated */
+		if (button_state != BUTTON_STATE_TIMEOUT &&
+		    button_press_duration < max_button_press_timeout) {
+			/* Invoke the registered user callback handler */
+			registered_callback(last_button_press_time, button_press_duration,
+					    BUTTON_PRESS_NORMAL);
+		}
+
+		/* Reset last_button_press_time to capture next button press event */
+		last_button_press_time = 0;
+
+		button_state = BUTTON_STATE_INIT;
+	}
+}
+
+int button_press_module_init(uint32_t max_timeout, button_press_callback_t callback)
+{
+	/* Cannot initialize new paramters of button press without calling deinit first */
+	if (BUTTON_STATE_DEINIT < button_state) {
+		return -EBUSY;
+	}
+	/* Invalid params */
+	if (0 == max_timeout || NULL == callback) {
+		return -EINVAL;
+	}
+
+	int ret = 0;
+
+	max_button_press_timeout = max_timeout;
+	registered_callback = callback;
+
+	ret = gpio_pin_configure_dt(&button, GPIO_INPUT | GPIO_PULL_UP);
+	if (ret != 0) {
+		printk("Error %d: failed to configure %s pin %d\n", ret, button.port->name,
+		       button.pin);
+		button_state = BUTTON_STATE_ERROR;
+		return ret;
+	}
+
+	/* Configrue interrputs on both edges so we can sample timestamp to caluclate duration of
+	 * button press */
+	ret = gpio_pin_interrupt_configure_dt(&button, GPIO_INT_EDGE_BOTH);
+	if (ret != 0) {
+		printk("Error %d: failed to configure interrupt on %s pin %d\n", ret,
+		       button.port->name, button.pin);
+		button_state = BUTTON_STATE_ERROR;
+		return ret;
+	}
+	gpio_init_callback(&button_cb_data, button_press_handler, BIT(button.pin));
+	gpio_add_callback_dt(&button, &button_cb_data);
+	printk("Set up button at %s pin %d\n\n", button.port->name, button.pin);
+
+	k_timer_init(&debounce_timer, button_debounce_timer_handler, NULL);
+	k_timer_init(&timeout_timer, button_timeout_handler, NULL);
+
+	/* Set state of button as configured. Only one configruation can exist at a time */
+	button_state = BUTTON_STATE_INIT;
+
+	return ret;
+}
+
+int button_press_module_deinit(void)
+{
+	if (BUTTON_STATE_DEINIT == button_state) {
+		return 0;
+	}
+
+	int ret = 0;
+
+	max_button_press_timeout = 0;
+	registered_callback = NULL;
+
+	/* Disconnect the GPIO from the MCU */
+	ret = gpio_pin_configure_dt(&button, GPIO_DISCONNECTED);
+	if (ret != 0) {
+		printk("Error %d: failed to disconnect %s pin %d\n", ret, button.port->name,
+		       button.pin);
+		button_state = BUTTON_STATE_ERROR;
+		return ret;
+	}
+
+	/* Disable all interrupts on it */
+	ret = gpio_pin_interrupt_configure_dt(&button, GPIO_INT_DISABLE);
+	if (ret != 0) {
+		printk("Error %d: failed to disable interrupt on %s pin %d\n", ret,
+		       button.port->name, button.pin);
+		button_state = BUTTON_STATE_ERROR;
+		return ret;
+	}
+
+	gpio_remove_callback_dt(&button, &button_cb_data);
+	if (ret != 0) {
+		printk("Error %d: failed to remove intr callback on %s pin %d\n", ret,
+		       button.port->name, button.pin);
+		button_state = BUTTON_STATE_ERROR;
+		return ret;
+	}
+
+	k_timer_stop(&debounce_timer);
+	k_timer_stop(&timeout_timer);
+
+	/* Set the button state to undefined so a new configruation can be set by calling the init
+	 * function */
+	button_state = BUTTON_STATE_DEINIT;
+
+	return ret;
+}
+
+button_press_state button_press_get_state(void)
+{
+	/* Return current state of button */
+	return button_state;
+}
diff --git a/samples/button_press_cb/src/button.h b/samples/button_press_cb/src/button.h
@@ -0,0 +1,65 @@
+/*
+ * Copyright (c) 2023 T-Mobile USA, Inc.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#ifndef BUTTON_H
+#define BUTTON_H
+
+#include <zephyr/kernel.h>
+
+typedef enum {
+	BUTTON_PRESS_NORMAL = 0,
+	BUTTON_PRESS_TIMEOUT = 1
+} button_press_type;
+
+typedef enum {
+	BUTTON_STATE_ERROR = -1,
+	BUTTON_STATE_DEINIT = 0,
+	BUTTON_STATE_INIT = 1,
+	BUTTON_STATE_DEBOUNCING = 2,
+	BUTTON_STATE_DEBOUNCED = 3,
+	BUTTON_STATE_TIMEOUT = 4
+} button_press_state;
+
+/**
+ * @brief Button callback definition, the user will implement the callback in the application code.
+ * It gives the timestamp of the button pressed (from system uptime in millisecs), the duration of
+ * how long the button was pressed, and the type of button press, whether a normal or a timeout.
+ *
+ * The duration parameter will be the max timeout value when a timeout occurs, this won't represent
+ * the real physical button press duration though. The callback will be invoked as soon as the
+ * timeout reaches even if the user has not release the button.
+ */
+typedef void (*button_press_callback_t)(uint32_t timestamp, uint32_t duration,
+					button_press_type type);
+
+/**
+ * @brief Button press initialization. Called by user application code to configure and initialize
+ * user button to generate callback on button presses.
+ *
+ * @param max_timeout   [in]    Max timeout value for which the user button can be pressed, after
+ * which it is considered to be not normal operation.
+ * @param callback      [in]    Function pointer to the callback that will be called when the button
+ * has been pressed for a certain duration
+ * @return int  status code indicating success/failure.
+ */
+int button_press_module_init(uint32_t max_timeout, button_press_callback_t callback);
+
+/**
+ * @brief De-initialize the button interrupt and callbacks if it was previously done so. Usually
+ * performed if we want to set a new configuration on the button.
+ *
+ * @return int status code indicating success/failure
+ */
+int button_press_module_deinit(void);
+
+/**
+ * @brief Get the button configured state. Handy getter function that user application code can use
+ * to determine if existing callback is set before configuring it with new parameters.
+ *
+ * @return button_press_state
+ */
+button_press_state button_press_get_state(void);
+
+#endif
diff --git a/samples/button_press_cb/src/main.c b/samples/button_press_cb/src/main.c
