kodeOS internals

Kody's pack

How Kody's animations ship as a folder of files: the manifest, the limits every file passes, which pack plays, and how to install one.

What it is

Kody's animations are files, not part of the kodeOS image, except for one scene. The folder of files is a pack, and a manifest, kode.json, names the scenes of the face and the animations of the other screens. A pack lets you add a scene without building a new kodeOS. The official pack is on the internal FAT of every Kode Dot as it ships and updates with assets_update. TBD: kodeOS updating the pack by itself after an OS update is in progress; this page says how once it lands. You can put a pack of your own on the microSD card.

kodeOS checks every file against a set of limits before it plays it, and plays one source only. A bad file is refused with a reason in the log. The checks judge the form of a file. A file that passes them and still crashes the renderer crashes the board each time Kody draws it.

How it is connected

flowchart LR
subgraph media["Media"]
  sd["/sdcard/kode"]
  fat["/storage/kode"]
end
sd --> stg["AO_Storage"]
fat --> stg
stg --> assets["kgui_assets.c"]
net["AO_Net<br/>assets_update"] --> assets
assets -- "kui_pack_parse<br/>kui_pack_check_anim" --> player["kui_kody players"]
class sd store
class fat store
class stg ao
class net ao

Who does what

A pack is one folder named kode at the root of a medium, flat, with no subfolders. Two pieces of code handle it:

• kui_pack.c in the kit parses and checks a manifest and a single Lottie, and is host-tested.
• kgui_assets.c in kgui does the rest. It reads the files through AO_Storage and AO_Net one operation at a time, chooses the source, guards it and installs it.

kgui_assets.c runs inside AO_Gui's steps and reaches AO_Gui through one callback.

The files

A file is a Lottie in one of two forms:

• .json, as an animation program exports it. This is the form to drop on a card.
• .json.z, the same JSON minified and deflated into one zlib stream. The official pack uses this form.

The manifest never repeats an animation's width, height, frame count or rate. They come from the Lottie's w, h, op - ip and fr.

One source plays

kodeOS picks the pack on the card if a card is mounted and its manifest passes, then the pack on the internal FAT, then the built-in reloj scene. It never mixes files from two sources. A card pack that passes hides the whole FAT pack even if it has fewer scenes. A broken manifest on the card is no error: the log says why and the FAT pack plays.

kgui chooses the source in four cases:

• When the face starts.
• On assets_reload.
• After an install commits.
• When a card-pack file is missing and kode.json is missing with it.

Dead scenes

A manifest that passes makes its source usable, and files are checked later, when they are about to play. A scene whose wake-up or loop is refused is dead.

• A step over scenes skips a dead scene.
• The face shows the built-in scene while it wants a dead one.
• A refused reaction leaves its trigger's list.
• A refused role file shows nothing.

When files are read

kgui never opens a file. It asks AO_Storage, which owns both media, with the same reading conversation the launcher uses, and copies each chunk into PSRAM.

• At the choice, it reads the manifest and the files of the two roles a screen plays, empty and loading. They stay in memory while the source is active. The files of writing and goodbye are named in the manifest and are not read.
• A scene's wake-up and loop are read when Kody is about to play them.
• A reaction is read when its trigger fires.

Each file is judged once, when it arrives. A deflated one is inflated into a scratch block for the checks and freed, and the player inflates it again at each play.

AO_Storage refuses an open the same way when the reader is taken and when the file is empty, so kgui asks a stat which it was. An empty file is refused (why=size). A taken reader is asked again a few times and then waits, never dead for that.

An install

An install writes the internal FAT only. It stages, then commits.

1. Stage. Files go into /storage/kode.new.
2. Commit. kodeOS reads the staged manifest, checks that it passes and carries a digest for every file it names, checks every file is there, matches its digest and passes the limits, and writes /storage/kode.new/.ok. Then it removes the files the active manifest names from /storage/kode, moves the new ones in, the manifest last, removes .ok and chooses the source again.

A failed check leaves /storage/kode as it was. If the power fails during the moves, .ok is still there at the next boot, kgui finishes the moves and logs assets: the interrupted install is finished.

A staged folder without .ok stays as it is, and the next install overwrites the files it names. A file that no manifest names is never read and never removed.

Specifications

The manifest

The top-level keys of kode.json.

The keys of one scene:

The face key has two parts:

• default is the scene the hour picks outside every window (the first scene when absent or unknown).
• hours is a list of windows {from, to, scene} with hours 0 to 23. A window starts at from and ends before to, from is less than to, and none crosses midnight.

The first window that holds the local hour wins, and a window naming no scene is dropped with a log line.

More rules of the manifest:

• An unknown key, role or trigger is ignored at every level and reported at debug level, so a pack made for a newer kodeOS plays on an older one.
• At most 128 reactions may be named across all scenes.
• One file can fill two places only when both places have the same canvas and the same anchor.

The roles

The canvas each role needs and where it plays.

A role the pack leaves out changes the screen:

• With no empty, the empty launcher is the QR alone.
• The pack format still names writing and goodbye, but nothing on the board plays them, so a pack without them loses nothing.
• With no loading, the loading screen is its line.

The limits

A file over a limit is refused and the log names the file and the reason word: size, depth, json, format, schema, name, file, hash, canvas, frames, fps, precomp or memory.

A precomposition is a layer that holds a group of layers. The Lottie lists the groups in assets and a layer points to one with refId.

The nesting limit protects AO_Gui's stack, because ThorVG recurses as deep as the Lottie nests. The depth is counted first by a scan that does not recurse and counts brackets outside strings, so the checker cannot overflow the stack it protects.

The official pack

The pack that ships on every Kode Dot.

The console functions

kgui registers seven functions. All answer in records: each line a job says is the record >|assets, and the job's end closes the line with >ok or >err. While a line is open every other command answers >err code=4 msg=busy.

Errors and refusals:

• A bad argument answers >err code=3 msg=arg: a word other than sd or fat, a byte count outside 1 to 2147483647, a URL that does not fit (127 characters) or a name that cannot be a pack file.
• A full queue answers >err code=5.
• Any other refusal is a record followed by >err code=5 msg=<function>.
• Another job, a pack not yet read at boot, or an image being written refuse everything but assets_info with op=<function> result=refused why=busy, and the host tools ask again.
• A step that gets no answer for 20 s ends with result=timeout.
• assets_try needs the face on the glass with Kody awake (why=face), refuses under the built-in scene (why=builtin), and choosing a scene (on the Settings list or with config key="scene") or the hour moving the scene ends it.
• Install refusals use the words busy, offline, url, room, download, hash, missing, write and move, or a limit's name such as depth, canvas or frames.

gui_info logs assets: source=<word> scenes=<n> ready=<yes|no> and one scene: line per scene, with (dead) on a dead one.

Gotchas

Example code

Install a pack of your own on the Kode Dot from a computer:

1. Put kode.json and the files it names in one folder, DIR. Name the scenes with a-z, 0-9 and _, and draw each animation for its role's canvas.
2. Run python3 tools/kcli.py -p PORT assets-install DIR over the USB-C cable, or python3 tools/kble.py assets-install DIR over Bluetooth. The tool adds the digests the manifest lacks and refuses a file name the board would refuse.
3. Watch the records. assets_begin answers op=begin result=ready, each file_put follows, and assets_commit ends with op=commit result=done.
4. Run assets_info. It reports source=fat and your pack's name and version.
5. Put the Kode Dot on the face. Kody wakes in the scene of the hour, or in the one you pick with config key="scene" value="<name>".

In the SDK

• components/kui/pack: kui_pack.c and kui_pack.h, the manifest parser and the Lottie checks.
• components/kui/kody/pack: the official pack's files.
• kgui_assets.c: reading, choosing, guarding and installing.