Build apps for Reload OS

An app is a small ELF file in the apps/ folder of the device's flash drive or SD card. The launcher shows it as a tile; a tap reads it into memory, links it against the firmware and runs it. The app kit builds one without the firmware's source.

In it: build.sh and new.sh, the hello example, and reloados/ - the firmware's ros.h, its configuration and api.txt, the list of everything an app may call. A kit belongs to one firmware version (reloados/VERSION); the apps it builds run on that version and on later ones with the same app interface.

Quick start

1. Install ESP-IDF v5.5.4 - exactly this version, the one the firmware is built with - with the target of your board's chip, and run its export.sh in the terminal you build from. macOS or Linux.

2. Unpack the kit and build the example - the first build downloads LVGL and the ELF loader.

   unzip ReloadOS-1.4.0-appkit.zip
   cd appkit
   ./build.sh hello            # -> hello/jc1060p470c/hello.elf

3. Copy it to the device: open http://<device>/files in a browser (Settings › Remote desktop on the device shows the address and the login), then Flash › apps › Upload. Or use the device as a USB drive for a PC, or an SD card.

4. Restart the device and tap the new tile.

Your own app: ./new.sh myapp, write myapp/main/myapp.c, ./build.sh myapp. The app kit guide has every step, the boards and what to do when something goes wrong.

The shape of an app

#include "ros.h"

static void create(lv_obj_t *body)   /* build the screen inside body; runs on the LVGL task */
{
    ros_ui_label(body, &lv_font_montserrat_32, ROS_C_TEXT, "Hello");
}

static void destroy(void)            /* the app closes: delete timers, stop what you started */
{
}

ROS_ELFAPP_META("Hello", LV_SYMBOL_SD_CARD, 0x6B4FBB);      /* the tile: name, glyph, colour */

static const ros_elfapp_t s_app = {
    .abi = ROS_ELFAPP_ABI, .board = ROS_BOARD_SHORT, .meta = &ros_elfapp_meta,
    .app = { .name = "Hello", .icon = LV_SYMBOL_SD_CARD, .color = 0x6B4FBB, .create = create, .destroy = destroy },
};

int main(int argc, char *argv[])     /* only hands the app back; the work starts in create() */
{
    if (argc > 0 && argv[0]) *(const ros_elfapp_t **)argv[0] = &s_app;
    return 0;
}

The rules, in short

• Nothing that waits on the LVGL task: network, files, serial lines and card readers go on a task of your own, with ros_lock() / ros_unlock() around its LVGL calls.
• Count your tasks, and end each with ros_task_end() - never vTaskDelete(): the app's code is unloaded only when none is left.
• Clean up in destroy(); free what you keep across opens in unload() - every load starts with fresh variables.
• Big buffers from PSRAM: internal RAM is the scarce one.
• Both orientations and every screen size: ROS_SCR_W, ROS_SCR_H, ROS_PORTRAIT are values, read them in create().
• Only what the firmware exports (reloados/api.txt): build.sh checks it, and so does the device.

More