ESP32 Based GPS Navigator (LVGL - LovyanGFX).

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

Don't forget to star ⭐️ this repository

Caution

Do not use in production (Experimental features).

Screenshots


Splash Screen	Search Satellite	Compass	Main Options	Waypoint Options


Rendered Map	Vectorized Map	Navigation Screen	Navigation Screen	Satellite Info


Add Waypoint	Add Waypoint (landscape)	Waypoint List


Settings	Compass Calibration	Touch Calibration	Map Settings	Device Settings

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

Boards

	FLASH	PSRAM	Environment	Full Support
ICENAV (Custom ESP32S3)	16M	8M	`[env:ICENAV_BOARD]`	✔️ YES
ESP32	16M	4M	`[env:ESP32_N16R4]`	✔️ YES
ESP32S3	16M	8M	`[env:ESP32S3_N16R8]`	✔️ YES
ELECROW ESP32 Terminal	16M	8M	`[env:ELECROW_ESP32]`	✔️ YES ¹ ²
MAKERFABS ESP32S3	16M	2M	`[env:MAKERF_ESP32S3]`	🚧 TESTING
LILYGO T-DECK	16M	8M	`[env:TDECK_ESP32S3]`	✔️ YES

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

-DPOWER_SAVE
-DARDUINO_RUNNING_CORE=1
-DARDUINO_EVENT_RUNNING_CORE=1

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 ²	Resolution	SPI	8bit	16bit	Touch	Build Flags ³
ILI9488 ⁴	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`

Modules

	Type	Build Flags ³	lib_deps ⁵ (no common environment)
	🔋 Batt. Monitor	`-DADC1` or `-DADC2` `-DBATT_PIN=ADCn_CHANNEL_x`
AT6558D	🛰️ GPS	`-DAT6558D_GPS`
HMC5883L	🧭 Compass	`-DHMC5883L`	`dfrobot/DFRobot_QMC5883@^1.0.0`
QMC5883	🧭 Compass	`-DQMC5883`	`dfrobot/DFRobot_QMC5883@^1.0.0`
MPU9250	🧭 IMU (Compass)	`-DIMU_MPU9250`	`bolderflight/Bolder Flight Systems MPU9250@^1.0.2`
BME280	🌡️ Temp ☁️ Pres 💧 Hum	`-DBME280`	`adafruit/Adafruit Unified Sensor@^1.1.14` `adafruit/Adafruit BusIO@^1.16.1` `adafruit/Adafruit BME280 Library@^2.2.4`

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!

Wiring

See hal.hpp for pinouts configuration

SD Renderized Map Tile File structure

Using Maperitive select your zone and generate your tiles. For that enter to MAP-> Set Geometry bounds draw or expand the square of your zone and run the command generate-tiles minzoom=6 maxzoom=17, It could takes long time, maybe 1 hour or more depending your area.

After that, copy the contents of directory Tiles into your SD in a directory called MAP.

On SD Card map tiles (256x256 PNG Format) should be stored, in these folders structure:

  [ 📁 MAP ]
     |________ [ 📁 zoom folder (number) ]
                          |__________________ [ 📁 tile X folder (number) ]
                                                         |_______________________ 🗺️ tile Y file.png

SD Vectorized Map File structure

Using OSM_Extract you can generate binary map files to later create vector maps. Once generated, these files should be saved in the mymap folder on the SD card.

The PBF files can be downloaded from the geofabrik website.

The PBF files should be saved in the pbf directory. Once saved, you should select the region or boundaries for which the GeoJSON files will be generated.

To obtain the boundaries use osmconvert file.pbf --out-statistics:

lon min: -5.5203154
lon max: 11.7825360
lat min: 35.2703341
lat max: 44.4078541

or use Bboxfinder website drawing a box on desired area.

For generate GeoJSON files run inside scripts directory:

min_lon=123
min_lat=123
max_lon=123
max_lat=123

./pbf_to_geojson.sh $min_lon $min_lat $max_lon $max_lat /pbf/clipped.pbf /maps/test

For generate binary map files run inside scripts directory.

./extract_features.py $min_lon $min_lat $max_lon $max_lat /maps/test

Once the process is completed, the maps will be inside the maps/mymap directory. Copy all folders to the SD card except the test_imgs directory into VECTMAP folder of the SD Card.

Please follow the instructions provided by OSM_Extract for any further questions.

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 ESP32 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, 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

CLI

IceNav has a basic CLI accessible via Serial and optionally via Telnet if enabled. 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
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
settings:       device settings
waypoint:       waypoint utilities
webfile:        enable/disable Web file server
wipe:           wipe preferences to factory default

Some extra details:

klist: List user custom settings:

    KEYNAME     DEFINED         VALUE 
    =======     =======         ===== 
    defZoom     custom         
      gpsTX     custom          
      gpsRX     custom          
     defLAT     custom          
     defLON     custom           
  defBright     custom          
   VmaxBatt     custom         
   VminBatt     custom          
   tempOffs     custom

kset KEYNAME: Set user custom settings:

In order to simplify the configuration of the device (minimum and maximum battery level, default position, etc...) via CLI it is possible to specify default values for the configuration. This has been done in order to speed up the device configuration process without having to invest "time" in modifying and creating extra configuration screens in the GUI (LVGL).

Available user parameters can be obtained using the klist command with a CLI connection (either via USB connection or TELNET connection)

nmcli: IceNav use a wcli network manager library. For more details of this command and its sub commands please refer to here

outnmea: this command toggle the GPS output to the serial console. With that it will be compatible with external GPS software like PyGPSClient and others. To stop these messages in your console, just only repeat the same command or perform a CTRL+C.

scshot: This utility can save a PNG screenshot to the root of your SD, with the name: screenshot.png.

This screenshot command can send the screenshot over WiFi using the following syntax (replace IP with your PC IP):

scshot 192.168.1.10 8123

Ensure your PC has the specified port open and firewall access enabled to receive the screenshot via the netcat command, like this:

nc -l -p 8123 > screenshot.png

Additionally, you can download the screenshot with webfile server.

settings: Device settings type settings for detailed options.

waypoint: type waypoint for detailed options.

Additionally, this waypoint command can send the waypoint over WiFi using the following syntax (replace IP with your PC IP):

waypoint down file.gpx 192.168.1.10 8123

Ensure your PC has the specified port open and firewall access enabled to receive the waypoint file via the netcat command, like this:

nc -l -p 8123 > waypoint.gpx

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

TO DO

LVGL 9 Integration
Support other resolutions and TFT models
Support for ready-made boards
Wifi CLI Manager
LVGL Optimization
GPX Integration
Multiple IMU's and Compass module implementation
Power saving
Vector maps
Google Maps navigation style
Optimize code
Fix bugs!
Web file server

Special thanks to....

@hpsaturn Thanks to him and his knowledge, this project is no longer sitting in a drawer 😏.
@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

Added support to Makerfabs ESP32-S3 Parallel TFT with Touch 3.5" ILI9488 from @makerfabs thanks to @hpsaturn to test it!
Improved documentation thanks to @hpsaturn
Improved auto mainScreen selection from env variable preset thanks to @hpsaturn
Improved getLat getLon from environment variables thanks to @hpsaturn
3DPrint case for an ESP32S3 Makerfabs Parallel board thanks to @hpsaturn
Vectorial Maps routines ESP32_GPS thanks to @aresta
OSM to binary vectorial maps OSM_Extract thanks to @aresta
Preferences Library Easy Preferences thanks to @hpsaturn
Wifi CLI manager esp32-wifi-cli thanks to @hpsaturn
Web file server based in @smford esp32-asyncwebserver-fileupload-example

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

Footnotes

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. ↩
See hal.hpp for pinouts configuration ↩ ↩²
platformio.ini file under the build_flags section ↩ ↩²
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 ↩
You need to add libraries dependencies if the buid flag requires ↩

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Screenshots

WiFi CLI Manager

Web File Server

Specifications

Boards

Screens

Modules

Wiring

SD Renderized Map Tile File structure

SD Vectorized Map File structure

Firmware install

CLI

Web File Server

TO DO

Special thanks to....

Credits

Files

README.md

Latest commit

History

README.md

File metadata and controls

Screenshots

WiFi CLI Manager

Web File Server

Specifications

Boards

Screens

Modules

Wiring

SD Renderized Map Tile File structure

SD Vectorized Map File structure

Firmware install

CLI

Web File Server

TO DO

Special thanks to....

Credits

Footnotes