Repository Setup

• [X] Create components/ and establish the first submodules
• [X] Add docs/ structure for hardware, protocol, build, and recovery notes
• [X] Decide initial local code layout (cmd/badgesnake, internal/, examples/microblocks)
• [X] Add a scripts/ directory for setup, flashing, and demo launch tooling

Product Definition

• [X] Write a short BadgeSnake product spec based on Battlesnake rules defaults
• [X] Define player count and supported connection methods
• [X] Define turn timing, board size, and failure behavior
• [X] Decide whether the game is fully Battlesnake-compatible or a local variant
• [X] Define what must be visible on the ePaper, RGB LED, buzzer, and 7-segment displays

Hardware Integration

• [X] Document BeagleBadge connectors used for Zepto players
• [X] Choose the Zepto transport layer: I2C, UART, SPI, or mixed
• [X] Define hot-plug and disconnect behavior
• [ ] Define power budget and connector limits for multiple attached Zeptos
• [ ] Capture display, LED, buzzer, and segment-display interface notes with control paths
• [X] Enable BeagleBadge J6/J7 I2C controllers in the device tree and verify they appear as Linux adapters
• [ ] Document Grove connector Linux line names and add a pinmux control path for switching Grove signals between UART, I2C, and GPIO roles

Host Runtime

• [X] Choose implementation language for the BadgeSnake host runtime
• [~] Build a local simulation mode that runs without attached hardware
• [~] Make the MicroBlocks IDE usable on BeagleBadge through a web-hosted path
• [X] Complete one successful end-to-end MicroBlocks web build and launch smoke test on BeagleBadge
• [ ] Add a kernel-visible I2C simulation path so Linux controller tools can issue real bus transactions against the simulator
• [ ] Choose and implement the kernel-visible simulation mechanism; i2c-stub is not sufficient for dynamic Boardie target behavior
• [ ] Add AM62L i2c-omap slave-mode support and validate it with slave-testunit
• [ ] Design and implement a serial-to-I2C endpoint bridge kernel driver for BadgeSnake
• [ ] Define the userspace endpoint ABI exposed by the bridge driver
• [X] Stage Armbian kernel config changes for I2C_SLAVE_TESTUNIT and I2C_SLAVE_EEPROM
• [X] Add a concrete slave-testunit bring-up guide and helper script
• [X] Add an exact x86 Docker host wrapper for the BeagleBadge vendor-edge kernel build
• [X] Add initial host-runtime code skeleton for protocol and in-memory transport
• [ ] Implement player registration and health monitoring
• [ ] Implement the game loop and deterministic move resolution
• [ ] Implement ePaper rendering pipeline
• [ ] Implement status indicators and audible feedback
• [ ] Add structured logging for gameplay and device events
• [X] Add a badge-launcher IIO sensor visualizer demo for the on-board light sensor, on-board accelerometer, and QWIIC OPT3001

Zepto Firmware Track

• [X] Select the first Zepto SDK/examples repo to import as a submodule
• [X] Define the protocol between BeagleBadge and Zepto boards
• [ ] Provide a minimal reference snake implementation
• [~] Add a MicroBlocks simulation path for I2C target handling
• [ ] Provide a failure-test firmware image that behaves badly on purpose
• [ ] Document classroom-friendly firmware update steps
• [X] Build and verify bb-imager-cli with zepto_i2c support on-device
• [X] Confirm which BeagleBadge I2C bus exposes a Zepto in MSPM0 BSL mode
• [X] Add a first native Zepto PlatformIO project and build blink
• [ ] Flash the first PlatformIO blink image successfully through MSPM0 I2C BSL
• [ ] Diagnose the current bb-imager-cli MSPM0 flash failure after BSL handshake succeeds
• [ ] Identify the Linux GPIO mapping and current pinmux state for Grove pin 1 (BSL) and pin 2 (RST) so Zepto bootloader entry can be automated

Build And Test

• [X] Add a host-side smoke test for the game engine
• [X] Add protocol tests with recorded fixtures
• [~] Add a Zephyr native_sim I2C-emulation transport test lane for host-only protocol validation
• [X] Add a hardware bring-up checklist for a fresh board
• [X] Add a demo-start script that validates prerequisites before launch
• [X] Add a release checklist for live classroom/demo use
• [X] Add a fixture validator for protocol inputs

Bootloader And Reliability

• [X] Record current boot flow and storage map in a dedicated recovery doc
• [ ] Configure /etc/fw_env.config for OSPI environment access using the derived candidate layout
• [ ] Verify fw_printenv and fw_setenv against both env copies after environment format is validated
• [X] Identify the correct bootloader source and artifact provenance
• [ ] Create a safe OSPI flashing procedure from Linux
• [ ] Test booting from OSPI without relying on microSD loader stages
• [ ] Define a good-boot marker and boot-attempt counter
• [ ] Add automatic rollback for failed system updates
• [ ] Add a systemd-based post-update reboot validation flow
• [ ] Test failure cases: bad DTB, bad kernel, bad rootfs, interrupted update
• [ ] Document full recovery from a non-booting OSPI image
• [X] Add repo-managed reboot helpers for repeated kernel iteration
• [X] Make the boot workspace service resume the latest local Codex session when possible

Immediate Next Actions

• [X] Decide the first set of upstream repos to add under components/
• [X] Add a recovery/boot documentation file with real commands, offsets, and serial-console expectations
• [X] Determine whether current /boot/tiboot3.bin, tispl.bin, and u-boot.img are the intended production boot artifacts
• [X] Confirm how BeagleBadge currently reaches serial console during recovery work
• [X] Pick the host runtime language and the initial simulation target
• [X] Run and capture one successful components/battlesnake-rules simulated CLI game on-device
• [ ] Decide whether the current Armbian kernel packaging should grow i2c-stub support or whether BadgeSnake testing should stay on sim:// until real Zepto devices are attached
• [X] Configure a default Rust toolchain for local bb-imager-rs builds
• [X] Reboot with the QWIIC I2C overlay enabled and verify new Linux adapters appear for J6/J7
• [X] Verify the Zepto in BSL mode ACKs at 0x48 on the correct QWIIC bus
• [~] Build bb-imager-cli with zepto_i2c and enumerate/flash the live Zepto over /dev/i2c-1
• [X] Review docs/ZeptoPlatformIO.md
• [X] Add a board-state preservation capture process before any fresh microSD image work
• [X] Run scripts/capture_beaglebadge_state.sh on the live board and copy the resulting archive off-board
• [X] Run scripts/build_beaglebadge_vendor_edge_kernel_x86_docker.sh on an x86 Docker host
• [X] Reinstall the returned vendor-edge-k3 kernel artifacts on BeagleBadge and reboot into the rebuilt kernel
• [ ] Rebuild the BeagleBadge vendor-edge-k3 kernel artifacts after restoring the missing K3 I2C slave config lines
• [~] Reinstall the corrected vendor-edge-k3 kernel artifacts on BeagleBadge and reboot again
• [X] Reinstall the corrected vendor-edge-k3 kernel artifacts on BeagleBadge
• [X] Restore the local QWIIC overlay after the DTB package refresh
• [X] Reboot into the corrected kernel+overlay state
• [X] Rebuild and install a kernel whose host build log shows the archive/k3-6.12 AM62L slave patch series applied
• [X] Reboot into the newly installed P5507 AM62L slave-test kernel and rerun slave-testunit binding checks
• [X] Verify i2c-slave-testunit is present after reboot
• [X] Prove that new_device can instantiate a slave-testunit node on J6 / i2c-1
• [X] Add enough AM62L i2c-omap slave registration support for slave-testunit to bind on J6 / i2c-1
• [ ] Diagnose why forced same-adapter transactions to bound slave-testunit on J6 currently time out
• [X] Rebuild and install the AM62L i2c-omap slave TX underflow/FIFO follow-up kernel
• [X] Reboot into the newly installed P024c AM62L slave-test kernel and rerun forced-read validation
• [X] Rebuild and install the AM62L 1-byte slave FIFO threshold follow-up kernel
• [X] Reboot into the pinned P9d8b 4-patch kernel
• [X] Re-test i2ctransfer -f -y 1 r1@0x30 after the 1-byte slave FIFO threshold follow-up kernel boots
• [X] Stage instrumentation for the first live AM62L slave transaction status path on J6 / i2c-1
• [X] Build and install the 5-patch AM62L diagnostic kernel
• [ ] Reboot into the 5-patch AM62L diagnostic kernel
• [X] Capture the initial i2c-omap slave status logs from J6 / i2c-1 during a failing read
• [ ] Rebuild the 6-patch ISR-branch diagnostic kernel after the corrected 0006 patch payload is in place
• [X] Locally preflight drivers/i2c/busses/i2c-omap.o on the BeagleBadge against the corrected six-patch source
• [X] Build and install the 6-patch ISR-branch diagnostic kernel
• [ ] Reboot into the 6-patch ISR-branch diagnostic kernel
• [X] Capture the first ISR-branch diagnostic result on J6
• [X] Build and install the 7-patch slave-lifetime diagnostic kernel
• [X] Reboot into the 7-patch slave-lifetime diagnostic kernel
• [X] Capture the first Pb92b self-read result on J6
• [X] Stage own-address and register-state diagnostics for same-adapter self-read and self-write on J6
• [ ] Build and install the 8-patch own-address diagnostic kernel
• [X] Reboot into the 8-patch own-address diagnostic kernel
• [X] Capture OA / SA / IE state for same-adapter self-read and self-write on J6
• [X] Stage a follow-up for stale master I2C_CON state leaking into slave listen mode
• [X] Build and install the 9-patch slave-listen cleanup kernel
• [X] Reboot into the 9-patch slave-listen cleanup kernel
• [X] Re-test same-adapter self-read and self-write on J6 after clearing master-only I2C_CON state
• [X] Validate J6 target mode with a true second controller or external initiator
• [X] Add a repeatable J7-to-J6 target-mode validation harness
• [ ] Make J7->J6 repeated-start / partial-command slave-testunit feature checks pass
• [X] Stage a repeated-start follow-up that defers I2C_SLAVE_STOP until the bus is idle
• [X] Build and install the 10-patch repeated-start follow-up kernel
• [X] Reboot into the 10-patch repeated-start follow-up kernel
• [X] Re-run scripts/validate_j7_to_j6_testunit_features.sh
• [X] Narrow the remaining repeated-start failure to repeated I2C_SLAVE_WRITE_REQUESTED callbacks on J6
• [X] Stage an 11-patch follow-up that tracks write transaction lifetime across RRDY bytes
• [X] Build and install the 11-patch write-transaction-state follow-up kernel
• [X] Reboot into the 11-patch write-transaction-state follow-up kernel
• [X] Fix the slave-testunit bring-up helper to tolerate an already-present bound node
• [X] Prove that GET_VERSION_WITH_REP_START now works on J7 -> J6
• [X] Re-run scripts/validate_j7_to_j6_testunit_features.sh
• [X] Narrow the remaining proc-call failure to the initial combined XUDF|XRDY slave TX condition
• [X] Stage a 12-patch follow-up that handles combined slave TX slots explicitly
• [X] Fix the empty 0012 Armbian patch payload after the first 12-patch host build failure
• [X] Build and install the 12-patch combined-slave-TX follow-up kernel
• [X] Reboot into the 12-patch combined-slave-TX follow-up kernel
• [X] Re-run scripts/validate_j7_to_j6_testunit_features.sh
• [X] Stage a 13-patch diagnostic follow-up to trace slave TX callback/value sequence
• [X] Build and install the 13-patch slave-TX-trace follow-up kernel
• [X] Reboot into the 13-patch slave-TX-trace follow-up kernel
• [X] Capture slave tx-requested / slave tx-processed logs during the proc-call tests
• [X] Prove that J6 already generates 0x04 0x03 0x02 0x01 during the proc-call read phase
• [X] Narrow the remaining proc-call gap to first-byte handling at repeated-start read address match
• [X] Stage a 14-patch follow-up that primes the first slave TX byte on read address match
• [X] Build and install the 14-patch first-byte-priming follow-up kernel
• [X] Reboot into the 14-patch first-byte-priming follow-up kernel
• [X] Re-run scripts/validate_j7_to_j6_testunit_features.sh
• [X] Prove that plain AAS-time priming fires but does not change the visible proc-call response
• [X] Add a true userspace SMBus block-proc-call probe for J7 -> J6
• [X] Prove that /dev/i2c-3 does not currently advertise I2C_FUNC_SMBUS_BLOCK_PROC_CALL
• [X] Decide that the next fix should target master-side SMBus/I2C_M_RECV_LEN capability
• [X] Stage a 15-patch follow-up that adds OMAP master-side I2C_M_RECV_LEN support
• [X] Build and copy back the 15-patch SMBus recv-len follow-up kernel
• [X] Install and reboot into the 15-patch SMBus recv-len follow-up kernel
• [X] Re-run ./scripts/test_j7_to_j6_smbus_block_proc_call.sh
• [X] Prove that J7 functionality bits changed after the 15-patch kernel
• [X] Prove that true SMBus block-proc-call is no longer blocked at the adapter capability check
• [X] Debug the new I2C_M_RECV_LEN path enough to isolate the repeated-first-byte / IRQ-loop failure mode
• [ ] Build and copy back the 16-patch recv-len IRQ-pacing follow-up kernel
• [ ] Install and reboot into the 16-patch recv-len IRQ-pacing follow-up kernel
• [X] Re-test raw I2C_RDWR|I2C_M_RECV_LEN and true SMBus block-proc-call on J7 -> J6
• [X] Capture the P641a regression mode: IRQ-work storm followed by NULL dereference in omap_i2c_transmit_data
• [ ] Diagnose why the 16-patch recv-len follow-up reaches omap_i2c_transmit_data with invalid state during a receive transaction
• [X] Stage a narrower fix for the P641a recv-len regression that guards against stale TX status
• [X] Copy back the rebuilt kernel artifacts for the narrower recv-len follow-up
• [X] Identify that the latest distinct 16-patch artifact is now P3659
• [X] Install and reboot into P3659
• [X] Re-test direct I2C_RDWR|I2C_M_RECV_LEN and true SMBus block-proc-call after the narrower stale-TX-status follow-up
• [X] Prove that the stale-TX-status guard removes the P641a IRQ-thread crash/oops
• [ ] Diagnose why P3659 still returns 0x04 0x00 0x00 0x00 0x00 / 0x00 0x00 0x00 0x00 instead of the expected proc-call payload
• [X] Identify the newer distinct 16-patch rebuilds after P3659
• [ ] Install and reboot into the newest copied 16-patch artifact (Pa309)
• [X] Install and reboot into the newest copied 16-patch artifact (Pa309)
• [X] Re-test SMBus block-proc-call and direct I2C_RDWR|I2C_M_RECV_LEN on Pa309
• [X] Prove that Pa309 still matches the P3659 zero-after-count-byte behavior
• [ ] Diagnose why the J7 master-side recv-len path still exposes only the count byte and zeros even though J6 generates non-zero payload bytes
• [X] Prove that the latest copied build after Pa309 was only a cached Pa309 re-version, not a new install target
• [ ] Ensure the next x86-host Armbian build actually consumes the newer f0fe74e4 / f051e986 submodule state before copying artifacts back
• [X] Ensure the next x86-host Armbian build actually consumes the newer f0fe74e4 / f051e986 submodule state before copying artifacts back
• [X] Identify the first distinct build from that newer state (P5248)
• [X] Install and reboot into P5248
• [X] Re-test SMBus block-proc-call and direct I2C_RDWR|I2C_M_RECV_LEN on P5248
• [X] Prove that P5248 still matches the P3659 / Pa309 zero-after-count-byte behavior
• [X] Keep the boot-session systemd unit installed but disabled by default on BeagleBadge
• [X] Encode the next live BeagleBadge validation request in docs/BeagleBadgeRequests.md
• [X] Build and copy back a distinct kernel artifact from recv-len payload tracing state (a140e1d / 4d98c2f)
• [X] Install and reboot into the recv-len payload tracing artifact
• [X] Capture dmesg | grep 'recv-len' after direct I2C_RDWR|I2C_M_RECV_LEN
• [X] Classify whether J7 skips payload RX, reads zeros from DATA_REG, or copies non-zero payload bytes that are lost later
• [X] Prove that the P7f58 payload-tracing kernel falls into the DATA_REG zeros case
• [X] Stage a recv-len no-CNT-rewrite experiment in i2c-omap
• [X] Encode the no-CNT-rewrite BeagleBadge validation request in docs/BeagleBadgeRequests.md
• [X] Build and copy back a distinct kernel artifact from no-CNT-rewrite state (e2cf5df / 3d54c59)
• [X] Install and reboot into the no-CNT-rewrite artifact
• [X] Re-test SMBus block-proc-call and direct I2C_RDWR|I2C_M_RECV_LEN on the no-CNT-rewrite artifact
• [X] Capture whether J7 receives non-zero payload bytes when CNT is not rewritten after the recv-len count byte
• [X] Prove that Pac0a restores non-zero payload bytes on true SMBus block-proc-call and direct recv-len
• [X] Clean the successful recv-len no-CNT-rewrite patch to remove temporary successful-path diagnostics
• [X] Regenerate the Armbian 0016 patch from the cleaned kernel source
• [X] Encode the cleaned recv-len smoke-test request in docs/BeagleBadgeRequests.md
• [X] Build and copy back a distinct kernel artifact from the cleaned recv-len state (3c92960 / e49bac3)
• [X] Install and reboot into the cleaned recv-len artifact
• [X] Re-test true SMBus block-proc-call and direct I2C_RDWR|I2C_M_RECV_LEN on the cleaned artifact
• [X] Confirm the cleaned artifact keeps the Pac0a payload fix without the temporary successful-path recv-len logs
• [ ] Diagnose why the raw i2ctransfer surrogate still reports 0x00 0x04 0x03 0x02 0x01 even after the no-CNT-rewrite fix
• [X] Document that P5910 validates a controlled multi-controller transaction path, not a fully proven multi-master arbitration transport
• [X] Encode the next badge-only J6/J7 role-reversal and dual-listener validation request
• [X] Validate the reverse topology with J7 as slave-testunit target and J6 as initiator
• [X] Validate a two-address J6/J7 setup with both adapters target-capable on the shared bus
• [X] Decide whether to move from badge-only validation to BeagleConnect Zepto testing
• [X] Diagnose why J6-as-initiator reverse topology fails with Input/output error and target-side Transmit underflow
• [X] Diagnose why a second active listener on the shorted J6/J7 bus causes both initiation directions to fail with Transmit underflow
• [X] Stage a role IRQ-mask follow-up for adapters that act as both target and initiator
• [X] Mirror the role IRQ-mask follow-up into the Armbian k3-6.12 patch stack as 0017
• [X] Encode the role IRQ-mask BeagleBadge validation request in docs/BeagleBadgeRequests.md
• [ ] Build and copy back a distinct kernel artifact from the role IRQ-mask state (ef2ef02 / 4fb8430)
• [X] Detect that the first copied rebuild after the role IRQ-mask request was still stale P5910
• [X] Install and reboot into the role IRQ-mask artifact
• [X] Re-test clean reverse topology with only J7 hosting slave-testunit
• [X] Re-test dual-listener J6/J7 setup after the role IRQ-mask patch
• [X] Decide whether the badge-only boundary is clear enough to connect one Zepto
• [ ] Diagnose why the raw reverse-topology surrogate now returns 0x00 0x00 0x04 0x03 0x02 even though true SMBus succeeds
• [X] Diagnose why the dual-listener setup still triggers Transmit underflow in both directions even after the role IRQ-mask patch
• [X] Stage an IRQENABLE clear follow-up for IP-v2 set/clear interrupt-enable semantics
• [X] Mirror the IRQENABLE clear follow-up into the Armbian k3-6.12 patch stack as 0018
• [X] Encode the IRQENABLE clear BeagleBadge validation request in docs/BeagleBadgeRequests.md
• [X] Build and copy back a distinct kernel artifact from the IRQENABLE clear state (eb09330 / b17e72e)
• [X] Install and reboot into the IRQENABLE clear artifact
• [X] Re-test the dual-listener J6/J7 setup after clearing IRQ enables before role-mask writes
• [X] Decide whether the badge-only boundary is clear enough to connect one Zepto after the IRQENABLE clear test
• [X] Prove that the stale ie=0x661f role bits disappear on the IRQENABLE clear kernel
• [X] Prove that reverse-topology true SMBus still works after the IRQENABLE clear patch
• [X] Prepare a concise TI E2E question now that stale role bits are gone but dual-listener timeouts remain
• [X] Add a BeagleBadge reproduction helper for the TI E2E dual-listener timeout report
• [X] Run scripts/reproduce_omap_i2c_dual_listener_timeout.sh on BeagleBadge and preserve its output for the TI E2E post
• [ ] Post the prepared AM62L OMAP I2C dual-listener timeout question to TI E2E
• [ ] Add a clearer runtime kernel/build identity marker than current uname / re-versioned package naming
• [ ] Diagnose the combined AAS|ARDY|XUDF|XRDY read-start condition on J6
• [ ] Decide whether to keep a same-adapter self-test path or switch validation to J7/external-initiator only
• [X] Mirror the staged AM62L i2c-omap slave-support change into the Armbian archive/k3-6.12 kernel patchset