Skip to content

Running the self tests

Fin edited this page Nov 14, 2026 · 2 revisions

Running the self-tests

You can test everything without a radio, a console or any key material.

python3 tuxchange/sp_relay.py selftest      # the daemon, the store, the control socket
python3 tuxchange/sp_link.py --selftest     # the handshake, the crypto, the frame builders
python3 tuxchange/sp_link.py --simulate     # a whole exchange through the state machine
python3 tuxchange/sp_build.py --selftest    # building a message from nothing
python3 tools/sp_selftest.py                # the end-to-end pipeline, synthetic

Running the full suite against your own data

Some checks are regressions against real hardware: a captured console frame that must be reproduced byte for byte, a real message that must parse. That data is a recording of specific consoles, carrying their identifiers and the Mii names of everyone they met, so it is not in the repository. Point Tuxchange at your own.

Where a corpus lives

The first match wins:

  1. $TUXCHANGE_CORPUS (may be several paths, separated like $PATH)
  2. ~/.config/tuxchange/corpus/
  3. ./tests/corpus/ (git-ignored)

manifest.json

Maps the logical names the tests ask for onto your filenames. Without it, a logical name is tried as a filename directly.

{
  "plaza_message":       "cecmsg_aabbccddeeff_to_112233445566_5.bin",
  "plaza_object_0":      "cecmsg_aabbccddeeff_to_112233445566_0.bin",
  "plaza_object_1":      "cecmsg_aabbccddeeff_to_112233445566_1.bin",
  "plaza_object_2":      "cecmsg_aabbccddeeff_to_112233445566_2.bin",
  "plaza_object_3":      "cecmsg_aabbccddeeff_to_112233445566_3.bin",
  "plaza_object_4":      "cecmsg_aabbccddeeff_to_112233445566_4.bin",
  "mii_message_a":       "cecmsg_aabbccddeeff_to_112233445566_5.bin",
  "mii_message_b":       "cecmsg_112233445566_to_aabbccddeeff_5.bin",
  "plaza_outbox":        "harvested/00020800_outbox_xxxxxxxxxx.bin",
  "second_title_outbox": "harvested/00030600_outbox_xxxxxxxxxx.bin",
  "console_nand":        "partitionA.bin",
  "console_nand_2":      "second_console_partitionA.bin",
  "console_nand_3":      "third_partitionA.bin"
}

Directory-shaped entries (harvested/, harvested_new/) are globbed relative to the corpus directory.

vectors.json

The numeric regression vectors: a real handshake, and what the messages should decode to.

{
  "handshake": {
    "console_mac":   "96:58:cb:aa:bb:cc",
    "console_token": "0011223344556677",
    "our_mac":       "ba:ae:6e:dd:ee:ff",
    "our_token":     "8899aabbccddeeff",
    "synack_seq":    95,
    "synack":        "08402c00...<the captured encrypted frame, hex>..."
  },
  "mii_messages": {
    "mii_message_a": {"mii_name": "...", "creator_mac": "b8:ae:6e:11:22:33"},
    "mii_message_b": {"mii_name": "...", "creator_mac": "94:58:cb:44:55:66"}
  }
}

With handshake present, --simulate replays a real captured exchange. Without it, the console's reply is built locally with a throwaway key and every step still runs: probe parse, token capture, key derivation, CCMP decrypt, YY parse, state machine.

Check what is found

python3 tuxchange/lp_corpus.py

What CI runs

The no-keys, no-corpus case, on Python 3.10 through 3.13, with no pip install at all. If a clone with only the standard library stops working, CI fails.

Keep your corpus out of git

tests/corpus/ is in .gitignore. CI fails the build if a capture or dump file type, a key file, or a bare 64-digit hex value is tracked anywhere in the repository. Do not defeat that with git add -f.

Clone this wiki locally