SDK

kui, the UI kit

The Kode Dot's UI kit on LVGL: kshell's colours, type and line glyphs, the focus ring, six components, the glass, touch maths, a keypad, and Kody.

What it is

kui is how an app gets the look of the Kode Dot. It is written in plain C on top of LVGL 9.6, the graphics library that draws the interface. It holds everything the system's own screens are made of:

• the named colours and sizes of the design
• the shared styles
• eighteen fonts and fifty-seven images, among them forty-three line glyphs
• six components
• Kody, the Kode Dot's character, with a player for his animations

The kit also holds the maths a touch screen needs, in plain C with no LVGL: the shape of the glass, a recogniser that tells a tap from a swipe, a page that follows a finger and lands on a spring, and the text rules of a phone-style keypad. They are host-tested, and any tool can use them.

The look is kshell's, Luismi's shell for the Kode Dot: a black page, dark rows, one Bold Yellow ring for the cursor, Outfit for words and DM Sans for numbers. The tokens, the type and the line glyphs come from there.

kui depends on LVGL and on three SDK layers, kbsp, khal and klog, and on nothing above them. A firmware with no Active Objects draws with it exactly as kodeOS does, and an app that does not draw never takes LVGL into its image.

The display itself (LVGL on the panel, the flush, the touch feed, the render pass) belongs to sdk/kscreen. An app that names kscreen gets kui with it, and kscreen_open() calls kui_init().

How it is connected

flowchart LR
app["Your code<br/>or kscreen"] --> kui["kui"]
kui --> lvgl["LVGL 9.6"]
subgraph sdk["SDK layers"]
  kbsp["kbsp"]
  khal["khal"]
  klog["klog"]
end
kui -- "glass size" --> kbsp
kui -- "PSRAM heap,<br/>ROM inflate" --> khal
kui -- "refusals" --> klog
kui -. "kui_pack.c only" .-> cjson["cJSON"]
class app app

One thread, no lock

Everything in the kit runs on the one thread that drives LVGL, so it needs no lock and has none.

kui_init() once

kui_init(disp) puts LVGL's simple theme on the display and initialises the shared styles. Call it after lv_init() and after the display exists, before any style or component. A second call does nothing.

You pay flash for what you name

The kit has no table of names. Every font, every image and every animation is its own object file, and the linker keeps only what code names. The shared styles name seven of the eighteen faces (caption, body, button, name, title, heading, code), and six of those fall back on a digits face, so kui_init() links those seven and the four digits faces into any firmware that calls it. The clock face, each glyph, each animation and the player itself are linked only when something names them.

LVGL's heap is in PSRAM

The board file selects LVGL's custom allocator (CONFIG_LV_USE_CUSTOM_MALLOC=y), and kui_mem.c provides the hooks, so naming kui is all an app does. The hooks take PSRAM through khal and never fall back to internal RAM: a widget tree that does not fit returns NULL to LVGL and leaves the pool that DMA buffers and task stacks need alone. Blocks are aligned to 8 bytes.

An app that picks another allocator in its sdkconfig.defaults gets a kui_mem.c that compiles to nothing. CMake names one hook to the linker (-u lv_malloc_core), because libkui.a reaches the linker before liblvgl.a asks for it.

Build changes kui makes to LVGL

Three changes:

• LVGL compiles at -O2 whatever the firmware is optimised for, because an app built at -Og or kodeOS at -Os would leave a full-screen redraw well over the panel's 16.8 ms.
• LVGL's draw threads get their stacks in PSRAM through the one xTaskCreate() its FreeRTOS layer makes.
• ThorVG, LVGL's vector engine, builds without its SVG loader and without its own threads. The loader brings libstdc++'s locale machinery for 207,088 bytes of flash and 5,000 bytes of internal RAM (measured on kodeOS), and ThorVG's threads overflow their 3 KB default stack.

Faces and glyphs follow the brand

Words are Outfit and numbers are DM Sans. An Outfit face leaves out the digits 0 to 9 and falls back on the digits face of its own size, so LVGL draws each digit from DM Sans on the baseline of the line. The signs between digits (colon, point, percent, degree) stay Outfit.

The glass has round corners

The panel is 410 x 502 behind a cover glass with 114 px corners, so anything inside a corner square but outside its circle is under the silk screen and never seen.

• Nothing sits in the corners.
• A full-width row stays between y 53 and y 448 with 18 px side margins.
• No hairline runs along the very edge.

kui_panel_check() walks an object tree and reports whatever draws under a corner.

Kody

The player draws Lottie animations with lv_lottie over ThorVG on the LVGL thread. The kit compiles one scene in, the clock scene, as the floor a board falls back on.

Every other animation belongs to Kody's pack, a flat folder /kode/ on the microSD card or the internal FAT that holds a manifest kode.json and the Lottie files it names. The pack reader in the kit parses and checks; the orchestration that finds the pack and loads it lives in kgui, above the SDK.

Specifications

The files

The kit's files, in five groups. This group is the core: the components, the styles, the tokens and the allocator.

The files: glass, panel and touch maths

The shape of the glass, the corner check and the three touch modules.

The files: Kody and his pack

The player, the built-in scene and the pack reader.

The files: fonts and images

The generated faces and images.

The files: build, tools and simulator

The build configuration, the generators, the simulator and the component's own files.

The components

Each call returns an LVGL object that already wears the kit's styles. You place it, fill it and listen to its events. Every object carries a name with its own counter, for example pill_3. The six components, and the flex box under them:

A sheet carries at most one answer button. Its children, all of card:

• handle
• hdr_disc, holding hdr_img and hdr_text
• hdr_title and hdr_sub
• body
• line1 to line3
• note
• code, code_l1 and code_l2
• actions, holding btn and btn_text

The header disc is at (32, 56), the body at (32, 188) and the answer button at y 395.

The macros KUI_RADIUS_GLASS (the glass's corner radius, from kbsp), KUI_OPA_PCT(p) and KUI_LEVEL_MAX come with kui.h.

The shared styles

All are extern lv_style_t kui_style_*, initialised by kui_init(). They come in five groups:

The focus ring is the cursor of the pad. kui_style_ring is an outline KUI_RING_W (4 px) wide and KUI_RING_GAP (4 px) off the object, outside it, in KUI_COLOR_FOCUS (Bold Yellow). It rings a checked pill, a swatch, a circle or a row, and kgui leaves 8 px of room round a ringed object so its container never cuts the ring (gui_ring_room()). ring_dark is the same outline in Soft Black for an object on a light surface, and action_ring is the ring on the answer button of a sheet.

The faces

All are 4 bits per pixel. The brand sets words in Outfit and numbers in DM Sans, and the kit follows that rule in the faces themselves. Eight faces are Outfit, in three weights. Ten are DM Sans Bold: the clock, the codes, the two big figures and six faces that hold the digits 0 to 9 and nothing else. kui_font_caption and kui_font_code also hold the four arrows, for a hint that spells a code with them. TEXT is ASCII less 0-9; LATIN1 adds 0xA0-0xFF, so an accent in an app's name has a glyph. The eighteen faces:

Text on Kody Blue or Bold Yellow is Soft Black (KUI_COLOR_ON_ACCENT): Light Grey would read 2.7:1 on the blue and 1.3:1 on the yellow.

The faces are under the SIL Open Font License 1.1, which travels with any firmware that ships them.

The images

The kit has 57 images, each its own object file. All are extern const lv_image_dsc_t.

The thirteen glyphs are 40 x 40 ARGB8888, black on transparent, recoloured by C code:

The 43 line glyphs are one stroke of 2.2 px with round ends on a 24 x 24 grid, drawn at the size where a screen sets it, in LV_COLOR_FORMAT_A8: the image holds only an alpha and the screen gives the colour with lv_obj_set_style_image_recolor() at LV_OPA_COVER. The name is kui_glyph_<name>_<size>, and core/include/kui_glyphs.h declares them all. The bodies of the drawings come from kshell and live in tools/glyphgen.py. The 96 px glyphs are drawn at their own size, because the 40 px ones come out soft when scaled up.

The games glyph is a gamepad. kgui draws it on the Games folder of Apps, beside more (a cog) for Tools, wifi for Radios, chip for Sensors, spk3 for Medias and apps for every other folder and for an app with no icon. A firmware keeps only the glyphs a screen names.

The wordmark, kui_wordmark, is 300 x 90 RGB565A8.

The tokens

core/assets/tokens.json is the source. A role is what a style asks for and a palette entry is what it gets, so re-pointing a role repaints every style that names it. tools/gen_tokens.py --check exits non-zero when the header does not match the source.

The palette is a black page, dark rows, and one yellow for what you press and where the cursor is. The first six entries are the page and the brand manual's five colours; the rest are the greys and greens of kshell's look. Each entry with the role it serves:

The roles are KUI_COLOR_BG, _TEXT_ON_BG, _TEXT_MUTED, _SURFACE, _SHEET, _TEXT, _ON_ACCENT, _OFF, _REST, _ACCENT, _LEVEL, _ACTION, _TRACK, _FOCUS, _OK, _CHARGE, _WARN and _DANGER, each an lv_color_hex() of a palette entry. _SURFACE is Row Dark, _SHEET is the page, _LEVEL, _ACTION, _FOCUS and _WARN are Bold Yellow, and _ACCENT is Kody Blue. Include kui.h, which brings LVGL first.

The sizes, in pixels:

The glass and the panel

The calls that know the shape of the glass.

Touch maths

All three modules are plain C with no LVGL, integer or float arithmetic only, and times are a free-running 32-bit millisecond counter that may wrap (kui_age_ms() is the one rule for the age of a stamp).

The calls of each module:

How each module behaves:

kui_gesture

• A press lands in a zone that takes some directions (KUI_GESTURE_DIR_UP, _DOWN, _LEFT, _RIGHT).
• The drag is decided once, at KUI_GESTURE_CLAIM_PX (12 px) from the landing: an axis under 3:2 over the other is DIAGONAL; a direction the zone takes is CLAIMED; any other is rejected (AXIS or ZONE).
• A press within KUI_GESTURE_TAP_PX (16 px) of the landing on both axes is still a TAP.
• Every sample is measured from the landing.

kui_spring

• Critically damped (KUI_SPRING_CRITICAL 1.0) or underdamped, evaluated in closed form from the clock, so the motion does not depend on how often it is looked at.
• A damping above 1 is 1.
• A period of 0 is at the target from the start.

kui_drag

• A page is one offset from closed (0) to open (the span), in phases IDLE, HELD, FOLLOW, SETTLE.
• From rest, the first KUI_DRAG_RESIST_FROM_PX (48) of travel moves it 35 % of the distance, growing back to the whole finger by KUI_DRAG_RESIST_TO_PX (160). A page caught in flight skips the resistance.
• Release opens when flung toward open faster than KUI_DRAG_FLING_PX_S (800), goes back when flung the other way, otherwise opens from halfway.
• The speed is measured over the last KUI_DRAG_VEL_WINDOW_MS (80) of 16 samples.
• The spring has a period of KUI_DRAG_SPRING_MS (250) and lands no later than KUI_DRAG_LAND_MAX_MS (320) after it started.

The caller owes a follower one answer to every catch: kui_drag_release(), kui_drag_grab() then its release, kui_drag_finish(), kui_drag_aim() or kui_drag_set(). A page left HELD is not stepped and stays frozen. Positions are projected onto the axis and signed toward open, and the point where the finger lifted is fed through kui_drag_follow() before kui_drag_release(), which takes no position.

The multitap keypad

The text rules of the phone keypad: ten character keys, a mode key and Delete. The module logs and prints nothing, because the text may be a secret, and kui_multitap_clear() zeroes every byte.

How the keypad behaves:

Kody's player

kui_kody.h plays animations one at a time on one draw buffer of its own, w x h ARGB8888, taken through LVGL's allocator on the first play and freed with the object.

It exists only with Lottie on, so a firmware without these three options has none of the functions, and a call fails at link time:

CONFIG_LV_USE_THORVG=y
CONFIG_LV_USE_THORVG_INTERNAL=y
CONFIG_LV_USE_LOTTIE=y

The calls of the player:

A player that is not visible (hidden, on a screen not on the glass, scrolled out of view) stands on the last frame it drew and goes on when seen.

An animation is its Lottie JSON, minified and deflated into one zlib stream (kui_kody_anim_t: zlib, zlib_len, json_len, canvas w and h, frames, fps 30, anchor, deflated), or plain JSON as a user's .json arrives. Each start inflates the JSON into a PSRAM block of exactly that size with the ROM inflater (khal_zlib_decompress()), hands it to lv_lottie, and frees it before the start is over.

An anchor is a frame of a loop with the same pose as frame 0, every anchor frames; reactions start and end on one, and the player switches only on an anchor or the last frame of a pass. kui_kody_next_anchor() and kui_kody_crossed() are the plain-integer answers behind that.

The three animations built into the kit:

A player plays only animations drawn for its own canvas. Scenes, wake-ups and reactions are 410 x 300; duda is 410 x 369; portatil and despide are 410 x 160; cargando is 264 x 264. All sit on the bottom edge of the glass except cargando, which is centred.

What a player costs:

Kody's pack

A pack is a flat folder: kode.json and the Lottie files it names, on the microSD card (/sdcard/kode/, wins) or the internal FAT (/storage/kode/), else the built-in scene (kui_pack_src_t).

The official pack in kody/pack/ has ten scenes, tren, parque, camping, azotea, madrugada, desayuno, taller, lluvia, playa and reloj. Its face has no windows and picks tren by default. Every scene has a wake-up, a loop and reactions for look, hour, notice and plug, and the first five also a joke. It also names the four roles outside the face.

The manifest has:

• format 1, name and version
• scenes, each with name, wake, loop, anchor and on, a list of files per trigger (look, hour, notice, plug, joke)
• face, with default and hours of from, to and scene
• the roles empty, writing, goodbye and loading
• a sha256 map of file name to digest

The canvas each role plays on:

The reader checks before anything plays. Unknown keys are ignored at every level, so a pack made for a newer firmware reads here. A window naming no scene is dropped, and a default naming none leaves the first scene the default, each with a warning.

The limits it enforces:

A refusal is one of size, depth, json, format, schema, name, file, hash, canvas, frames, fps, precomp or memory (kui_pack_err_word()).

The calls are:

• kui_pack_parse() and kui_pack_free()
• kui_pack_scene_find() and kui_pack_file_find()
• kui_pack_scene_for_hour(): the first window holding the hour, else the default, also for a negative hour while the time is unknown
• kui_pack_hashed(): an installer's precondition
• kui_pack_role_canvas() and kui_pack_file_canvas()
• kui_pack_check_anim(), kui_pack_json_depth() and kui_pack_file_name_ok()

Parser arrays live in PSRAM, and cJSON appears in kui_pack.c and nowhere else.

The generators and the simulator

Five scripts regenerate the generated files. Run each from the kit's directory.

The five scripts:

The lint of kodygen.py refuses pucker and bloat, zig-zag, an effect that is not a blur, an expression, an image layer, a text layer or a 3D layer, naming the animation, layer and property. --check compares every stored stream with a fresh one and fails a stream over 5 % longer. --lint prints one line per animation and writes nothing.

python3 -m unittest discover -s components/kui/tools/tests runs the generator's tests.

The simulator in sim/ draws a consumer's screens on a desktop with LVGL 9.6 over SDL2: kui_sim <screen> [--snapshot OUT.png] [--set SUBJECT=VALUE]... [--device] [--bezel]. A consumer hands it kui_sim_screens[], kui_sim_setup() and kui_sim_set() (kui_sim.h) and builds with kui_sim_add().

It does not simulate an Active Object: no selection, scrolling, sheets or live values, and no Lottie, because its LVGL is built in C alone, so kui_kody.c compiles to nothing there. Timing on the desktop says nothing about the board.

Gotchas

Example code

The part of kui that needs no screen: the keypad's text rules. Press key 4 twice for "h", wait a second, then three times for "i". The console prints text: hi. The visual half of the kit has its example in sdk/kscreen.

/*
 * multitap_hi.c - 2026-10-28 - from Kode with love
 *
 * Types "hi" on the UI kit's phone keypad with no screen. Key 4 twice is
 * "h"; a second later, key 4 three times is "i". The console prints hi.
 */
#include "kode.h"
#include "kui_multitap.h"
 
/* Press key 4 count times, 100 ms apart, starting at start_ms. */
static void press_four(kui_multitap_t * const keypad, uint32_t start_ms, uint32_t count)
{
    for (uint32_t i = 0U; i < count; ++i) {
        (void)kui_multitap_press(keypad, KUI_MULTITAP_KEY_4, start_ms + (i * 100U));
    }
}
 
/* Bring the system up, type the text and log it. */
void app_main(void)
{
    kui_multitap_t keypad;
 
    kode_init();
    kui_multitap_init(&keypad, KUI_MULTITAP_SSID_MAX);
    press_four(&keypad, 0U, 2U);
    press_four(&keypad, 1000U, 3U);
    KLOG_I("multitap", "text: %s", kui_multitap_text(&keypad));
    kui_multitap_clear(&keypad);
}

Compiled against the SDK with ESP-IDF v6.1 on 2026-10-28. TBD: a run on a Kode Dot.

In the SDK

• components/kui: the kit, one folder per module.
• kui.h: the components, styles, faces and images.
• components/kui/README.md: using the kit from an app, and regenerating the assets.