Skip to main content
Version: v2.4.0 (Current)

Contributing to Artok

The Artok HMI ecosystem is built on a Hardware-Agnostic Runtime. This architecture strictly decouples the UI logic and assets from the master firmware. While Artok Studio and the core C Runtime (atk_api.c) are proprietary, the Hardware Abstraction Layer (HAL) and Public Headers are open for community development.

🏗️ The Decoupled Architecture​

Artok's power lies in its "Write Once, Render Anywhere" approach.

  • The ui.bin: Contains the entire UI structure, Lua logic, and assets. It is hardware-blind.
  • The Runtime: A pre-compiled engine that parses the binary and manages.
  • The HAL: The only part of the code that "knows" the hardware.

Where You Can Contribute​

We welcome contributions that expand the "Southbound" connectivity of the Runtime.

1. Device Support (The atk_hal Layer)​

Since the Runtime is agnostic, it relies on contributors to provide high-performance bridges to specific silicon:

  • Display Drivers: Implementing DMA-based flushing for LTDC, MIPI, or SPI/Parallel interfaces.
  • Touch Interfaces: Drivers for various I2C/SPI touch controllers.
  • Storage Engines: Drivers to fetch ui.bin blocks from SPI Flash, SD Cards, or internal memory.

2. System Porting​

Providing standardized project templates for different build systems:

  • CMake Toolchains: Optimizing toolchain-arm.cmake for various GCC/Clang versions.
  • RTOS Integration: Standardized "Main Loop" wrappers for FreeRTOS, Zephyr, and RT-Thread.

📋 Coding Standards for HALs​

If you are developing a new HAL for a specific development board, please follow these rules:

  • Separation of Concerns: Ensure no UI-specific logic enters the HAL. The HAL should only handle pixel pushing and byte reading.
  • Non-Blocking I/O: Use DMA for display and flash access to ensure the Agnostic Runtime can maintain 60 FPS.
  • Namespace: All hardware-specific functions must reside in atk_hal.c and follow the atk_hal_ prefix.

🚀 Proposing API Changes​

Because the implementation of atk_api.h is private, you cannot submit PRs for the core logic. However, you can influence the roadmap:

  1. Open an Issue: Request a new feature (e.g., atk_api_set_blur_effect).
  2. Define the Header: Propose the function signature and expected behavior.
  3. Integration: If the proposal is accepted, the Artok core team will implement the logic and update the public headers in the next release.

⚖️ License Note​

By contributing to the HAL or Connect layers, you agree that your code will be licensed under the project's open-source license (e.g., MIT/Apache 2.0), allowing it to be integrated into the Artok ecosystem.