kodeOS internals

Command set

Every verb of the kodeOS console, grouped by the Active Object that owns it, with its arguments, its answer and its limits.

What it is

This page lists every command of the console of a Kode Dot: its arguments, what it answers and how long the console waits for it. The grammar of a line and the shape of each answer are on internals/console-protocol. Commands that an app adds are on internals/variables-and-functions.

The board has one list of commands, the array CMDS[] near the end of console_ao.c. The parser reads it, help prints it and this page follows it. If this page and help ever differ, believe help: it prints the verbs of your build, and a Kconfig option can remove a group. The groups below follow the parts of the board. The order of help is the order of CMDS[].

Try these first:

• help prints every verb with its arguments.
• ping answers pong, the liveness check.
• info says what the board is and what runs on it. ps lists the Active Objects and the memory.
• led_rgb rgb=0,0,200 sets the LED to blue.
• bat_info shows the battery. ls path="/" lists the files. screenshot takes a picture of the glass.
• config lists every stored setting.

How it is connected

flowchart LR
host["Host line<br/>cable or Bluetooth"]
subgraph board["On the Kode Dot"]
  con["AO_Console<br/>CMDS[]"]
  own["Owning AO"]
  dev["kdrv driver"]
  con -- "publish or post" --> own
  own --> dev
  own -. "answer event" .-> con
end
host -- "command" --> con
con -- "records, >ok" --> host
class host ext
class con,own ao

AO_Console parses and validates. It owns no device. A handler posts a request to the Active Object that owns the device (led_* to AO_LedMgr, app_* to AO_AppMgr, wifi_* to AO_Radio) and the owner answers by event.

A line comes from one of four sources: the cable (and the charging base), Bluetooth, the Kode channel and the scheduler. A line from the channel waits in a queue when the console is busy and is not answered busy (internals/kode-channel). A line from the scheduler is a cron entry running on its own account, and its replies go to the log. sdk/kaos/console has the policy of the sources.

A few bench verbs have no owner to ask and run inside the AO_Console step: i2c_scan, clocks, temp, display_info, time, exp, exp_help, pwd, the nvs_* verbs and the _help tables of the chips.

A Kconfig option can remove a verb. This table lists which option guards which verbs:

See internals/console-protocol for the in-flight rule and the watchdog classes.

These files hold the console:

Specifications

Argument cells write the key, its type and whether it is required. Optional keys show their default after =. An enum lists its words after "one of". A record cell names the keys of each >| record without the prefix.

System and liveness

No Active Object owns these verbs. They answer from the AO_Console task.

What the records say:

• slot carries state as running, inactive, empty or absent.
• coredump reads none, or present with owner kodeos or other, and the task and PC when known.
• recog in the c5 record says what the P4 recognises on the C5: kode, stock, old or nolink.
• In ps, int_low is the lowest the internal pool has been since boot and the number to judge a build by.
• alloc_fail counts refused allocations, log_dropped counts console lines the event pool could not carry and rx_dropped counts bytes lost on input.

LED

Owner: AO_LedMgr. Each verb publishes one event and answers >ok at once.

Storage media

Owner: AO_Storage. The sd_* and fs_* verbs differ only in the medium: the microSD card or the internal FAT partition.

The file tree

Owner: AO_Storage, through console_fs.c. These verbs take a path, absolute or relative to one working directory that AO_Console keeps (it starts at /, moves only on cd and is lost at reset). / exists only in the console and has two children, sdcard and storage.

How write behaves:

• line=0 writes the whole file, truncating it or appending with append=on.
• line=<n> replaces line n through a temporary file and three renames. It answers noline (code 3) for a line the file lacks and toolarge when the file or the result passes 32 KB.
• append=on with a non-zero line answers appendline at once.
• text="" writes an empty file.
• A \n inside the quotes writes a newline.

Missing volumes answer volume. file_put answers code 3 msg=path for a path that names no volume and runs on the cable, the base and Bluetooth.

Files and payloads

Owners: AO_Storage for the files, AO_Display for the capture. The bulk answers are base64 d records, described on internals/console-protocol.

screenshot freezes the shadow copy of the glass in AO_Display and takes the rectangles the panel received, so it captures LVGL and raw pixel writers alike. A black screen is not an error and logs a warning. The enum word http exists in a build with KODEOS_SHOT_HTTP.

dst=http uploads a JPEG over the Kode channel. token is required (1 to 128 characters of letters, digits, _ and -) and refused with another destination.

• With none of fps, secs, the answer is screenshot dst=http bytes id seq.
• With either, a stream starts and the answer is screenshot dst=http mode=stream fps secs at once, with defaults of 2 frames a second and 60 s.
• stop=on ends a stream and takes no other key.

The refusals are in internals/kode-channel.

Apps

Owner: AO_AppMgr. See internals/apps-region and internals/boot-model.

install takes its image from src: fs: or sd: (the prefix is removed and the name is searched on the card first), http://, https://, pending (the mailbox) or terminal. terminal streams the image down the port the command arrived on and needs size and crc32; every other source refuses them with code 3. The destinations:

• os writes the inactive kodeOS slot, switches to it and resets. The new image has to confirm itself or the board returns to the old one.
• app writes the apps region. It runs the app only with run=on. run is refused with any other destination. From the terminal, name is the image's project name: the region makes room before the image arrives, and with name the old copy of that app goes first instead of the oldest app. Each app the install evicts prints >|evicted name="<project>" kept=off before >|ready. name is refused with code 3 outside src="terminal" dst=app.
• c5 updates the ESP32-C5 firmware. It runs from the cable and the base only.
• pending parks the image undecoded in the mailbox. src="pending" dst=pending is refused.

From a medium >ok is an accept. From the terminal it is a result. kcli.py install and kble.py install run the exchange for you.

app_run, install dst=os and hcf reset the board.

The app's variables, functions and settings

Four verbs and config exist in every build with a console. internals/variables-and-functions explains them.

Refusals of variable and function:

• Unknown row, value= or watch= on a function, and arg= on a variable are code 3.
• A watch period from 1 to 99 is code 3 with msg=watch.
• An arg in the wrong form, out of range or refused by the row is code 3 with msg=arg.
• A getter or run that fails is code 5 with the row name.

Settings

config with no keys lists every setting in registration order. With key it reads one. With key and value it sets one, and the answer is the record with the new value. A string setting is quoted and every other kind is bare. stored=yes means the key is in NVS and stored=no means the owner's default applies. The console never touches NVS: it sends a request per key and the owner answers within 1 s. The first request for a key is published; once the owner has answered, the console posts to it directly and keeps 4 slots of its queue free.

wifi_join, wifi_ps, chan and chan_keep exist only in a build with Wi-Fi or the channel, off_after only with KODE_LOWPOWER, sleep_after only with KODE_LOWPOWER_IDLE as well, and wifi and ble only with their radio service. mag_cal exists with the IMU's owner. kodeOS builds without KODE_LOWPOWER_IDLE and lists 24 rows.

The refusals:

• Unknown key: code 3 msg=key.
• value without key: code 2.
• A wrong form or range: code 3 msg=value.
• A value the owner refuses: code 5 msg=value. A zone that is not a POSIX TZ string is one of these.
• An owner whose queue has fewer than 4 free slots: code 4 msg=busy. Nothing is sent and nothing changes.
• An owner that does not answer in 1 s: code 6.

In a listing, a silent owner gives value=- stored=- and the listing goes on. An app adds rows with KODE_CONFIG_ADD(), up to 32 rows in 4 tables.

Rules worth knowing:

• ble=on means advertise from boot.
• charge and charge_ma replace the boot policy of the charger.
• chan=off leaves the channel at once.
• chan_keep is how long the broker keeps the channel's session while the board is away, so how long the commands sent meanwhile wait. A set is stored at once and used at the next connect, a renewal included. channel_info shows the live age as keep=.
• sleep_after is the time without input before the board goes from AWAKE to ASLEEP, and off_after the time ASLEEP before OFF. A button, a touch or a console line from any port restarts the count, and never counts nothing. sleep_after does not depend on lock or kody_sleep.
• scene=auto erases the chosen scene.
• kody_sleep=lock erases its key.

Buttons, power and display

The brightness is config key="bright". The charger is charge and charge_ma. charge_limit is not a verb.

• sleep takes the board to ASLEEP: light sleep with the radios kept up and the time on the dimmed glass. AO_LowPower asks every owner to put its device at rest, and >ok comes when the state has changed. A refusal is quoted: cable: external power while VBUS is present, or the name of the owner that is busy, for example storage: file write. A busy or silent owner is not final. The request is begun again every second for 10 s and the verb is answered once, at the end. A cable is refused at once. The verb works from every port, and a line on Bluetooth or the Kode channel wakes a board that sleeps. The console waits up to 17 s for the answer.
• power_off takes the board to OFF: deep sleep with the C5 held in reset. >ok comes when the state has changed, a moment before the P4 stops. It is refused for the same reasons as sleep. Only the bottom button wakes the board, and the wake is a boot.
• ship_mode puts the board into ship mode and is the only door to it: no app and no other verb reaches it. On battery nothing could answer afterwards. To switch the board on again, press the bottom button, which is wired to the QON pin of the charger chip. On USB the board cannot switch off.
• lowpower_info prints >|lowpower state=awake|asleep|off for_s= cause= sleep_after= off_after= wakes_bot= wakes_ble= wakes_mqtt= wakes_timer= last_busy= and >|lowpower_stats slept_pct= sleeps= wakes_c5= wakes_tx= tx_sta= tx_serial= tx_hci= knocks_max= deaf=. The cause is request, idle, off_after, bot, ble, mqtt, cable, timer or boot. The two times are seconds and 0 is never. wakes_bot, wakes_ble and wakes_mqtt count the wakes from ASLEEP by the bottom button, a Bluetooth line and the Kode channel, and wakes_timer the wakes for an owner's time (the radio wakes, in which the Kode channel works with the glass dark). last_busy is the last refusal, quoted, or -. The tx_ fields are - until a wake has been noted. slept_pct is the share of the time since boot spent in light sleep.
• lowpower_info last=on prints the summary the board keeps of its last rest, so a run on battery can be read back on the cable: >|lowpower_last start= for_s= slept_pct= sleeps= wakes_c5= wakes_tx= deaf= end= samples= (start in Unix seconds, - when the clock was not set; end is a cause word, or asleep when nothing ended it), then one >|lp_sample t= ma= mv= per minute, oldest first: the seconds from the start, the cell current in mA (negative out of the cell) and the cell voltage in mV. It goes out in slices like help. A board with no summary prints >|lowpower_last present=no.

Scheduled commands

Owner: AO_Scheduler (sdk/kaos/scheduler). cron keeps the table of entries. An entry is a name, a time in the five fields of cron and a console line to run at that time. It exists with KODE_SCHEDULER.

when is a string like every other, with one bare word: an expression is quoted and off is bare. A quoted "off" and a bare expression are both refused, so each has one way to be typed.

cron                                          list every entry, mqtt first
cron name="riego"                             show one
cron name="riego" when="0 7 * * *" cmd="ping" add an entry, or change it
cron name="riego" when=off                    remove it
cron name="mqtt" when="*/5 * * * *"           change the built-in entry
cron name="mqtt" when=off                     switch the safety net off

• The records come in the order of the table, mqtt first, then >ok. A set answers with the entry as it now is, then >ok. A removal, and mqtt switched off, answer >ok alone.
• owner is console, code or builtin. next is the next minute as Unix seconds in UTC, or - when the clock is not set or the entry is off. cmd is - for an entry with no line (an entry of code, and mqtt). stored says whether the entry survives a reset. A switched-off mqtt lists with when="off" and next=-, and a time given to it switches it on again.
• The time is the UTC calendar of the epoch clock in five fields: minute, hour, day of month, month, day of week. Each takes *, numbers, lists (1,15), ranges (9-17) and steps (*/5, 9-17/2). The least period is one minute.
• The line runs with the source SCHED when the minute comes. It must start with a verb this build has, other than cron, or the entry is refused when it is made. The payload verbs are accepted then and refused only when they run (>err code=5 msg=sched in the log). If the console is in the middle of another command at that minute, AO_Scheduler gives the line again every second, for up to 10 s from the start of the minute's work; past that it drops the line with a warning, the entry '<name>' did not run: the work of its minute ran out of time, and the entry runs again at its next time. Its replies go to the log as notices, sched: <reply>. config key="log" value=w hides them. A record whose line does not fit one console line with the other fields is cut, after a cmd: cut to fit one line warning. The entry keeps the whole line.
• From the Kode channel cron is accepted like every other verb, and the entry it leaves is stored (internals/kode-channel).
• mqtt takes no cmd. Its work is the look at the sessions of the Kode channel in a radio wake.

The console refuses before it posts anything:

AO_Scheduler refuses with one of these reasons, and the console turns it into the answer:

Removing a name that no console entry holds answers msg=name.

Chip fields

Five chips share one shape. pmic and gauge (AO_Power), ioexp (AO_IoExp), tp (AO_Touch) and sd (AO_Storage) read and write the fields of one chip. audio, haptic and c5 have the same shape in their own sections.

An unknown field is code 3 msg=field. value without field is code 2. A read-only field, or a value the field cannot hold, is code 3 with the field name. A chip that does not answer is code 5. Writes are read back, so ichg_ma set to 500 answers 512.

Notes per chip:

• pmic refuses batfet_dis (ship mode is ship_mode) and reg_rst (use pmic_reset).
• gauge values are unsigned.
• ioexp writes to c7 or o7 change the supply of the panel.
• tp with dis_auto_sleep set to 0 puts the controller to sleep until a finger touches the glass or the board resets.
• sd fields from the card are read-only. width_req (1 or 4) and freq_req_khz (400 to 50000) set the next mount.
• c5 has no writable row and answers from the snapshot of the last link start.
• audio reads the register back, since mic_db rounds.

The field tables are on the pages of the drivers, for example sdk/kdrv/bq25896.

Clocks, time and temperature

No owner. These answer immediately.

Audio

Owner: AO_Audio.

audio and audio_help are in the chip fields. dac_vol_db and adc_vol_db use the chip's dB scale where 0 is the loudest clean level. adc_scale_db and pga are two different microphone gains. reg32, reg34 and drc_en are read-only.

Infrared

Owner: AO_Ir. The block is on the ESP32-C5.

NFC

Owner: AO_Nfc, the ST25R3916B on the antenna board. The reader field is on only while a verb waits. nfc_field and nfc_emulate keep it off.

uid has 4, 7 or 10 bytes, atqa two, sak one. A coherent uid atqa sak set clones a card. uri or text presents a Type-2 tag a phone reads.

When a tag is in the window but the exchange fails, nfc_read and nfc_write put the raw kode_status_t in code:

• 3: no key opened it.
• 1: no NDEF message.
• 2: the tag stopped answering.

nfc_read and nfc_write try the twenty most common Mifare Classic keys. kodeOS reads cards with keys it holds and does not recover a key that is on no list.

RFID, 125 kHz

Owner: AO_Rfid. The carrier is on only while a read, a clone or a test window runs.

A job that holds the front end makes the others answer code 3 msg="rfid busy or not fitted" for a read or a clone, and code 4 busy for rfid_field. A board with no antenna board closes its windows empty, since the board cannot sense the antenna. id that is not ten hex digits is code 3 msg=id.

Haptic

Owner: AO_Haptic, the AW86233 and its LRA. haptic and haptic_help follow the chip fields.

The record states what was asked for, not what was felt. gain is a percent of full scale, clamped to the rating of the LRA.

The expansion header

Owner: whoever holds KBSP_RES_EXP, or nobody. The fourteen positions of J3 are served by khal_exp.

A write needs both pos and mode:

• Any key without pos is code 2 msg=pos.
• pos without mode is code 2 msg=mode.
• The first write claims KBSP_RES_EXP for "console (bench)" until the next boot.
• If an app holds the header, every write is code 5 msg=owned, while reads still work.
• A request khal_exp refuses is code 5 msg=exp.

duty is in tenths of a percent. caps letters are d digital, m matrix, a adc, l low power. The tag of a lent position is clipped to 8 characters.

Injected input

No owner. These verbs publish the events that AO_Touch and AO_Buttons publish, so no receiver can tell them from a finger or a thumb. All answer >ok as accepts.

Coordinates outside the panel are refused, never clamped.

• btn with hold is for top and bot only, and double for top only. Other ids answer code 3 msg=id.
• An injected press never starts the 600 ms hold clock of AO_Buttons, so a host that wants a held thumb sends press, hold, release. The hold of bot is the HOME signal of AO_Boot.
• press and release go through the same door as a real button, so kode_buttons_read() follows them.

The mirror

Owner: AO_Display. Built with KODEOS_MIRROR. See internals/mirror.

GUI and boot

What the gui record says:

• sel is the selection of the launcher in quotes, or - for none: the project name of an installed app, the file name of a file, and /<group> for a group.
• level is root or group, and group is the name of the open group in quotes, or - at the root.
• sheet is the card that is up, or -. state is face while the Lock is awake and rest at Rest, and returning while the first frame after an app waits for the list.
• kody is playing, paused, asleep or none. lock_s is the auto-lock time in seconds, or never. stack_free is the bytes of AO_Gui's stack that were never used.
• The gesture record has drag (idle, pending, follow or settle) and counters since boot that each stop at 65535: the presses that ended as a tap, the drags the recognizer claimed, the followed drags that landed (commits) and those released short (shorts), and the presses it rejected by reason (diagonal, axis, zone, blocked).
• The record reaches the Kode channel as it reaches the cable. The log lines that gui_info also writes do not. One of those lines starts with ui: and gives the interface settings and the buzzes asked and held back (internals/gui/buttons-and-gestures).

The NVS store

No owner. A value is read by the next app through kode_nvs_get(). Values sit in plain flash.

The radio and the identity

Owner: AO_Radio. Built with KODEOS_RADIO.

The identity verbs answer code 5 identity with no key or certificate, locked after ident_lock, and refused with the link down, another request in flight or no answer in 3 s.

ident_csr, ident_cert, ident_lock and c5_wipe refuse Bluetooth with msg=cable. confirm=on is required for the last two: without it the answer is code 3 msg=confirm and nothing happens. c5_wipe stops at the first step that fails with vault, btkeys or ble.

install dst=c5 verifies the image before it asks the C5 for anything: CRC, container digest, ESP header and chip id, so an image for the P4 is refused by name. Its >ok means the C5 took and activated the image. The update ends with the link off, so run radio_up and read c5. The C5 has no rollback: a bad image leaves it unreachable.

Wi-Fi

Owner: AO_Radio. Built with KODEOS_WIFI. Most verbs hand their deadline to the owner. The state record is wifi (idle, connecting, got_ip or disconnected) with ssid ip rssi en, where en is the stored flag and not the association.

Bluetooth

Owner: AO_Radio. Built with KODEOS_BLE. See internals/ble-console.

Network and MQTT

Owner: AO_Net. KODEOS_NET builds the network verbs and KODEOS_MQTT the MQTT verbs. lwIP runs on the P4.

The five mqtt_* verbs answer code 4 busy while the Kode channel holds the one MQTT client. mqtt_down waits for the esp-mqtt task and has no console deadline. net_ping is the ICMP verb because ping is the liveness check. The ceiling of count is the ceiling of the listing, since every echo is an event. rx_dropped of net_info counts the MQTT messages the driver dropped since boot because its receive ring was full. It is not the rx_dropped of ps, which counts console input bytes that were lost. See internals/kode-channel for the fields of channel_info.

Logging

The global level is config key="log". It is stored, and setting it back to the build level erases the key. Answers are never filtered.

• At n the console shows answers, notices, warnings and errors.
• At off it shows answers only.
• The guided tests print their prompts at notice level, so e hides them on the console and not on the glass.
• A line that the build removed with CONFIG_KLOG_MAXIMUM_LEVEL cannot come back.

Self-tests

test runs one row or a group. test_report prints the report that the last whole user run kept in NVS.

A timeout is a row nobody judged. fail counts every row that did not pass, timeouts included. A skipped row found nothing to judge, such as a slot with no card. Rows run one at a time in the order of TESTS[]. A verdict block of log lines with the tag kcli comes before the summary.

The groups:

Every row also runs by name. Some run only by name: screenshot, jpeg (with the mirror), fs, boot, apps, kfw, id, ble_console and net (with their options), c5, psram, and the user rows sd_user, c5_user, nfc_field, rfid_field, power_plug, nfc_card and rfid_card.

The rows that need a person:

• buttons: six prompts, 20 s each, a press let go within 3 s.
• led (three colours) and display (five fields): TOP is yes and BOT is no.
• tp: two targets, 64 px tolerance, 20 s each.

The criteria of each row are on internals/production-test.

The E5 final test

test component=all is the final test of a finished Kode Dot on the E5 station. A station computer starts it over the cable, and the Kode Dot runs the rows, the camera's checks of the glass and the LED, and the operator's presses and touches. Then the computer decides the verdict. AO_Console hands the line to AO_TestDot, which answers the records on the open line and closes it with >ok when the camera part ends. The rest arrives through test_dot_poll.

all is refused in this order: not_built, the source (cable, net or sched), locked, busy, then the fixture: camera, then station_i2c. On a Kode Dot without the station, test therefore ends in >err code=4 msg=camera and leaves the glass, the radio and every owner as they were.

The verbs of the test are cable only, and the station's computer is their only client. Their keys, records and refusals are on internals/e5-wire-contract.

The owner is AO_TestDot (sdk/kaos/test-dot). The console's factory_reset is refused as busy while a run goes.

Gotchas

Example code

Send commands from a terminal with tools/kcli.py. It prints the records and checks the terminator.

1. Connect the Kode Dot over the USB-C cable and load ESP-IDF in your terminal, which provides pyserial.
2. Run python3 tools/kcli.py -p PORT --settle 5 cmd 'ls path="/"'. It prints one record for sdcard, one for storage and then ok.
3. Run python3 tools/kcli.py -p PORT cmd 'led_rgb rgb=0,0,200'. The LED turns blue.
4. Run python3 tools/kcli.py -p PORT cmd 'config key="bright" value=40'. The record shows value=40 stored=yes and the glass dims.
5. For a verb that works for a while, add --gap 10 after cmd so kcli.py keeps listening for the ! lines of the outcome.

The verbs that carry a payload (install with src="terminal", file_put, file_get, screenshot) have their own kcli.py subcommands: install, file-put, file-get and screenshot -o shot.png. Do not send them with cmd.

In the SDK

• components/kaos/console: console_ao.c holds CMDS[] and every handler.
• components/kaos/autotest: the TESTS[] table behind test.
• components/kaos/test_dot: AO_TestDot and the test_dot_* verbs.
• tools/kcli.py: the reference host program.