HoloCubic App SDK

Develop HoloCubic apps with Lua and LVGL

The app package defines its name, entry point, and assets. Lua handles lifecycle, networking, and device logic; LVGL builds the interface. Use the public C ABI only when native performance is required.

View the workflow ↓

holo://appREADY

hello/
├── app.info
├── main.lua
├── main.png
├── assets/
└── modules/ # optional

$ app.rescan()
✓ Hello is ready

Basic workflow

Create the app package

Prepare app.info, main.lua, and required assets.

Build the interface

Use LVGL widgets or Canvas for the 320 × 240 screen.

Install and rescan

Upload to /sd/apps/{app-id}, then rescan apps.

SDK STACK

Development layers and responsibilities

Every layer has a clear boundary, from app package to native extension. Start with Lua and LVGL; use the C ABI only for a measured performance need.

APP.INFO

App SDK

Directory, metadata, entry point, lifecycle, deployment, and cleanup. An app starts independently and stops tasks and releases resources on exit.

[app]
name = "Hello"
entry = "main.lua"
icon = "main.png"

LUA

Lua API

NodeMCU-style timers, networking, and files plus HoloCubic capabilities for BLE services, IPC, and device state.

local timer = tmr.create()
timer:alarm(1000, tmr.ALARM_AUTO, function()
  print("tick", tmr.time())
end)

LVGL 8.3

LVGL UI

Widgets, styles, events, animation, images, fonts, and Canvas, designed around 320 × 240 and short callbacks.

local label = lv_label_create(lv_scr_act())
lv_label_set_text(label, "Hello, Holo.")
lv_obj_center(label)

C ABI

A versioned Host API for performance-sensitive audio, protocol, and sustained computation. It neither exposes nor permits reliance on host-firmware internals.

const holo_host_api_v1 *host;
int holo_module_init(const holo_host_api_v1 *api) {
  host = api;
  return HOLO_OK;
}

PUBLIC BOUNDARY

Public SDK rules

01Depend only on documented APIs; never link host-firmware internals.
02Keep callbacks short and release timers, events, and fonts on exit.
03Use opaque handles, POD structures, and stable error codes across the native boundary.

View example repository ↗Ask about the SDK