Skip to content

README.md

Latest commit

 

History

History
129 lines (88 loc) · 3.04 KB

README.md

File metadata and controls

129 lines (88 loc) · 3.04 KB
Raw

CardputerZero Compass

Compass app for M5Stack CardputerZero.

Features

  • 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

Dependencies

Run the bootstrap script once after cloning this repository:

./bootstrap.sh

It 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-venv so bootstrap.sh can 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 sdl2

macOS supports the SDL desktop build only. Device framebuffer and Debian packaging are Linux/CardputerZero targets.

Project dependencies pulled from repos.json:

  • lvgl
  • spdlog
  • smooth_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 Pillow

Font 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.

Build

For Linux SDL testing:

cmake -S . -B build/sdl -DCOMPASS_USE_SDL=ON
cmake --build build/sdl -j8

For macOS SDL testing:

cmake -S . -B build/macos-sdl -DCOMPASS_USE_SDL=ON
cmake --build build/macos-sdl -j8

For CardputerZero framebuffer build:

cmake -S . -B build/cp0 -DCOMPASS_USE_SDL=OFF
cmake --build build/cp0 -j8

For 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 -j8

The output binary is dist/M5CardputerZero-Compass.

Usage

Run the SDL build:

./dist/M5CardputerZero-Compass

Calibration data is saved to calibration.conf for SDL builds. Packaged CardputerZero launches use $HOME/.config/Compass/calibration.conf by default.

Override the calibration path:

COMPASS_CALIBRATION_PATH=./calibration.conf ./dist/M5CardputerZero-Compass

Key controls:

  • Compass page: 8 expand/collapse sensor info, Esc exit
  • Expanded info: 7 open calibration, 8 collapse sensor info
  • Calibration page: 6 or Enter start/save calibration, 4 or Esc back

Package

Build the cp0/CardputerZero Debian package:

./packaging/deb/package_deb.sh

The 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_0.1.1_m5stack1_arm64.deb