ESP32-S3 Integration Guide

The Artok HMI Runtime is highly optimized for the ESP32-S3 series. By leveraging the S3's dual-core architecture, high-speed PSRAM, and Octal SPI capabilities, Artok can drive high-resolution displays (up to 800x480) with fluid 60FPS animations and near-instant asset loading.

---

📦 1. Hardware Requirements

To achieve maximum performance on the ESP32-S3, we recommend the following hardware configuration:

Component	Recommended Spec	Benefit
PSRAM	2MB - 8MB (Octal/Quad)	Enables full-frame double buffering for tear-free UI.
Flash	8MB+ (Octal/Quad)	High-speed UI asset streaming from external W25Qxx.
Interface	RGB565 / SPI / i8080	Native support for high-speed display protocols.

---

🔧 2. Hardware Abstraction (HAL)

The ESP32-S3 implementation requires mapping your storage and display drivers to the Artok HAL structure.

Storage & Display Bridge

#include <Artok_HMI.h>

// 1. Flash Read (Using ESP-IDF Partition or SPI)
uint32_t esp32_flash_read(uint8_t* buf, uint32_t addr, uint32_t size) {
    // Offset 0 maps to the start of your ui.bin in external flash
    // return my_spi_flash_read(addr, buf, size);
    return size; 
}

// 2. Display Flush (Optimized for S3 DMA)
void esp32_disp_flush(void *drv, int32_t x1, int32_t y1, int32_t x2, int32_t y2, void *color) {
    // Send pixel data to the LCD via DMA (e.g., using esp_lcd driver)
    // lcd_panel_draw_bitmap(panel_handle, x1, y1, x2, y2, color);
    
    // Crucial: This signal must be called once the DMA transfer is complete
    ART_FlushComplete(); 
}

🚀 3. The 4-Tier Initialization Sequence

On the ESP32-S3, we recommend allocating the display buffers in PSRAM (SPIRAM) to keep the internal SRAM available for your core application logic.

HMI_Hardware_Interface_t artok_hw;

void setup() {
    // TIER 1: Initialize Core Engine
    ART_Init();

    // Configure HAL Interface
    artok_hw.read_flash = esp32_flash_read;
    artok_hw.disp_flush_cb = esp32_disp_flush;
    
    // Allocate buffers in PSRAM to support larger resolutions
    artok_hw.disp_buffer_1 = heap_caps_malloc(800 * 40 * 2, MALLOC_CAP_SPIRAM); 
    artok_hw.disp_buffer_size_bytes = 800 * 40 * 2;
    artok_hw.comm_send = esp32_uart_send;

    // TIER 2: Connectivity & Display
    ART_InitComm(&artok_hw, NULL, 0); 
    ART_InitDisplay(&artok_hw);

    // TIER 3: Input Driver (Capacitive Touch)
    ART_InitInput(&artok_hw);

    // TIER 4: Start Engine
    // Provide the flash address where the Artok-Vite binary is stored
    if (ART_StartHMI(0x200000, &artok_hw)) {
        log_i("Artok HMI Running on ESP32-S3");
    }
}

🎮 4. Application Control (Public API)

The Artok API allows your application to interact with the UI via UUID strings. This remains consistent across all platforms, ensuring your logic is portable.

void loop() {
    // 1. Maintain the UI Heartbeat (Animations & Logic)
    ART_MainLoop();

    // 2. Update a Label using its UUID
    int rssi = WiFi.RSSI();
    char wifi_buf[16];
    sprintf(wifi_buf, "%d dBm", rssi);
    atk_api_set_text("UUID_WIFI_SIGNAL", wifi_buf);

    // 3. Update an Image based on state
    if (rssi > -50) {
        atk_api_set_image("UUID_WIFI_ICON", "RES_UUID_WIFI_FULL");
    } else {
        atk_api_set_image("UUID_WIFI_ICON", "RES_UUID_WIFI_LOW");
    }

    delay(1);
}
// Note: Ensure ART_IncTick(1) is called via a high-priority timer or SysTick

🛡️ 5. ESP32-S3 Specific Notes

• Task Pinning: For optimal performance under FreeRTOS, we recommend pinning the ART_MainLoop() to Core 1, leaving Core 0 for system tasks (WiFi, BT, and TCP/IP).

• DMA Alignment: Ensure display buffers allocated in PSRAM are aligned according to the S3 DMA requirements (usually 32-byte alignment).

• Memory Management: The Artok engine manages its own internal heap for widgets. Do not attempt to manually free objects created by the runtime.