TactilityC improvements (#359)

- Expose HAL Configuration's `UiScale`
- Updated docs
- Fix for `tt_timer_alloc()`
- Changed `enum class` to regular C `enum`
- Renamed enums (add prefix)
- Include `<stdbool.h>` where needed

TactilityC/Include/tt_app.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include <stdio.h>
+#include <stdbool.h>
 
 #include "tt_app_manifest.h"
 

TactilityC/Include/tt_gps.h

@@ -1,5 +1,7 @@
 #pragma once
 
+#include <stdbool.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif

TactilityC/Include/tt_hal.h

@@ -0,0 +1,20 @@
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** Affects LVGL widget style */
+enum UiScale {
+    /** Ideal for very small non-touch screen devices (e.g. Waveshare S3 LCD 1.3") */
+    UiScaleSmallest,
+    /** Nothing was changed in the LVGL UI/UX */
+    UiScaleDefault
+};
+
+/** @return the UI scaling setting for this device. */
+UiScale tt_hal_configuration_get_ui_scale();
+
+#ifdef __cplusplus
+}
+#endif

TactilityC/Include/tt_hal_device.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include <stdint.h>
+#include <stdbool.h>
 
 #ifdef __cplusplus
 extern "C" {

TactilityC/Include/tt_hal_display.h

@@ -1,8 +1,8 @@
 #pragma once
 
 #include <tt_kernel.h>
-
-#include "tt_hal_device.h"
+#include <tt_hal_device.h>
+#include <stdbool.h>
 
 #ifdef __cplusplus
 extern "C" {

TactilityC/Include/tt_hal_gpio.h

@@ -7,31 +7,74 @@
 extern "C" {
 #endif
 
+/** Logical GPIO pin identifier used by the HAL. Typically maps to the SoC GPIO number. */
 typedef unsigned int GpioPin;
+/** Value indicating that no GPIO pin is used/applicable. */
 #define GPIO_NO_PIN -1
 
-/** @warning The order must match tt::hal::gpio::Mode */
-enum class GpioMode {
-    Disable = 0,
-    Input,
-    Output,
-    OutputOpenDrain,
-    InputOutput,
-    InputOutputOpenDrain
+/** GPIO pin mode used by the HAL.
+ * @warning The order must match tt::hal::gpio::Mode
+ */
+enum GpioMode {
+    /** Pin is disabled (high-impedance). */
+    GpioModeDisable = 0,
+    /** Pin configured as input only. */
+    GpioModeInput,
+    /** Pin configured as push-pull output only. */
+    GpioModeOutput,
+    /** Pin configured as open-drain output only. */
+    GpioModeOutputOpenDrain,
+    /** Pin configured for both input and output (push-pull). */
+    GpioModeInputOutput,
+    /** Pin configured for both input and output (open-drain). */
+    GpioModeInputOutputOpenDrain
 };
 
-/** Configure a single pin */
+/** Configure a single GPIO pin.
+ * @param[in] pin      GPIO number to configure.
+ * @param[in] mode     Desired I/O mode for the pin.
+ * @param[in] pullUp   Enable internal pull-up if true.
+ * @param[in] pullDown Enable internal pull-down if true.
+ * @return true on success, false if the pin is invalid or configuration failed.
+ */
 bool tt_hal_gpio_configure(GpioPin pin, GpioMode mode, bool pullUp, bool pullDown);
 
-/** Configure a set of pins defined by their bit index */
+/** Configure a set of GPIO pins in one call.
+ * The bit index of pin N is (1ULL << N).
+ * @param[in] pinBitMask Bit mask of pins to configure.
+ * @param[in] mode       Desired I/O mode for the pins.
+ * @param[in] pullUp     Enable internal pull-up on the selected pins if true.
+ * @param[in] pullDown   Enable internal pull-down on the selected pins if true.
+ * @return true on success, false if any pin is invalid or configuration failed.
+ */
 bool tt_hal_gpio_configure_with_pin_bitmask(uint64_t pinBitMask, GpioMode mode, bool pullUp, bool pullDown);
 
+/** Set the input/output mode for the specified pin.
+ * @param[in] pin  The pin to configure.
+ * @param[in] mode The mode to set.
+ * @return true on success, false if the pin is invalid or mode not supported.
+ */
 bool tt_hal_gpio_set_mode(GpioPin pin, GpioMode mode);
 
+/** Read the current logic level of a pin.
+ * The pin should be configured for input or input/output.
+ * @param[in] pin The pin to read.
+ * @return true if the level is high, false if low. If the pin is invalid, the
+ *         behavior is implementation-defined and may return false.
+ */
 bool tt_hal_gpio_get_level(GpioPin pin);
 
+/** Drive the output level of a pin.
+ * The pin should be configured for output or input/output.
+ * @param[in] pin   The pin to drive.
+ * @param[in] level Output level to set (true = high, false = low).
+ * @return true on success, false if the pin is invalid or not configured as output.
+ */
 bool tt_hal_gpio_set_level(GpioPin pin, bool level);
 
+/** Get the number of GPIO pins available on this platform.
+ * @return The count of valid GPIO pins.
+ */
 int tt_hal_gpio_get_pin_count();
 
 #ifdef __cplusplus

TactilityC/Include/tt_hal_i2c.h

@@ -3,6 +3,7 @@
 #include <freertos/FreeRTOS.h>
 #include <hal/i2c_types.h>
 #include <stddef.h>
+#include <stdbool.h>
 
 #ifdef __cplusplus
 extern "C" {

TactilityC/Include/tt_hal_touch.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include "tt_hal_device.h"
+#include <stdbool.h>
 
 #ifdef __cplusplus
 extern "C" {

TactilityC/Include/tt_kernel.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include <stdint.h>
+#include <stdbool.h>
 
 #ifdef __cplusplus
 extern "C" {

TactilityC/Include/tt_lock.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include "tt_kernel.h"
+#include <stdbool.h>
 
 #ifdef __cplusplus
 extern "C" {

TactilityC/Include/tt_lvgl.h

@@ -1,5 +1,7 @@
 #pragma once
 
+#include <stdbool.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif

TactilityC/Include/tt_message_queue.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include <freertos/FreeRTOS.h>
+#include <stdbool.h>
 
 #ifdef __cplusplus
 extern "C" {

TactilityC/Include/tt_timer.h

@@ -3,13 +3,13 @@
 #include "tt_thread.h"
 #include <freertos/FreeRTOS.h>
 
+#include <stdint.h>
+#include <stdbool.h>
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-#include <stdint.h>
-#include <stdbool.h>
-
 /** The handle that represents a timer instance */
 typedef void* TimerHandle;
 

TactilityC/Source/tt_hal.cpp

@@ -0,0 +1,13 @@
+#include "tt_hal.h"
+
+#include <Tactility/Tactility.h>
+#include <Tactility/hal/Configuration.h>
+
+extern "C" {
+
+UiScale tt_hal_configuration_get_ui_scale() {
+    auto scale = tt::hal::getConfiguration()->uiScale;
+    return static_cast<UiScale>(scale);
+}
+
+}

TactilityC/Source/tt_init.cpp

@@ -7,6 +7,7 @@
 #include "tt_bundle.h"
 #include "tt_file.h"
 #include "tt_gps.h"
+#include "tt_hal.h"
 #include "tt_hal_device.h"
 #include "tt_hal_display.h"
 #include "tt_hal_gpio.h"
@@ -183,6 +184,7 @@ const esp_elfsym main_symbols[] {
     ESP_ELFSYM_EXPORT(tt_bundle_put_string),
     ESP_ELFSYM_EXPORT(tt_gps_has_coordinates),
     ESP_ELFSYM_EXPORT(tt_gps_get_coordinates),
+    ESP_ELFSYM_EXPORT(tt_hal_configuration_get_ui_scale),
     ESP_ELFSYM_EXPORT(tt_hal_device_find),
     ESP_ELFSYM_EXPORT(tt_hal_display_driver_alloc),
     ESP_ELFSYM_EXPORT(tt_hal_display_driver_draw_bitmap),

TactilityC/Source/tt_timer.cpp

@@ -5,42 +5,44 @@ struct TimerWrapper {
     std::unique_ptr<tt::Timer> timer;
 };
 
+#define HANDLE_TO_WRAPPER(handle) static_cast<TimerWrapper*>(handle)
+
 extern "C" {
 
 TimerHandle tt_timer_alloc(TimerType type, TimerCallback callback, void* callbackContext) {
-    auto wrapper = std::make_shared<TimerWrapper>();
-    wrapper->timer = std::make_unique<tt::Timer>((tt::Timer::Type)type, [callback, callbackContext](){ callback(callbackContext); });
-    return wrapper.get();
+    auto wrapper = new TimerWrapper;
+    wrapper->timer = std::make_unique<tt::Timer>(static_cast<tt::Timer::Type>(type), [callback, callbackContext](){ callback(callbackContext); });
+    return wrapper;
 }
 
 void tt_timer_free(TimerHandle handle) {
-    auto* wrapper = (TimerWrapper*)handle;
+    auto* wrapper = static_cast<TimerWrapper*>(handle);
     wrapper->timer = nullptr;
     delete wrapper;
 }
 
 bool tt_timer_start(TimerHandle handle, TickType_t intervalTicks) {
-    return ((TimerWrapper*)handle)->timer->start(intervalTicks);
+    return HANDLE_TO_WRAPPER(handle)->timer->start(intervalTicks);
 }
 
 bool tt_timer_restart(TimerHandle handle, TickType_t intervalTicks) {
-    return ((TimerWrapper*)handle)->timer->restart(intervalTicks);
+    return HANDLE_TO_WRAPPER(handle)->timer->restart(intervalTicks);
 }
 
 bool tt_timer_stop(TimerHandle handle) {
-    return ((TimerWrapper*)handle)->timer->stop();
+    return HANDLE_TO_WRAPPER(handle)->timer->stop();
 }
 
 bool tt_timer_is_running(TimerHandle handle) {
-    return ((TimerWrapper*)handle)->timer->isRunning();
+    return HANDLE_TO_WRAPPER(handle)->timer->isRunning();
 }
 
 uint32_t tt_timer_get_expire_time(TimerHandle handle) {
-    return ((TimerWrapper*)handle)->timer->getExpireTime();
+    return HANDLE_TO_WRAPPER(handle)->timer->getExpireTime();
 }
 
 bool tt_timer_set_pending_callback(TimerHandle handle, TimerPendingCallback callback, void* callbackContext, uint32_t callbackArg, TickType_t timeoutTicks) {
-    return ((TimerWrapper*)handle)->timer->setPendingCallback(
+    return HANDLE_TO_WRAPPER(handle)->timer->setPendingCallback(
         callback,
         callbackContext,
         callbackArg,
@@ -49,7 +51,7 @@ bool tt_timer_set_pending_callback(TimerHandle handle, TimerPendingCallback call
 }
 
 void tt_timer_set_thread_priority(TimerHandle handle, ThreadPriority priority) {
-    ((TimerWrapper*)handle)->timer->setThreadPriority((tt::Thread::Priority)priority);
+    HANDLE_TO_WRAPPER(handle)->timer->setThreadPriority(static_cast<tt::Thread::Priority>(priority));
 }
 
 }