{"id":28858085,"url":"https://github.com/0015/offline-map-viewer-for-e-paper","last_synced_at":"2025-09-08T20:34:01.675Z","repository":{"id":296306310,"uuid":"990423139","full_name":"0015/Offline-Map-Viewer-for-E-Paper","owner":"0015","description":"This project displays your **real-time GPS location** on a **preloaded offline map** using a **Raspberry Pi** and a **Waveshare E-Paper display**. It works completely offline — no internet connection is required. Perfect for use in outdoor or off-grid environments.","archived":false,"fork":false,"pushed_at":"2025-05-28T06:15:32.000Z","size":889,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-17T06:59:54.919Z","etag":null,"topics":["e-ink","e-paper","gps-location","localmap","map","osm","portable-map","python","raspberry-pi"],"latest_commit_sha":null,"homepage":"https://youtu.be/ggmhJsFT2ZE","language":"Python","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/0015.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-05-26T05:13:32.000Z","updated_at":"2025-06-08T14:36:24.000Z","dependencies_parsed_at":"2025-05-30T01:03:52.869Z","dependency_job_id":"07987c91-b665-4f51-83e4-c13091f00183","html_url":"https://github.com/0015/Offline-Map-Viewer-for-E-Paper","commit_stats":null,"previous_names":["0015/offline-map-viewer-for-e-paper"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/0015/Offline-Map-Viewer-for-E-Paper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0015%2FOffline-Map-Viewer-for-E-Paper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0015%2FOffline-Map-Viewer-for-E-Paper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0015%2FOffline-Map-Viewer-for-E-Paper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0015%2FOffline-Map-Viewer-for-E-Paper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0015","download_url":"https://codeload.github.com/0015/Offline-Map-Viewer-for-E-Paper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0015%2FOffline-Map-Viewer-for-E-Paper/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260862914,"owners_count":23074182,"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":["e-ink","e-paper","gps-location","localmap","map","osm","portable-map","python","raspberry-pi"],"created_at":"2025-06-20T02:04:45.951Z","updated_at":"2025-09-08T20:34:01.647Z","avatar_url":"https://github.com/0015.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Offline Map Viewer for E-Paper\n\u003cdiv align=\"center\"\u003e\n\n[![Offline Map Downloader](./misc/demo.jpg)](https://youtu.be/ggmhJsFT2ZE)\n\u003cp\u003eLocal map viewer running on RPI\u003c/p\u003e\n\u003c/div\u003e\n\nThis project displays your **real-time GPS location** on a **preloaded offline map** using a **Raspberry Pi** and a **Waveshare E-Paper display**. It works completely offline — no internet connection is required. Perfect for use in outdoor or off-grid environments.\n\n## 📌 Features\n\n- Displays your live location on an offline map stored as `.mbtiles`\n- Uses a GPS module (no internet needed)\n- Runs on Raspberry Pi (e.g. Zero 2 W)\n- Renders map view to a Waveshare 7.3-inch E-Paper screen\n- Only updates the screen when movement exceeds a distance threshold\n\n## 🛠 Requirements\n\n- Raspberry Pi Zero 2 W (https://amzn.to/43cJ68f)\n- GPS module (https://amzn.to/4kldao2)\n- Waveshare E-Paper 7.3\" display (https://amzn.to/3ZhvdDc)\n- Pre-rendered map in `.mbtiles` format (https://github.com/0015/OfflineMapDownloader)\n- Python 3.x\n\n## 📦 Installation\n\n1. Clone this repository:\n   ```bash\n   git clone https://github.com/0015/Offline-Map-Viewer-for-E-Paper.git\n   cd offline-map-viewer\n   ```\n\n2. Install dependencies:\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n3. Install Waveshare E-Paper Python driver:  \n   Follow instructions at: [https://github.com/waveshare/e-Paper](https://github.com/waveshare/e-Paper)\n\n## 🚀 Usage\n\n```bash\npython3 Offline_map_viewer.py --mbtiles path_to_your_tiles.mbtiles --zoom 17 --min-distance 5.0\n```\n\n### Optional arguments:\n\n| Argument            | Description                                         | Default              |\n|---------------------|-----------------------------------------------------|----------------------|\n| `--mbtiles`         | Path to your `.mbtiles` map file                    | `map_tiles.mbtiles`  |\n| `--zoom`            | Zoom level of the map                              | `17`                 |\n| `--min-distance`    | Minimum meters moved before map refreshes          | `1.0`                |\n\nExample:\n```bash\npython3 Offline_map_viewer.py --mbtiles skate_park.mbtiles --zoom 17 --min-distance 3.0\n```\n\n## 🗺 Creating MBTiles\n\nYou can create `.mbtiles` files using the **[Offline Map Downloader](https://github.com/0015/OfflineMapDownloader)** project.\n\nThis tool allows you to download OpenStreetMap tile data for offline use without relying on API keys. It’s lightweight, simple to use, and ideal for generating tiles for embedded or offline mapping applications.\n\n## 🛰 How it Works\n\n- The GPS module receives satellite signals to determine your location — no internet connection is required.\n- Your current coordinates are converted to pixel locations on an offline tile map.\n- Only when you move beyond a certain distance, the E-Paper screen is updated with a new map view.\n\n## 🎥 Watch the Build Process\n\nYou can see how this device was built step-by-step in the following video:\n\n📺 [Watch on YouTube](https://youtu.be/xLXnn48pIV4)\n\nThis video walks through the hardware setup, code integration, and testing of the offline map viewer with the e-paper display.\n\n## 🔁 Auto-Start on Boot (Optional)\n\nTo make the map viewer run automatically on system startup (even after reboot), you can install it as a systemd service.\n\n### Step-by-Step:\n\n1. Download and run the installer script:\n   ```bash\n   chmod +x install_offline_map_service.sh\n   ./install_offline_map_service.sh\n   ```\n\n2. Reboot and confirm it's running:\n   ```bash\n   sudo systemctl status offline-map.service\n   ```\n\n3. View live log output:\n   ```bash\n   journalctl -u offline-map.service -f\n   ```\n\n4. Stop or restart manually if needed:\n   ```bash\n   sudo systemctl stop offline-map.service\n   sudo systemctl start offline-map.service\n   ```\n\n### ⚙️ Customizing the Installer Script\n\nThe following variables are defined at the top of `install_offline_map_service.sh`.  \nBe sure to edit them according to your environment before running the script:\n\n```bash\nUSERNAME=\"ThatProject\"                                            # Your Raspberry Pi username\nPROJECT_DIR=\"/home/${USERNAME}/Offline-Map-Viewer-for-E-Paper\"    # Project directory\nSCRIPT_PATH=\"${PROJECT_DIR}/Offline_map_viewer.py\"                # Path to the main script\nMBTILES_PATH=\"${PROJECT_DIR}/map_tiles.mbtiles\"                   # Path to the MBTiles file\nZOOM_LEVEL=19                                                     # Zoom level to use (e.g. 19, 18, 17...)\nMIN_DISTANCE=0.5                                                  # Minimum movement in meters to trigger update\n```\nThis ensures the script starts automatically and restarts if it crashes.\n\n## 📄 License\n\nThis project is licensed under the MIT License.\n\n\u003e This is a simple proof-of-concept project for personal and non-commercial use.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0015%2Foffline-map-viewer-for-e-paper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0015%2Foffline-map-viewer-for-e-paper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0015%2Foffline-map-viewer-for-e-paper/lists"}