Pi Weather Ink

A Raspberry Pi weather station with Waveshare 2.13" e-Paper displays. Supports multiple display models (bi-color and monochrome). Shows current temperature, daily max, and weather summary.

• Current temperature, daily max temperature with a beautiful weather icon
• Multi-language weather summaries
• 10 supported Waveshare 2.13" display models (bi-color and monochrome)
• Desktop development with built-in e-Paper emulator

Table of Contents

• Quick Start
• What You Need
• Installation
• Configuration
• Usage
• Supported Display Models
• Development & Testing
• Troubleshooting
• File Structure
• Credits
• License

Quick Start

TL;DR - Get a free Pirate Weather API key, then run:

curl -fsSL https://raw.githubusercontent.com/b0x42/pi-weather-ink/main/install.sh | bash

The installer sets up everything: dependencies, SPI, configuration, and an optional systemd service. See Installation for manual setup.

What You Need

Hardware

• Raspberry Pi (Zero W, 3, 4, or 5)
• Any Waveshare 2.13" e-Paper display (see Supported Display Models)
• Internet connection

Software

• Free Pirate Weather API key
• Raspberry Pi OS, DietPi, or Debian-based Linux distro
• DejaVu Sans Bold font (pre-installed on Raspberry Pi OS and DietPi)

Installation

Run the installer on your Raspberry Pi — it handles SPI, dependencies, configuration, and the systemd service:

curl -fsSL https://raw.githubusercontent.com/b0x42/pi-weather-ink/main/install.sh | bash

Prefer manual setup? Follow the step-by-step Manual Installation Guide (pipx or venv).

Updating

To update, simply re-run the installer — it detects the existing installation, upgrades the application, and keeps your configuration.

Uninstalling

See the Uninstall Guide for step-by-step removal instructions.

Configuration

All settings are configured via environment variables in your .env file.

Variable	Description	Default
PIRATE_WEATHER_API_KEY	Your Pirate Weather API key	Required
LATITUDE	Your location's latitude	52.5200 (Berlin)
LONGITUDE	Your location's longitude	13.4050 (Berlin)
LANGUAGE	Weather summary language (see options)	de
UNITS	si for Celsius, us for Fahrenheit	si
DISPLAY_MODEL	Display model (see Supported Display Models)	epd2in13bc
FLIP_DISPLAY	Set to true to rotate display 180°	false
UPDATE_INTERVAL_SECONDS	How often to refresh (1800 = 30 min)	1800

Usage

Manual Start

cd ~/pi-weather-ink
source venv/bin/activate
pi-weather-ink

Run as System Service (recommended)

For automatic startup on boot:

sudo cp pi-weather-ink.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable pi-weather-ink
sudo systemctl start pi-weather-ink

Check status:

sudo systemctl status pi-weather-ink

View logs:

tail -f /var/log/pi-weather-ink.log

Supported Display Models

All Waveshare 2.13" e-Paper displays are supported:

104×212 Resolution

Model	Type	Colors	Model ID
2.13" e-Paper HAT (B)	Bi-color	Black/Red	epd2in13bc (default)
2.13" e-Paper HAT (D)	Monochrome	Black/White	epd2in13d

122×250 Resolution

Model	Type	Colors	Model ID
2.13" e-Paper HAT	Monochrome	Black/White	epd2in13
2.13" e-Paper HAT V2	Monochrome	Black/White	epd2in13_V2
2.13" e-Paper HAT V3	Monochrome	Black/White	epd2in13_V3
2.13" e-Paper HAT V4	Monochrome	Black/White	epd2in13_V4
2.13" e-Paper HAT (B) V3	Bi-color	Black/Red	epd2in13b_V3
2.13" e-Paper HAT (B) V4	Bi-color	Black/Red	epd2in13b_V4
2.13" e-Paper HAT (G)	4-color	Black/White/Yellow/Red	epd2in13g

Features:

• Bi-color displays: Red activates when current temp ≥ max temp
• Layout automatically scales based on display resolution
• All displays work with both hardware and emulator

Development & Testing

Development Configuration

Variable	Description	Default
USE_EMULATOR	Use E-Paper-Emulator instead of hardware	false
USE_TKINTER	Use Tkinter window instead of browser (only with emulator)	false
LOG_FILE_PATH	Path to log file (use local path on macOS)	/var/log/pi-weather-ink.log
FONT_PATH	TrueType font file (see macOS font setup)	/usr/share/fonts/.../DejaVuSans-Bold.ttf

Quick Setup (macOS/Linux)

# 1. Clone and setup (includes E-Paper-Emulator and pytest)
git clone https://github.com/b0x42/pi-weather-ink.git
cd pi-weather-ink
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# 2. Setup environment
cp .env.example .env
# Edit .env and add your PIRATE_WEATHER_API_KEY

# 3. Run with emulator (opens in browser at http://localhost:5000)
USE_EMULATOR=true pi-weather-ink

# Or use Tkinter window instead of browser
USE_EMULATOR=true USE_TKINTER=true pi-weather-ink

macOS: Install Font

# DejaVu Sans is required (pre-installed on Raspberry Pi OS and DietPi)
brew install font-dejavu

# Add to .env
echo "FONT_PATH=~/Library/Fonts/DejaVuSans-Bold.ttf" >> .env

Test Different Display Models

# Bi-color (black/red) - opens in browser
USE_EMULATOR=true DISPLAY_MODEL=epd2in13bc pi-weather-ink

# Monochrome (black/white) - opens in browser
USE_EMULATOR=true DISPLAY_MODEL=epd2in13d pi-weather-ink

Note: The emulator uses Flask and serves at http://localhost:5000 by default. Set USE_TKINTER=true if you prefer a native window.

Running Tests

python -m pytest tests/ -v

Troubleshooting

See the Troubleshooting Guide for solutions to common issues including display not updating, API errors, service problems, and the Pi Zero ReadBusy hang fix.

File Structure

pi-weather-ink/
├── install.sh                  # Automated installer for Raspberry Pi
├── pi-weather-ink.service      # Systemd service file
├── .env                        # Your configuration (create from .env.example)
├── .env.example                # Configuration template
├── pi_weather_ink/             # Main package
│   ├── pi_weather_ink.py       # Main application
│   ├── display_config.py       # Display configuration and module loading
│   └── emulator_adapter.py     # E-Paper-Emulator adapter for testing without hardware
├── icons/                      # Weather icon assets
│   ├── icons.json              # Weather icon unicode mapping
│   └── weathericons.ttf        # Weather icons font
├── scripts/
│   └── fix-pi-zero-readbusy.sh # Pi Zero ReadBusy hang fix script
├── tests/                      # Test files
│   ├── test_pi_weather_ink.py
│   ├── test_display_config.py
│   └── test_emulator_integration.py
└── docs/
    ├── TROUBLESHOOTING.md      # Troubleshooting guide (includes Pi Zero fix)
    └── MANUAL_INSTALL.md       # Manual installation guide

Credits

• Weather icons: Erik Flowers Weather Icons
• Weather data: Pirate Weather API
• e-Paper library: Waveshare e-Paper

License

MIT License - see LICENSE