STM32 LTDC Integration Guide

The Artok HMI Runtime is engineered to extract maximum performance from the STM32 ecosystem. On high-end STM32 chips, the runtime utilizes the LTDC (LCD Thin Film Transistor Controller) and DMA2D (Chrom-Art Accelerator) to handle alpha-blending and pixel-pushing without taxing the main CPU core.

---

📦 1. Hardware Configuration

For the Artok Reference Board (STM32F103RET6 or STM32F4/F7/H7 series), the hardware mapping follows a standard industrial pattern. The runtime is natively optimized for 16-bit RGB565 color depth to balance visual quality with memory efficiency.

Component	Interface	Description
TFT LCD	LTDC / 8080 / SPI	16-bit RGB565 is the native runtime format.
External Flash	SPI / QSPI	W25Qxx storage for the ui.bin and visual assets.
SRAM	Internal / SDRAM	Framebuffers should be placed in the fastest available RAM.

---

🔧 2. Hardware Abstraction (HAL)

Integrating Artok requires bridging your STM32 HAL drivers to the atk_runtime interface. This is done by providing function pointers for flash reading and display flushing.

Storage & Display Implementation

#include "atk_runtime.h"

// 1. Flash Read (Using STM32 HAL SPI)
uint32_t stm32_flash_read(uint8_t* p_buffer, uint32_t address, uint32_t size) {
    // Offset 0 maps to the start of the UI binary in your W25Qxx
    if (HAL_W25Q_Read(p_buffer, address, size) == HAL_OK) {
        return size;
    }
    return 0;
}

// 2. Display Flush (Optimized for LTDC/DMA2D)
void stm32_disp_flush(void *p_disp_drv, int32_t x1, int32_t y1, int32_t x2, int32_t y2, void *p_color) {
    // If using LTDC, update the layer buffer address or use DMA2D to copy
    // If using SPI/8080, trigger a DMA transfer here
    LCD_Draw_Window(x1, y1, x2, y2, (uint16_t*)p_color);
    
    // Crucial: ART_FlushComplete() MUST be called in the DMA Transfer Complete ISR
}

🚀 3. The 4-Tier Initialization Sequence

Follow the mandatory boot sequence to ensure the Artok kernel is properly mapped to your STM32 peripherals.

HMI_Hardware_Interface_t hmi_hal;

void Artok_App_Start(void) {
    // TIER 1: Core System Init
    ART_Init();

    // Prepare HAL Structure
    hmi_hal.read_flash = stm32_flash_read;
    hmi_hal.disp_flush_cb = stm32_disp_flush;
    hmi_hal.disp_buffer_1 = (void*)0x20000000; // Fast Internal SRAM
    hmi_hal.disp_buffer_size_bytes = 240 * 20 * 2; // 20-line draw buffer
    hmi_hal.comm_send = stm32_uart_send;

    // TIER 2: Connectivity & Graphics Pipe
    ART_InitComm(&hmi_hal, NULL, 0); 
    ART_InitDisplay(&hmi_hal);

    // TIER 3: Input (Touch Panel)
    ART_InitInput(&hmi_hal);

    // TIER 4: Launch HMI
    if (ART_StartHMI(0x00000000, &hmi_hal)) {
        printf("Artok Runtime Active\n");
    }
}

🎮 4. Interaction API

Once initialized, use the UUID-based API to manipulate the UI from your STM32 application logic. This decoupled approach allows you to modify the UI in Artok-Vite without refactoring your C code.

void main_loop(void) {
    while (1) {
        // High-frequency HMI task (Handles animations & scripts)
        ART_MainLoop();

        // Application Logic: Update a Meter via UUID
        uint16_t sensor_val = HAL_ADC_GetValue(&hadc1);
        atk_api_set_value("UUID_PRESSURE_METER", sensor_val);

        // Application Logic: Change text based on state
        if (sensor_val > THRESHOLD) {
            atk_api_set_text("UUID_STATUS_LABEL", "WARNING: HIGH PRESSURE");
            atk_api_set_color("UUID_STATUS_LABEL", 0xFF0000); // Red
        }
    }
}

🛡️ 5. Performance Optimization

• Chrom-Art (DMA2D): If your STM32 supports it, the Artok Runtime automatically leverages it for hardware-accelerated color-fill and image-copying.

• Interrupt Priority: The Display DMA interrupt should have a higher priority than the UI Task to prevent flickering during heavy communication.

• Flash Latency: For W25Qxx SPI Flash, we recommend a minimum SPI clock of 24MHz to ensure smooth screen transitions.