https://github.com/b0x42/pi-weather-ink
Raspberry Pi weather station with Waveshare 2.13" bi-color and monochrome e-Paper display
https://github.com/b0x42/pi-weather-ink
e-paper epaper-display home-automation iot pirate-weather python raspberry-pi waveshare weather-station
Last synced: about 2 months ago
JSON representation
Raspberry Pi weather station with Waveshare 2.13" bi-color and monochrome e-Paper display
- Host: GitHub
- URL: https://github.com/b0x42/pi-weather-ink
- Owner: b0x42
- License: mit
- Created: 2025-02-13T15:25:47.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-04-23T10:57:29.000Z (2 months ago)
- Last Synced: 2026-04-23T12:27:41.443Z (2 months ago)
- Topics: e-paper, epaper-display, home-automation, iot, pirate-weather, python, raspberry-pi, waveshare, weather-station
- Language: Python
- Homepage:
- Size: 621 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
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](#quick-start)
- [What You Need](#what-you-need)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Supported Display Models](#supported-display-models)
- [Development & Testing](#development--testing)
- [Troubleshooting](#troubleshooting)
- [File Structure](#file-structure)
- [Credits](#credits)
- [License](#license)
## Quick Start
> **TL;DR** - Get a free [Pirate Weather API key](https://pirate-weather.apiable.io/products/weather-data/plans), then run:
```bash
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](#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](#supported-display-models))
- Internet connection
### Software
- Free [Pirate Weather API key](https://pirate-weather.apiable.io/products/weather-data/plans)
- 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:
```bash
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](docs/MANUAL_INSTALL.md) (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](docs/MANUAL_INSTALL.md#uninstall) 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](https://pirateweather.net/en/latest/API/#language)) | de |
| `UNITS` | `si` for Celsius, `us` for Fahrenheit | si |
| `DISPLAY_MODEL` | Display model (see [Supported Display Models](#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
```bash
cd ~/pi-weather-ink
source venv/bin/activate
pi-weather-ink
```
### Run as System Service (recommended)
For automatic startup on boot:
```bash
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:**
```bash
sudo systemctl status pi-weather-ink
```
**View logs:**
```bash
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)](https://www.waveshare.com/wiki/2.13inch_e-Paper_HAT_(B)_Manual) | Bi-color | Black/Red | `epd2in13bc` (default) |
| [2.13" e-Paper HAT (D)](https://www.waveshare.com/wiki/2.13inch_e-Paper_HAT_(D)_Manual) | Monochrome | Black/White | `epd2in13d` |
### 122×250 Resolution
| Model | Type | Colors | Model ID |
|-------|------|--------|----------|
| [2.13" e-Paper HAT](https://www.waveshare.com/wiki/2.13inch_e-Paper_HAT_Manual) | Monochrome | Black/White | `epd2in13` |
| [2.13" e-Paper HAT V2](https://www.waveshare.com/wiki/2.13inch_e-Paper_HAT_Manual) | Monochrome | Black/White | `epd2in13_V2` |
| [2.13" e-Paper HAT V3](https://www.waveshare.com/wiki/2.13inch_e-Paper_HAT_Manual) | Monochrome | Black/White | `epd2in13_V3` |
| [2.13" e-Paper HAT V4](https://www.waveshare.com/wiki/2.13inch_e-Paper_HAT_Manual) | Monochrome | Black/White | `epd2in13_V4` |
| [2.13" e-Paper HAT (B) V3](https://www.waveshare.com/wiki/2.13inch_e-Paper_HAT_(B)_Manual) | Bi-color | Black/Red | `epd2in13b_V3` |
| [2.13" e-Paper HAT (B) V4](https://www.waveshare.com/wiki/2.13inch_e-Paper_HAT_(B)_Manual) | Bi-color | Black/Red | `epd2in13b_V4` |
| [2.13" e-Paper HAT (G)](https://www.waveshare.com/wiki/2.13inch_e-Paper_HAT_(G)_Manual) | 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](#macos-install-font)) | `/usr/share/fonts/.../DejaVuSans-Bold.ttf` |
### Quick Setup (macOS/Linux)
```bash
# 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
```bash
# 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
```bash
# 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
```bash
python -m pytest tests/ -v
```
## Troubleshooting
See the [Troubleshooting Guide](docs/TROUBLESHOOTING.md) 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](https://github.com/erikflowers/weather-icons)
- Weather data: [Pirate Weather API](https://pirateweather.net/)
- e-Paper library: [Waveshare e-Paper](https://github.com/waveshareteam/e-Paper)
## License
MIT License - see [LICENSE](LICENSE)