Raspberry Pi (Linux) Integration Guide

The Artok HMI Runtime for Linux brings professional embedded UI capabilities to the Raspberry Pi (Zero, 3, 4, and 5). Unlike the bare-metal versions, the Linux runtime operates as a high-priority userspace process, interfacing with the Linux Framebuffer (/dev/fb0) or DRM/KMS for hardware-accelerated rendering.

---

📦 1. System Requirements

Artok is compiled as a shared or static library for ARMv7/ARMv8 (AArch64). It is compatible with Raspberry Pi OS (Lite recommended) and Ubuntu Server.

Requirement	Recommended Spec	Benefit
OS	Raspberry Pi OS Lite (64-bit)	Minimal background overhead for 60FPS UI.
Memory	512MB+ RAM	Smooth handling of large image assets and Lua scripts.
Graphics	Framebuffer / DRM-KMS	Direct access to the video core without an X11 server.

---

🔧 2. Hardware Abstraction (Linux Drivers)

On Linux, the "Flash" is typically a file on the SD card (the ui.bin exported from Artok-Vite), and the "Display" is the Linux Framebuffer.

File & Framebuffer Bridge

#include <fcntl.h>
#include <unistd.h>
#include <sys/mman.h>
#include "atk_runtime.h"

static int ui_file_fd;
static int fb_fd;

// 1. "Flash" Read (Using Linux File I/O)
uint32_t linux_file_read(uint8_t* buf, uint32_t addr, uint32_t size) {
    lseek(ui_file_fd, addr, SEEK_SET);
    return read(ui_file_fd, buf, size);
}

// 2. Display Flush (Using Linux Framebuffer mmap)
void linux_fb_flush(void *drv, int32_t x1, int32_t y1, int32_t x2, int32_t y2, void *color) {
    // Map the Artok draw buffer to the /dev/fb0 memory area
    // Copying pixel data to the mapped memory...
    
    // Signal transfer complete
    ART_FlushComplete();
}

🚀 3. The 4-Tier Initialization Sequence

Initialization on Linux involves opening the device files and the UI binary before starting the Artok engine loop.

HMI_Hardware_Interface_t linux_hal;

int main() {
    // Open UI Binary and Framebuffer
    ui_file_fd = open("ui.bin", O_RDONLY);
    fb_fd = open("/dev/fb0", O_RDWR);

    // TIER 1: Core System Init
    ART_Init();

    // Prepare HAL Structure
    linux_hal.read_flash = linux_file_read;
    linux_hal.disp_flush_cb = linux_fb_flush;
    linux_hal.disp_buffer_1 = malloc(800 * 480 * 2); 
    linux_hal.disp_buffer_size_bytes = 800 * 480 * 2;
    linux_hal.comm_send = linux_uart_send;

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

    // TIER 3: Input (Event Device /dev/input/eventX)
    ART_InitInput(&linux_hal);

    // TIER 4: Launch HMI
    if (ART_StartHMI(0, &linux_hal)) {
        while (1) {
            ART_MainLoop();
            usleep(5000); // 5ms heartbeat
        }
    }
    return 0;
}

🎮 4. Interaction API

In the Linux environment, you can use the Artok API to bridge your high-level Python or C++ logic to the HMI via the UUID system.

// Example: Updating system stats from Linux procfs
void update_system_info() {
    char cpu_temp[16];
    // Read from /sys/class/thermal/thermal_zone0/temp
    atk_api_set_text("UUID_CPU_TEMP_LABEL", "54.2 C");
    
    // Check network status
    if (network_is_up()) {
        atk_api_set_color("UUID_NET_ICON", 0x00FF00); // Green
    }
}

🛡️ 5. Linux Optimization Notes

• CPU Affinity: For maximum smoothness, use sched_setaffinity to pin the Artok process to a specific core (e.g., Core 3) to avoid context switching jitter.

• Permissions: Ensure your user is part of the video and input groups to access /dev/fb0 and /dev/input/event* without root privileges.

• X11/Wayland: Artok is designed for Direct Rendering. Ensure you are not running an X server or Wayland compositor on the same TTY to avoid screen flickering or resource contention.