Refactor LVGL code into kernel module (#472)

* **New Features**
  * Added a standalone LVGL module and enabled LVGL support in the simulator for richer local UI testing.

* **Refactor**
  * HAL and LVGL split into distinct modules; startup and device attach/detach flows reorganized for clearer lifecycle management.
  * Public APIs tightened with clearer nullability/documentation.

* **Bug Fixes**
  * More consistent LVGL start/stop and device attach/detach behavior for improved stability.

Tactility/Include/Tactility/Tactility.h

@@ -27,9 +27,10 @@ void run(const Configuration& config, Module* platformModule, Module* deviceModu
 
 /**
  * While technically nullable, this instance is always set if tt_init() succeeds.
+ * Could return nullptr if init was not called.
  * @return the Configuration instance that was passed on to tt_init() if init is successful
  */
-const Configuration* _Nullable getConfiguration();
+const Configuration* getConfiguration();
 
 /** Provides access to the dispatcher that runs on the main task.
  * @warning This dispatcher is used for WiFi and might block for some time during WiFi connection.
@@ -40,7 +41,7 @@ Dispatcher& getMainDispatcher();
 namespace hal {
 
 /** While technically this configuration is nullable, it's never null after initHeadless() is called. */
-const Configuration* _Nullable getConfiguration();
+const Configuration* getConfiguration();
 
 } // namespace hal
 

Tactility/Include/Tactility/app/App.h

@@ -44,7 +44,8 @@ public:
     virtual void onDestroy(AppContext& appContext) {}
     virtual void onShow(AppContext& appContext, lv_obj_t* parent) {}
     virtual void onHide(AppContext& appContext) {}
-    virtual void onResult(AppContext& appContext, LaunchId launchId, Result result, std::unique_ptr<Bundle> _Nullable resultData) {}
+    /** resultData could be null */
+    virtual void onResult(AppContext& appContext, LaunchId launchId, Result result, std::unique_ptr<Bundle> resultData) {}
 
     Mutex& getMutex() { return mutex; }
 
@@ -81,9 +82,9 @@ std::shared_ptr<App> create() { return std::shared_ptr<T>(new T); }
 /**
  * @brief Start an app
  * @param[in] id application name or id
- * @param[in] parameters optional parameters to pass onto the application
+ * @param[in] parameters optional parameters to pass onto the application. can be nullptr.
  */
-LaunchId start(const std::string& id, std::shared_ptr<const Bundle> _Nullable parameters = nullptr);
+LaunchId start(const std::string& id, std::shared_ptr<const Bundle> parameters = nullptr);
 
 /** @brief Stop the currently showing app. Show the previous app if any app was still running. */
 void stop();
@@ -103,10 +104,10 @@ void stopAll(const std::string& id);
 bool isRunning(const std::string& id);
 
 /** @return the currently running app context (it is only ever null before the splash screen is shown) */
-std::shared_ptr<AppContext> _Nullable getCurrentAppContext();
+std::shared_ptr<AppContext> getCurrentAppContext();
 
 /** @return the currently running app (it is only ever null before the splash screen is shown) */
-std::shared_ptr<App> _Nullable getCurrentApp();
+std::shared_ptr<App> getCurrentApp();
 
 bool install(const std::string& path);
 

Tactility/Include/Tactility/app/AppRegistration.h

@@ -18,7 +18,7 @@ bool removeAppManifest(const std::string& id);
  * @param[in] id the manifest id
  * @return the application manifest if it was found
  */
-_Nullable std::shared_ptr<AppManifest> findAppManifestById(const std::string& id);
+std::shared_ptr<AppManifest> findAppManifestById(const std::string& id);
 
 /** @return a list of all registered apps. This includes user and system apps. */
 std::vector<std::shared_ptr<AppManifest>> getAppManifests();

Tactility/Include/Tactility/app/ElfApp.h

@@ -8,20 +8,26 @@ namespace tt::app {
 
 typedef void* (*CreateData)();
 typedef void (*DestroyData)(void* data);
-typedef void (*OnCreate)(void* appContext, void* _Nullable data);
-typedef void (*OnDestroy)(void* appContext, void* _Nullable data);
-typedef void (*OnShow)(void* appContext, void* _Nullable data, lv_obj_t* parent);
-typedef void (*OnHide)(void* appContext, void* _Nullable data);
-typedef void (*OnResult)(void* appContext, void* _Nullable data, LaunchId launchId, Result result, Bundle* resultData);
+/** data is nullable */
+typedef void (*OnCreate)(void* appContext, void* data);
+/** data is nullable */
+typedef void (*OnDestroy)(void* appContext, void* data);
+/** data is nullable */
+typedef void (*OnShow)(void* appContext, void* data, lv_obj_t* parent);
+/** data is nullable */
+typedef void (*OnHide)(void* appContext, void* data);
+/** data is nullable, resultData is nullable. */
+typedef void (*OnResult)(void* appContext, void* data, LaunchId launchId, Result result, Bundle* resultData);
 
+/** All fields are nullable */
 void setElfAppParameters(
-    CreateData _Nullable createData,
-    DestroyData _Nullable destroyData,
-    OnCreate _Nullable onCreate,
-    OnDestroy _Nullable onDestroy,
-    OnShow _Nullable onShow,
-    OnHide _Nullable onHide,
-    OnResult _Nullable onResult
+    CreateData createData,
+    DestroyData destroyData,
+    OnCreate onCreate,
+    OnDestroy onDestroy,
+    OnShow onShow,
+    OnHide onHide,
+    OnResult onResult
 );
 
 std::shared_ptr<App> createElfApp(const std::shared_ptr<AppManifest>& manifest);

Tactility/Include/Tactility/file/FileLock.h

@@ -15,6 +15,6 @@ namespace tt::file {
  * @param[in] path the path to find a lock for
  * @return a lock instance when a lock was found, otherwise nullptr
  */
-std::shared_ptr<Lock> _Nullable findLock(const std::string& path);
+std::shared_ptr<Lock> findLock(const std::string& path);
 
 }

Tactility/Include/Tactility/hal/Configuration.h

@@ -31,7 +31,7 @@ struct Configuration {
      * Called before I2C/SPI/etc is initialized.
      * Used for powering on the peripherals manually.
      */
-    const InitBoot _Nullable initBoot = nullptr;
+    const InitBoot initBoot = nullptr;
 
     /** Init behaviour: default (esp_lvgl_port for ESP32, nothing for PC) or None (nothing on any platform). Only used in Tactility, not in TactilityHeadless. */
     const LvglInit lvglInit = LvglInit::Default;

Tactility/Include/Tactility/hal/display/DisplayDevice.h

@@ -26,7 +26,8 @@ public:
     virtual bool isPoweredOn() const { return true; }
     virtual bool supportsPowerControl() const { return false; }
 
-    virtual std::shared_ptr<touch::TouchDevice> _Nullable getTouchDevice() = 0;
+    /** Could return nullptr if not started */
+    virtual std::shared_ptr<touch::TouchDevice> getTouchDevice() = 0;
 
     /** Set a value in the range [0, 255] */
     virtual void setBacklightDuty(uint8_t backlightDuty) { /* NO-OP */ }
@@ -40,10 +41,12 @@ public:
     virtual bool startLvgl() = 0;
     virtual bool stopLvgl() = 0;
 
-    virtual lv_display_t* _Nullable getLvglDisplay() const = 0;
+    /** Could return nullptr if not started */
+    virtual lv_display_t* getLvglDisplay() const = 0;
 
     virtual bool supportsDisplayDriver() const = 0;
-    virtual std::shared_ptr<DisplayDriver> _Nullable getDisplayDriver() = 0;
+    /** Could return nullptr if not supported */
+    virtual std::shared_ptr<DisplayDriver> getDisplayDriver() = 0;
 };
 
 } // namespace tt::hal::display

Tactility/Include/Tactility/hal/encoder/EncoderDevice.h

@@ -17,7 +17,8 @@ public:
     virtual bool startLvgl(lv_display_t* display) = 0;
     virtual bool stopLvgl() = 0;
 
-    virtual lv_indev_t* _Nullable getLvglIndev() = 0;
+    /** Could return nullptr if not started */
+    virtual lv_indev_t* getLvglIndev() = 0;
 };
 
 }

Tactility/Include/Tactility/hal/gps/GpsDevice.h

@@ -48,7 +48,7 @@ private:
 
     const GpsConfiguration configuration;
     RecursiveMutex mutex;
-    std::unique_ptr<Thread> _Nullable thread;
+    std::unique_ptr<Thread> thread;
     bool threadInterrupted = false;
     std::vector<GgaSubscription> ggaSubscriptions;
     std::vector<RmcSubscription> rmcSubscriptions;

Tactility/Include/Tactility/hal/keyboard/KeyboardDevice.h

@@ -20,7 +20,8 @@ public:
     /** @return true when the keyboard currently is physically attached */
     virtual bool isAttached() const = 0;
 
-    virtual lv_indev_t* _Nullable getLvglIndev() = 0;
+    /** Could return nullptr if not started */
+    virtual lv_indev_t* getLvglIndev() = 0;
 };
 
 }

Tactility/Include/Tactility/hal/sdcard/SdCardDevice.h

@@ -67,8 +67,8 @@ public:
     bool isMounted(TickType_t timeout = kernel::MAX_TICKS) const { return getState(timeout) == State::Mounted; }
 };
 
-/** Return the SdCard device if the path is within the SdCard mounted path (path std::string::starts_with() check)*/
-std::shared_ptr<SdCardDevice> _Nullable find(const std::string& path);
+/** Return the SdCard device if the path is within the SdCard mounted path (path std::string::starts_with() check), otherwise return nullptr */
+std::shared_ptr<SdCardDevice> find(const std::string& path);
 
 /**
  * Attempt to find an SD card that the specified belongs to,

Tactility/Include/Tactility/hal/sdcard/SdmmcDevice.h

@@ -82,7 +82,8 @@ public:
 
     State getState(TickType_t timeout) const override;
 
-    sdmmc_card_t* _Nullable getCard() { return card; }
+    /** return card when mounted, otherwise return nullptr */
+    sdmmc_card_t* getCard() { return card; }
 };
 
 }

Tactility/Include/Tactility/hal/sdcard/SpiSdCardDevice.h

@@ -29,7 +29,7 @@ public:
             gpio_num_t spiPinInt,
             MountBehaviour mountBehaviourAtBoot,
             /** When customLock is a nullptr, use the SPI default one */
-            std::shared_ptr<Lock> _Nullable customLock = nullptr,
+            std::shared_ptr<Lock> customLock = nullptr,
             std::vector<gpio_num_t> csPinWorkAround = std::vector<gpio_num_t>(),
             spi_host_device_t spiHost = SPI2_HOST,
             int spiFrequencyKhz = SDMMC_FREQ_DEFAULT
@@ -50,7 +50,7 @@ public:
         gpio_num_t spiPinWp; // Write-protect
         gpio_num_t spiPinInt; // Interrupt
         MountBehaviour mountBehaviourAtBoot;
-        std::shared_ptr<Lock> _Nullable customLock;
+        std::shared_ptr<Lock> customLock; // can be nullptr
         std::vector<gpio_num_t> csPinWorkAround;
         spi_host_device_t spiHost;
         bool formatOnMountFailed = false;
@@ -91,7 +91,8 @@ public:
 
     State getState(TickType_t timeout) const override;
 
-    sdmmc_card_t* _Nullable getCard() { return card; }
+    /** return card when mounted, otherwise return nullptr */
+    sdmmc_card_t* getCard() { return card; }
 };
 
 }

Tactility/Include/Tactility/hal/spi/Spi.h

@@ -24,7 +24,7 @@ struct Configuration {
     /** Whether configuration can be changed. */
     bool isMutable;
     /** Optional custom lock - otherwise creates one internally */
-    std::shared_ptr<Lock> _Nullable lock;
+    std::shared_ptr<Lock> lock;
 };
 
 enum class Status {

Tactility/Include/Tactility/hal/touch/TouchDevice.h

@@ -22,11 +22,13 @@ public:
     virtual bool startLvgl(lv_display_t* display) = 0;
     virtual bool stopLvgl() = 0;
 
-    virtual lv_indev_t* _Nullable getLvglIndev() = 0;
+    /** Could return nullptr if not started */
+    virtual lv_indev_t* getLvglIndev() = 0;
 
     virtual bool supportsTouchDriver() = 0;
 
-    virtual std::shared_ptr<TouchDriver> _Nullable getTouchDriver() = 0;
+    /** Could return nullptr if not supported */
+    virtual std::shared_ptr<TouchDriver> getTouchDriver() = 0;
 };
 
 }

Tactility/Include/Tactility/hal/touch/TouchDriver.h

@@ -11,13 +11,13 @@ public:
      *
      * @param[in] x array of X coordinates
      * @param[in] y array of Y coordinates
-     * @param[in] strength optional array of strengths
+     * @param[in] strength optional array of strengths (nullable)
      * @param[in] pointCount the number of points currently touched on the screen
      * @param[in] maxPointCount the maximum number of points that can be touched at once
      *
      * @return true when touched and coordinates are available
      */
-    virtual bool getTouchedPoints(uint16_t* x, uint16_t* y, uint16_t* _Nullable strength, uint8_t* pointCount, uint8_t maxPointCount) = 0;
+    virtual bool getTouchedPoints(uint16_t* x, uint16_t* y, uint16_t* strength, uint8_t* pointCount, uint8_t maxPointCount) = 0;
 };
 
 }

Tactility/Include/Tactility/kernel/SystemEvents.h

@@ -12,11 +12,6 @@ enum class SystemEvent {
     /** Gained IP address */
     NetworkConnected,
     NetworkDisconnected,
-    /** LVGL devices are initialized and usable */
-    LvglStarted,
-    /** LVGL devices were removed and not usable anymore */
-    LvglStopped,
-    /** An important system time-related event, such as NTP update or time-zone change */
     Time,
 };
 

Tactility/Include/Tactility/lvgl/LvglSync.h

@@ -8,23 +8,13 @@ namespace tt::lvgl {
 
 constexpr TickType_t defaultLockTime = 500 / portTICK_PERIOD_MS;
 
-/**
- * LVGL locking function
- * @param[in] timeoutMillis timeout in milliseconds. waits forever when 0 is passed.
- * @warning this works with milliseconds, as opposed to every other FreeRTOS function that works in ticks!
- * @warning when passing zero, we wait forever, as this is the default behaviour for esp_lvgl_port, and we want it to remain consistent
- */
-typedef bool (*LvglLock)(uint32_t timeoutMillis);
-typedef void (*LvglUnlock)();
-
-void syncSet(LvglLock lock, LvglUnlock unlock);
-
 /**
  * LVGL locking function
  * @param[in] timeout as ticks
  * @warning when passing zero, we wait forever, as this is the default behaviour for esp_lvgl_port, and we want it to remain consistent
  */
-bool lock(TickType_t timeout);
+bool lock(TickType_t timeout = portMAX_DELAY);
+
 void unlock();
 
 std::shared_ptr<Lock> getSyncLock();

Tactility/Include/Tactility/service/ServiceRegistration.h

@@ -40,26 +40,26 @@ State getState(const std::string& id);
  * @param[in] id the id as defined in the manifest
  * @return the matching manifest or nullptr when it wasn't found
  */
-std::shared_ptr<const ServiceManifest> _Nullable findManifestById(const std::string& id);
+std::shared_ptr<const ServiceManifest> findManifestById(const std::string& id);
 
 /** Find a ServiceContext by its manifest id.
  * @param[in] id the id as defined in the manifest
  * @return the service context or nullptr when it wasn't found
  */
-std::shared_ptr<ServiceContext> _Nullable findServiceContextById(const std::string& id);
+std::shared_ptr<ServiceContext> findServiceContextById(const std::string& id);
 
 /** Find a Service by its manifest id.
  * @param[in] id the id as defined in the manifest
  * @return the service context or nullptr when it wasn't found
  */
-std::shared_ptr<Service> _Nullable findServiceById(const std::string& id);
+std::shared_ptr<Service> findServiceById(const std::string& id);
 
 /** Find a Service by its manifest id.
  * @param[in] id the id as defined in the manifest
  * @return the service context or nullptr when it wasn't found
  */
 template <typename T>
-std::shared_ptr<T> _Nullable findServiceById(const std::string& id) {
+std::shared_ptr<T> findServiceById(const std::string& id) {
     return std::static_pointer_cast<T>(findServiceById(id));
 }
 

Tactility/Include/Tactility/service/gps/GpsService.h

@@ -34,7 +34,8 @@ class GpsService final : public Service {
     bool startGpsDevice(GpsDeviceRecord& deviceRecord);
     static bool stopGpsDevice(GpsDeviceRecord& deviceRecord);
 
-    GpsDeviceRecord* _Nullable findGpsRecord(const std::shared_ptr<hal::gps::GpsDevice>& record);
+    /** return nullptr when not found */
+    GpsDeviceRecord* findGpsRecord(const std::shared_ptr<hal::gps::GpsDevice>& record);
 
     void onGgaSentence(hal::Device::Id deviceId, const minmea_sentence_gga& gga);
     void onRmcSentence(hal::Device::Id deviceId, const minmea_sentence_rmc& rmc);

Tactility/Include/Tactility/service/loader/Loader.h

@@ -62,10 +62,10 @@ public:
     /**
      * @brief Start an app given an app id and an optional bundle with parameters
      * @param id the app identifier
-     * @param parameters optional parameter bundle
+     * @param parameters optional parameter bundle (nullable)
      * @return the launch id
      */
-    app::LaunchId start(const std::string& id, std::shared_ptr<const Bundle> _Nullable parameters);
+    app::LaunchId start(const std::string& id, std::shared_ptr<const Bundle> parameters);
 
     /**
      * @brief Stops the top-most app (the one that is currently active shown to the user
@@ -85,8 +85,8 @@ public:
      */
     void stopAll(const std::string& id);
 
-    /** @return the AppContext of the top-most application */
-    std::shared_ptr<app::AppContext> _Nullable getCurrentAppContext();
+    /** @return the AppContext of the top-most application, or nullptr if no app is running. */
+    std::shared_ptr<app::AppContext> getCurrentAppContext();
 
     /** @return true if the app is running anywhere in the app stack (the app does not have to be the top-most one for this to return true) */
     bool isRunning(const std::string& id) const;
@@ -95,6 +95,7 @@ public:
     std::shared_ptr<PubSub<Event>> getPubsub() const { return pubsubExternal; }
 };
 
-std::shared_ptr<LoaderService> _Nullable findLoaderService();
+/** return the service or nullptr if it's not running */
+std::shared_ptr<LoaderService> findLoaderService();
 
 } // namespace