Imported from cthulu/m5weather (AGENTS.md). Install upstream with npx skills add cthulu/m5weather. Copyright stays with the author.

M5PaperWeather

Project Overview

M5PaperWeather is an embedded firmware project for the M5Stack Paper - an ESP32-based e-ink handheld device with a 960x540 16-level grayscale display. It fetches weather data from OpenWeatherMap and electricity pricing from Tibber, then renders a comprehensive weather dashboard on the e-paper display.

Originally forked from Bastelschlumpf/M5PaperWeather.

Hardware

• Device: M5Stack Paper (ESP32-based)
• Board config: m5stack-fire (in platformio.ini)
• Display: 960x540 e-ink, 16 grayscale levels
• Sensors: SHT30 (temperature + humidity)
• Connectivity: WiFi, USB serial (WCH CH340)

Key Concepts

Data Sources

• OpenWeatherMap API: Hourly/daily weather forecasts, sunrise/sunset, wind data
• Tibber API: Hourly electricity pricing (min/max/current)
• SHT30 Sensor: Internal temperature and humidity readings
• RTC: Real-time clock for timestamps

Display Layout (960x540)

• Header (top): Version, city name, update time, WiFi RSSI, battery level
• Weather section (left, 232x251): Current weather icon, condition, temp, rain
• Tibber graph (top-right, 685x240): 12-hour electricity price step chart
• Daily forecast (middle strip, 780x122): 7-day forecast with icons, min/max temp, precipitation
• Bottom graphs (4 columns, 232x122 each):
  • Temperature 12h
  • Rain 12h (dual: pop% + rain mm)
  • Temperature 7-day
  • Rain 7-day (dual: pop% + rain mm)

Architecture

• Data.hpp - MyData struct holding all collected data (weather, Tibber, sensor, WiFi, battery)
• Display.hpp - WeatherDisplay class rendering all visual elements to the e-paper canvas
• Config.hpp - Build-time configuration (coordinates, API keys, WiFi credentials)
• Icons.hpp - Embedded weather icon bitmaps (01d/01n through 50d/50n, plus unknown)
• main.cpp - Entry point, fetches data and triggers display updates

State & Persistence

• Non-Volatile Storage (NVS) used for a simple counter (nvsCounter)
• Data fetched hourly or manually via button press
• Display uses M5EPD_Canvas for off-screen rendering before pushing to e-paper

Build & Run

Prerequisites

• PlatformIO installed (VS Code extension or CLI)
• M5Stack Paper device connected via USB

Configuration

1. Copy src/Config.hpp to src/ConfigOverride.hpp (gitignored)
2. Edit ConfigOverride.hpp with your:
   • GPS coordinates (LATITUDE, LONGITUDE)
   • City name (CITY_NAME)
   • OpenWeatherMap API key (OPENWEATHER_API)
   • WiFi credentials (WIFI_SSID, WIFI_PW)

Build Commands

# Install dependencies and build
pio run

# Upload to device
pio run --target upload

# Monitor serial output (115200 baud)
pio monitor

# Upload and monitor
pio run --target upload && pio monitor

Dependencies (from platformio.ini)

File Structure

src/
  main.cpp          - Entry point, main loop
  Data.hpp          - MyData struct, all data models
  Display.hpp       - WeatherDisplay class, rendering logic
  Config.hpp        - Default config (copy to ConfigOverride.hpp)
  Icons.hpp         - Embedded weather icon bitmaps
  Tibber.hpp        - Tibber GraphQL API client (price queries, JWT auth)
  wifi.hpp          - WiFi connection helpers
  webserver.hpp     - HTTP client for API calls
  rtc.hpp           - RTC time management
  Utils.hpp         - Utility helpers (time parsing, string formatting)

Tibber Integration

Uses the Tibber v1-beta GraphQL API to fetch hourly electricity prices. The Tibber.hpp client queries current, today, and tomorrow price info, parsing total (kWh rate + tax + grid) into a 13-hour array rendered as a step chart on the display. API key is configured via TIBBER_API_KEY in ConfigOverride.hpp.

License

GPL-3.0

Notable Implementation Details

• Wind arrow drawing borrowed from ESP32-Revised-Weather-Display (David Bird)
• Graph rendering supports night zone shading, dual-axis charts, and step charts
• E-paper partial updates via UPDATE_MODE_GC16 for faster refresh
• Battery and WiFi RSSI visualized as circular indicators