View on GitHub
MiniNav

Build from source

For changing WiFi names and passwords or other options, or working on the code. Just want MiniNav on the board? Use the one-click flasher instead.

1Install the tools

ESP-IDF 5.4 (Espressif's official SDK). One time only, about 15 minutes.

  1. Install the command-line tools (git, compilers): 
    xcode-select --install
  2. Get ESP-IDF v5.4.2 and install it for the ESP32-S3: 
    mkdir -p ~/esp && cd ~/esp
git clone -b v5.4.2 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf && ./install.sh esp32s3
  3. Every new terminal: load the tools with 
    . ~/esp/esp-idf/export.sh
  1. Install prerequisites (Debian/Ubuntu): 
    sudo apt install git wget flex bison gperf python3 python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0
  2. Get ESP-IDF v5.4.2: 
    mkdir -p ~/esp && cd ~/esp
git clone -b v5.4.2 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf && ./install.sh esp32s3
  3. Allow your user to use the serial port: 
    sudo usermod -aG dialout $USER   # then log out and back in
  4. Every new terminal: 
    . ~/esp/esp-idf/export.sh
  1. Download the ESP-IDF Windows Installer from Espressif (docs.espressif.com, "Get Started", Windows) and pick version v5.4.2.
  2. Run it with the defaults. It installs Git, Python and the toolchain.
  3. Open the ESP-IDF 5.4 PowerShell shortcut it creates. All commands below run there.

2Build and flash

The board flashes over its USB-C port, no buttons needed in most cases.

  1. Get the MiniNav source and the display library: 
    git clone https://github.com/MiniNavDevice/MiniNav.git
cd MiniNav
tools/fetch_lovyangfx.sh        # downloads LovyanGFX 1.2.32 into components/
    On Windows run the two commands inside tools/fetch_lovyangfx.sh by hand.
  2. Optional: change WiFi names and passwords or other options: 
    idf.py menuconfig               # → "MiniNav (Android Auto minimap)"
    Defaults: board WiFi MiniNav / mininav123, phone hotspot MiniNavHotspot / mininav123, right-hand drive. Pick your own passwords if others could be near your bike or car.
  3. Build: 
    idf.py build
    The first build takes a few minutes.
  4. Plug the board into the computer and find its port:
    SystemPort looks likeFind it with
    macOS/dev/cu.usbmodem101ls /dev/cu.usbmodem*
    Linux/dev/ttyACM0ls /dev/ttyACM*
    WindowsCOM5Device Manager → Ports
  5. Flash (use your port): 
    idf.py -p /dev/cu.usbmodem101 -b 921600 flash
  6. The board restarts by itself. You see the boot animation, then the connection screen.
If flashing can't connectHold BOOT, tap RESET, release BOOT, then flash again.
Watch the log (optional)idf.py -p <port> monitor shows what the board is doing; quit with Ctrl+]. While the map plays it prints a [perf] line with the frame rate every 10 s.

3Next steps

The board now shows its connection screen. Carry on with the main guide: set up the phone, connect and ride or drive.