Offline Map Viewer for E-Paper

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:

   git clone https://github.com/0015/Offline-Map-Viewer-for-E-Paper.git
   cd offline-map-viewer

2. Install dependencies:

   pip install -r requirements.txt

3. Install Waveshare E-Paper Python driver:
   Follow instructions at: https://github.com/waveshare/e-Paper

🚀 Usage

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:

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 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

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:

   chmod +x install_offline_map_service.sh
   ./install_offline_map_service.sh

2. Reboot and confirm it's running:

   sudo systemctl status offline-map.service

3. View live log output:

   journalctl -u offline-map.service -f

4. Stop or restart manually if needed:

   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:

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.