{"id":26281877,"url":"https://github.com/celliesprojects/openstreetmap-esp32","last_synced_at":"2025-07-04T00:05:18.627Z","repository":{"id":282406090,"uuid":"948427701","full_name":"CelliesProjects/OpenStreetMap-esp32","owner":"CelliesProjects","description":"This PlatformIO library provides a OpenStreetMap (OSM) map fetching and caching system for ESP32-based devices.","archived":false,"fork":false,"pushed_at":"2025-06-12T17:51:35.000Z","size":271,"stargazers_count":9,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-04T00:03:47.803Z","etag":null,"topics":["esp32","esp32-arduino","esp32-s2","esp32-s3","geolocation","gps","gps-location","gps-tracker","lovyangfx","map","openstreetmap","platformio-library","pngdec","psram-needed"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CelliesProjects.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-14T10:15:41.000Z","updated_at":"2025-06-12T17:48:36.000Z","dependencies_parsed_at":"2025-03-14T13:31:59.003Z","dependency_job_id":"c9cc0edf-1194-44c1-9fa6-ee7232cf00b7","html_url":"https://github.com/CelliesProjects/OpenStreetMap-esp32","commit_stats":null,"previous_names":["celliesprojects/openstreetmap-esp32"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/CelliesProjects/OpenStreetMap-esp32","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CelliesProjects%2FOpenStreetMap-esp32","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CelliesProjects%2FOpenStreetMap-esp32/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CelliesProjects%2FOpenStreetMap-esp32/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CelliesProjects%2FOpenStreetMap-esp32/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CelliesProjects","download_url":"https://codeload.github.com/CelliesProjects/OpenStreetMap-esp32/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CelliesProjects%2FOpenStreetMap-esp32/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263421911,"owners_count":23464047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp32","esp32-arduino","esp32-s2","esp32-s3","geolocation","gps","gps-location","gps-tracker","lovyangfx","map","openstreetmap","platformio-library","pngdec","psram-needed"],"created_at":"2025-03-14T16:15:37.254Z","updated_at":"2025-07-04T00:05:18.535Z","avatar_url":"https://github.com/CelliesProjects.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"## OpenStreetMap-esp32\n\n[![License](https://img.shields.io/github/license/CelliesProjects/OpenStreetMap-esp32)](https://github.com/CelliesProjects/OpenStreetMap-esp32/blob/main/LICENSE)\n[![Release](https://img.shields.io/github/v/release/CelliesProjects/OpenStreetMap-esp32)](https://github.com/CelliesProjects/OpenStreetMap-esp32/releases/latest)\n[![Issues](https://img.shields.io/github/issues/CelliesProjects/OpenStreetMap-esp32)](https://github.com/CelliesProjects/OpenStreetMap-esp32/issues)\n[![PlatformIO](https://img.shields.io/badge/PlatformIO-Compatible-green?logo=platformio)](https://registry.platformio.org/libraries/celliesprojects/openstreetmap-esp32)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/0961fc2320cd495a9411eb391d5791ca)](https://app.codacy.com/gh/CelliesProjects/OpenStreetMap-esp32/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_grade)\n\nThis PlatformIO library provides a [OpenStreetMap](https://www.openstreetmap.org/) (OSM) map fetching and tile caching system for ESP32-based devices.  \nUnder the hood it uses [LovyanGFX](https://github.com/lovyan03/LovyanGFX) and [PNGdec](https://github.com/bitbank2/PNGdec) to do the heavy lifting.\n\n[![map](https://github.com/user-attachments/assets/39a7f287-c59d-4365-888a-d4c3f77a1dd1 \"Click to visit OpenStreetMap.org\")](https://www.openstreetmap.org/)\n\nA map is composed from downloaded OSM tiles and returned as a LGFX sprite.  \nTile fetching and decoding is performed concurrently across both cores on dualcore ESP32 devices.  \nA composed map can be pushed to the screen, saved to SD or used for further composing.  \nDownloaded tiles are cached in psram for reuse.\n\nThis should work on any ESP32 type with psram and a LovyanGFX compatible display.  \nOSM tiles are quite large at 128kB or insane large at 512kB per tile, so psram is required.\n\n### Multiple tile formats and providers are supported\n\nYou can switch provider and tile format at runtime, or set up a different default tile provider if you want.  \nThis library can do it all and is very easy to configure and use.  \n\n## How to use\n\nThis library is **PlatformIO only** due to use of modern C++ features. The Arduino IDE is **not** supported.  \nUse [the latest Arduino ESP32 Core version](https://github.com/pioarduino/platform-espressif32/releases/latest) from [pioarduino](https://github.com/pioarduino/platform-espressif32) to compile this library.\n\nSee the example PIO settings and example code to get started.\n\n### Example `platformio.ini` settings\n\nThese settings use `Arduino Release v3.2.0 based on ESP-IDF v5.4.1` from pioarduino.\n\n```bash\n[env]\nplatform = https://github.com/pioarduino/platform-espressif32/releases/download/53.03.20/platform-espressif32.zip\nframework = arduino\n\nlib_deps =\n    celliesprojects/OpenStreetMap-esp32@^1.2.0\n    lovyan03/LovyanGFX@^1.2.7\n    bitbank2/PNGdec@^1.1.3\n```\n\n## Functions\n\n### Get the minimum zoom level\n\n```c++\nint getMinZoom()\n```\n\n### Get the maximum zoom level\n\n```c++\nint getMaxZoom()\n```\n\n### Set map size\n\n```c++\nvoid setSize(uint16_t w, uint16_t h)\n```\n\n- If no size is set a 320px by 240px map will be returned.  \n- The tile cache might need resizing if the size is increased. \n\n### Get the number of tiles needed to cache a map\n\n```c++\nuint16_t tilesNeeded(uint16_t w, uint16_t h)\n```\n\nThis returns the number of tiles required to cache the given map size.  \n\n### Resize the tiles cache\n\n```c++\nbool resizeTilesCache(uint16_t numberOfTiles)\n```\n\n- The cache content is cleared before resizing.\n- Each 256px tile allocates **128kB** psram.\n- Each 512px tile allocates **512kB** psram.\n\n**Don't over-allocate**  \nWhen resizing the cache, keep in mind that the map sprite also uses psram.  \nThe PNG decoders -~50kB for each core- also live in psram.  \nUse the above `tilesNeeded` function to calculate a safe and sane cache size if you change the map size.  \n\n### Fetch a map\n\n```c++\nbool fetchMap(LGFX_Sprite \u0026map, double longitude, double latitude, uint8_t zoom)\n```\n\n- Overflowing `longitude` are wrapped and normalized to +-180°.\n- Overflowing `latitude` are clamped to +-90°.\n- Valid range for the `zoom` level is from `getMinZoom()` to `getMaxZoom()`.  \n\n### Free the psram memory used by the tile cache\n\n```c++\nvoid freeTilesCache()\n```\n\n- Does **not** free the PNG decoder(s).\n\n### Switch to a different tile provider\n\n```c++\nbool setTileProvider(int index)\n```\n\nThis function will switch to tile provider `index` defined in `src/TileProvider.hpp`.  \n\n- Returns `true` and clears the cache on success.  \n- Returns `false` -and the current tile provider is unchanged- if no provider at the index is defined.\n\n### Get the number of defined providers\n\n`OSM_TILEPROVIDERS` gives the number of defined providers.  \n\nExample use:  \n\n```c++\nconst int numberOfProviders = OSM_TILEPROVIDERS;\n```\n\n**Note:** In the default setup there is only one provider defined.\n\nSee `src/TileProvider.hpp` for example setups for [https://www.thunderforest.com/](https://www.thunderforest.com/) that only require an API key and commenting/uncommenting 2 lines.\n\nRegistration and a hobby tier are available for free.\n\n### Adding tile providers\n\nOther providers should work if a new definition is created in `src/TileProvider.hpp`.  \nCheck out the existing templates to see how this works.\n\nIf you encounter a problem or want to request support for a new provider, please check the [issue tracker](../../issues) for existing reports or [open an issue](../../issues/new).\n\n\n### Get the provider name\n\n```c++\nchar *getProviderName()\n```\n\n### Set the render mode\n\n```c++\nvoid setRenderMode(RenderMode mode)\n```\n\nAvailable modes:\n\n- `RenderMode::ACCURATE` (default)  \nDownloads map tiles **without a timeout**, ensuring a complete map with **no missing tiles** in most cases.  \nBest suited for reliability and full-quality rendering.\n\n- `RenderMode::FAST`\nDownloads map tiles **with a timeout**.  \nThis mode can produce the map **more quickly**, but some **tiles may be missing** if a request times out.  \nIdeal when operating under time constraints.\n\n## Example code\n\n### Example returning the default 320x240 map\n\n```c++\n#include \u003cArduino.h\u003e\n#include \u003cWiFi.h\u003e\n\n#define LGFX_M5STACK_CORE2  // for supported devices see \n                            // https://github.com/lovyan03/LovyanGFX\n\n#include \u003cLGFX_AUTODETECT.hpp\u003e\n#include \u003cLovyanGFX.hpp\u003e\n\n#include \u003cOpenStreetMap-esp32.hpp\u003e\n\nconst char *ssid = \"xxx\";\nconst char *password = \"xxx\";\n\nLGFX display;\nOpenStreetMap osm;\n\ndouble longitude = 5.9;\ndouble latitude = 51.5;\nint zoom = 5;\n\nvoid setup()\n{\n    Serial.begin(115200);\n    Serial.printf(\"WiFi connecting to %s\\n\", ssid);\n\n    WiFi.begin(ssid, password);\n    while (WiFi.status() != WL_CONNECTED)\n    {\n        delay(10);\n        Serial.print(\".\");\n    }\n\n    Serial.println(\"\\nWiFi connected\");\n\n    display.begin();\n    display.setRotation(1);\n    display.setBrightness(110);\n\n    // create a sprite to store the map\n    LGFX_Sprite map(\u0026display); \n\n    // returned map is 320px by 240px by default\n    const bool success = osm.fetchMap(map, longitude, latitude, zoom);\n\n    if (success)\n        map.pushSprite(0, 0);\n    else\n        Serial.println(\"Failed to fetch map.\");\n}\n\nvoid loop()\n{\n    delay(1000);\n}\n```\n\n### Example setting map resolution and cache size on RGB panel devices\n\n```c++\n#include \u003cArduino.h\u003e\n#include \u003cWiFi.h\u003e\n#include \u003cLovyanGFX.hpp\u003e\n\n#include \"LGFX_ESP32_8048S050C.hpp\" // replace with your panel config\n\n#include \u003cOpenStreetMap-esp32.hpp\u003e\n\nconst char *ssid = \"xxx\";\nconst char *password = \"xxx\";\n\nLGFX display;\nOpenStreetMap osm;\n\nint mapWidth = 480;\nint mapHeight = 800;\nint cacheSize = 20; // cache size in tiles where each osm tile is 128kB\ndouble longitude = 5.9;\ndouble latitude = 51.5;\nint zoom = 5;\n\nvoid setup()\n{\n    Serial.begin(115200);\n    Serial.printf(\"WiFi connecting to %s\\n\", ssid);\n\n    WiFi.begin(ssid, password);\n    while (WiFi.status() != WL_CONNECTED)\n    {\n        delay(10);\n        Serial.print(\".\");\n    }\n\n    Serial.println(\"\\nWiFi connected\");\n\n    display.begin();\n    display.setRotation(1);\n    display.setBrightness(110);\n\n    osm.resizeTilesCache(cacheSize);\n    osm.setSize(mapWidth, mapHeight);\n\n    LGFX_Sprite map(\u0026display);\n\n    const bool success = osm.fetchMap(map, longitude, latitude, zoom);\n    if (success)\n    {\n        // Draw a crosshair on the map\n        map.drawLine(0, map.height() / 2, map.width(), map.height() / 2, 0);\n        map.drawLine(map.width() / 2, 0, map.width() / 2, map.height(), 0);\n\n        map.pushSprite(0, 0);\n    }\n    else\n        Serial.println(\"Failed to fetch map.\");\n}\n\nvoid loop()\n{\n    delay(1000);\n}\n```\n\n## License differences between this library and the map data\n\n### This library has a MIT license\n\nThe `OpenstreetMap-esp32` library -this library- is licensed under the [MIT license](/LICENSE).\n\n### The downloaded tile data has a ODbL license\n\nOpenStreetMap® is open data, licensed under the [Open Data Commons Open Database License (ODbL)](https://opendatacommons.org/licenses/odbl/) by the OpenStreetMap Foundation (OSMF).\n\nUse of any OSMF provided service is governed by the [OSMF Terms of Use](https://osmfoundation.org/wiki/Terms_of_Use).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcelliesprojects%2Fopenstreetmap-esp32","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcelliesprojects%2Fopenstreetmap-esp32","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcelliesprojects%2Fopenstreetmap-esp32/lists"}