Various improvements (#461)

* **New Features**
  * Time and delay utilities added (ticks, ms, µs); SD card now uses an expansion-header CS pin; HTTP downloads warn when run on the GUI task and yield to avoid blocking.

* **Bug Fixes / Reliability**
  * Many hard-crash paths converted to guarded checks to reduce abrupt termination and improve stability.

* **Tests**
  * Unit tests added to validate time and delay accuracy.

* **Chores**
  * License header and build/macro updates.

TactilityKernel/Include/Tactility/Check.h

@@ -0,0 +1,32 @@
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <Tactility/Log.h>
+
+__attribute__((noreturn)) extern void __crash(void);
+
+#define CHECK_GET_MACRO(_1, _2, NAME, ...) NAME
+#define check(...) CHECK_GET_MACRO(__VA_ARGS__, CHECK_MSG, CHECK_NO_MSG)(__VA_ARGS__)
+
+#define CHECK_NO_MSG(condition) \
+    do { \
+        if (!(condition)) { \
+            LOG_E("Error", "Check failed: %s at %s:%d", #condition, __FILE__, __LINE__); \
+            __crash(); \
+        } \
+    } while (0)
+
+#define CHECK_MSG(condition, message) \
+    do { \
+        if (!(condition)) { \
+            LOG_E("Error", "Check failed: %s at %s:%d", message, __FILE__, __LINE__); \
+            __crash(); \
+        } \
+    } while (0)
+
+#ifdef __cplusplus
+}
+#endif

TactilityKernel/Include/Tactility/Delay.h

@@ -0,0 +1,54 @@
+#pragma once
+
+#include "Time.h"
+#include <stdint.h>
+
+#ifdef ESP_PLATFORM
+#include <rom/ets_sys.h>
+#else
+#include <unistd.h>
+#endif
+
+#include <Tactility/Check.h>
+#include "Tactility/FreeRTOS/FreeRTOS.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * Delay the current task for the specified amount of ticks
+ * @warning Does not work in ISR context
+ */
+static inline void delay_ticks(TickType_t ticks) {
+    check(xPortInIsrContext() == pdFALSE);
+    if (ticks == 0U) {
+        taskYIELD();
+    } else {
+        vTaskDelay(ticks);
+    }
+}
+
+/**
+ * Delay the current task for the specified amount of milliseconds
+ * @warning Does not work in ISR context
+ */
+static inline void delay_millis(uint32_t milliSeconds) {
+    delay_ticks(millis_to_ticks(milliSeconds));
+}
+
+/**
+ * Stall the currently active CPU core for the specified amount of microseconds.
+ * This does not allow other tasks to run on the stalled CPU core.
+ */
+static inline void delay_micros(uint32_t microseconds) {
+#ifdef ESP_PLATFORM
+    ets_delay_us(microseconds);
+#else
+    usleep(microseconds);
+#endif
+}
+
+#ifdef __cplusplus
+}
+#endif

TactilityKernel/Include/Tactility/FreeRTOS/port.h

@@ -5,6 +5,6 @@
 #include "FreeRTOS.h"
 
 #ifndef ESP_PLATFORM
-#define xPortInIsrContext(x) (false)
+#define xPortInIsrContext() (pdFALSE)
 #define vPortAssertIfInISR()
 #endif

TactilityKernel/Include/Tactility/Time.h

@@ -0,0 +1,65 @@
+#pragma once
+
+#include <stdint.h>
+
+#include "Tactility/FreeRTOS/task.h"
+
+#ifdef ESP_PLATFORM
+#include <esp_timer.h>
+#else
+#include <sys/time.h>
+#include <time.h>
+#endif
+
+// Projects that include this header must align with Tactility's frequency (e.g. apps)
+static_assert(configTICK_RATE_HZ == 1000);
+
+static inline uint32_t get_tick_frequency() {
+    return configTICK_RATE_HZ;
+}
+
+/** @return the amount of ticks that have passed since FreeRTOS' main task started */
+static inline TickType_t get_ticks() {
+    if (xPortInIsrContext() == pdTRUE) {
+        return xTaskGetTickCountFromISR();
+    } else {
+        return xTaskGetTickCount();
+    }
+}
+
+/** @return the milliseconds that have passed since FreeRTOS' main task started */
+static inline size_t get_millis() {
+    return get_ticks() * portTICK_PERIOD_MS;
+}
+
+/** @return the frequency at which the kernel task schedulers operate */
+uint32_t kernel_get_tick_frequency();
+
+/** @return the microseconds that have passed since boot */
+static inline int64_t get_micros_since_boot() {
+#ifdef ESP_PLATFORM
+    return esp_timer_get_time();
+#else
+    timespec ts;
+    if (clock_gettime(CLOCK_MONOTONIC, &ts) == 0) {
+        return (static_cast<int64_t>(ts.tv_sec) * 1000000LL) + (ts.tv_nsec / 1000);
+    }
+    timeval tv;
+    gettimeofday(&tv, nullptr);
+    return (static_cast<int64_t>(tv.tv_sec) * 1000000LL) + tv.tv_usec;
+#endif
+}
+
+/** Convert seconds to ticks */
+static inline TickType_t seconds_to_ticks(uint32_t seconds) {
+    return static_cast<uint64_t>(seconds) * 1000U / portTICK_PERIOD_MS;
+}
+
+/** Convert milliseconds to ticks */
+static inline TickType_t millis_to_ticks(uint32_t milliSeconds) {
+#if configTICK_RATE_HZ == 1000
+    return static_cast<TickType_t>(milliSeconds);
+#else
+    return static_cast<TickType_t>(((float)configTICK_RATE_HZ) / 1000.0f * (float)milliSeconds);
+#endif
+}

TactilityKernel/Include/Tactility/concurrent/EventGroup.h

@@ -5,21 +5,21 @@
 extern "C" {
 #endif
 
-#include <assert.h>
 #include <stdbool.h>
 #include <stdint.h>
 
+#include <Tactility/Check.h>
 #include <Tactility/Error.h>
 #include <Tactility/FreeRTOS/event_groups.h>
 
 static inline void event_group_construct(EventGroupHandle_t* eventGroup) {
-    assert(xPortInIsrContext() == pdFALSE);
+    check(xPortInIsrContext() == pdFALSE);
     *eventGroup = xEventGroupCreate();
 }
 
 static inline void event_group_destruct(EventGroupHandle_t* eventGroup) {
-    assert(xPortInIsrContext() == pdFALSE);
-    assert(*eventGroup != NULL);
+    check(xPortInIsrContext() == pdFALSE);
+    check(*eventGroup != NULL);
     vEventGroupDelete(*eventGroup);
     *eventGroup = NULL;
 }

TactilityKernel/Include/Tactility/concurrent/Mutex.h

@@ -4,6 +4,8 @@
 
 #include <assert.h>
 #include <stdbool.h>
+
+#include <Tactility/Check.h>
 #include <Tactility/FreeRTOS/semphr.h>
 
 #ifdef __cplusplus
@@ -28,17 +30,17 @@ inline static void mutex_destruct(struct Mutex* mutex) {
 }
 
 inline static void mutex_lock(struct Mutex* mutex) {
-    assert(xPortInIsrContext() != pdTRUE);
+    check(xPortInIsrContext() != pdTRUE);
     xSemaphoreTake(mutex->handle, portMAX_DELAY);
 }
 
 inline static bool mutex_try_lock(struct Mutex* mutex) {
-    assert(xPortInIsrContext() != pdTRUE);
+    check(xPortInIsrContext() != pdTRUE);
     return xSemaphoreTake(mutex->handle, 0) == pdTRUE;
 }
 
 inline static bool mutex_try_lock_timed(struct Mutex* mutex, TickType_t timeout) {
-    assert(xPortInIsrContext() != pdTRUE);
+    check(xPortInIsrContext() != pdTRUE);
     return xSemaphoreTake(mutex->handle, timeout) == pdTRUE;
 }
 
@@ -51,7 +53,7 @@ inline static bool mutex_is_locked(struct Mutex* mutex) {
 }
 
 inline static void mutex_unlock(struct Mutex* mutex) {
-    assert(xPortInIsrContext() != pdTRUE);
+    check(xPortInIsrContext() != pdTRUE);
     xSemaphoreGive(mutex->handle);
 }
 

TactilityKernel/Include/Tactility/concurrent/RecursiveMutex.h

@@ -3,7 +3,7 @@
 #pragma once
 
 #include <stdbool.h>
-#include <assert.h>
+#include <Tactility/Check.h>
 #include <Tactility/FreeRTOS/semphr.h>
 
 #ifdef __cplusplus
@@ -19,14 +19,14 @@ inline static void recursive_mutex_construct(struct RecursiveMutex* mutex) {
 }
 
 inline static void recursive_mutex_destruct(struct RecursiveMutex* mutex) {
-    assert(mutex->handle != NULL);
-    vPortAssertIfInISR();
+    check(mutex->handle != NULL);
+    check(xPortInIsrContext() != pdTRUE);
     vSemaphoreDelete(mutex->handle);
     mutex->handle = NULL;
 }
 
 inline static void recursive_mutex_lock(struct RecursiveMutex* mutex) {
-    assert(xPortInIsrContext() != pdTRUE);
+    check(xPortInIsrContext() != pdTRUE);
     xSemaphoreTakeRecursive(mutex->handle, portMAX_DELAY);
 }
 
@@ -39,17 +39,17 @@ inline static bool recursive_mutex_is_locked(struct RecursiveMutex* mutex) {
 }
 
 inline static bool recursive_mutex_try_lock(struct RecursiveMutex* mutex) {
-    assert(xPortInIsrContext() != pdTRUE);
+    check(xPortInIsrContext() != pdTRUE);
     return xSemaphoreTakeRecursive(mutex->handle, 0) == pdTRUE;
 }
 
 inline static bool recursive_mutex_try_lock_timed(struct RecursiveMutex* mutex, TickType_t timeout) {
-    assert(xPortInIsrContext() != pdTRUE);
+    check(xPortInIsrContext() != pdTRUE);
     return xSemaphoreTakeRecursive(mutex->handle, timeout) == pdTRUE;
 }
 
 inline static void recursive_mutex_unlock(struct RecursiveMutex* mutex) {
-    assert(xPortInIsrContext() != pdTRUE);
+    check(xPortInIsrContext() != pdTRUE);
     xSemaphoreGiveRecursive(mutex->handle);
 }
 

TactilityKernel/Source/Crash.cpp

@@ -0,0 +1,39 @@
+#include <Tactility/Log.h>
+#include <Tactility/FreeRTOS/task.h>
+
+static const auto* TAG = LOG_TAG("Kernel");
+
+static void log_memory_info() {
+#ifdef ESP_PLATFORM
+    LOG_E(TAG, "Default memory caps:");
+    LOG_E(TAG, "  Total: %" PRIu64, static_cast<uint64_t>(heap_caps_get_total_size(MALLOC_CAP_DEFAULT)));
+    LOG_E(TAG, "  Free: %" PRIu64, static_cast<uint64_t>(heap_caps_get_free_size(MALLOC_CAP_DEFAULT)));
+    LOG_E(TAG, "  Min free: %" PRIu64, static_cast<uint64_t>(heap_caps_get_minimum_free_size(MALLOC_CAP_DEFAULT)));
+    LOG_E(TAG, "Internal memory caps:");
+    LOG_E(TAG, "  Total: %" PRIu64, static_cast<uint64_t>(heap_caps_get_total_size(MALLOC_CAP_INTERNAL)));
+    LOG_E(TAG, "  Free: %" PRIu64, static_cast<uint64_t>(heap_caps_get_free_size(MALLOC_CAP_INTERNAL)));
+    LOG_E(TAG, "  Min free: %" PRIu64, static_cast<uint64_t>(heap_caps_get_minimum_free_size(MALLOC_CAP_INTERNAL)));
+#endif
+}
+
+static void log_task_info() {
+    const char* name = pcTaskGetName(nullptr);
+    const char* safe_name = name ? name : "main";
+    LOG_E(TAG, "Task: %s", safe_name);
+}
+
+extern "C" {
+
+__attribute__((noreturn)) void __crash(void) {
+    log_task_info();
+    log_memory_info();
+    // TODO: Add breakpoint when debugger is attached.
+#ifdef ESP_PLATFORM
+    esp_system_abort("System halted. Connect debugger for more info.");
+#else
+    while (true) { /* Indefinite lock-up */ }
+#endif
+    __builtin_unreachable();
+}
+
+}

TactilityKernel/Source/Driver.cpp

@@ -70,7 +70,6 @@ static error_t driver_remove(Driver* driver) {
 
     ledger.lock();
     const auto iterator = std::ranges::find(ledger.drivers, driver);
-    // check that there actually is a 3 in our vector
     if (iterator == ledger.drivers.end()) {
         ledger.unlock();
         return ERROR_NOT_FOUND;
@@ -184,7 +183,7 @@ error_t driver_unbind(Driver* driver, Device* device) {
     driver_internal_data(driver)->use_count--;
     driver_unlock(driver);
 
-    LOG_I(TAG, "unbound %s to %s", driver->name, device->name);
+    LOG_I(TAG, "unbound %s from %s", driver->name, device->name);
 
     return ERROR_NONE;
 

TactilityKernel/Source/Log.cpp

@@ -7,6 +7,8 @@
 #include <stdio.h>
 #include <stdarg.h>
 
+extern "C" {
+
 void log_generic(const char* tag, const char* format, ...) {
     va_list args;
     va_start(args, format);
@@ -16,4 +18,6 @@ void log_generic(const char* tag, const char* format, ...) {
     va_end(args);
 }
 
+}
+
 #endif

TactilityKernel/Source/concurrent/EventGroup.cpp

@@ -48,7 +48,7 @@ error_t event_group_wait(
     uint32_t* outFlags,
     TickType_t timeout
 ) {
-    if (xPortInIsrContext()) {
+    if (xPortInIsrContext() == pdTRUE) {
         return ERROR_ISR_STATUS;
     }