kodeOS internals

E5 wire contract

The console contract between the E5 station's computer and a Kode Dot: every verb and record, the order of a run, the refusals and the error codes.

What it is

The E5 station tests a finished Kode Dot and decides whether it ships. A computer drives the unit over the USB-C console, in the same text protocol as any other console client, with a set of verbs that only a kodeOS built with KODE_TEST_DOT knows. The Kode Dot measures and the computer judges. This page is the contract between the two halves: the verbs the computer sends, the records it reads back and the order a run follows.

The Kode Dot's side is the Active Object AO_TestDot (sdk/kaos/test-dot). The computer's side is tools/factory/test_dot_final.py in the KodeOS repository. Both change in the same KodeOS release. The line grammar, the terminators and the error codes are those of internals/console-protocol, and the rows a run asks for are on internals/production-test.

How it is connected

sequenceDiagram
autonumber
participant PC as Station computer
participant K as Kode Dot
PC->>K: info, test_dot_info
K-->>PC: serial, versions, test_dot state
PC->>K: test_dot_screen phase=connecting
PC->>K: test_dot_place
K-->>PC: place records, location blob
PC->>K: test component=all
K-->>PC: rows, camera records, blobs, ok
loop until poll state=done
  PC->>K: test_dot_poll
  K-->>PC: operator steps, rows, poll
  PC->>K: pads, NFC, RFID, radio
end
PC->>K: test_dot_result verdict=pass
K-->>PC: ok after the factory reset
PC->>K: test_dot_photos, test_dot_lock

One session

The computer opens the port once and keeps it open from test_dot_place to test_dot_lock. Opening the port resets the board, and what a run keeps (the PASS screen, the ship countdown) lives in RAM, so a second open would drop it. A run that must stop sends test_dot_end, or closes the port and lets the next open start from a boot.

The station's program

The program is tools/factory/test_dot_final.py, with its page in tools/factory/ui/. It identifies the Kode Dot, places it under the camera, runs the rows, does its own part (the rear pads, NFC, RFID, the radio) beside the operator, judges, tells the Kode Dot the verdict, saves the photos, locks a PASS and writes the report. It refuses a kodeOS that answers test_dot_info with code 1, and writes nothing for it.

Specifications

The rules of the wire

The order of a run

The computer waits at step 6 until the Kode Dot says the run is done, with a budget of 300 s. The Kode Dot's own watchdog for the run is 240 s. A bench run sends test_dot_end where a PASS sends the lock. The unit is unplugged at the end: 15 s after the cable leaves, a unit that passed switches off. A cable put back during the count cancels the count and nothing else. The Kode Dot stays armed, and the next unplug counts 15 s again.

The waits

Every verb that can take long has three bounds, and each sits above the one before. The Kode Dot's bound is the longest it waits for an owner. The console's line is the longest it keeps the verb open. The computer's wait is the longest it listens. The order guarantees that the Kode Dot's own answer, a timeout included, reaches the computer before either of the others gives up.

The line is the reset's bound plus 5 s (KODE_TEST_DOT_LINE_MS), and the computer adds 5 s to each Kode Dot bound. The station's program holds a copy of each bound under the name KODE_*_S, and a test of the program checks every copy against kqp_config.h in the SDK.

The verbs

The records of the open line

test component=all prints these before its >ok, in the order the run reaches them. A record the run reaches later goes into the ring and arrives through test_dot_poll with the same text.

<w> is pass, fail or noverdict. A noverdict means the Kode Dot could not measure, and the computer reports it as NO VERDICT, not as a failure.

The records of the ring

The buttons are asked for 20 s each, with 3 s to let go. A wrong button is forgiven twice, and the third wrong press gives the test up. A double press is asked again once and then fails the step. AO_Buttons and AO_Touch write these records, with buttons_test_record() and touch_test_record(), and the console prints the same text for test component=buttons and test component=tp. The touch targets are at (80, 215) and (335, 285) of the 410 x 502 glass, 20 s each, within 64 px, and a tap off the target is forgiven twice.

test_dot_poll answers the ring in order, then poll dropped=<n> when newer records pushed older ones out of its 64 places, then:

The records of the other verbs

Blobs and photos

A blob is a JPEG that crosses the wire as records. It is sent as one header and a run of data records, with no end marker. The receiver counts len.

The names a pass keeps are location (the marks photo, 352 x 256), colours (a strip of five 96 x 64 crops: red, green, blue, white, grey), dead_<x>_<y> and on_<x>_<y> (64 px crops of a defect) and zone_<x0>_<y0> (a 128 x 96 crop), eight at most. location arrives after the placement and again after the first camera step. The camera part lends colours and the crops after its verdict. test_dot_blob asks again for location or colours.

test_dot_photos names a photo photo_<NN>_<what> where NN is its number from 1 and what is the pattern: place, black_marks, panel_off, white, grey, red, green, blue, led_off, led_red, led_green or led_blue. A pass keeps 14 at most. The computer checks length and CRC and asks again with only= for one that arrived short or wrong. The photos and blobs of a pass live until test_dot_end or a reset, and a PASS does not free them.

The refusals

Gotchas

Example code

Run the whole program against a fake Kode Dot, with no board and no station.

1. Run python3 tools/factory/ui/test_dot_sim.py --case pass. The program speaks this contract to the fake Kode Dot: placement, rows, camera, operator steps, pads, radio, verdict, photos and lock.
2. Read the last line: PASS with the time and the path of report.html. Open it to see the steps and the pictures.
3. Run it again with --case fail. The last line reads FAIL and the report names the step.
4. With a Kode Dot built with the option and the cable in, run python3 tools/kcli.py -p PORT --settle 5 cmd 'test_dot_info'. The answer is the test_dot record and >ok.

In the SDK

• test_dot_verbs.c: the verbs, their keys and the blob writer.
• test_dot_ao.c: the records of every verb and the order of a run.
• test_dot_cam.c: the camera part's records.
• tools/factory: the station's program, its page, its simulator and ui/EVENTS.md, the events it prints for the page.