Add CPU/MCU interface contract draft

[xbattlax]

Summary

Adds a new I/O board software-interface contribution area and an xbattlax draft contract that connects the recent hardware/spec work to the ROS2 and firmware work.

This includes:

• a versioned CPU/MCU serial framing proposal with watchdog and safety behavior
• ROS2 bridge mapping for cmd_vel, odometry, battery, diagnostics, bumper/cliff/wheel-drop, e-stop, and dock IR homing
• a bringup and validation plan from codec tests to STM32 dev board, I/O board bench, rolling base, cleaning-load tests, and dock/IR simulation
• a hardware/software decision ledger for the current integration gaps: micro-ROS vs custom serial, wheel connector reconciliation, LiDAR UART ownership, bumper sensor naming, side-brush quantity, fan driver behavior, dock-contact semantics, dock IR sensors, and obstacle camera ownership
• a docking/IR requirements note based on maintainer feedback from oomwoo-io-board#1
• a dependency-free Python reference codec, deterministic MCU frame generator, and unit tests
• links from the main module table, architecture, software interfaces, io-pcb RFC, and compute-benchmark notes

Review Follow-Up

Updated after maintainer feedback on July 19, 2026:

• rebased on current main
• removed the dock-cycle RFC edit because main now has the IR-homing design there
• removed the part-specs/OsakaTX edit to avoid touching another contributor's namespace
• kept the ARCHITECTURE, SOFTWARE_INTERFACES, and io-pcb changes as draft/proposed interface notes

This PR is deliberately framed as a draft integration contract, not final firmware or final PCB layout.

Verification

• python3 -m unittest discover -s contributions/io-board-interface/xbattlax/tests -p 'test_*.py'
• python3 contributions/io-board-interface/xbattlax/tools/sim_mcu.py --count 2
• git diff --check origin/main...HEAD

[xbattlax]

Follow-up commit e569a92 incorporates maintainer feedback from oomwoo-io-board#1:

• records Pi 4 2 GB as a provisional measured baseline to reproduce, with the live-MCU/dock/camera caveat still explicit
• adds dock/IR/camera requirements: 130 degree front obstacle camera, Gazebo dock IR emitter, front left/right IR homing sensors with baffle, left/right dock-search sensors, Nav2 predock pose, non-Nav2 final approach, and undocking
• links those requirements into dock-cycle, SOFTWARE_INTERFACES.md, and the CPU/MCU bridge draft

Verification:

• python3 -m unittest discover -s contributions/io-board-interface/xbattlax/tests -p 'test_*.py'
• python3 contributions/io-board-interface/xbattlax/tools/sim_mcu.py --count 2
• git diff --check

[xbattlax]

Thanks, fixed.

I rebased oomwoo#27 on current main and force-pushed with --force-with-lease.

Review follow-up:

• removed the dock-cycle RFC edit, since main now has the IR-homing design there
• removed the part-specs/OsakaTX edit, so the PR no longer touches another contributor's namespace
• kept ARCHITECTURE, SOFTWARE_INTERFACES, and io-pcb as draft/proposed interface notes
• left the new io-board-interface module and the xbattlax namespaced contract in place

Current head: 1d6482f

Verification:

• python3 -m unittest discover -s contributions/io-board-interface/xbattlax/tests -p 'test_*.py'
• python3 contributions/io-board-interface/xbattlax/tools/sim_mcu.py --count 2
• git diff --check origin/main...HEAD