ESPIDF-Component ui_app

Overview

The UI App component provides a comprehensive, thread-safe, and configurable solution for user interface control on ESP32 using the ESP-IDF framework. It is designed for embedded applications that require robust LED and button management, including advanced features such as debouncing, press/hold detection, and flexible task management.

This component leverages FreeRTOS and ESP-IDF APIs to deliver:

• Full-featured LED control (ON, OFF, BLINK) with polarity support
• Button handling with software debouncing and short/long press detection
• Callback-based event handling for clean application integration
• Task-based architecture for responsive UI
• Memory- and resource-efficient implementation

Features

• LED Control: Supports ON, OFF, and BLINK modes with configurable blink period and polarity (active-high/active-low).
• Button Handling: Software debouncing, short/long press detection, and callback registration.
• Thread-Safe: All operations are FreeRTOS task and queue based for safe multitasking.
• Configurable Task Parameters: Adjust stack size and priority for button event processing.
• USB Pin Repurposing: Optionally disables USB to free up GPIOs for UI use.
• Comprehensive Error Handling: All API functions validate parameters and log errors.

API Summary

LED Control

• led_handler_t *ui_app_init_led(const char *ledName, uint8_t ledPinNum, bool isLedInverted);

  • Initializes an LED with the specified name, GPIO pin, and polarity.

• void ui_app_set_led_mode(led_handler_t *ledHandler, led_mode_e ledMode, ...);

  • Sets the LED mode (ON, OFF, BLINK) and optionally the blink period.

Button Handling

• button_handler_t *ui_app_init_button(const char *btnName, uint8_t btnPinNum, uint16_t pressDebounce, uint16_t holdDebounce, button_event_short_callback_t pressCb, button_event_long_callback_t holdCb);

  • Initializes a button with debouncing, press/hold detection, and event callbacks.

• void ui_app_button_task_config(uint8_t task_priority, uint16_t stack_depth);

  • Configures the FreeRTOS task parameters for button event processing.

Data Structures

• led_handler_t: Structure for LED configuration and state.
• button_handler_t: Structure for button configuration and state.
• led_mode_e: Enum for LED modes (ON, OFF, BLINK).
• button_event_short_callback_t / button_event_long_callback_t: Callback types for button events.

Usage Example

#include "ui_app.h"

// Initialize an LED (active-low on GPIO 2)
led_handler_t *led = ui_app_init_led("Status LED", 2, true);
ui_app_set_led_mode(led, LED_BLINK, 500); // Blink every 500ms

// Initialize a button with 20ms debounce and 1000ms hold threshold
button_handler_t *btn = ui_app_init_button(
    "User Button", 0, 20, 1000,
    on_short_press, on_long_press
);

// Optionally configure button task parameters
ui_app_button_task_config(2, 4096);

Thread Safety

All LED and button operations are thread-safe and use FreeRTOS primitives for synchronization and event handling.

Error Handling

All API functions validate parameters and log errors using the ESP-IDF logging system. Functions that allocate resources return NULL on failure.

Configuration Notes

• Task Stack/Prio: Use ui_app_button_task_config() before initialization to set custom stack size and priority.
• Debounce: Minimum recommended debounce is 10ms. Shorter values may cause unreliable detection.
• Polarity: Set isLedInverted to true for active-low LEDs.
• USB Pins: Using GPIO 18/19 for UI disables USB functionality.

Supported Chipsets

Supported Chipset	Notes
ESP32-C3	Tested & Fully supported

Limitations

• Only supports ESP-IDF APIs.
• Assumes a single UI task instance per application.
• Using USB pins for UI disables USB.

License

This component is proprietary and intended for internal use only within the company. Redistribution or external use is not permitted without explicit authorization.

---

For further details, refer to the source code and inline documentation in ui_app.c and ui_app.h.