Skip to content
BranchesTags

Repository files navigation

Static Badge master devel ViewCount

IceNav logo

ESP32 Based GPS Navigator (LVGL - LovyanGFX).

IceNav concept design
Conceptual design — not final hardware.
  • Note: Under development (experimental features under devel branch)
  • There is the possibility to use two types of maps: Rendered Maps or Tiles (large files), and Vector Maps (small files).
  • Recommended to use an ESP32-S3 or ESP32-P4 with PSRAM and a screen with a parallel bus for optimal performance, although SPI screens also yield good results.
Don't forget to star ⭐️ this repository
buymeacoffee-animated-badge

Screenshots
See more...
Splash Screen Search Satellite Compass1 Main Options Waypoint/Track Options
Rendered Map Vectorized Map Navigation Screen Navigation Screen Satellite Info
NMEA Debug Add Waypoint Waypoint List Track List 3D Map view
GPS Logger GPS Logger Climb Analyzer
Settings Compass Calibration Touch Calibration Map Settings
Device Settings Sensor Info

LilyGo T-DECK
Compass Rendered Map Waypoint on Map
Navigation Screen Edit Waypoint Satellite Info

WiFi CLI Manager

Web File Server

Specifications

Currently, IceNav works with the following hardware setups and specs

Highly recommended an ESP32S3 or ESP32P4 with PSRAM and 320x480 Screen

Important

Please review the platformio.ini file to choose the appropriate environment as well as the different build flags for your correct setup. Support for ESP32-S2 is discontinued due to IRAM issues.

Boards

FLASH PSRAM Environment 2 Full Support
ICENAV (Custom ESP32S3) 16M 8M [env:ICENAV_BOARD] ✔️ YES
ESP32S3 16M 8M [env:ESP32S3_N16R8] ✔️ YES
ELECROW ESP32 Terminal 16M 8M [env:ELECROW_ESP32] ✔️ YES 3
MAKERFABS ESP32S3 16M 2M [env:MAKERF_ESP32S3] 🚧 TESTING
LILYGO T-DECK 16M 8M [env:TDECK_ESP32S3] ✔️ YES
LILYGO T-DECK PLUS 16M 8M [env:TDECK_ESP32S3] 🚧 TESTING
LILYGO T4-S3 16M 8M [env:T4_S3] ✔️ YES
WAVESHARE ESP32-P4-WIFI6 3.5inch Smart Vision 16M 32M [env:WAVESHARE_P4_35] ✔️ YES
WAVESHARE ESP32-P4-WIFI6 4.3inch Development Board 32M 32M [env:WAVESHARE_P4_43] ✔️ YES

Important

Known Issue: ESP32-P4 + ESP32-C6 — Reboots with SD + WiFi On boards that pair an ESP32-P4 with an ESP32-C6 co-processor (e.g. WAVESHARE_P4_43), enabling WiFi while an SD card is mounted via SDMMC can cause intermittent crashes or reboots. The backtrace typically shows sdio_read → xRingbufferCreateStatic. Root cause: The SDMMC peripheral is shared between the SD card slot and the C6 SDIO link. The ESP-Hosted MCU firmware does not properly serialise concurrent access, leading to a corrupted ring buffer allocation and a system panic. This is a known ESP-Hosted firmware bug, tracked upstream at espressif/esp-hosted-mcu#144 and #184. Espressif has acknowledged it; a fix is expected in a future release. Workaround: Disable WiFi via CLI Settings

If the board has a BOOT button it is possible to use power saving functions. To do this, simply include the following Build Flags in the required env in platformio.ini

-DPOWER_SAVE
-DINVERT_BOOT_PIN (if the button signal is inverted, e.g. Waveshare P4 boards)

Important

Currently, this project can run on any board with an ESP32S3 and at least a 320x480 TFT screen. The idea is to support all existing boards on the market that I can get to work, so if you don't want to use the specific IceNav board, please feel free to create an issue, and I will look into providing support. Any help or contribution is always welcome

Screens

Driver 2 Resolution SPI 8bit 16bit Touch Build Flags 4
ILI9488 5 320x480 ✔️ ➖ ➖ XPT2046 -DILI9488_XPT2046_SPI
ILI9488 320x480 ✔️ ➖ ➖ FT5x06 -DILI9488_FT5x06_SPI
ILI9488 320x480 ➖ ✔️ ➖ ➖ -DILI9488_NOTOUCH_8B
ILI9488 320x480 ➖ ➖ ✔️ FT5x06 -DILI9488_FT5x06_16B
ILI9341 320x240 ✔️ ➖ ➖ XPT2046 -DILI9341_XPT2046_SPI
ILI9341 320x240 ✔️ ➖ ➖ ➖ -DILI9341_NOTOUCH_SPI

Important

If you are using a TFT with SPI shared bus, for example with an SD card, you need to add the following buildflag: -DSPI_SHARED

Modules

Type Build Flags 4
🔋 Batt. Monitor -DBATT_ADC_UNIT=n (1 or 2)
-DBATT_ADC_CHANNEL=x
-DBATT_DIVIDER_R1=n (default 100000)
-DBATT_DIVIDER_R2=n (default 100000)
AT6558D 🛰️ GPS -DAT6558D_GPS
HMC5883L / QMC5883 🧭 Compass (auto-detected) -DCOMPASS_AUTO
MPU9250 🧭 IMU (Compass) -DIMU_MPU9250
BME280 🌡️ Temp
☁️ Pres
💧 Hum		 -DBME280
MPU6050 📳 IMU -DMPU6050

Other setups like another sensors types, etc... not listed in the specs, now They are not included

If you wish to add any other type of sensor, module, etc., you can create a PR without any problem, and we will try to implement it. Thank you!

IMU Accelerometer Axis Configuration

When using an IMU for tilt-compensated heading (-DMPU6050 or -DIMU_MPU9250), the physical mounting orientation must be configured via build flags.

Flag Default Description
-DIMU_ACCEL_X_SIGN 1 Sign applied to raw ax (+1 or -1)
-DIMU_ACCEL_Y_SIGN 1 Sign applied to raw ay (+1 or -1)
-DIMU_ACCEL_Z_SIGN 1 Sign applied to raw az (+1 or -1)

The correct value for each axis depends on how the IMU is physically mounted. If tilting the device causes the heading to drift instead of remaining stable, invert the sign of the affected axis.

These flags can be set either in the board definition JSON (boards/*.json) under extra_flags, or in platformio.ini under build_flags for the target environment.

Wiring

See hal.hpp for pinouts configuration

SD Card File Structure

IceNav reads every map, route, track and waypoint from the SD card. The SD Card File Structure document describes the folder layout of each data type — rendered tiles, vectorized maps, A* routes, GPX tracks and waypoints — and how to generate the map and route files.

Mass Copy Script for Map Tiles

For efficient transfer of millions of map tiles to SD cards or external storage devices, IceNav includes a high-performance mass copy script. This script is optimized for copying large numbers of small files (such as map tiles) and can reduce transfer time from hours to minutes.

Key features:

  • ✅ Optimized for millions of small files - Much faster than traditional copy methods
  • ✅ Real-time progress monitoring - See exactly what's being copied
  • ✅ Resumable transfers - Continue interrupted copies
  • ✅ Built-in integrity verification - Sample file verification
  • ✅ Performance metrics - Speed and time statistics

For detailed instructions on how to use the mass copy script, please refer to the Mass Copy Tools Documentation.

Download link: tools/mass_copy/rsync_copy.sh

Firmware install

Important

Please install first PlatformIO open source ecosystem for IoT development compatible with Arduino IDE and its command line tools (Windows, MacOs and Linux). Also, you may need to install git in your system.

For ICENAV board run:

pio run --target upload

For ESP32S3 Makerfab board:

pio run -e MAKERF_ESP32S3 --target upload

For Other boards:

pio run -e environment --target upload

After this, load the icons and assets with:

pio run --target uploadfs

Tip

Optional, firmware upgrade is possible from SD Card, please see PR #259 for detailed instructions

Tip

Optional, for map debugging with specific coordinates, or when you are in indoors, you are able to set the defaults coordinates, on two ways:

Using the CLI

Using the next commands to set your default coordinates, for instance:

klist
kset defLAT 52.5200
kset defLON 13.4049

Using enviroment variables:

Export your coordinates before to build and upload, for instance:

export ICENAV3_LAT=52.5200
export ICENAV3_LON=13.4049
pio run --target upload

Crash diagnostics

On every boot IceNav logs the reset reason (power-on, panic, watchdog, brownout...) to the serial monitor and appends it to DIAG.log in the SD card root, along with the firmware version.

If the previous session ended in a crash, the ESP32 automatically stores a core dump in a dedicated flash partition. On the next boot with an SD card present, IceNav:

  • Appends a crash summary to DIAG.log (faulting task, program counter, exception cause and backtrace).
  • Copies the full core dump to COREDUMP.elf in the SD card root.
  • Erases the flash partition, ready for the next crash.

To get a full decoded report (source file and line for each backtrace frame), analyze COREDUMP.elf on your PC with the espcoredump.py tool included with ESP-IDF/PlatformIO, using the ELF of the same firmware build (.pio/build/<environment>/firmware.elf):

espcoredump.py info_corefile -c COREDUMP.elf -t elf .pio/build/ICENAV_BOARD/firmware.elf

Tip

If there is no SD card inserted, the core dump is kept in flash (the serial monitor shows coredump stored at boot) and will be recovered on the first boot with an SD card. Alternatively it can be extracted over USB without SD card:

espcoredump.py --port /dev/ttyACM0 info_corefile .pio/build/ICENAV_BOARD/firmware.elf

CLI

IceNav has a basic CLI accessible via Serial and optionally via Telnet if enabled (port 11000). When you access the CLI and type help, you should see the following commands:

clear:          clear shell
info:           get device information
klist:          list of user preferences. ('all' param show all)
kset:           set an user extra preference
mem:            memory snapshot (heap, LVGL, stacks)
nmcli:          network manager CLI. Type nmcli help for more info
outnmea:        toggle GPS NMEA output (or Ctrl+C to stop)
poweroff:       perform a ESP32 deep sleep
reboot:         perform a ESP32 reboot
scshot:         screenshot to SD or sending a PC
webfile:        enable/disable Web file server
wipe:           wipe preferences to factory default

For more details about these commands, see CLI documentation.

Web File Server

IceNav has a small web file server (https://youtu.be/IYLcdP40cU4) to manage existing files on the SD card. An active WiFi connection is required (to do this, see how to do it using CLI).

The Web File Server will start automatically if default automatic network connection is enabled (see CLI).

To access the Web File Server, simply use any browser and go to the following address: http://icenav.local

Known issue (ESP32-P4 boards): uploading files crashes the device (assert failed: sdio_rx_get_buffer). This is a known upstream bug in the ESP-Hosted SDIO driver used for WiFi on the C6 co-processor (espressif/esp-hosted-mcu#144, #184), not fixable from this project. Two triggers confirmed: uploading a file larger than ~100KB, and uploading any file (even a few hundred bytes) into a new folder that has to be created on the SD card. Uploading into an existing folder works fine for small files. Downloading files is not affected. Track the upstream issues for a fix.

Special thanks to....

  • @hpsaturn Thanks to him and his knowledge, this project is no longer sitting in a drawer 😏.
  • @Xinyuan-LilyGO for provide me hardware to test it.
  • @waveshareteam for provide me latest ESP32P4 hardware to test it.
  • @Elecrow-RD For your interest in my project and for providing me with hardware to test it.
  • @pcbway for bringing a first prototype of the IceNav PCB to reality 💪
  • @lovyan03 for his library; I still have a lot to learn from it.
  • @lvgl for creating an amazing UI
  • And of course, to my family, who supports me through all this development and doesn’t understand why. 😘 I will never be able to thank you enough for the time I've dedicated.

Credits

Map data is available thanks to the great OpenStreetMap project and contributors. The map data is available under the Open Database License.

© OpenStreetMap contributors

Footnotes

  1. Widgets are draggable ↩

  2. See hal.hpp for pinouts configuration ↩ ↩2

  3. For ELECROW board UART port is shared with USB connection, GPS pinout are mapped to IO19 and IO40 (Analog and Digital Port). If CLI isn't used is possible to attach GPS module to UART port but for upload the firmware (change pinout at hal.hpp), the module should be disconnected. ↩

  4. platformio.ini file under the build_flags section ↩ ↩2

  5. If Touch SPI is wired to the same SPI of ILI9488 ensure that TFT MISO line has 3-STATE for screenshots (read GRAM) or leave out ↩

About

🛰️ ESP32 Based GPS Navigator with OSM offline maps. Multi GNSS

Topics

arduinocompassdiyesp32-p4esp32-s3gpsgps-navigationgps-trackerlilygolovyangfxlvglmakerfabsnmeaoffline-mapsopenstreetmaposmplatformiopsramtftwaveshare

Resources

Readme
GPL-3.0 license

Contributing

Contributing
Activity

Stars

468 stars

Watchers

11 watching

Forks

61 forks
Report repository

Releases

Packages

Used by

Contributors

Languages