https://github.com/0015/offline-map-viewer-for-e-paper
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.
https://github.com/0015/offline-map-viewer-for-e-paper
e-ink e-paper gps-location localmap map osm portable-map python raspberry-pi
Last synced: 10 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/0015/offline-map-viewer-for-e-paper
- Owner: 0015
- License: mit
- Created: 2025-05-26T05:13:32.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-28T06:15:32.000Z (about 1 year ago)
- Last Synced: 2025-06-17T06:59:54.919Z (about 1 year ago)
- Topics: e-ink, e-paper, gps-location, localmap, map, osm, portable-map, python, raspberry-pi
- Language: Python
- Homepage: https://youtu.be/ggmhJsFT2ZE
- Size: 868 KB
- Stars: 7
- Watchers: 0
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Offline Map Viewer for E-Paper
[](https://youtu.be/ggmhJsFT2ZE)
Local map viewer running on RPI
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.
## 📌 Features
- Displays your live location on an offline map stored as `.mbtiles`
- Uses a GPS module (no internet needed)
- Runs on Raspberry Pi (e.g. Zero 2 W)
- Renders map view to a Waveshare 7.3-inch E-Paper screen
- Only updates the screen when movement exceeds a distance threshold
## 🛠 Requirements
- Raspberry Pi Zero 2 W (https://amzn.to/43cJ68f)
- GPS module (https://amzn.to/4kldao2)
- Waveshare E-Paper 7.3" display (https://amzn.to/3ZhvdDc)
- Pre-rendered map in `.mbtiles` format (https://github.com/0015/OfflineMapDownloader)
- Python 3.x
## 📦 Installation
1. Clone this repository:
```bash
git clone https://github.com/0015/Offline-Map-Viewer-for-E-Paper.git
cd offline-map-viewer
```
2. Install dependencies:
```bash
pip install -r requirements.txt
```
3. Install Waveshare E-Paper Python driver:
Follow instructions at: [https://github.com/waveshare/e-Paper](https://github.com/waveshare/e-Paper)
## 🚀 Usage
```bash
python3 Offline_map_viewer.py --mbtiles path_to_your_tiles.mbtiles --zoom 17 --min-distance 5.0
```
### Optional arguments:
| Argument | Description | Default |
|---------------------|-----------------------------------------------------|----------------------|
| `--mbtiles` | Path to your `.mbtiles` map file | `map_tiles.mbtiles` |
| `--zoom` | Zoom level of the map | `17` |
| `--min-distance` | Minimum meters moved before map refreshes | `1.0` |
Example:
```bash
python3 Offline_map_viewer.py --mbtiles skate_park.mbtiles --zoom 17 --min-distance 3.0
```
## 🗺 Creating MBTiles
You can create `.mbtiles` files using the **[Offline Map Downloader](https://github.com/0015/OfflineMapDownloader)** project.
This 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.
## 🛰 How it Works
- The GPS module receives satellite signals to determine your location — no internet connection is required.
- Your current coordinates are converted to pixel locations on an offline tile map.
- Only when you move beyond a certain distance, the E-Paper screen is updated with a new map view.
## 🎥 Watch the Build Process
You can see how this device was built step-by-step in the following video:
📺 [Watch on YouTube](https://youtu.be/xLXnn48pIV4)
This video walks through the hardware setup, code integration, and testing of the offline map viewer with the e-paper display.
## 🔁 Auto-Start on Boot (Optional)
To make the map viewer run automatically on system startup (even after reboot), you can install it as a systemd service.
### Step-by-Step:
1. Download and run the installer script:
```bash
chmod +x install_offline_map_service.sh
./install_offline_map_service.sh
```
2. Reboot and confirm it's running:
```bash
sudo systemctl status offline-map.service
```
3. View live log output:
```bash
journalctl -u offline-map.service -f
```
4. Stop or restart manually if needed:
```bash
sudo systemctl stop offline-map.service
sudo systemctl start offline-map.service
```
### ⚙️ Customizing the Installer Script
The following variables are defined at the top of `install_offline_map_service.sh`.
Be sure to edit them according to your environment before running the script:
```bash
USERNAME="ThatProject" # Your Raspberry Pi username
PROJECT_DIR="/home/${USERNAME}/Offline-Map-Viewer-for-E-Paper" # Project directory
SCRIPT_PATH="${PROJECT_DIR}/Offline_map_viewer.py" # Path to the main script
MBTILES_PATH="${PROJECT_DIR}/map_tiles.mbtiles" # Path to the MBTiles file
ZOOM_LEVEL=19 # Zoom level to use (e.g. 19, 18, 17...)
MIN_DISTANCE=0.5 # Minimum movement in meters to trigger update
```
This ensures the script starts automatically and restarts if it crashes.
## 📄 License
This project is licensed under the MIT License.
> This is a simple proof-of-concept project for personal and non-commercial use.