button reader and button service added to demonstrate a freertos thread that reacts to a semaphore triggered from an ISR.

Author: mattheweshleman

example/CMakeLists.txt

@@ -2,6 +2,7 @@
 set(MOCKS_TOP_DIR ${CMAKE_CURRENT_SOURCE_DIR}/test/mocks CACHE INTERNAL "")
 set(DRIVERS_TOP_DIR ${CMAKE_CURRENT_SOURCE_DIR}/drivers CACHE INTERNAL "")
 
+include_directories(services/include)
 add_subdirectory(services)
 add_subdirectory(drivers)
 add_subdirectory(apps)

example/apps/demoPcApp/CMakeLists.txt

@@ -16,4 +16,4 @@ FetchContent_MakeAvailable(FreeRTOS-Kernel-DemoPcApp)
 
 add_executable(demoPcApp main.cpp)
 include_directories(${FREERTOS_KERNEL_PATH}/include)
-target_link_libraries(demoPcApp hwLockCtrlService freertos_kernel freertos_config)
+target_link_libraries(demoPcApp hwLockCtrlService buttonService freertos_kernel freertos_config)

example/apps/demoPcApp/main.cpp

@@ -5,6 +5,7 @@
 #include "FreeRTOS.h"
 #include "task.h"
 #include "hwLockCtrlService.h"
+#include "buttonService.h"
 
 static HLCS_LockStateT s_lastState = HLCS_LOCK_STATE_UNKNOWN;
 
@@ -54,7 +55,8 @@ DesiredAction GetUserAction()
     std::cout << "0: Unlock the lock" << std::endl;
     std::cout << "1: Lock the lock" << std::endl;
     std::cout << "2: Self Test the lock" << std::endl;
-    std::cout << "3: Exit" << std::endl
+    std::cout << "3: Button ISR" << std::endl;
+    std::cout << "9: Exit" << std::endl
               << std::endl;
 
     while (true) {
@@ -67,6 +69,9 @@ DesiredAction GetUserAction()
             case '2':
                 return DesiredAction::SELF_TEST;
             case '3':
+                ButtonService_SimulateIsr();
+                continue;
+            case '9':
                 return DesiredAction::EXIT;
             default:
                 vTaskDelay(10);
@@ -97,13 +102,24 @@ void UserInputTask(void*)
     }
 }
 
+void ButtonChangeCallback(ButtonFlagT flags, ButtonStateT state, void* context)
+{
+    (void)context;
+    printf("%s(flags = 0x%x, state = %d)\n",
+           __FUNCTION__ , flags, state);
+}
+
 int main()
 {
     HLCS_Init();
     HLCS_RegisterChangeStateCallback(LockStateChangeCallback);
     HLCS_RegisterSelfTestResultCallback(SelfTestResultCallback);
     HLCS_Start(EXECUTION_OPTION_NORMAL);
 
+    ButtonService_Init();
+    ButtonService_RegisterButtonChangeCallback(ButtonChangeCallback, nullptr);
+    ButtonService_Start(EXECUTION_OPTION_NORMAL);
+
     TaskHandle_t input_thread = nullptr;
     BaseType_t ok = xTaskCreate(UserInputTask, "Input", 2000,
                                 nullptr, tskIDLE_PRIORITY+2, &input_thread);

example/drivers/CMakeLists.txt

@@ -1 +1,2 @@
 add_subdirectory(hwLockCtrl)
+add_subdirectory(buttonReader)

example/drivers/buttonReader/CMakeLists.txt

@@ -0,0 +1,3 @@
+include_directories(include)
+add_library(buttonReader include/buttonReader.h src/buttonReader.c)
+target_include_directories(buttonReader PUBLIC include)

example/drivers/buttonReader/include/buttonReader.h

@@ -0,0 +1,74 @@
+/*
+MIT License
+
+Copyright (c) <2024> <Matthew Eshleman - https://covemountainsoftware.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+*/
+
+/**
+ * @brief public header for the Button Reader driver.
+ *        This driver provides methods to read
+ *        the status of up to 16 buttons.
+ *        Additionally, it provides an ISR callback.
+ *
+  */
+#ifndef BUTTON_READER_H
+#define BUTTON_READER_H
+
+#include <stdbool.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief  initializes the driver.
+ * @return true - initialization completed successfully.
+ *         false - some error.
+ */
+bool ButtonReaderInit();
+
+/**
+ * Read the pressed/released status. Guaranteed atomic.
+ * @param pressed: which buttons pressed since last read.
+ * @param released: which buttons released since last read.
+ * @return true: read ok. otherwise error.
+ */
+bool ButtonReaderRead(uint16_t* pressed, uint16_t* released);
+
+/*
+ * ISR Function Callback type.
+ */
+typedef void (*ButtonReaderIsrCallback)(void* context);
+
+/**
+ * Register a callback to be executed when the button change ISR is hit.
+ * @param callback
+ * @param context
+ * @return
+ */
+bool ButtonReaderRegisterIsrCallback(ButtonReaderIsrCallback callback, void* context);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif //BUTTON_READER_H

example/drivers/buttonReader/src/buttonReader.c

@@ -0,0 +1,54 @@
+/*
+ *   This concrete implementation of the Button Reader "C" style interface
+ *   is for demo purposes only. The focus of this project
+ *   is how to test FreeRTOS threads, hence
+ *   this fake driver module.
+ */
+#include "buttonReader.h"
+#include <stdio.h>
+
+static ButtonReaderIsrCallback s_isrCallback;
+static void* s_isrContext;
+
+bool ButtonReaderInit()
+{
+    printf("%s() executed\n", __FUNCTION__);
+    s_isrCallback = NULL;
+    s_isrContext = NULL;
+    return true;
+}
+
+bool ButtonReaderRead(uint16_t* pressed, uint16_t* released)
+{
+    static bool toggle = false;
+    printf("%s() executed\n", __FUNCTION__);
+
+    if ((pressed == NULL) || (released == NULL))
+    {
+        return false;
+    }
+
+    if (toggle)
+    {
+        *pressed = 2;
+        *released = 0;
+    }
+    else
+    {
+        *pressed = 0;
+        *released = 2;
+    }
+
+    toggle = !toggle;
+
+    return true;
+}
+
+bool ButtonReaderRegisterIsrCallback(ButtonReaderIsrCallback callback, void* context)
+{
+    printf("%s() executed\n", __FUNCTION__);
+
+    s_isrCallback = callback;
+    s_isrContext = context;
+    return true;
+}

example/services/CMakeLists.txt

@@ -1,2 +1,3 @@
 include_directories(${FREERTOS_KERNEL_PATH}/include)
-add_subdirectory(hwLockCtrlService)
+add_subdirectory(hwLockCtrlService)
+add_subdirectory(buttonService)

example/services/buttonService/CMakeLists.txt

@@ -0,0 +1,5 @@
+include_directories(include)
+add_subdirectory(test)
+add_library(buttonService include/buttonService.h src/buttonService.c)
+target_link_libraries(buttonService buttonReader freertos_kernel freertos_config)
+target_include_directories(buttonService PUBLIC include)

example/services/buttonService/include/buttonService.h

@@ -0,0 +1,103 @@
+/*
+MIT License
+
+Copyright (c) <2024> <Matthew Eshleman - https://covemountainsoftware.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+*/
+
+#ifndef BUTTON_SERVICE_H
+#define BUTTON_SERVICE_H
+
+#include <stdbool.h>
+#include "cmsExecutionOption.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Buttons supported on this product
+ */
+typedef enum ButtonFlag {
+    BUTTON_ON_OFF = 0x1,
+    BUTTON_FUNC_A = 0x2,
+} ButtonFlagT;
+
+typedef enum ButtonState {
+    BUTTON_PRESSED,
+    BUTTON_RELEASED,
+} ButtonStateT;
+
+/**
+ * Initialize the Button Service. Does not start the thread, just prepares.
+ */
+void ButtonService_Init();
+
+/**
+ * Destroy the ButtonService. Typically only called in unit testing environment.
+ */
+void ButtonService_Destroy();
+
+/**
+ * Start the button service/thread. Init() must have been called first.
+ * @param option
+ */
+void ButtonService_Start(ExecutionOptionT option);
+
+/**
+ * typedef for the button service callback
+ */
+typedef void (*ButtonService_ButtonChangeCallback)(ButtonFlagT flags, ButtonStateT state, void *context);
+
+/**
+ * Register callback to be executed from the button service
+ * thread context. Guaranteed to NOT be called from an ISR context.
+ * @param callback
+ * @param context
+ */
+void ButtonService_RegisterButtonChangeCallback(ButtonService_ButtonChangeCallback callback, void *context);
+
+/****************************************************************************/
+/*****  Backdoor functionality provided for unit testing access only ********/
+/****************************************************************************/
+
+/**
+ * provided for unit testing access only. For the button service,
+ * will check if semaphore token is available or not (i.e.
+ * the button ISR has occurred).
+ *
+ * @param option EXECUTION_OPTION_NORMAL - internal, normal thread use
+ *               EXECUTION_OPTION_UNIT_TEST - for unit testing
+ *
+ * @return true: an event was processed
+ *         false: no events, nothing processed.
+ */
+bool ButtonService_ProcessOneEvent(ExecutionOptionT option);
+
+/**
+ * Fake/simulate the ISR that the button service relies upon
+ */
+void ButtonService_SimulateIsr();
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif //BUTTON_SERVICE_H