TactilityKernel improvements (#464)

* **New Features**
  * Thread API with lifecycle, priority, affinity and state monitoring
  * Timer subsystem: one-shot/periodic timers, reset, pending callbacks, expiry queries
  * Expanded I²C: register-level ops, bulk writes, presence checks, ESP32 integration and new config properties
  * GPIO controller: pin level and options APIs
  * Error utilities: new error code, error-to-string, timeout helper and common macros
  * Device construction helpers (construct+start)

* **Tests**
  * New unit tests for thread and timer behavior

* **Documentation**
  * Expanded coding style guide (files/folders, C conventions)

TactilityKernel/Bindings/i2c-controller.yaml

@@ -1,10 +1 @@
 bus: i2c
-
-properties:
-  clock-frequency:
-    type: int
-    description: Initial clock frequency in Hz
-  pin-sda:
-    type: phandle-array
-  pin-scl:
-    type: phandle-array

TactilityKernel/CMakeLists.txt

@@ -7,6 +7,8 @@ if (DEFINED ENV{ESP_IDF_VERSION})
     idf_component_register(
         SRCS ${SOURCES}
         INCLUDE_DIRS "Include/"
+        # TODO move the related logic for esp_time in Tactility/time.h into the Platform/ subproject
+        REQUIRES esp_timer
     )
 
 else ()

TactilityKernel/Include/tactility/check.h

@@ -14,7 +14,7 @@ __attribute__((noreturn)) extern void __crash(void);
 #define CHECK_NO_MSG(condition) \
     do { \
         if (!(condition)) { \
-            LOG_E("Error", "Check failed: %s at %s:%d", #condition, __FILE__, __LINE__); \
+            LOG_E("Error", "Check failed: %s\n\tat %s:%d", #condition, __FILE__, __LINE__); \
             __crash(); \
         } \
     } while (0)
@@ -22,7 +22,7 @@ __attribute__((noreturn)) extern void __crash(void);
 #define CHECK_MSG(condition, message) \
     do { \
         if (!(condition)) { \
-            LOG_E("Error", "Check failed: %s at %s:%d", message, __FILE__, __LINE__); \
+            LOG_E("Error", "Check failed: %s\n\tat %s:%d", message, __FILE__, __LINE__); \
             __crash(); \
         } \
     } while (0)

TactilityKernel/Include/tactility/concurrent/thread.h

@@ -0,0 +1,182 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include "tactility/error.h"
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifdef ESP_PLATFORM
+#include <esp_log.h>
+#endif
+
+#include <tactility/freertos/task.h>
+#include <tactility/concurrent/mutex.h>
+
+#include <assert.h>
+#include <stdbool.h>
+#include <stdint.h>
+
+typedef enum {
+    THREAD_STATE_STOPPED,
+    THREAD_STATE_STARTING,
+    THREAD_STATE_RUNNING,
+} ThreadState;
+
+/** ThreadPriority */
+enum ThreadPriority {
+    THREAD_PRIORITY_NONE = 0U,
+    THREAD_PRIORITY_IDLE = 1U,
+    THREAD_PRIORITY_LOWER = 2U,
+    THREAD_PRIORITY_LOW = 3U,
+    THREAD_PRIORITY_NORMAL = 4U,
+    THREAD_PRIORITY_HIGH = 5U,
+    THREAD_PRIORITY_HIGHER = 6U,
+    THREAD_PRIORITY_CRITICAL = 7U
+};
+
+typedef int32_t (*thread_main_fn_t)(void* context);
+typedef void (*thread_state_callback_t)(ThreadState state, void* context);
+
+struct Thread;
+typedef struct Thread Thread;
+
+/**
+ * @brief Creates a new thread instance with default settings.
+ * @return A pointer to the created Thread instance, or NULL if allocation failed.
+ */
+Thread* thread_alloc(void);
+
+/**
+ * @brief Creates a new thread instance with specified parameters.
+ * @param[in] name The name of the thread.
+ * @param[in] stack_size The size of the thread stack in bytes.
+ * @param[in] function The main function to be executed by the thread.
+ * @param[in] function_context A pointer to the context to be passed to the main function.
+ * @param[in] affinity The CPU core affinity for the thread (e.g., tskNO_AFFINITY).
+ * @return A pointer to the created Thread instance, or NULL if allocation failed.
+ */
+Thread* thread_alloc_full(
+    const char* name,
+    configSTACK_DEPTH_TYPE stack_size,
+    thread_main_fn_t function,
+    void* function_context,
+    portBASE_TYPE affinity
+);
+
+/**
+ * @brief Destroys a thread instance.
+ * @param[in] thread The thread instance to destroy.
+ * @note The thread must be in the STOPPED state.
+ */
+void thread_free(Thread* thread);
+
+/**
+ * @brief Sets the name of the thread.
+ * @param[in] thread The thread instance.
+ * @param[in] name The new name for the thread.
+ * @note Can only be called when the thread is in the STOPPED state.
+ */
+void thread_set_name(Thread* thread, const char* name);
+
+/**
+ * @brief Sets the stack size for the thread.
+ * @param[in] thread The thread instance.
+ * @param[in] stack_size The stack size in bytes. Must be a multiple of 4.
+ * @note Can only be called when the thread is in the STOPPED state.
+ */
+void thread_set_stack_size(Thread* thread, size_t stack_size);
+
+/**
+ * @brief Sets the CPU core affinity for the thread.
+ * @param[in] thread The thread instance.
+ * @param[in] affinity The CPU core affinity.
+ * @note Can only be called when the thread is in the STOPPED state.
+ */
+void thread_set_affinity(Thread* thread, portBASE_TYPE affinity);
+
+/**
+ * @brief Sets the main function and context for the thread.
+ * @param[in] thread The thread instance.
+ * @param[in] function The main function to be executed.
+ * @param[in] context A pointer to the context to be passed to the main function.
+ * @note Can only be called when the thread is in the STOPPED state.
+ */
+void thread_set_main_function(Thread* thread, thread_main_fn_t function, void* context);
+
+/**
+ * @brief Sets the priority for the thread.
+ * @param[in] thread The thread instance.
+ * @param[in] priority The thread priority.
+ * @note Can only be called when the thread is in the STOPPED state.
+ */
+void thread_set_priority(Thread* thread, enum ThreadPriority priority);
+
+/**
+ * @brief Sets a callback to be invoked when the thread state changes.
+ * @param[in] thread The thread instance.
+ * @param[in] callback The callback function.
+ * @param[in] context A pointer to the context to be passed to the callback function.
+ * @note Can only be called when the thread is in the STOPPED state.
+ */
+void thread_set_state_callback(Thread* thread, thread_state_callback_t callback, void* context);
+
+/**
+ * @brief Gets the current state of the thread.
+ * @param[in] thread The thread instance.
+ * @return The current ThreadState.
+ */
+ThreadState thread_get_state(Thread* thread);
+
+/**
+ * @brief Starts the thread execution.
+ * @param[in] thread The thread instance.
+ * @note The thread must be in the STOPPED state and have a main function set.
+ * @retval ERROR_NONE when the thread was started
+ * @retval ERROR_UNDEFINED when the thread failed to start
+ */
+error_t thread_start(Thread* thread);
+
+/**
+ * @brief Waits for the thread to finish execution.
+ * @param[in] thread The thread instance.
+ * @param[in] timeout The maximum time to wait in ticks.
+ * @param[in] poll_interval The interval between status checks in ticks.
+ * @retval ERROR_NONE when the thread was stopped
+ * @retval ERROR_TIMEOUT when the thread was not stopped because the timeout has passed
+ * @note Cannot be called from the thread being joined.
+ */
+error_t thread_join(Thread* thread, TickType_t timeout, TickType_t poll_interval);
+
+/**
+ * @brief Gets the FreeRTOS task handle associated with the thread.
+ * @param[in] thread The thread instance.
+ * @return The TaskHandle_t, or NULL if the thread is not running.
+ */
+TaskHandle_t thread_get_task_handle(Thread* thread);
+
+/**
+ * @brief Gets the return code from the thread's main function.
+ * @param[in] thread The thread instance.
+ * @return The return code of the thread's main function.
+ * @note The thread must be in the STOPPED state.
+ */
+int32_t thread_get_return_code(Thread* thread);
+
+/**
+ * @brief Gets the minimum remaining stack space for the thread since it started.
+ * @param[in] thread The thread instance.
+ * @return The minimum remaining stack space in bytes.
+ * @note The thread must be in the RUNNING state.
+ */
+uint32_t thread_get_stack_space(Thread* thread);
+
+/**
+ * @brief Gets the current thread instance.
+ * @return A pointer to the current Thread instance, or NULL if not called from a thread created by this module.
+ */
+Thread* thread_get_current(void);
+
+#ifdef __cplusplus
+}
+#endif

TactilityKernel/Include/tactility/concurrent/timer.h

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include "tactility/error.h"
+#include "tactility/freertos/timers.h"
+#include "tactility/concurrent/thread.h"
+
+#include <stdbool.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+enum TimerType {
+    TIMER_TYPE_ONCE = 0,    // Timer triggers once after time has passed
+    TIMER_TYPE_PERIODIC = 1 // Timer triggers repeatedly after time has passed
+};
+
+typedef void (*timer_callback_t)(void* context);
+typedef void (*timer_pending_callback_t)(void* context, uint32_t arg);
+
+struct Timer;
+
+/**
+ * @brief Creates a new timer instance.
+ * @param[in] type The timer type.
+ * @param[in] ticks The timer period in ticks.
+ * @param[in] callback The callback function.
+ * @param[in] context The context to pass to the callback function.
+ * @return A pointer to the created timer instance, or NULL if allocation failed.
+ */
+struct Timer* timer_alloc(enum TimerType type, TickType_t ticks, timer_callback_t callback, void* context);
+
+/**
+ * @brief Destroys a timer instance.
+ * @param[in] timer The timer instance to destroy.
+ */
+void timer_free(struct Timer* timer);
+
+/**
+ * @brief Starts the timer.
+ * @param[in] timer The timer instance.
+ * @return ERROR_NONE on success, ERROR_TIMEOUT if the command queue was full.
+ */
+error_t timer_start(struct Timer* timer);
+
+/**
+ * @brief Stops the timer.
+ * @param[in] timer The timer instance.
+ * @return ERROR_NONE on success, ERROR_TIMEOUT if the command queue was full.
+ */
+error_t timer_stop(struct Timer* timer);
+
+/**
+ * @brief Set a new interval and reset the timer.
+ * @param[in] timer The timer instance.
+ * @param[in] interval The new timer interval in ticks.
+ * @return ERROR_NONE on success, ERROR_TIMEOUT if the command queue was full.
+ */
+error_t timer_reset_with_interval(struct Timer* timer, TickType_t interval);
+
+/**
+ * @brief Reset the timer.
+ * @param[in] timer The timer instance.
+ * @return ERROR_NONE on success, ERROR_TIMEOUT if the command queue was full.
+ */
+error_t timer_reset(struct Timer* timer);
+
+/**
+ * @brief Check if the timer is running.
+ * @param[in] timer The timer instance.
+ * @return true when the timer is running.
+ */
+bool timer_is_running(struct Timer* timer);
+
+/**
+ * @brief Gets the expiry time of the timer.
+ * @param[in] timer The timer instance.
+ * @return The expiry time in ticks.
+ */
+TickType_t timer_get_expiry_time(struct Timer* timer);
+
+/**
+ * @brief Calls xTimerPendFunctionCall internally.
+ * @param[in] timer The timer instance.
+ * @param[in] callback the function to call
+ * @param[in] context the first function argument
+ * @param[in] arg the second function argument
+ * @param[in] timeout the function timeout (must set to 0 in ISR mode)
+ * @return ERROR_NONE on success, ERROR_TIMEOUT if the command queue was full.
+ */
+error_t timer_set_pending_callback(struct Timer* timer, timer_pending_callback_t callback, void* context, uint32_t arg, TickType_t timeout);
+
+/**
+ * @brief Set callback priority (priority of the timer daemon task).
+ * @param[in] timer The timer instance.
+ * @param[in] priority The priority.
+ */
+void timer_set_callback_priority(struct Timer* timer, enum ThreadPriority priority);
+
+#ifdef __cplusplus
+}
+#endif

TactilityKernel/Include/tactility/defines.h

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * @brief Contains various unsorted defines
+ * @note Preprocessor defines with potentially clashing names implement an #ifdef check.
+ */
+#pragma once
+
+#ifndef MIN
+/** @brief Get the minimum value of 2 values */
+#define MIN(a, b) (((a) < (b)) ? (a) : (b))
+#endif
+
+#ifndef MAX
+/** @brief Get the maximum value of 2 values */
+#define MAX(a, b) (((a) > (b)) ? (a) : (b))
+#endif
+
+#ifndef CLAMP
+/** @brief Clamp a value between the provided minimum and maximum */
+#define CLAMP(min, max, value) (((value) < (min)) ? (min) : (((value) > (max)) ? (max) : (value)))
+#endif

TactilityKernel/Include/tactility/device.h

@@ -133,6 +133,10 @@ error_t device_stop(struct Device* device);
  */
 void device_set_parent(struct Device* device, struct Device* parent);
 
+error_t device_construct_add(struct Device* device, const char* compatible);
+
+error_t device_construct_add_start(struct Device* device, const char* compatible);
+
 static inline void device_set_driver(struct Device* device, struct Driver* driver) {
     device->internal.driver = driver;
 }

TactilityKernel/Include/tactility/drivers/gpio_controller.h

@@ -10,17 +10,85 @@ extern "C" {
 #include <tactility/error.h>
 
 struct GpioControllerApi {
+    /**
+     * @brief Sets the logical level of a GPIO pin.
+     * @param[in] device the GPIO controller device
+     * @param[in] pin the pin index
+     * @param[in] high true to set the pin high, false to set it low
+     * @return ERROR_NONE if successful
+     */
     error_t (*set_level)(struct Device* device, gpio_pin_t pin, bool high);
+
+    /**
+     * @brief Gets the logical level of a GPIO pin.
+     * @param[in] device the GPIO controller device
+     * @param[in] pin the pin index
+     * @param[out] high pointer to store the pin level
+     * @return ERROR_NONE if successful
+     */
     error_t (*get_level)(struct Device* device, gpio_pin_t pin, bool* high);
+
+    /**
+     * @brief Configures the options for a GPIO pin.
+     * @param[in] device the GPIO controller device
+     * @param[in] pin the pin index
+     * @param[in] options configuration flags (direction, pull-up/down, etc.)
+     * @return ERROR_NONE if successful
+     */
     error_t (*set_options)(struct Device* device, gpio_pin_t pin, gpio_flags_t options);
+
+    /**
+     * @brief Gets the configuration options for a GPIO pin.
+     * @param[in] device the GPIO controller device
+     * @param[in] pin the pin index
+     * @param[out] options pointer to store the configuration flags
+     * @return ERROR_NONE if successful
+     */
     error_t (*get_options)(struct Device* device, gpio_pin_t pin, gpio_flags_t* options);
 };
 
+/**
+ * @brief Sets the logical level of a GPIO pin.
+ * @param[in] device the GPIO controller device
+ * @param[in] pin the pin index
+ * @param[in] high true to set the pin high, false to set it low
+ * @return ERROR_NONE if successful
+ */
 error_t gpio_controller_set_level(struct Device* device, gpio_pin_t pin, bool high);
+
+/**
+ * @brief Gets the logical level of a GPIO pin.
+ * @param[in] device the GPIO controller device
+ * @param[in] pin the pin index
+ * @param[out] high pointer to store the pin level
+ * @return ERROR_NONE if successful
+ */
 error_t gpio_controller_get_level(struct Device* device, gpio_pin_t pin, bool* high);
+
+/**
+ * @brief Configures the options for a GPIO pin.
+ * @param[in] device the GPIO controller device
+ * @param[in] pin the pin index
+ * @param[in] options configuration flags (direction, pull-up/down, etc.)
+ * @return ERROR_NONE if successful
+ */
 error_t gpio_controller_set_options(struct Device* device, gpio_pin_t pin, gpio_flags_t options);
+
+/**
+ * @brief Gets the configuration options for a GPIO pin.
+ * @param[in] device the GPIO controller device
+ * @param[in] pin the pin index
+ * @param[out] options pointer to store the configuration flags
+ * @return ERROR_NONE if successful
+ */
 error_t gpio_controller_get_options(struct Device* device, gpio_pin_t pin, gpio_flags_t* options);
 
+/**
+ * @brief Configures the options for a GPIO pin using a pin configuration structure.
+ * @param[in] device the GPIO controller device
+ * @param[in] config the pin configuration structure
+ * @return ERROR_NONE if successful
+ */
 static inline error_t gpio_set_options_config(struct Device* device, const struct GpioPinConfig* config) {
     return gpio_controller_set_options(device, config->pin, config->flags);
 }

TactilityKernel/Include/tactility/drivers/i2c_controller.h

@@ -13,18 +13,154 @@ extern "C" {
 #include <tactility/freertos/freertos.h>
 #include <tactility/error.h>
 
+/**
+ * @brief API for I2C controller drivers.
+ */
 struct I2cControllerApi {
+    /**
+     * @brief Reads data from an I2C device.
+     * @param[in] device the I2C controller device
+     * @param[in] address the 7-bit I2C address of the slave device
+     * @param[out] data the buffer to store the read data
+     * @param[in] dataSize the number of bytes to read
+     * @param[in] timeout the maximum time to wait for the operation to complete
+     * @retval ERROR_NONE when the read operation was successful
+     * @retval ERROR_TIMEOUT when the operation timed out
+     */
     error_t (*read)(struct Device* device, uint8_t address, uint8_t* data, size_t dataSize, TickType_t timeout);
+
+    /**
+     * @brief Writes data to an I2C device.
+     * @param[in] device the I2C controller device
+     * @param[in] address the 7-bit I2C address of the slave device
+     * @param[in] data the buffer containing the data to write
+     * @param[in] dataSize the number of bytes to write
+     * @param[in] timeout the maximum time to wait for the operation to complete
+     * @retval ERROR_NONE when the write operation was successful
+     * @retval ERROR_TIMEOUT when the operation timed out
+     */
     error_t (*write)(struct Device* device, uint8_t address, const uint8_t* data, uint16_t dataSize, TickType_t timeout);
+
+    /**
+     * @brief Writes data to then reads data from an I2C device.
+     * @param[in] device the I2C controller device
+     * @param[in] address the 7-bit I2C address of the slave device
+     * @param[in] writeData the buffer containing the data to write
+     * @param[in] writeDataSize the number of bytes to write
+     * @param[out] readData the buffer to store the read data
+     * @param[in] readDataSize the number of bytes to read
+     * @param[in] timeout the maximum time to wait for the operation to complete
+     * @retval ERROR_NONE when the operation was successful
+     * @retval ERROR_TIMEOUT when the operation timed out
+     */
     error_t (*write_read)(struct Device* device, uint8_t address, const uint8_t* writeData, size_t writeDataSize, uint8_t* readData, size_t readDataSize, TickType_t timeout);
+
+    /**
+     * @brief Reads data from a register of an I2C device.
+     * @param[in] device the I2C controller device
+     * @param[in] address the 7-bit I2C address of the slave device
+     * @param[in] reg the register address to read from
+     * @param[out] data the buffer to store the read data
+     * @param[in] dataSize the number of bytes to read
+     * @param[in] timeout the maximum time to wait for the operation to complete
+     * @retval ERROR_NONE when the read operation was successful
+     * @retval ERROR_TIMEOUT when the operation timed out
+     */
+    error_t (*read_register)(struct Device* device, uint8_t address, uint8_t reg, uint8_t* data, size_t dataSize, TickType_t timeout);
+
+    /**
+     * @brief Writes data to a register of an I2C device.
+     * @param[in] device the I2C controller device
+     * @param[in] address the 7-bit I2C address of the slave device
+     * @param[in] reg the register address to write to
+     * @param[in] data the buffer containing the data to write
+     * @param[in] dataSize the number of bytes to write
+     * @param[in] timeout the maximum time to wait for the operation to complete
+     * @retval ERROR_NONE when the write operation was successful
+     * @retval ERROR_TIMEOUT when the operation timed out
+     */
+    error_t (*write_register)(struct Device* device, uint8_t address, uint8_t reg, const uint8_t* data, uint16_t dataSize, TickType_t timeout);
 };
 
+/**
+ * @brief Reads data from an I2C device using the specified controller.
+ * @param[in] device the I2C controller device
+ * @param[in] address the 7-bit I2C address of the slave device
+ * @param[out] data the buffer to store the read data
+ * @param[in] dataSize the number of bytes to read
+ * @param[in] timeout the maximum time to wait for the operation to complete
+ * @retval ERROR_NONE when the read operation was successful
+ */
 error_t i2c_controller_read(struct Device* device, uint8_t address, uint8_t* data, size_t dataSize, TickType_t timeout);
 
+/**
+ * @brief Writes data to an I2C device using the specified controller.
+ * @param[in] device the I2C controller device
+ * @param[in] address the 7-bit I2C address of the slave device
+ * @param[in] data the buffer containing the data to write
+ * @param[in] dataSize the number of bytes to write
+ * @param[in] timeout the maximum time to wait for the operation to complete
+ * @retval ERROR_NONE when the write operation was successful
+ */
 error_t i2c_controller_write(struct Device* device, uint8_t address, const uint8_t* data, uint16_t dataSize, TickType_t timeout);
 
+/**
+ * @brief Writes data to then reads data from an I2C device using the specified controller.
+ * @param[in] device the I2C controller device
+ * @param[in] address the 7-bit I2C address of the slave device
+ * @param[in] writeData the buffer containing the data to write
+ * @param[in] writeDataSize the number of bytes to write
+ * @param[out] readData the buffer to store the read data
+ * @param[in] readDataSize the number of bytes to read
+ * @param[in] timeout the maximum time to wait for the operation to complete
+ * @retval ERROR_NONE when the operation was successful
+ */
 error_t i2c_controller_write_read(struct Device* device, uint8_t address, const uint8_t* writeData, size_t writeDataSize, uint8_t* readData, size_t readDataSize, TickType_t timeout);
 
+/**
+ * @brief Reads data from a register of an I2C device using the specified controller.
+ * @param[in] device the I2C controller device
+ * @param[in] address the 7-bit I2C address of the slave device
+ * @param[in] reg the register address to read from
+ * @param[out] data the buffer to store the read data
+ * @param[in] dataSize the number of bytes to read
+ * @param[in] timeout the maximum time to wait for the operation to complete
+ * @retval ERROR_NONE when the read operation was successful
+ */
+error_t i2c_controller_read_register(struct Device* device, uint8_t address, uint8_t reg, uint8_t* data, size_t dataSize, TickType_t timeout);
+
+/**
+ * @brief Writes data to a register of an I2C device using the specified controller.
+ * @param[in] device the I2C controller device
+ * @param[in] address the 7-bit I2C address of the slave device
+ * @param[in] reg the register address to write to
+ * @param[in] data the buffer containing the data to write
+ * @param[in] dataSize the number of bytes to write
+ * @param[in] timeout the maximum time to wait for the operation to complete
+ * @retval ERROR_NONE when the write operation was successful
+ */
+error_t i2c_controller_write_register(struct Device* device, uint8_t address, uint8_t reg, const uint8_t* data, uint16_t dataSize, TickType_t timeout);
+
+/**
+ * @brief Writes an array of register-value pairs to an I2C device.
+ * @param[in] device the I2C controller device
+ * @param[in] address the 7-bit I2C address of the slave device
+ * @param[in] data an array of bytes where even indices are register addresses and odd indices are values
+ * @param[in] dataSize the number of bytes in the data array (must be even)
+ * @param[in] timeout the maximum time to wait for each operation to complete
+ * @retval ERROR_NONE when all write operations were successful
+ */
+error_t i2c_controller_write_register_array(struct Device* device, uint8_t address, const uint8_t* data, uint16_t dataSize, TickType_t timeout);
+
+/**
+ * @brief Checks if an I2C device is present at the specified address.
+ * @param[in] device the I2C controller device
+ * @param[in] address the 7-bit I2C address to check
+ * @param[in] timeout the maximum time to wait for the check to complete
+ * @retval ERROR_NONE when a device responded at the address
+ */
+error_t i2c_controller_has_device_at_address(struct Device* device, uint8_t address, TickType_t timeout);
+
 extern const struct DeviceType I2C_CONTROLLER_TYPE;
 
 #ifdef __cplusplus

TactilityKernel/Include/tactility/error.h

@@ -2,6 +2,10 @@
 
 #pragma once
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 // Avoid potential clash with bits/types/error_t.h
 #ifndef __error_t_defined
 typedef int error_t;
@@ -17,3 +21,11 @@ typedef int error_t;
 #define ERROR_RESOURCE 7 // A problem with a resource/dependency
 #define ERROR_TIMEOUT 8
 #define ERROR_OUT_OF_MEMORY 9
+#define ERROR_NOT_SUPPORTED 10
+
+/** Convert an error_t to a human-readable text. Useful for logging. */
+const char* error_to_string(error_t error);
+
+#ifdef __cplusplus
+}
+#endif

TactilityKernel/Include/tactility/time.h

@@ -1,7 +1,13 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Time-keeping related functionality.
+ * This includes functionality for both ticks and seconds.
+ */
 #pragma once
 
 #include <stdint.h>
 
+#include "defines.h"
 #include "tactility/freertos/task.h"
 
 #ifdef ESP_PLATFORM
@@ -32,6 +38,14 @@ static inline size_t get_millis() {
     return get_ticks() * portTICK_PERIOD_MS;
 }
 
+static inline TickType_t get_timeout_remaining_ticks(TickType_t timeout, TickType_t start_time) {
+    TickType_t ticks_passed = get_ticks() - start_time;
+    if (ticks_passed >= timeout) {
+        return 0;
+    }
+    return timeout - ticks_passed;
+}
+
 /** @return the frequency at which the kernel task schedulers operate */
 uint32_t kernel_get_tick_frequency();
 

TactilityKernel/Source/concurrent/dispatcher.cpp

@@ -11,7 +11,7 @@
 #include <tactility/log.h>
 #include <atomic>
 
-#define TAG LOG_TAG("Dispatcher")
+#define TAG LOG_TAG(Dispatcher)
 
 static constexpr EventBits_t BACKPRESSURE_WARNING_COUNT = 100U;
 static constexpr EventBits_t WAIT_FLAG = 1U;

TactilityKernel/Source/concurrent/thread.cpp

@@ -0,0 +1,278 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <tactility/concurrent/thread.h>
+#include <tactility/concurrent/mutex.h>
+#include <tactility/check.h>
+#include <tactility/delay.h>
+#include <tactility/log.h>
+#include <tactility/time.h>
+
+#include <cstdlib>
+#include <cstring>
+#include <string>
+
+static const size_t LOCAL_STORAGE_SELF_POINTER_INDEX = 0;
+static const char* TAG = LOG_TAG(Thread);
+
+struct Thread {
+    TaskHandle_t taskHandle = nullptr;
+    ThreadState state = THREAD_STATE_STOPPED;
+    thread_main_fn_t mainFunction = nullptr;
+    void* mainFunctionContext = nullptr;
+    int32_t callbackResult = 0;
+    thread_state_callback_t stateCallback = nullptr;
+    void* stateCallbackContext = nullptr;
+    std::string name = "unnamed";
+    enum ThreadPriority priority = THREAD_PRIORITY_NORMAL;
+    struct Mutex mutex = { 0 };
+    configSTACK_DEPTH_TYPE stackSize = 4096;
+    portBASE_TYPE affinity = -1;
+
+    Thread() {
+        mutex_construct(&mutex);
+    }
+
+    ~Thread() {
+        mutex_destruct(&mutex);
+    }
+
+    void lock() { mutex_lock(&mutex); }
+
+    void unlock() { mutex_unlock(&mutex); }
+};
+
+static void thread_set_state_internal(Thread* thread, ThreadState newState) {
+    thread->lock();
+    thread->state = newState;
+    auto cb = thread->stateCallback;
+    auto cb_ctx = thread->stateCallbackContext;
+    thread->unlock();
+    if (cb) {
+        cb(newState, cb_ctx);
+    }
+}
+
+static void thread_main_body(void* context) {
+    check(context != nullptr);
+    auto* thread = static_cast<Thread*>(context);
+
+    // Save Thread instance pointer to task local storage
+    check(pvTaskGetThreadLocalStoragePointer(nullptr, LOCAL_STORAGE_SELF_POINTER_INDEX) == nullptr);
+    vTaskSetThreadLocalStoragePointer(nullptr, LOCAL_STORAGE_SELF_POINTER_INDEX, thread);
+
+    LOG_I(TAG, "Starting %s", thread->name.c_str()); // No need to lock as we don't allow mutation after thread start
+    check(thread->state == THREAD_STATE_STARTING);
+    thread_set_state_internal(thread, THREAD_STATE_RUNNING);
+
+    int32_t result = thread->mainFunction(thread->mainFunctionContext);
+    thread->lock();
+    thread->callbackResult = result;
+    thread->unlock();
+
+    check(thread->state == THREAD_STATE_RUNNING);
+    thread_set_state_internal(thread, THREAD_STATE_STOPPED);
+    LOG_I(TAG, "Stopped %s", thread->name.c_str()); // No need to lock as we don't allow mutation after thread start
+
+    vTaskSetThreadLocalStoragePointer(nullptr, LOCAL_STORAGE_SELF_POINTER_INDEX, nullptr);
+
+    thread->lock();
+    thread->taskHandle = nullptr;
+    thread->unlock();
+
+    vTaskDelete(nullptr);
+}
+
+extern "C" {
+
+Thread* thread_alloc(void) {
+    auto* thread = new(std::nothrow) Thread();
+    if (thread == nullptr) {
+        return nullptr;
+    }
+    return thread;
+}
+
+Thread* thread_alloc_full(
+    const char* name,
+    configSTACK_DEPTH_TYPE stack_size,
+    thread_main_fn_t function,
+    void* function_context,
+    portBASE_TYPE affinity
+) {
+    auto* thread = new(std::nothrow) Thread();
+    if (thread != nullptr) {
+        thread_set_name(thread, name);
+        thread_set_stack_size(thread, stack_size);
+        thread_set_main_function(thread, function, function_context);
+        thread_set_affinity(thread, affinity);
+    }
+    return thread;
+}
+
+void thread_free(Thread* thread) {
+    check(thread);
+    check(thread->state == THREAD_STATE_STOPPED);
+    check(thread->taskHandle == nullptr);
+    delete thread;
+}
+
+void thread_set_name(Thread* thread, const char* name) {
+    check(name != nullptr);
+    thread->lock();
+    check(thread->state == THREAD_STATE_STOPPED);
+    thread->name = name;
+    thread->unlock();
+}
+
+void thread_set_stack_size(Thread* thread, size_t stack_size) {
+    thread->lock();
+    check(stack_size > 0);
+    check(thread->state == THREAD_STATE_STOPPED);
+    thread->stackSize = stack_size;
+    thread->unlock();
+}
+
+void thread_set_affinity(Thread* thread, portBASE_TYPE affinity) {
+    thread->lock();
+    check(thread->state == THREAD_STATE_STOPPED);
+    thread->affinity = affinity;
+    thread->unlock();
+}
+
+void thread_set_main_function(Thread* thread, thread_main_fn_t function, void* context) {
+    thread->lock();
+    check(function != nullptr);
+    check(thread->state == THREAD_STATE_STOPPED);
+    thread->mainFunction = function;
+    thread->mainFunctionContext = context;
+    thread->unlock();
+}
+
+void thread_set_priority(Thread* thread, enum ThreadPriority priority) {
+    thread->lock();
+    check(thread->state == THREAD_STATE_STOPPED);
+    thread->priority = priority;
+    thread->unlock();
+}
+
+void thread_set_state_callback(Thread* thread, thread_state_callback_t callback, void* context) {
+    thread->lock();
+    check(callback != nullptr);
+    check(thread->state == THREAD_STATE_STOPPED);
+    thread->stateCallback = callback;
+    thread->stateCallbackContext = context;
+    thread->unlock();
+}
+
+ThreadState thread_get_state(Thread* thread) {
+    check(xPortInIsrContext() == pdFALSE);
+    thread->lock();
+    ThreadState state = thread->state;
+    thread->unlock();
+    return state;
+}
+
+error_t thread_start(Thread* thread) {
+    thread->lock();
+    check(thread->mainFunction != nullptr);
+    check(thread->state == THREAD_STATE_STOPPED);
+    check(thread->stackSize);
+    thread->unlock();
+
+    thread_set_state_internal(thread, THREAD_STATE_STARTING);
+
+    thread->lock();
+    uint32_t stack_depth = thread->stackSize / sizeof(StackType_t);
+    enum ThreadPriority priority = thread->priority;
+    portBASE_TYPE affinity = thread->affinity;
+    thread->unlock();
+
+    BaseType_t result;
+    if (affinity != -1) {
+#ifdef ESP_PLATFORM
+        result = xTaskCreatePinnedToCore(
+            thread_main_body,
+            thread->name.c_str(),
+            stack_depth,
+            thread,
+            (UBaseType_t)priority,
+            &thread->taskHandle,
+            affinity
+        );
+#else
+        result = xTaskCreate(
+            thread_main_body,
+            thread->name.c_str(),
+            stack_depth,
+            thread,
+            (UBaseType_t)priority,
+            &thread->taskHandle
+        );
+#endif
+    } else {
+        result = xTaskCreate(
+            thread_main_body,
+            thread->name.c_str(),
+            stack_depth,
+            thread,
+            (UBaseType_t)priority,
+            &thread->taskHandle
+        );
+    }
+
+    if (result != pdPASS) {
+        thread_set_state_internal(thread, THREAD_STATE_STOPPED);
+        thread->lock();
+        thread->taskHandle = nullptr;
+        thread->unlock();
+        return ERROR_UNDEFINED;
+    }
+
+    return ERROR_NONE;
+}
+
+error_t thread_join(Thread* thread, TickType_t timeout, TickType_t poll_interval) {
+    check(thread_get_current() != thread);
+
+    TickType_t start_ticks = get_ticks();
+    while (thread_get_task_handle(thread)) {
+        delay_ticks(poll_interval);
+        if (get_ticks() - start_ticks > timeout) {
+            return ERROR_TIMEOUT;
+        }
+    }
+
+    return ERROR_NONE;
+}
+
+TaskHandle_t thread_get_task_handle(Thread* thread) {
+    thread->lock();
+    auto* handle = thread->taskHandle;
+    thread->unlock();
+    return handle;
+}
+
+int32_t thread_get_return_code(Thread* thread) {
+    thread->lock();
+    check(thread->state == THREAD_STATE_STOPPED);
+    auto result = thread->callbackResult;
+    thread->unlock();
+    return result;
+}
+
+uint32_t thread_get_stack_space(Thread* thread) {
+    if (xPortInIsrContext() == pdTRUE) {
+        return 0;
+    }
+    thread->lock();
+    check(thread->state == THREAD_STATE_RUNNING);
+    auto result = uxTaskGetStackHighWaterMark(thread->taskHandle) * sizeof(StackType_t);
+    thread->unlock();
+    return result;
+}
+
+Thread* thread_get_current(void) {
+    check(xPortInIsrContext() == pdFALSE);
+    return (Thread*)pvTaskGetThreadLocalStoragePointer(nullptr, LOCAL_STORAGE_SELF_POINTER_INDEX);
+}
+
+}

TactilityKernel/Source/concurrent/timer.c

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <tactility/concurrent/timer.h>
+#include <tactility/check.h>
+#include <tactility/freertos/timers.h>
+#include <stdlib.h>
+
+struct Timer {
+    TimerHandle_t handle;
+    timer_callback_t callback;
+    void* context;
+};
+
+static void timer_callback_internal(TimerHandle_t xTimer) {
+    struct Timer* timer = (struct Timer*)pvTimerGetTimerID(xTimer);
+    if (timer != NULL && timer->callback != NULL) {
+        timer->callback(timer->context);
+    }
+}
+
+struct Timer* timer_alloc(enum TimerType type, TickType_t ticks, timer_callback_t callback, void* context) {
+    check(xPortInIsrContext() == pdFALSE);
+    check(callback != NULL);
+
+    struct Timer* timer = (struct Timer*)malloc(sizeof(struct Timer));
+    if (timer == NULL) {
+        return NULL;
+    }
+
+    timer->callback = callback;
+    timer->context = context;
+
+    BaseType_t auto_reload = (type == TIMER_TYPE_ONCE) ? pdFALSE : pdTRUE;
+    timer->handle = xTimerCreate(NULL, ticks, auto_reload, timer, timer_callback_internal);
+
+    if (timer->handle == NULL) {
+        free(timer);
+        return NULL;
+    }
+
+    return timer;
+}
+
+void timer_free(struct Timer* timer) {
+    check(xPortInIsrContext() == pdFALSE);
+    check(timer != NULL);
+    // MAX_TICKS or a reasonable timeout for the timer command queue
+    xTimerDelete(timer->handle, portMAX_DELAY);
+    free(timer);
+}
+
+error_t timer_start(struct Timer* timer) {
+    check(xPortInIsrContext() == pdFALSE);
+    check(timer != NULL);
+    return (xTimerStart(timer->handle, portMAX_DELAY) == pdPASS) ? ERROR_NONE : ERROR_TIMEOUT;
+}
+
+error_t timer_stop(struct Timer* timer) {
+    check(xPortInIsrContext() == pdFALSE);
+    check(timer != NULL);
+    return (xTimerStop(timer->handle, portMAX_DELAY) == pdPASS) ? ERROR_NONE : ERROR_TIMEOUT;
+}
+
+error_t timer_reset_with_interval(struct Timer* timer, TickType_t interval) {
+    check(xPortInIsrContext() == pdFALSE);
+    check(timer != NULL);
+    if (xTimerChangePeriod(timer->handle, interval, portMAX_DELAY) != pdPASS) {
+        return ERROR_TIMEOUT;
+    }
+    return (xTimerReset(timer->handle, portMAX_DELAY) == pdPASS) ? ERROR_NONE : ERROR_TIMEOUT;
+}
+
+error_t timer_reset(struct Timer* timer) {
+    check(xPortInIsrContext() == pdFALSE);
+    check(timer != NULL);
+    return (xTimerReset(timer->handle, portMAX_DELAY) == pdPASS) ? ERROR_NONE : ERROR_TIMEOUT;
+}
+
+bool timer_is_running(struct Timer* timer) {
+    check(xPortInIsrContext() == pdFALSE);
+    check(timer != NULL);
+    return xTimerIsTimerActive(timer->handle) != pdFALSE;
+}
+
+TickType_t timer_get_expiry_time(struct Timer* timer) {
+    check(xPortInIsrContext() == pdFALSE);
+    check(timer != NULL);
+    return xTimerGetExpiryTime(timer->handle);
+}
+
+error_t timer_set_pending_callback(struct Timer* timer, timer_pending_callback_t callback, void* context, uint32_t arg, TickType_t timeout) {
+    (void)timer; // Unused in this implementation but kept for API consistency if needed later
+    BaseType_t result;
+    if (xPortInIsrContext() == pdTRUE) {
+        check(timeout == 0);
+        result = xTimerPendFunctionCallFromISR(callback, context, arg, NULL);
+    } else {
+        result = xTimerPendFunctionCall(callback, context, arg, timeout);
+    }
+    return (result == pdPASS) ? ERROR_NONE : ERROR_TIMEOUT;
+}
+
+void timer_set_callback_priority(struct Timer* timer, enum ThreadPriority priority) {
+    (void)timer; // Unused in this implementation but kept for API consistency if needed later
+    check(xPortInIsrContext() == pdFALSE);
+
+    TaskHandle_t task_handle = xTimerGetTimerDaemonTaskHandle();
+    check(task_handle != NULL);
+
+    vTaskPrioritySet(task_handle, (UBaseType_t)priority);
+}

TactilityKernel/Source/crash.cpp

@@ -1,7 +1,7 @@
 #include <tactility/freertos/task.h>
 #include <tactility/log.h>
 
-static const auto* TAG = LOG_TAG("Kernel");
+static const auto* TAG = LOG_TAG(Kernel);
 
 static void log_memory_info() {
 #ifdef ESP_PLATFORM

TactilityKernel/Source/device.cpp

@@ -146,6 +146,7 @@ failed_ledger_lookup:
 }
 
 error_t device_start(Device* device) {
+    LOG_I(TAG, "start %s", device->name);
     if (!device->internal.state.added) {
         return ERROR_INVALID_STATE;
     }
@@ -166,6 +167,7 @@ error_t device_start(Device* device) {
 }
 
 error_t device_stop(struct Device* device) {
+    LOG_I(TAG, "stop %s", device->name);
     if (!device->internal.state.added) {
         return ERROR_INVALID_STATE;
     }
@@ -183,6 +185,56 @@ error_t device_stop(struct Device* device) {
     return ERROR_NONE;
 }
 
+error_t device_construct_add(struct Device* device, const char* compatible) {
+    struct Driver* driver = driver_find_compatible(compatible);
+    if (driver == nullptr) {
+        LOG_E(TAG, "Can't find driver '%s' for device '%s'", compatible, device->name);
+        return ERROR_RESOURCE;
+    }
+
+    error_t error = device_construct(device);
+    if (error != ERROR_NONE) {
+        LOG_E(TAG, "Failed to construct device %s: %s", device->name, error_to_string(error));
+        goto on_construct_error;
+    }
+
+    device_set_driver(device, driver);
+
+    error = device_add(device);
+    if (error != ERROR_NONE) {
+        LOG_E(TAG, "Failed to add device %s: %s", device->name, error_to_string(error));
+        goto on_add_error;
+    }
+
+    return ERROR_NONE;
+
+    on_add_error:
+    device_destruct(device);
+    on_construct_error:
+    return error;
+}
+
+error_t device_construct_add_start(struct Device* device, const char* compatible) {
+    error_t error = device_construct_add(device, compatible);
+    if (error != ERROR_NONE) {
+        goto on_construct_add_error;
+    }
+
+    error = device_start(device);
+    if (error != ERROR_NONE) {
+        LOG_E(TAG, "Failed to start device %s: %s", device->name, error_to_string(error));
+        goto on_start_error;
+    }
+
+    return ERROR_NONE;
+
+on_start_error:
+    device_remove(device);
+    device_destruct(device);
+on_construct_add_error:
+    return error;
+}
+
 void device_set_parent(Device* device, Device* parent) {
     assert(!device->internal.state.started);
     device->parent = parent;

TactilityKernel/Source/drivers/i2c_controller.cpp

@@ -1,6 +1,4 @@
 // SPDX-License-Identifier: Apache-2.0
-
-#include <tactility/driver.h>
 #include <tactility/drivers/i2c_controller.h>
 #include <tactility/error.h>
 
@@ -23,6 +21,34 @@ error_t i2c_controller_write_read(Device* device, uint8_t address, const uint8_t
     return I2C_DRIVER_API(driver)->write_read(device, address, writeData, writeDataSize, readData, readDataSize, timeout);
 }
 
+error_t i2c_controller_read_register(Device* device, uint8_t address, uint8_t reg, uint8_t* data, size_t dataSize, TickType_t timeout) {
+    const auto* driver = device_get_driver(device);
+    return I2C_DRIVER_API(driver)->read_register(device, address, reg, data, dataSize, timeout);
+}
+
+error_t i2c_controller_write_register(Device* device, uint8_t address, uint8_t reg, const uint8_t* data, uint16_t dataSize, TickType_t timeout) {
+    const auto* driver = device_get_driver(device);
+    return I2C_DRIVER_API(driver)->write_register(device, address, reg, data, dataSize, timeout);
+}
+
+error_t i2c_controller_write_register_array(Device* device, uint8_t address, const uint8_t* data, uint16_t dataSize, TickType_t timeout) {
+    const auto* driver = device_get_driver(device);
+    if (dataSize % 2 != 0) {
+        return ERROR_INVALID_ARGUMENT;
+    }
+    for (int i = 0; i < dataSize; i += 2) {
+        error_t error = I2C_DRIVER_API(driver)->write_register(device, address, data[i], &data[i + 1], 1, timeout);
+        if (error != ERROR_NONE) return error;
+    }
+    return ERROR_NONE;
+}
+
+error_t i2c_controller_has_device_at_address(Device* device, uint8_t address, TickType_t timeout) {
+    const auto* driver = device_get_driver(device);
+    uint8_t message[2] = { 0, 0 };
+    return I2C_DRIVER_API(driver)->write(device, address, message, 2, timeout);
+}
+
 const struct DeviceType I2C_CONTROLLER_TYPE { 0 };
 
 }

TactilityKernel/Source/error.cpp

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <tactility/error.h>
+
+extern "C" {
+
+const char* error_to_string(error_t error) {
+    switch (error) {
+        case ERROR_NONE:
+            return "no error";
+        case ERROR_UNDEFINED:
+            return "undefined";
+        case ERROR_INVALID_STATE:
+            return "invalid state";
+        case ERROR_INVALID_ARGUMENT:
+            return "invalid argument";
+        case ERROR_MISSING_PARAMETER:
+            return "missing parameter";
+        case ERROR_NOT_FOUND:
+            return "not found";
+        case ERROR_ISR_STATUS:
+            return "ISR status";
+        case ERROR_RESOURCE:
+            return "resource";
+        case ERROR_TIMEOUT:
+            return "timeout";
+        case ERROR_OUT_OF_MEMORY:
+            return "out of memory";
+        case ERROR_NOT_SUPPORTED:
+            return "not supported";
+        default:
+            return "unknown";
+    }
+}
+
+}