Testing and Debugging
CrossInk runs on real hardware, so debugging usually combines local build checks, simulator checks, and on-device logs.
Local checks
Make sure clang-format 21+ is installed and available in PATH before running the formatting step. If needed, see Getting Started.
./bin/clang-format-fix
pio check --fail-on-defect low --fail-on-defect medium --fail-on-defect high
pio run -e simulator
pio run -e default
pio run without -e builds the release matrix from platformio.ini (teensy, tiny, xlarge, and no_emoji). Use it before opening broad firmware PRs, but prefer explicit environments while iterating.
Flash and monitor
Flash firmware:
pio run -e default --target upload
Open serial monitor:
pio device monitor
Optional enhanced monitor:
python3 -m pip install pyserial colorama matplotlib
python3 scripts/debugging_monitor.py
Useful bug report contents
- Firmware version and build environment
- Exact steps to reproduce
- Expected vs actual behavior
- Serial logs from boot through failure
- Whether issue reproduces after clearing the affected book cache or using Clear Reading Cache