{"id":18363065,"url":"https://github.com/snacsnoc/pocket-esp32-gps","last_synced_at":"2026-02-13T10:18:42.678Z","repository":{"id":261185284,"uuid":"864480525","full_name":"snacsnoc/pocket-esp32-gps","owner":"snacsnoc","description":"Handheld ESP32-based GPS with map display and distance calculator ","archived":false,"fork":false,"pushed_at":"2024-12-06T09:08:36.000Z","size":209,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-13T20:14:49.790Z","etag":null,"topics":["esp32","esp8266","gps-tracker","micropython","micropython-esp32"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/snacsnoc.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}},"created_at":"2024-09-28T10:30:31.000Z","updated_at":"2024-12-09T12:38:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"3e860b76-3873-4aa0-b800-e3c78d5240cd","html_url":"https://github.com/snacsnoc/pocket-esp32-gps","commit_stats":null,"previous_names":["snacsnoc/pocket-esp32-gps"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/snacsnoc/pocket-esp32-gps","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snacsnoc%2Fpocket-esp32-gps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snacsnoc%2Fpocket-esp32-gps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snacsnoc%2Fpocket-esp32-gps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snacsnoc%2Fpocket-esp32-gps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/snacsnoc","download_url":"https://codeload.github.com/snacsnoc/pocket-esp32-gps/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snacsnoc%2Fpocket-esp32-gps/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266405405,"owners_count":23923536,"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","status":"online","status_checked_at":"2025-07-21T11:47:31.412Z","response_time":64,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","esp8266","gps-tracker","micropython","micropython-esp32"],"created_at":"2024-11-05T23:04:43.158Z","updated_at":"2026-02-13T10:18:37.652Z","avatar_url":"https://github.com/snacsnoc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ESP32-Powered Handheld GPS Unit 🌐\n\nFollow this project's development on Hackaday.io: [PocketNav32](https://hackaday.io/project/199321-pocketnav-32) 📸  \n---\n\n\nThis project uses an ESP32 microcontroller to process GPS data and display it on an OLED screen, creating a simple hackable platform.\n\n### Current Features:\n- Retrieves and displays latitude and longitude in real-time, including horizontal precision, altitude and number of satellites used.\n- Computes the distance between two user-defined coordinates in meters.\n- Displays a vector-based map with land and water features.\n- A menu-driven interface enables users to adjust display and device settings.\n\n## Hardware Requirements\n\n- ESP32 development board\n  - ESP8266 can be used but the UART RX pins must be reassigned\n- GPS module (compatible with UART) \n    - GT U7M module used\n- SSD1306 OLED display\n    - Any I2C-compatible display can be used\n- Buttons for setting points and switching modes\n- LEDs for status indication\n- Tools: `mpfshell`, or `make` for flashing code.\n- A smile on your face\n\n## Pin Configuration\n| Component          | Pin Number |\n|--------------------|------------|\n| **GPS Module**     | RX: 16     |\n| **OLED Display**   | SCL: 22, SDA: 21 |\n| **Set Button**     | 13         |\n| **Mode Button**    | 14         |\n| **Display Toggle** | 33         |\n| **Navigate Button**| 32         |\n| **Mode LED**       | 12         |\n| **Success LED**    | 26         |\n| **Error LED**      | 27         |\n| **Warning LED**    | 25         |\n| **PPS (Pulse Per Second) from GPS**     | 4          |\n\n\n## Installation and Usage\n\n1. **Hardware Setup**: Connect the components according to the pin configuration.\n2. **Code Deployment**:\n    * Upload all files in the `src/` directory to the root directory of your ESP32 running [MicroPython](https://docs.micropython.org/en/latest/esp32/tutorial/intro.html)\n    * Optionally use the Makefile to upload the files to the ESP32 using the `make flash` command.\n\n3. **Map Data**:\n   - Upload a GeoJSON map file to the ESP32 flash storage root directory.\n   - Ensure the filename matches `simplified_out_0229.geojson` (hardcoded in `src/handlers/display_handler.py`).\n\n1. Power on the device.\n2. Drink a glass of water to stay hydrated.\n3. The device will start in GPS display mode, showing real-time GPS data.\n4. **Operation**:\n    * Press the reset/mode button to switch to the vector map display, distance calculation mode, settings, and the about screen.\n    * In distance mode, press the set button to mark point A, then again to mark point B.\n        * The device will display the calculated distance between the two points.\n    * In vector mapping mode, press the nav button to zoom in/out.\n\n## Menu\nThe project has a menu system with the following screens:\n```mermaid\ngraph LR\n    Start[GPS Display]\n    Second[Secondary GPS Display]\n    Map[Vector Map Display]\n    Zoom[Zoom Map Level]\n    Distance[Distance Calculation Mode]\n    Settings[Settings Screen]\n    About[About Screen]\n\n    Start --\u003e Second\n    Second --\u003e Map\n    Map --\u003e Zoom\n    Zoom --\u003e Map\n    Map --\u003e Distance\n    Distance --\u003e Settings\n    Settings --\u003e About\n    About --\u003e Start\n```\n## Note\n\nThe GPS module works best when you have a clear view of the sky. So, take a break and enjoy the outdoors for optimal results!\n\n## Roadmap\n* Map rendering improvements: Optimize vector map display and add more features, including allowing larger uploaded maps.\n* Battery optimization: Improve power management for extended battery life.\n* E-ink display usage.\n* Additional sensors: Add sensors like compass or barometer for enhanced functionality.\n* Navigation features: Add support for waypoint saving and route history.\n* Build a 3D-printed enclosure.\n* PCB design and layout.\n\nFeel free to submit a PR for any of the above, or anything else you see that can be improved!\n\n### Where to Buy Components\n**Note:** These links are simply for your convenience, feel free to use and support your favourite online electronics retailer.\n\n| **Component**       | **Description**                | **Purchase Link**                  |\n|---------------------|--------------------------------|------------------------------------|\n| **ESP32 Development Board** | ESP32S module (ESP32-WROOM-32 variations) | [Aliexpress](https://www.aliexpress.com/item/1005007370074458.html) |\n| **GPS Module (GT U7M)**      | UART-compatible GPS module | [Aliexpress](https://www.aliexpress.com/item/1005001713388717.html) |\n| **SSD1306 OLED Display**     | 128x64 I2C OLED display    | [Aliexpress](https://www.aliexpress.com/item/1005004355547926.html) |\n| **Breadboard**                | Prototyping the circuit | [Aliexpress](https://www.aliexpress.com/item/1005004317066197.html) |\n| **Push Buttons**             | Buttons for input   | [Aliexpress](https://www.aliexpress.com/item/1005005315348507.html) |\n| **Status LEDs**              | LEDs for status indication  | [Aliexpress](https://www.aliexpress.com/item/1005004837079861.html) |\n| **Resistors and Dupont Connectors**      | For connections and components | [Aliexpress](https://www.aliexpress.com/item/1005006378959096.html) |\n| **Eternal Happiness**         | Equanimity with the Earth | Priceless |\n\nApproximate build cost: $25 CAD.\n\n## Contributing\n\n**How to Contribute:**\n\t1.\tFork the repository and create a feature branch.\n\t2.\tFollow PEP 8 for Python coding style.\n\t3.\tSubmit a pull request with a description of your changes.\n\n## FAQs\n* **Can I use a different GPS module?** Yes, ensure it supports UART. \n    * If a PPS pin is not used, adjust the PPS handler method in `src/handlers/gps_handler.py`\n* **Does this work on ESP32-S1/2/3?** Yes. Change pin mapping configuration as needed.\n* **Can I add more buttons or LEDs?** Update the pin configuration and handlers in `src/handlers/button_handler.py` and `src/handlers/led_handler.py` to accommodate additional components.\n* **What MicroPython versions are supported?** Tested with MicroPython versions 1.23, 1.24, and v1.25.0-preview.72.g2e796d6c3 (2024-11-30).\n\n## Screenshots \nPlease see the Hackaday.io page [PocketNav32](https://hackaday.io/project/199321-pocketnav-32) for pictures and video of operation.\n\n## License\nThis project is licensed under the GNU General Public License v3.0 (GPLv3), see `LICENSE` for more details.\nThis project uses the `ssd1306.py` driver from the MicroPython project, which is licensed under the MIT License. See `LICENSE-MIT`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnacsnoc%2Fpocket-esp32-gps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsnacsnoc%2Fpocket-esp32-gps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnacsnoc%2Fpocket-esp32-gps/lists"}