Arduino/Arduino/WeatherPredictor/docs/superpowers/specs/2026-07-17-weather-predictor-design.md

Weather Predictor — Design Spec

Date: 2026-07-17 Status: Approved (design), pending implementation plan

Overview

An autonomous barometric weather-prediction station built on a Wemos D1 mini (ESP8266). It measures atmospheric pressure and temperature (BMP180), keeps accurate time (DS3231 RTC), predicts near-term weather locally using the Zambretti algorithm (pressure trend based, no internet required), and displays current readings + forecast on a small TFT. A built-in web interface (served from the device) shows live readings, a 24 h history chart, and editable settings.

All on-device and web text is in English.

Hardware

Component	Model
MCU	Wemos D1 mini (ESP8266, ~4 MB flash)
Pressure/Temp sensor	BMP180 (GY-68), I2C addr 0x77
RTC	DS3231 (HW-022, no EEPROM), I2C addr 0x68, battery-backed
Display	0.96" 80×160 TFT, ST7735S, 4-wire SPI, driver INITR_MINI160x80

Wiring

Display uses hardware SPI; both I2C modules share one bus (D1/D6).

Signal	Wemos pin	GPIO
TFT CS	D8	15
TFT DC	D3	0
TFT RES	D4	2
TFT SDA (MOSI)	D7	13
TFT SCL (SCK)	D5	14
TFT BLK (backlight)	D2	4
I2C SCL (BMP180 + DS3231)	D1	5
I2C SDA (BMP180 + DS3231)	D6	12

Power: all modules on 3.3 V / GND. I2C init: Wire.begin(D6 /*SDA*/, D1 /*SCL*/).

Software Architecture

Arduino IDE project: main .ino sketch + per-module .h/.cpp tabs. Each module has one clear responsibility and a small interface.

Module	Responsibility	Key library
config.h	Pins, I2C addresses, timing constants, defaults	—
sensors	Read BMP180 pressure + temperature	Adafruit_BMP085
rtc	Read/set DS3231 time; NTP sync when Wi-Fi up	RTClib
display	Render the status screen	Adafruit_GFX, Adafruit_ST7735
forecast	Zambretti prediction (pure, host-testable)	—
history	Ring buffer of samples + LittleFS persistence	LittleFS
settings	Load/save settings JSON	ArduinoJson, LittleFS
wifi	Connect via WiFiManager captive portal	WiFiManager
webserver	HTTP server + REST API + static page	ESP8266WebServer

Third-party libraries (Arduino Library Manager)

Adafruit_GFX, Adafruit_ST7735, Adafruit_BMP085 (works for BMP180), RTClib, ArduinoJson, WiFiManager (tzapu). Built-in: SPI, Wire, ESP8266WiFi, ESP8266WebServer, LittleFS, time.h (NTP/SNTP).

Forecast Logic (Zambretti)

1. BMP180 reports absolute pressure → convert to mean sea-level (MSL) pressure using the configured altitude (barometric formula).
2. Store MSL pressure samples in the history buffer.
3. Compute the 3-hour pressure trend → rising / steady / falling (threshold ≈ ±1.6 hPa over 3 h).
4. Zambretti lookup from (MSL pressure, trend, season-from-month) → one of ~26 forecast codes → mapped to a short English label (e.g. Sunny, Fine, Changeable, Rain likely, Stormy) + an icon + trend arrow (↑ / → / ↓).
5. Until ~3 h of data exist after boot, show Collecting data….

Southern-hemisphere handling is not needed (fixed northern location); season derived from RTC month.

Display Layout (80×160, portrait)

Top→bottom: large time HH:MM; date; MSL pressure (hPa) with trend arrow; temperature (°C); forecast label + icon. Backlight on D2 (dimming/night mode is a possible later enhancement, not in initial scope).

Data Flow

BMP180 ──▶ sensors ──▶ MSL convert ──▶ history (RAM ring buffer)
DS3231 ──▶ rtc                              │
                                            ▼
                          forecast (Zambretti) ──┬──▶ display
                                                 └──▶ webserver /api
history ──(every ~15 min)──▶ LittleFS  (restored on boot)
settings ◀──▶ LittleFS  (edited via web)

• Sensor sampling: every ~1 min (display/current values).
• History granularity: one stored sample every ~5 min → ~24–48 h in RAM.
• Flash flush: every ~15 min (and buffer capped) to limit flash wear.

Web Interface

Single page served from the device; no external CDNs (works even if the client has no internet). Vanilla JS + a small self-written inline SVG chart.

Pages/sections:

1. Live — current time, MSL pressure + trend, temperature, forecast.
2. History — 24 h pressure + temperature chart.
3. Settings — altitude (m, default 150), timezone/UTC offset, default coordinates (54.9870, 82.8730) shown; editable and persisted to LittleFS.

REST API:

• GET /api/current → time, pressure (abs + MSL), temperature, trend, forecast.
• GET /api/history → array of recent samples for the chart.
• GET /api/settings / POST /api/settings → read/update settings.

Storage (LittleFS)

• /settings.json — altitude, timezone offset, coordinates.
• /history.dat (or .json) — periodic snapshot of the sample ring buffer, reloaded on boot so the trend survives restarts.

Wi-Fi & Time

• WiFiManager: on first boot (or no known network) the device opens a captive-portal AP so Wi-Fi is configured from a phone — no reflashing.
• NTP: when Wi-Fi is connected, sync time and write it to the DS3231. DS3231 (battery-backed) keeps accurate time when offline.
• Default location for timezone context: 54.9870 N, 82.8730 E (Novosibirsk, UTC+7), altitude 150 m — all editable via web.

Defaults Summary

Setting	Default	Editable in web
Altitude	150 m	yes
Coordinates	54.9870, 82.8730	yes
Timezone	UTC+7	yes
Sensor sample interval	~60 s	no (constant)
History sample interval	~5 min	no (constant)
Flash flush interval	~15 min	no (constant)

Testing

Manual (Arduino IDE, no automated harness):

1. Sensors — Serial print of BMP180 pressure/temp; sanity-check values.
2. RTC — set time, power-cycle, verify time held by battery; verify NTP sync updates DS3231.
3. MSL conversion — verify computed sea-level pressure is plausible for 150 m (abs ≈ MSL − ~18 hPa).
4. Trend/forecast — inject synthetic pressure series via Serial or by editing the buffer; confirm rising/steady/falling classification and Zambretti label mapping against known reference values.
5. Display — verify layout, no overflow, correct icons/arrows.
6. Web — load page over LAN, confirm live values, chart renders, settings save and persist across reboot.
7. Persistence — reboot; confirm settings and history restored from flash.

Out of Scope (initial)

• Online forecast providers (variant B/C hybrid).
• Cyrillic display fonts (English only).
• Backlight night dimming, CSV/JSON export (possible later enhancements).