CrossVi runs on real hardware, so debugging usually combines local build checks and on-device logs.
For layout and interaction work without hardware, use the X3/X4 desktop UI simulator. It runs the production renderer and Activities with clickable controls and exact model-specific framebuffer dimensions.
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
python3 scripts/test_simulator.pyDo not use PlatformIO upload for the first CrossVi installation. Use the Web
Flasher procedure in the README
and require Validate partition table to pass first; PlatformIO's ESP32 upload
target also writes the bootloader, partition table and otadata helper.
For a Developer Edition device whose matching partition layout and recovery path have already been verified, flash a development build with:
pio run --target uploadOpen serial monitor:
pio device monitorOptional enhanced monitor:
python3 -m pip install pyserial colorama matplotlib
python3 scripts/debugging_monitor.py- Firmware version and build environment
- Exact steps to reproduce
- Expected vs actual behavior
- Serial logs from boot through failure
- Whether the issue reproduces after using the firmware's book-cache command or moving aside only the affected book's generated
sections/directory (after an SD-card backup)