Arduino IDE Integration Guide

The Artok HMI Runtime for Arduino allows developers to leverage the full power of the Artok ecosystem within the familiar Arduino environment. By utilizing a pre-compiled, high-performance C engine, you can achieve professional 60FPS fluid interfaces on MCUs like the STM32F103RET6, ESP32, and Teensy.

---

📦 1. Library Installation

Artok is provided as a professional static library.

1. Download the Artok_HMI library folder.
2. Move the folder to your Arduino libraries directory (usually Documents/Arduino/libraries/).

---

🔧 2. Hardware Abstraction Layer (HAL)

Before initializing the engine, you must map your hardware peripherals (Flash and Display) to the Artok HAL structure.

Flash & Display Callbacks

Create a bridge between your SPI Flash driver and the Artok Runtime:

#include <Artok_HMI.h>

// 1. Flash Read Callback
uint32_t my_flash_read(uint8_t* p_buffer, uint32_t address, uint32_t size) {
    // Implement your SPI Flash read logic here
    // return W25Q_ReadBytes(p_buffer, address, size);
    return size; 
}

// 2. Display Flush Callback
void my_disp_flush(void *p_disp_drv, int32_t x1, int32_t y1, int32_t x2, int32_t y2, void *p_color) {
    // Bridge to your TFT driver (e.g., ST7789 or ILI9341)
    // tft.drawRGBBitmap(x1, y1, (uint16_t*)p_color, (x2-x1+1), (y2-y1+1));
    
    // Crucial: Signal Artok that the DMA/Transfer is complete
    ART_FlushComplete(); 
}

🚀 3. The 4-Tier Initialization Sequence

To ensure system stability, Artok uses a tiered boot sequence. This ensures hardware and connectivity are ready before the UI is parsed.

HMI_Hardware_Interface_t artok_hw;

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

    // Configure HAL Interface
    artok_hw.read_flash = my_flash_read;
    artok_hw.disp_flush_cb = my_disp_flush;
    artok_hw.disp_buffer_1 = malloc(ART_LCD_WIDTH * 20 * 2); // 20-line buffer
    artok_hw.disp_buffer_size_bytes = ART_LCD_WIDTH * 20 * 2;
    artok_hw.comm_send = my_serial_send; // Required for Artok-Connect

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

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

    // TIER 4: Start HMI Logic
    // Point to the UI binary address in external flash
    if (ART_StartHMI(0x00100000, &artok_hw)) {
        Serial.println("Artok Engine Online");
    }
}

🎮 4. Application Logic (Public API)

The Artok API uses UUID strings generated by the Artok-Vite editor. This decouples your code from the visual design.

Updating the UI You can update UI elements from anywhere in your code using their unique identifiers.

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

    // 2. Update a Label (Push Model)
    atk_api_set_text("UUID_ROOM_TEMP", "24.5 °C");

    // 3. Update a Gauge or Slider
    atk_api_set_value("UUID_POWER_GAUGE", 85);

    // 4. Change a Status Color
    atk_api_set_color("UUID_STATUS_LED", 0x00FF00); // Green

    delay(5);
}

// Ensure ART_IncTick(1) is called every 1ms via a timer interrupt

🎮 📡 5. Artok-Connect Integration

If the Arduino is receiving commands from an external Main Board, feed the incoming data stream into the Artok Southbound pipe:

void loop() {
    if (Serial1.available()) {
        uint8_t incoming = Serial1.read();
        ART_FeedData(&incoming, 1);
    }
    
    ART_MainLoop();
}

🛡️ 6. Deployment Notes

• Pre-compiled Core: The libartok_runtime.a is optimized for ARM Cortex-M architecture. Do not attempt to decompile or modify internal headers.

• Memory Management: Ensure your disp_buffer_1 is allocated in internal SRAM for maximum performance.

• Color Depth: The runtime is optimized for 16-bit (RGB565).