kodeOS internals

kgui

AO_Gui, the Active Object that draws every screen of kodeOS: its task, its states, its doors, the settings it keeps, its files, and the page for each screen.

What it is

kgui is the component that draws everything you see on the glass of a Kode Dot running kodeOS. It holds one Active Object, AO_Gui, and the screens it shows:

• The face is the lock screen and home. It shows the time, the date and the battery over Kody's scene.
• Apps (the launcher) is a rail of folders and apps. The face opens it with a tap, TOP, the pad's right or a swipe to either side.
• Settings is a control centre: Wi-Fi, Bluetooth and Settings, the battery and Turn off, then a brightness level and a volume level. It comes down over the face.
• The loading screen and the touch test serve the factory tests and the self-test.

A full-glass card, the sheet, rises over these whenever a page, a question, a write or a pairing code needs the whole display.

AO_Gui owns LVGL and the widget tree and owns no device. Fingers arrive from sdk/kaos/touch, buttons from sdk/kaos/buttons, the lists of apps from sdk/kaos/storage and sdk/kaos/appmgr, and pixels leave through sdk/kaos/display. kgui sits above the SDK and is not part of it: it includes kode.h and kode_ao.h like any app, the SDK never includes it, and a firmware without a screen leaves it out and carries no LVGL. The kit it draws with is sdk/kui. An app that wants a screen of its own uses sdk/kscreen.

The look follows kshell, Luismi's shell for the Kode Dot: a black page, dark rows, one yellow ring that shows where the cursor is. Colours, type and glyphs live in sdk/kui.

How it is connected

flowchart LR
subgraph inputs["Inputs"]
  touch["AO_Touch"]
  btn["AO_Buttons"]
  boot["AO_Boot"]
end
subgraph owners["Owners"]
  lists["AO_Storage<br/>AO_AppMgr"]
  state["Wi-Fi, BLE, power,<br/>display owners"]
end
touch -- "TOUCH_EVT_SIG" --> gui["AO_Gui<br/>LVGL, the screens"]
btn -- "BUTTON_EVT_SIG" --> gui
boot -- "HOME_SIG" --> gui
lists -- "app and file lists" --> gui
state -- "published state" --> gui
gui -- "request functions" --> state
gui -- "DISPLAY_FLUSH_SIG" --> disp["AO_Display"]
gui -- "kode_haptic_play()" --> hap["AO_Haptic"]
class gui ao
class disp ao
class hap ao

Priority and stack

AO_Gui runs at priority 3 (KODE_PRIO_USER_GUI), above only AO_Net. A repaint spends most of its time waiting for the panel's DMA, up to 500 ms inside one step, and at this level that wait delays no other Active Object.

It has a 64-event queue and a 24 KB stack in static internal RAM, because ThorVG rasterises Kody on that stack. Every lv_* call in kodeOS runs on this one task, so LVGL needs no mutex and a widget callback may post events like any other code.

The tick

The tick is a one-shot timer. AO_Gui arms it again after each pass, for the time LVGL says its next timer is due and never more than 10 ms (KODE_GUI_TICK_MS). A periodic timer would post on every expiry whether AO_Gui had run or not, and one slow step elsewhere, such as an SD card mount, would fill the queue with stale ticks. Re-arming keeps at most one tick waiting, so a busy board lowers the frame rate and overflows nothing.

One tick does these jobs:

1. Applies a back that a swipe recorded.
2. Repeats a held pad button on the rail.
3. Feeds LVGL one input read while a finger rests.
4. Steps whatever moves: a curtain, a card, the rail, the launch scene, a system card's rise, the face's red arc.
5. Calls lv_timer_handler().
6. Counts the lock, the auto-lock, the red arc, the wait for Remove and the two waits of a launch.

At Rest the tick waits 1,000 ms (KGUI_REST_TICK_MS) instead, and never past the next brightness step or the end of a hint.

Events and requests

AO_Gui asks owners by event. It never calls a driver. What it shows (Wi-Fi on, battery percent, brightness) comes from events it subscribed to:

• POWER_EVT_SIG
• WIFI_STATE_SIG
• BLE_STATE_SIG
• DISPLAY_STATE_SIG
• RADIO_STATE_SIG

What it wants done it asks for with a request function that posts to the owner:

• wifi_start_request()
• ble_unpair_request()
• display_brightness_request()
• appmgr_run_request()
• appmgr_flash_request()
• appmgr_erase_request()
• autotest_run_request()
• boot_factory_reset_request()
• test_dot_screen_done()
• kode_power_off()
• kode_haptic_play()

A list arrives as one event per entry and an end marker, in pages of 24, and AO_Gui asks the next page itself with storage_list_page() or appmgr_list_page().

Drawing

LVGL's heap lives in PSRAM through the kit's kui_mem.c, with no fallback to internal RAM. When the panel exposes its two framebuffers, LVGL draws straight into them in direct mode. A panel with one framebuffer gets two draw buffers of 41,000 bytes each in PSRAM.

AO_Gui posts each rendered chunk to AO_Display as DISPLAY_FLUSH_SIG, and waits on a semaphore for the panel to take it. That semaphore is one of the three documented exceptions to "everything is an event" (sdk/design-rules).

No screen load is animated. A door between the face, Apps and Settings is a curtain: two still pictures of the screens, drawn on a screen of their own and moved by a spring or by a finger. The curtain is described on internals/gui/settings-screen and internals/gui/face.

Start

main/main.c calls kode_init() and then kgui_start(). The panel was announced from inside kode_init(), before AO_Gui existed, so AO_Gui asks for the announcement again with display_state_request(). When the panel answers, AO_Gui:

1. Starts LVGL.
2. Builds the screens, the sheet, the hint and the players of Kody.
3. Reads its stored settings.
4. Asks both owners for their lists.
5. Enters the face, which is the first lit frame. A board that comes back from an app enters Apps instead.

If the panel is down or LVGL fails to start, AO_Gui stays in Gui_waiting and the board is console-only.

The return from an app

An app ends in a reset, so every return to kodeOS is a boot. A boot that comes back from an app lights Apps, in the group of the app that ran and with that app in focus, and shows no face. The state Gui_returning holds the first frame black until the installed list has ended or 800 ms (KGUI_LIST_WAIT_MS) have passed, so the rail opens already laid out around the app. The reset cause is never read: only the fact that an app was launched.

When the app ended badly (a panic, a watchdog or a brownout) the Stopped card rises over Apps. A clean end shows no card.

The board's rest

When the board rests (CONFIG_KODE_LOWPOWER), AO_LowPower asks every owner to get ready, and AO_Gui answers by entering Gui_asleep:

1. The tick stops, and a finger or a card in the middle of something is dropped.
2. The glass takes the page the rest holds: the face with Kody standing on frame 0 of his scene, or a black page when the board is about to turn off.
3. AO_Gui renders the figures of the clock once into PSRAM and hands them to AO_Display, which writes the time into the panel's memory once a minute while the link is down.
4. It tells AO_LowPower it is ready.

A locked card of a running write refuses the round, so the glass stays lit during a write. On the wake, AO_Gui draws again on DISPLAY_REPAINT_SIG and returns to the face. The press of BOT that woke the board, and its release, do nothing else. If AO_LowPower refused a Turn off, the reason is said as a hint at the wake. The rest itself is on internals/power-and-sleep.

The face has a rest of its own, Rest, which dims the same face while the board stays awake (internals/gui/face). The two are different things: Rest is a look of the face, and Gui_asleep is the board parked.

The E5 test

A build with CONFIG_KODE_TEST_DOT makes AO_Gui the host of the E5 test's screens (sdk/kaos/test-dot). AO_TestDot publishes TEST_DOT_SCREEN_REQ_SIG with a screen or a pattern, and the first request that is not the end takes the glass from whichever screen is up. AO_Gui enters Gui_test_dot, a child of Gui_running, and logs door: <from> -> e5 test (the station).

On entry the hint and any card go, the armed press, the held bottom button and a finger that is down are forgotten, Rest's brightness steps stop so the glass keeps the level AO_TestDot set, and the black page is loaded. Each request is built with the kui_test_dot module on that page, drawn at once, flushed, and only then answered with test_dot_screen_done(kind, seq), echoing the number of the request. The answer is what lets the camera take its photo.

While the state stands:

• Touch, the buttons, HOME and the doors do nothing. The operator answers AO_TestDot's prompts on those very buttons, and the screens it publishes draw the prompts, so no guided test takes the glass from it.
• Nothing counts toward Rest, the auto-lock or the lock, and Kody does not play.
• A round of AO_LowPower is refused with E5 test, and a Bluetooth pairing is refused.
• The state ends on the request for no screen, which test_dot_end publishes. AO_Gui then clears the canvas and goes to the face with a cut, and logs door: e5 test -> face (test_dot_end). A FAIL stays on the glass until then, or until the next boot.

gui_info shows the state as test_dot.

Console doors

The console does not link to kgui. gui_info publishes GUI_DUMP_REQ_SIG and AO_Gui answers with a published state event, so a build without a GUI needs no stubs and gui_info times out. kgui adds six settings to config (lock, scene, clock, kody_sleep, haptic_ui, usb_awake), with AO_Gui as their owner, and seven assets_ functions for Kody's pack, registered in kgui_start() once the queue exists.

Specifications

The task

The states

AO_Gui is a hierarchical state machine. The state that is current decides which screen is loaded. Only a state's entry action loads a screen.

A flash write is not a state. Gui_running handles APP_FLASH_PROGRESS_SIG, APP_FLASH_FAIL_SIG and APP_FLASH_DONE_SIG with no transition and raises, rewrites or removes the one sheet over whichever screen is up.

The doors

A door is a request to change screen, a private signal that whatever asks posts with gui_door_post(). The state that is current answers it, so one signal can open on one screen and close on another. Each taken door logs door: <from> -> <to> (<what asked>).

The face is home. Apps is beside it and Settings comes down over it.

A sheet swallows the settings door, the auto-lock, the unlock and the door to Rest, and answers only home. The boot, the end of a guided test and the return from an app are hard cuts with no motion.

While a curtain moves, the state is still the screen where the door started. The door is taken when the curtain lands.

The settings it keeps

AO_Gui keeps eleven keys in the NVS namespace kgui. The six that have a config key are described on internals/settings.

A zone key left in kgui by an older build is copied to AO_Boot's kset/zone once and erased (gui_zone_migrate()). The keys pulls, quiet_kody and motion, which an older build kept, are erased once at boot.

The two interface settings, haptic_ui and usb_awake, are rows of the Settings page too, as Vibration and While charging. The console and the page go through the same code, so a value set in one shows in the other. A change is applied at once, stored, and logged as <key>: <word> (stored).

The Kconfig options

The component has two options.

CONFIG_KODEOS_GUI has no prompt: it is set whenever kgui is in the build, and it selects KODEOS_APPMGR and KODEOS_AUTOTEST.

The files

Everything is in components/kgui of the kodeOS repository. kgui_ao.c holds the state machine and decides. Each module below owns one thing and knows nothing of the Active Object; a module with a model keeps LVGL out of it, so its rules run in host tests.

The screens are built from kui.h and LVGL alone, never from kode.h, so the simulator builds them unchanged. Every callback is registered from C by ui_build(), and no screen declares one.

The parts

Gotchas

Example code

Walk the doors of the interface from the console of a Kode Dot. Opening the port restarts the board, so send everything in one session:

1. Run gui_info. The state reads face, because the board has started and did not come back from an app.
2. Send tap x=205 y=300. Apps slides in from the right, and gui_info reads state=browsing and level=root.
3. Send btn id=bot state=press, then btn id=bot state=release. Apps goes back to the face, which slides in from the left.
4. Send swipe x0=205 y0=30 x1=205 y1=320 ms=900. The finger pulls Settings down over the face and lets go past halfway. The settings screen opens, and the >|gesture record reads commits=1.
5. Send swipe x0=205 y0=320 x1=205 y1=30 ms=900. The settings screen goes up and the face is back.

In the SDK

• components/kgui: the whole component, in the kodeOS repository.
• kgui_ao.c: AO_Gui, with the contract of every function.
• components/kui: the kit that kgui draws with.