Offline maps on ESP32, over LVGL 9.x. Tiles come off an SD card, GPS coordinates turn into screen positions, and nothing needs a network or an API key.
v2 adds turn-by-turn navigation: a route drawn on the map, a marker that follows it, and the next turn - still entirely offline.
One component, two APIs. v2.0.0 added the navigation layer; it changed no
function, no struct and no behaviour in map_tiles.h. Every v1 project builds
untouched against v2.0.0 — the major version marks the new surface, not a break.
Nothing forces a choice either: both headers can be used in one firmware, and
they share the tile format and the SD card layout.
v1 API — map_tiles.h |
v2 API — the navigation layer | |
|---|---|---|
| Headers | map_tiles.h |
map_view.h, map_route.h, map_tile_cache.h, map_geo.h |
| Added in | 1.0.0 | 2.0.0 |
| Shape | a fixed grid of lv_image widgets, one per tile |
one map_view widget that draws every tile itself |
| View centre | integer tile index | continuous world-pixel coordinate |
| Panning | 256 px jumps when the grid re-anchors | smooth, with fling momentum |
| Tile loading | the whole grid, synchronously, on the UI thread | per tile, LRU cached, on a background task |
| A cache miss | blocks until the SD card answers | draws a placeholder and queues a read |
| Position | a marker you place yourself | a GPS fix snapped onto a route |
| Routes | — | polyline with per-zoom detail, map matching, turn instructions |
| Off route | — | detected, with the distance and direction back |
| Memory | one buffer per grid slot, all resident | a bounded LRU, 128 KB per slot |
| Built for | a map you drag by hand | a map that keeps up with a moving vehicle |
| Read | Usage below | Navigation layer (v2) below |
Pick v1 when you want a map to look at: a viewer, a tracker, a position on a screen. Pick v2 when something is moving and the map has to keep up with it.
v2.0.0 (September 25, 2026)
- New navigation layer, added alongside the existing API - nothing was changed or removed.
map_geo- Web Mercator, haversine, bearings, point-to-segment projectionmap_route- offlineroute.binloading, per-zoom level of detail, map matching, turn instructionsmap_tile_cache- LRU tile cache with a background loader task, so the UI thread never blocks on the SD cardmap_view- a continuous-coordinate LVGL widget that draws tiles, route and marker itself
- Major version because the component now carries two rendering paths, not because anything broke. The v1 API is unchanged, source-compatible, and still the right answer for a map you pan by hand.
- See Navigation layer (v2) below.
v1.3.0 (December 20, 2025)
- Fixed critical marker positioning bugs in example code:
- Bug Fix #1: Corrected
map_display_add_marker()to calculate position from actual GPS coordinates instead of using stored offset - Bug Fix #2: Added scroll position compensation for scrollable map containers
- Markers now appear at correct GPS locations regardless of map center position, zoom level, or scroll position
- Bug Fix #1: Corrected
- Enhanced debug logging with detailed marker calculation information
- Added bounds checking for marker positions with warnings
- LVGL 9.x Compatible: Fully compatible with LVGL 9.x image handling
- GPS Coordinate Conversion: Convert GPS coordinates to tile coordinates and vice versa
- Dynamic Tile Loading: Load map tiles on demand from file system
- Configurable Grid Size: Support for different grid sizes (3x3, 5x5, 7x7, etc.)
- Multiple Tile Types: Support for up to 8 different tile types (street, satellite, terrain, hybrid, etc.)
- Memory Efficient: Configurable memory allocation (SPIRAM or regular RAM)
- Multiple Zoom Levels: Support for different map zoom levels
- Error Handling: Comprehensive error handling and logging
- C API: Clean C API for easy integration
v2 adds:
- Smooth Panning: Continuous world-pixel view centre, drag with fling momentum - no 256 px jumps
- Non-blocking Tiles: LRU cache fed by a background task, so the UI thread never waits on the SD card
- Offline Routes:
route.bingeometry with per-zoom level of detail, map matching and turn instructions - Follow Mode: Eased follow-the-vehicle with a configurable marker offset
- ESP-IDF 5.0 or later
- LVGL 9.3
- File system support (FAT/SPIFFS/LittleFS)
- Map tiles in binary format (RGB565, 256x256 pixels)
PSRAM: optional for v1, in practice required for v2. A decoded tile is
128 KB, and the navigation layer keeps a cache of them - 25 slots for a 466 px
view, 48 for a 720 px one, which is 3 to 6 MB. The v1 grid can be shrunk to fit
internal RAM; the v2 cache cannot. The targets list in idf_component.yml
covers the component as a whole, so it includes chips that can run v1 happily
and have nowhere to put a v2 tile cache.
You can easily add this component to your project using the idf.py command or by manually updating your idf_component.yml file.
From your project's root directory, simply run the following command in your terminal:
idf.py add-dependency "0015/map_tiles^2.0.0"This command will automatically add the component to your idf_component.yml file and download the required files the next time you build your project.
Add to your project's main/idf_component.yml:
dependencies:
map_tiles:
git: "https://github.com/0015/map_tiles.git"
version: "^2.0.0"- Copy the
map_tilesfolder to your project'scomponentsdirectory - The component will be automatically included in your build
The rest of this page documents the v1 API (
map_tiles.h), which is unchanged in v2.0.0. For routes and navigation, jump to Navigation layer (v2).
#include "map_tiles.h"
// Configure the map tiles with multiple tile types and custom grid size
const char* tile_folders[] = {"street_map", "satellite", "terrain", "hybrid"};
map_tiles_config_t config = {
.base_path = "/sdcard", // Base path to tile storage
.tile_folders = {tile_folders[0], tile_folders[1], tile_folders[2], tile_folders[3]},
.tile_type_count = 4, // Number of tile types
.default_zoom = 10, // Default zoom level
.use_spiram = true, // Use SPIRAM if available
.default_tile_type = 0, // Start with street map (index 0)
.grid_cols = 5, // Grid width (tiles)
.grid_rows = 5 // Grid height (tiles)
};
// Initialize map tiles
map_tiles_handle_t map_handle = map_tiles_init(&config);
if (!map_handle) {
ESP_LOGE(TAG, "Failed to initialize map tiles");
return;
}// Set center position from GPS coordinates
map_tiles_set_center_from_gps(map_handle, 37.7749, -122.4194); // San Francisco
// Get grid dimensions
int grid_cols, grid_rows;
map_tiles_get_grid_size(map_handle, &grid_cols, &grid_rows);
int tile_count = map_tiles_get_tile_count(map_handle);
// Load tiles for the configured grid size
for (int row = 0; row < grid_rows; row++) {
for (int col = 0; col < grid_cols; col++) {
int index = row * grid_cols + col;
int tile_x, tile_y;
map_tiles_get_position(map_handle, &tile_x, &tile_y);
bool loaded = map_tiles_load_tile(map_handle, index,
tile_x + col, tile_y + row);
if (!loaded) {
ESP_LOGW(TAG, "Failed to load tile %d", index);
}
}
}// Get grid dimensions and tile count
int grid_cols, grid_rows;
map_tiles_get_grid_size(map_handle, &grid_cols, &grid_rows);
int tile_count = map_tiles_get_tile_count(map_handle);
// Create image widgets for each tile
lv_obj_t** tile_images = malloc(tile_count * sizeof(lv_obj_t*));
for (int i = 0; i < tile_count; i++) {
tile_images[i] = lv_image_create(parent_container);
// Get the tile image descriptor
lv_image_dsc_t* img_dsc = map_tiles_get_image(map_handle, i);
if (img_dsc) {
lv_image_set_src(tile_images[i], img_dsc);
// Position the tile in the grid
int row = i / grid_cols;
int col = i % grid_cols;
lv_obj_set_pos(tile_images[i],
col * MAP_TILES_TILE_SIZE,
row * MAP_TILES_TILE_SIZE);
}
}// Switch to different tile types
map_tiles_set_tile_type(map_handle, 0); // Street map
map_tiles_set_tile_type(map_handle, 1); // Satellite
map_tiles_set_tile_type(map_handle, 2); // Terrain
map_tiles_set_tile_type(map_handle, 3); // Hybrid
// Get current tile type
int current_type = map_tiles_get_tile_type(map_handle);
// Get available tile types
int type_count = map_tiles_get_tile_type_count(map_handle);
for (int i = 0; i < type_count; i++) {
const char* folder = map_tiles_get_tile_type_folder(map_handle, i);
printf("Tile type %d: %s\n", i, folder);
}// Convert GPS to tile coordinates
double tile_x, tile_y;
map_tiles_gps_to_tile_xy(map_handle, 37.7749, -122.4194, &tile_x, &tile_y);
// Check if GPS position is within current tile grid
bool within_tiles = map_tiles_is_gps_within_tiles(map_handle, 37.7749, -122.4194);
// Get marker offset for precise positioning
int offset_x, offset_y;
map_tiles_get_marker_offset(map_handle, &offset_x, &offset_y);// Clean up when done
map_tiles_cleanup(map_handle);The component expects map tiles in a specific binary format:
- File Structure:
{base_path}/{map_tile}/{zoom}/{tile_x}/{tile_y}.bin - Format: 12-byte header + raw RGB565 pixel data
- Size: 256x256 pixels
- Color Format: RGB565 (16-bit per pixel)
/sdcard/
├── street_map/ // Tile type 0
│ ├── 10/
│ │ ├── 164/
│ │ │ ├── 395.bin
│ │ │ ├── 396.bin
│ │ │ └── ...
│ │ └── ...
│ └── ...
├── satellite/ // Tile type 1
│ ├── 10/
│ │ ├── 164/
│ │ │ ├── 395.bin
│ │ │ └── ...
│ │ └── ...
│ └── ...
├── terrain/ // Tile type 2
│ └── ...
└── hybrid/ // Tile type 3
└── ...
| Parameter | Type | Description | Default |
|---|---|---|---|
base_path |
const char* |
Base directory for tile storage | Required |
tile_folders |
const char*[] |
Array of folder names for different tile types | Required |
tile_type_count |
int |
Number of tile types (max 8) | Required |
default_zoom |
int |
Initial zoom level | Required |
use_spiram |
bool |
Use SPIRAM for tile buffers | false |
default_tile_type |
int |
Initial tile type index | Required |
grid_cols |
int |
Number of tile columns (max 10) | 5 |
grid_rows |
int |
Number of tile rows (max 10) | 5 |
map_tiles_init()- Initialize map tiles systemmap_tiles_cleanup()- Clean up resources
map_tiles_load_tile()- Load a specific tilemap_tiles_get_image()- Get LVGL image descriptormap_tiles_get_buffer()- Get raw tile buffer
map_tiles_get_grid_size()- Get current grid dimensionsmap_tiles_get_tile_count()- Get total number of tiles in grid
map_tiles_gps_to_tile_xy()- Convert GPS to tile coordinatesmap_tiles_set_center_from_gps()- Set center from GPSmap_tiles_is_gps_within_tiles()- Check if GPS is within current tiles
map_tiles_get_position()- Get current tile positionmap_tiles_set_position()- Set tile positionmap_tiles_get_marker_offset()- Get marker offsetmap_tiles_set_marker_offset()- Set marker offset
map_tiles_set_tile_type()- Set active tile typemap_tiles_get_tile_type()- Get current tile typemap_tiles_get_tile_type_count()- Get number of available typesmap_tiles_get_tile_type_folder()- Get folder name for a type
map_tiles_set_zoom()- Set zoom levelmap_tiles_get_zoom()- Get current zoom level
map_tiles_set_loading_error()- Set error statemap_tiles_has_loading_error()- Check error state
Everything above this line is the v1 API and is unchanged in v2.0.0.
The v1 API loads a fixed grid of tiles anchored to an integer tile coordinate. That is the right shape for a map you drag by hand. It is the wrong shape for navigation, where the map has to keep up with a moving position: crossing a tile boundary means reloading the whole grid, synchronously, on the UI thread.
v2.0.0 adds a second path built for that case. It is purely additive - the headers, functions and behaviour described above are unchanged.
| Header | What it gives you |
|---|---|
map_geo.h |
Web Mercator conversions, haversine distance, bearings, point-to-segment projection, distance and duration formatting. No LVGL, no ESP-IDF. |
map_route.h |
Load route.bin, walk it at a level of detail suited to the current zoom, snap a GPS fix onto it, and find the next turn. |
map_tile_cache.h |
An LRU cache of decoded tiles fed by a background FreeRTOS task. A miss returns NULL immediately and queues a read; it never blocks. |
map_view.h |
One LVGL object that renders tiles, the route and the position marker, centred on a floating-point world-pixel coordinate. Drag to pan with momentum, or let it follow the vehicle. |
#include "map_view.h"
#include "map_route.h"
map_route_handle_t route = map_route_load("/sdcard/route.bin", true);
lv_obj_t *map = map_view_create(lv_screen_active());
lv_obj_set_size(map, 720, 720);
map_view_set_tile_source(map, "/sdcard", "tiles1", 48, true);
map_view_set_zoom_range(map, 12, 19);
map_view_set_zoom(map, 17);
map_view_set_route(map, route);
map_view_set_follow(map, true);
map_view_set_follow_offset(map, 120); // put the marker below centre
// then, on every GPS fix:
map_route_match_t m;
map_route_match(route, lat, lon, 35.0, &m);
map_view_set_position(map, lat, lon, heading, true);
map_view_set_progress(map, m.traveled_m);
map_view_set_off_route(map, !m.on_route);
map_view_set_return_target(map, m.return_lat, m.return_lon, !m.on_route);map_view raises LV_EVENT_VALUE_CHANGED whenever the user drags the map and
follow mode releases, so the app can offer a re-centre button.
map_route_match() is the whole per-fix step. Everything a navigation screen
shows comes out of this one struct:
| Field | |
|---|---|
on_route, cross_track_m |
whether the fix is on the road, and how far off it is |
snapped_lat/lon, route_bearing_deg |
the fix projected onto the route |
traveled_m, remaining_m |
progress along the current lap |
next_maneuver, dist_to_maneuver_m |
index into the turn list, and how far to it |
arrived |
inside the arrival radius; never set on a loop |
lapped |
this fix crossed the start line of a loop |
return_lat/lon, return_bearing_deg |
the nearest point on the route, and the bearing to it |
Progress freezes while you are off route, deliberately. A route that doubles
back or loops passes within metres of itself, so letting an off-route fix pick
the globally nearest segment can snap you onto the leg you rode an hour ago and
make the distance remaining lurch by kilometres. traveled_m and remaining_m
are therefore reported from the last fix that was genuinely on the road.
map_view_set_return_target() draws a dashed tether from the marker to the
nearest point on the route and, when that point is off screen, an arrow at the
edge pointing at it. Pass the match's return_lat / return_lon and
!on_route.
Which way that is, said the way a person can act on it, is
map_geo_angle_diff_deg(heading, m.return_bearing_deg): a signed angle
relative to where the rider is facing, so the UI can say "to your left" rather
than "bearing 274".
The route file says which it is; there is nothing to switch on the device.
MAP_ROUTE_KIND_DRIVE |
MAP_ROUTE_KIND_EXERCISE |
|
|---|---|---|
| Reaching the end | arrived is set |
counts a lap and carries on |
| What the app shows | remaining, ETA | distance covered, elapsed |
A closed circuit - one whose last point is its first - reports
map_route_is_loop(). Matching wraps across that seam, so crossing the start
line continues onto the next lap instead of running off the end of the array,
and match.lapped fires once each time round.
Counting laps is harder than it looks: standing on the start line you are equally close to the first segment and the last, so successive fixes flip between "just started" and "nearly done". A lap is therefore only counted when the circuit has actually been ridden - start, middle, end, start - which wobble at the line can never fake.
A corridor download covers a few zoom levels and nothing else. Asking the view for any other zoom is not an error anywhere in the stack: the cache reports a miss, the view draws a placeholder, and the result looks like a broken map rather than a missing download.
map_tile_cache_probe_zooms() reads the folder and says what is really there,
so an app can clamp itself to it at start-up:
int lo = 0, hi = 0;
if (map_tile_cache_probe_zooms("/sdcard", "tiles1", &lo, &hi) > 0) {
map_view_set_zoom_range(map, lo, hi);
}map_view is an LVGL widget and every map_view_* call needs the LVGL lock,
like any other. map_tile_cache_get() must be called from the LVGL thread -
it is the only place slots are allocated or evicted, which is what lets the
loader task read tiles without a lock.
The loader task is the only thread of its own the component starts, and it touches nothing but the slot it was handed. Hand fixes to the LVGL thread rather than calling into the view from a GPS callback.
| Tile cache | 128 KB per slot. A 466x466 view draws at most 3x3 tiles and warms the ring around them, so 28 slots (3.5 MB) covers it; a 720x720 view wants 48 (6 MB). |
| Route | 16 bytes per point plus 20 per turn. A 10,000-point route is about 160 KB. |
| Widgets | one, rather than one per tile. |
Both the cache and the route allocate from SPIRAM when you ask them to.
Produced on a PC by the navigation packager in
OfflineMapDownloader
(app_nav.py), or from a GPX with route_format.py. Fixed-size little-endian
records, so the device reads the arrays straight into PSRAM and uses them in
place - no XML or JSON parsing, and no per-point allocation.
Each point carries a min_zoom byte: the lowest zoom at which that vertex still
has to be drawn. Rendering at zoom Z is one filtered pass over the array, which
is what keeps a 10,000-point route cheap to draw when zoomed out. The exact
layout is documented at the top of include/map_route.h; route_format.py is
the writer for the same contract.
Geometry (map_geo.h)
map_geo_lon_to_world_px()/map_geo_lat_to_world_py()and their inversesmap_geo_world_size_px(),map_geo_meters_per_pixel()map_geo_distance_m(),map_geo_bearing_deg()map_geo_normalize_deg(),map_geo_angle_diff_deg()- the signed difference that turns a bearing into "to your left"map_geo_point_segment_dist_m()- projection onto a segmentmap_geo_format_distance(),map_geo_format_duration()
Routes (map_route.h)
map_route_load()/map_route_free()map_route_peek()- read a route file's header into amap_route_info_twithout loading its geometry, so a card holding many routes can be listed cheaplymap_route_get_name(),map_route_get_total_distance_m(),map_route_get_total_duration_s()map_route_is_loop(),map_route_get_kind(),map_route_get_tile_folder()map_route_get_point_count(),map_route_get_point()map_route_get_maneuver_count(),map_route_get_maneuver()map_route_get_start(),map_route_get_destination(),map_route_get_bounds()map_route_next_lod_point()- walk the polyline at a given zoommap_route_match()- snap a fix onto the route, with a windowed searchmap_route_reset_match(),map_route_set_search_window(),map_route_set_arrival_radius()map_maneuver_type_name(),map_maneuver_type_symbol()
Tile cache (map_tile_cache.h)
map_tile_cache_create()/map_tile_cache_destroy()map_tile_cache_begin_frame(),map_tile_cache_get(),map_tile_cache_prefetch()map_tile_cache_get_version()- poll to know when to repaintmap_tile_cache_set_folder(),map_tile_cache_clear(),map_tile_cache_get_stats()map_tile_cache_probe_zooms()- which zoom levels the card actually holds
Map view (map_view.h)
map_view_create(),map_view_set_tile_source(),map_view_set_tile_folder(),map_view_get_tile_cache()map_view_set_zoom(),map_view_get_zoom(),map_view_set_zoom_range(),map_view_zoom_in/out()map_view_set_center(),map_view_get_center(),map_view_fit_bounds()map_view_set_route(),map_view_set_progress()map_view_set_position(),map_view_set_off_route(),map_view_set_return_target()- the tether back to the roadmap_view_set_follow(),map_view_get_follow(),map_view_set_follow_offset()map_view_set_style(),map_view_get_style(),map_view_set_debug_overlay()map_view_screen_to_latlon(),map_view_latlon_to_screen()
The v2/ folder of
the examples repository: full turn-by-turn navigation on a battery-powered
466x466 round AMOLED. It includes a route simulator, so you can exercise the
whole guidance path - turns, off-route alerts, laps - without a GPS fix or
leaving your desk.
v1
- Memory Usage: Each tile uses ~128KB (256×256×2 bytes)
- Grid Size: Larger grids use more memory (3x3=9 tiles, 5x5=25 tiles, 7x7=49 tiles)
- SPIRAM: Recommended for ESP32-S3 with PSRAM for better performance
- File System: Ensure adequate file system performance for tile loading
- Tile Caching: Component maintains tile buffers until cleanup
v2
- Cache size is not a free choice.
map_viewonly warms the ring around the visible tiles when the cache can hold the ring and the screen. Below that it silently stops prefetching, and panning starts showing placeholders. - The SD card is off the UI thread, but it is still the limit: a cache miss costs a placeholder for as long as the read takes.
- Route drawing is one filtered pass over the point array, so a 10,000-point route costs what its level of detail at the current zoom costs, not what the whole route costs.
- Rendering is software. At 466x466 the whole frame is about 217,000 pixels; a chip with 2D acceleration or a faster PSRAM bus will hold a higher frame rate than one without.
map_tiles_projects holds the complete, buildable projects, split by which API they use:
| Project | What it shows | |
|---|---|---|
| v1 | v1/01.Simple_Map |
Interactive map viewer: touch, zoom, manual coordinate entry. Three boards. |
| v1 | v1/02.ESP32-S3_Map_LoRa_GPS |
Live GPS tracking with positions shared over LoRa. |
| v2 | v2/01.Navigation_ESP32-S3-Touch-AMOLED-1.75 |
Turn-by-turn navigation on a battery-powered 466x466 round AMOLED, 1.75 inch. |
The examples/ directory in this repository holds one short snippet per API:
basic_map_display.c
for v1, and
navigation_minimal.c
for v2 — loading a route, following it, and turning each fix into a turn
instruction, in one file.
This component is released under the MIT License. See LICENSE file for details.
Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.
For questions and support, please open an issue on the GitHub repository.