SDK

AO_TestDot

The Active Object that runs the E5 final test of a finished Kode Dot: the option, what it owns and asks, its verbs, the screens, the lock and the PASS.

What it is

The E5 station is the last test a Kode Dot goes through in the factory. The assembled unit sits in a nest, a computer drives it over the USB-C cable, a camera on the top connector watches the glass, and an operator presses buttons and touches the screen when the Kode Dot asks. AO_TestDot is the Active Object on the Kode Dot's side of that test.

test component=all is the test. The station's computer starts it and decides whether the unit passes. AO_TestDot owns the sequence: which row runs next, which photo is taken, how long each wait may last, and what the Kode Dot does with a PASS. It owns no device of the Kode Dot itself. Every row, button, brightness and charger setting belongs to its owner, and AO_TestDot asks that owner by event.

It sleeps from boot. At boot it reads one stored flag and nothing else: it claims nothing, allocates nothing and switches nothing on. The first verb from the cable that needs the station wakes it, and test_dot_end gives everything back. A customer's Kode Dot therefore carries the test and pays for it in flash and in a few KB of internal RAM.

The option is CONFIG_KODE_TEST_DOT. It is off in the SDK and on in kodeOS, as KODE_LOWPOWER and KODE_SCHEDULER are. An app that turns it on gets the same test. The wire between the computer and the Kode Dot is on internals/e5-wire-contract, and the rows it runs are on internals/production-test.

How it is connected

flowchart LR
pc["Station computer<br/>USB-C console"] --> con["AO_Console"]
con -- "TEST_DOT_REQ_SIG" --> td["AO_TestDot"]
td -- "records, end, blobs" --> con
td --> wk["its worker<br/>camera, relays, ADC, loop"]
wk --> j3["J3: OV5640, PCF8574, ADS1115"]
td -- "events" --> own["AO_Radio, AO_Autotest,<br/>AO_Buttons, AO_Touch, AO_Display,<br/>AO_Power, AO_Log, AO_Boot, AO_LedMgr"]
td -- "TEST_DOT_SCREEN_REQ_SIG" --> host["AO_Gui (kgui)<br/>or kscreen"]
host -- "test_dot_screen_done()" --> td
class pc ext
class con,td,own,host ao

What it owns and what it asks

While it is awake AO_TestDot holds the station's hardware on J3 and nothing else. Everything else is a request.

One worker task runs every job that blocks: the camera's probe, a grab, the analysis, the relays, the ADC, the pads loop. It runs one job and posts the result back, and AO_TestDot decides the next one (sdk/design-rules, rule 9). A job cannot be cancelled. One that runs past KODE_TEST_DOT_JOB_MS is given up, its step fails and its late answer is dropped, but it keeps the worker until it ends.

Dormant, awake, ending

AO_TestDot has one state and a mode.

The other verbs wake nothing and run in any mode.

The wake and the refusals of test component=all

The wake is also the fixture check. It runs in this order, and the first step that fails ends it:

1. The worker starts and the AO subscribes to the events it waits for.
2. AO_Radio switches J3's supply on. The wait is KODE_TEST_DOT_RAIL_MS (45 s), because a Wi-Fi sweep can hold the C5 that long.
3. The worker probes the camera on both sides of J3 for KODE_TEST_DOT_PROBE_MS (2 s), then reads the module's version. A rail that did not come up or a camera that did not answer ends the wake with camera.
4. The worker checks that the PCF8574 and the ADS1115 both answer and writes the relays' rest byte, 0xFF. A missing chip ends the wake with station_i2c.
5. AO_Display is asked for the level it has, then for 100 %.

A wake that fails writes the relays' rest byte if the chips were touched, closes the camera, returns J3, switches the supply off and answers >err code=4 msg=<word>. The brightness is never touched, so the glass stays as it was.

test component=all is refused in this order. The first that applies answers:

On a customer's Kode Dot, which has no fixture, test ends at step 5 after the wake's wait and leaves the Kode Dot as it found it.

The run

A run starts on the line of test component=all and keeps that line open until the camera part ends. It then closes the line with >ok and goes on in the background. What the background says goes into a ring of 64 records, which test_dot_poll drains.

The run is over when the rows after the camera and the operator part have both ended. A watchdog of KODE_TEST_DOT_RUN_MS (240 s) ends it earlier. c5 and psram are not rows of the run. The computer's radio check covers the C5, and psram stays a row of its own.

The camera part is a fixed sequence. Each of its steps takes one photo or one verdict, and one QP rest paces the settle before a photo. The analysis is pure C in kaos/test_dot/analysis (tdan.h), with no hardware and no RTOS, and the host suite checks it against drawn frames.

The screens and the patterns

AO_TestDot draws nothing. It publishes TEST_DOT_SCREEN_REQ_SIG with a kind, a sequence number and a few argument bytes, and the firmware's LVGL owner builds it with the kui_test_dot module (sdk/kui). In kodeOS the host is AO_Gui, in its state Gui_test_dot. In an app the option selects kscreen, whose kscreen_test_dot_event() does the same on the app's glass.

The host draws the frame, flushes it, and only then calls test_dot_screen_done(kind, seq). AO_TestDot accepts an answer only when both the kind and the number match the request it waits for, so a late answer to an earlier request cannot release a later photo. The wait is KODE_TEST_DOT_SCREEN_MS (2 s). When it runs out the step goes on without a frame: a camera step fails, and the test_dot_screen verb answers ok=0.

The patterns keep the geometry the analysis reads, to the pixel, and none of them follows the kit's palette. The OK and FAIL icons exist as patterns and no run photographs them. The pads screen exists in the module, and no verb asks for it.

The result and the PASS

The computer decides the verdict. It tells the Kode Dot with test_dot_result.

• verdict=pass is refused with no_run unless a run reached its end since the last test_dot_end, and with failed after a FAIL. It then asks AO_Boot for the factory reset with the ship end and waits. When the reset is done the glass shows PASS and the verb answers >ok.
• A reset that stops puts FAIL on the glass and answers >err code=4 msg=reset_<step>, where the step is find, install, apps, link, wipe, nvs or request. A reset that does not answer within KODE_TEST_DOT_RESET_MS answers >err code=6 msg=reset_timeout.
• verdict=fail erases nothing. During a run it first ends the run (test=all result=aborted why=verdict), cancels the operator's steps and puts FAIL on the glass. The FAIL stays there until test_dot_end or the next boot.

The ship end of the reset does not restart the board. When every step is done, AO_Boot asks AO_Power to watch the cable. AO_Power counts KODE_SHIP_UNPLUG_MS (15 s) from the poll that sees VBUS gone. A poll that sees it back cancels the count and leaves AO_Power armed, and the next unplug counts the whole 15 s again. AO_Boot waits in Boot_shipping, awake and already erased, through all of it. When the count ends AO_Boot erases the NVS namespaces once more, because the settings keep being written while the cable is in. It then writes the boot request of the welcome app, the last thing it writes, and AO_Power opens the battery path. The glass shows PASS all that time. The wake from ship mode is BOT or USB, and the first boot after it runs the welcome app once.

AO_Boot walks the reset one step at a time, each with its own budget: find the welcome app, install it from the card if it is only there, remove the other apps, bring the C5 link up, wipe the C5's networks and keys and this chip's bonds, erase the other nvs namespaces, and write the request. It keeps the identity, the station lock, kodeOS, the welcome app and the files. A welcome app that is neither installed nor on the card stops it at find before anything is erased.

The lock

test_dot_lock confirm=on writes locked in the NVS namespace kstation (KODE_STATION_NVS_NS) and answers >ok. A failed write answers >err code=4 msg=nvs.

• In the session that locked, every verb except test_dot_end answers >err code=5 msg=locked.
• At the next boot AO_TestDot reads the flag and every verb answers locked, test_dot_end and test_dot_info included.
• The factory reset keeps the key. Only a full flash erase (esptool erase-flash) removes it, which is also how a returned unit is tested again.
• factory_reset on the console is not a station verb and still works.

The end

test_dot_end on a dormant Kode Dot has nothing to give back except the glass: it asks the screen host to leave it (TEST_DOT_SCR_END) and answers. A screen that test_dot_screen showed before any wake goes with it. On an awake one it gives back in this order: the run is cancelled and the LED goes off, the boost goes off, a job still out answers, the dock console's pins come back, the relays go to rest and the camera closes, then the supply, the brightness, the glass, the memory and the subscriptions. Every wait of the end has a bound, and together they are at most 50 s (KODE_TEST_DOT_END_MS). A job that does not answer in KODE_TEST_DOT_JOB_MS answers the verb with timeout, and the rest of the end runs in the background when the job does answer. Every verb is busy until then.

The end does not cancel the ship countdown. The boost limit is restored by the end, at the fall of VBUS and at every boot.

Specifications

TBD: not yet run on a Kode Dot on a station. The figures below come from the code and its host tests; the stack, the camera's timing and the pads loop need a run on the bench.

The option

The task and its memory

The verbs

Every verb is the cable's alone and is registered by kaos_test_dot_register(). Each one posts a TestDotReqEvt to AO_TestDot with the console's sequence number, and the AO answers with TEST_DOT_REC_SIG records, optional TEST_DOT_LEND_SIG blobs and one TEST_DOT_ANS_SIG. The console's watchdog for these verbs is KODE_TEST_DOT_LINE_MS (295.15 s). The fields of every record are on internals/e5-wire-contract.

The timeouts

Every wait of the AO has a bound, held in kqp_config.h.

The bounds stack. Each one sits above the one it contains: the Kode Dot's own bound, then the console's line, then the wait of the computer, which adds 5 s to the bound (internals/e5-wire-contract). The AO's answer, a timeout included, therefore always reaches the line before anything gives it up. _Static_asserts in test_dot_ao.c hold the order: the sweep covers the driver's two scan constants, a discovery is longer than a radio check, and the line is longer than the reset, a discovery, the pads loop, the end, and the fixture check and a run's watchdog together.

A run that hits its watchdog prints test=all result=timeout why=watchdog, ends the line with >err code=6 msg=test if it is still open and shows FAIL.

The signals and the calls

A blob is lent, never copied. A copy of tens of kilobytes into events would be the pool's whole size, so the console writes the bytes from the AO's memory, paced like help, and gives the loan back when the last line is out.

Gotchas

Example code

You can see the dormant AO on any Kode Dot built with the option, with no station. Connect the cable and use tools/kcli.py.

1. Run python3 tools/kcli.py -p PORT --settle 5 cmd 'test_dot_info'. It prints >|test_dot state=dormant locked=0 run=none psram_free=<bytes> j3=free and >ok.
2. Run python3 tools/kcli.py -p PORT --settle 5 cmd --timeout 60 'test component=all'. After a pause it prints >err code=4 msg=camera.
3. Run test_dot_info again. The state is still dormant, j3 is free and psram_free is the figure of step 1.

In the SDK

• components/kaos/test_dot: test_dot_ao.c (the AO), test_dot_verbs.c (the console's side), test_dot_cam.c and test_dot_worker.c (the worker's jobs), and analysis/ (tdan.h, the screen analysis).
• components/kdrv: ov5640/ (the camera), station/ (kdrv_pcf8574, kdrv_ads1115 and kdrv_dock_loop).
• components/kui/test_dot: the screens and patterns.
• kqp_config.h: every bound above.