Compass app for M5Stack CardputerZero.
- Show compass heading with animated dial
- Show pitch/roll bubble level overlay
- Expand live accelerometer, gyroscope, and magnetometer values
- Calibrate hard-iron and cross-axis magnetic distortion with full 3D rotation
- Save and load calibration data between launches within the same device boot
- Require calibration on first use and confirm when calibration is saved
- On devices without a magnetometer, show an optional entry notice, a tilt bubble, and live six-axis data
Run the bootstrap script once after cloning this repository:
./bootstrap.shIt creates .venv/, installs the Python build tools, fetches dependencies from
repos.json, and keeps all third-party source under dependencies/.
System packages expected by the build:
- CMake and a C/C++ compiler
- SDL2 development files for
COMPASS_USE_SDL=ON python3-venvsobootstrap.shcan create.venv/aarch64-linux-gnu-gcc/g++for cross-building the CardputerZero package
On macOS, install the desktop build tools with Homebrew:
brew install cmake pkg-config sdl2macOS supports the SDL desktop build only. Device framebuffer and Debian packaging are Linux/CardputerZero targets.
Project dependencies pulled from repos.json:
lvglspdlogsmooth_ui_toolkit
Image asset conversion runs during build and uses LVGL's Python converter. If the converter dependencies are missing, install them in your Python environment:
./.venv/bin/python -m pip install pypng lz4 PillowFont conversion is not part of the normal build. If fonts are regenerated with
src/assets/convert_fonts.py, install lv_font_conv separately and keep it
available in PATH.
For Linux SDL testing:
cmake -S . -B build/sdl -DCOMPASS_USE_SDL=ON
cmake --build build/sdl -j8For macOS SDL testing:
cmake -S . -B build/macos-sdl -DCOMPASS_USE_SDL=ON
cmake --build build/macos-sdl -j8For CardputerZero framebuffer build:
cmake -S . -B build/cp0 -DCOMPASS_USE_SDL=OFF
cmake --build build/cp0 -j8For cross build from x86 Linux with the GNU aarch64 toolchain:
cmake -S . -B build/cp0 \
-DCOMPASS_USE_SDL=OFF \
-DCMAKE_TOOLCHAIN_FILE=cmake/aarch64-linux-gnu.cmake
cmake --build build/cp0 -j8The output binary is dist/M5CardputerZero-Compass.
Run the SDL build:
./dist/M5CardputerZero-CompassCalibration data is saved to /tmp/Compass/calibration.conf by default for both
SDL and CardputerZero builds. Launches within the same device boot reuse this
data. When the device reboots and /tmp is cleared, calibration is required again.
On devices with a working magnetometer, if no valid saved calibration exists,
a required-calibration dialog appears.
Press Enter to start, then rotate the device through every direction, away from
metal and magnets. Calibration must pass the quality checks and be saved before
entering the compass. Esc exits the app during this required flow.
The completion dialog confirms that calibration was saved; press Enter to return
to the compass. Later launches reuse the saved calibration until temporary data
is cleared.
Devices without a magnetometer skip calibration and show Compass not supported
as an entry notice. Press 7 or Space to toggle Don't show again,
then 8 or Enter to continue; Esc also dismisses the notice.
The main view reuses the original tilt bubble, crosshairs, and sensor panels.
Without a magnetometer, the original bubble, crosshairs, and travel are enlarged
to 1.5 times their compass size.
The original bottom-right 8 button expands/collapses the six-axis data; the
two remaining sensor groups are vertically centered in the existing data area.
The compass dial, cardinal directions, magnetic channels, and calibration controls
are hidden. A magnetic read failure also preserves live six-axis data, and the magnetometer is retried every 5 seconds. Once it recovers, normal
compass operation resumes, requiring calibration if no valid calibration is saved.
If the six-axis sensor itself is unavailable, the sensor-error screen is shown.
The entry-notice preference persists across launches and reboots at
$XDG_CONFIG_HOME/Compass/skip-six-axis-notice, or
~/.config/Compass/skip-six-axis-notice if XDG_CONFIG_HOME is unset.
Set COMPASS_PREFERENCES_PATH to override the preference file for development.
Delete that file to show the notice again. This preference is separate from the
temporary magnetic calibration data.
During calibration, coverage and captured sample count are shown below the progress
bar. The first automatic check runs after 20 seconds; unsuccessful checks retry
every 2 seconds while capture continues. Enter also attempts to finish and save.
Turn the device over and rotate around all three axes when prompted. Sensor
failures and magnetic interference have separate messages. Coverage is a motion
indicator, not a countdown to completion.
Override the calibration path for development (a persistent path keeps data across reboots):
COMPASS_CALIBRATION_PATH=./calibration.conf ./dist/M5CardputerZero-CompassPreview a device without a magnetometer using the SDL build:
COMPASS_MOCK_NO_MAGNETOMETER=1 ./dist/M5CardputerZero-CompassKey controls:
- Compass page:
8expand/collapse sensor info,KEY_HELPopen help (Hon SDL), holdEscto exit - Help overlay:
KEY_HELPorH(SDL) orEscclose - Expanded info:
7open calibration,8collapse sensor info - Calibration page:
6or Enter starts/saves calibration; Enter returns after success - Calibration page:
4or Esc goes back for optional calibration; Esc exits during required calibration
Build the cp0/CardputerZero Debian package:
./packaging/deb/package_deb.shThe package script is device-targeted only. It always configures the framebuffer
build and produces an arm64 APPLaunch package.
The generated package is written to dist/:
dist/m5cardputerzero-compass_1.0.1_m5stack1_arm64.deb
- Continue the release version from
v1.0.0; the CMake/package version is now1.0.1. - Keep real accelerometer and gyroscope data available on devices without BMM150.
- Show a dismissible entry notice with a persistent don't-show-again option.
- Reuse the original animated tilt bubble and sensor panels, hiding compass-only elements.
- Preserve six-axis readings when magnetic reads fail, and retry magnetic detection automatically.