ESP8266 weather station that posts sensor data to Nostr via WebSocket with BIP-340 Schnorr signatures.
Viewer app: github.com/samthomson/weather — sample app for displaying weather data from Nostr events, deployed at weather.shakespeare.wtf
Supported Boards:
- NodeMCU v2 (ESP8266)
- ESP32 Dev Board
Sensors:
- DHT11 temp/humidity — also works: DHT22
- PMS5003 particulate matter — reads PM1.0, PM2.5, PM10 | also works: PMS7003
- MQ-135 air quality — uncalibrated gas detection, raw ADC (0-4095 on ESP32) | also works: MQ-2, other MQ series
- MQ-7 carbon monoxide — uncalibrated raw ADC; second analog channel
- SCD41 — real CO₂ (NDIR, ppm) + temp/humidity (I2C)
- SGP41 — VOC + NOx index, unitless 1-500 (I2C, Sensirion gas index algorithm)
- BME680 — temp/humidity/pressure + gas resistance (I2C)
- SSD1306 OLED display (I2C) - optional
Wall-powered reference build for new prototypes: ESP32, particulates, temp/humidity/pressure, daylight, rain — no MQ gas sensor, no OLED.
| Qty | Part |
|---|---|
| 1 | ESP32 dev board (same class as board = esp32dev in PlatformIO) |
| 1 | BME280 breakout (I2C, 3.3 V) — temperature, humidity, barometric pressure |
| 1 | PMS5003 — PM1.0, PM2.5, PM10 (include a cable if the module does not ship with one) |
| 1 | BH1750 breakout (I2C) — ambient light (lux) |
| 1 | MH-RD rain sensor module (resistive panel, analog out) |
| 1 | USB cable — connector must match the board (Micro-USB or USB-C) |
| 1 | USB wall charger — 5 V, ≥ 1 A (2 A is a comfortable margin for ESP32 + PMS fan) |
Hookup wire or Dupont jumpers between the dev board and breakouts are assumed by your enclosure / assembly.
MVP firmware: In secrets_stationN.h, enable ENABLE_BME280, ENABLE_BH1750, ENABLE_RAIN, and ENABLE_PMS with PMS_MODEL "PMS5003"; set ENABLE_DHT, ENABLE_MQ, and ENABLE_OLED to false. Use a PlatformIO ESP32 environment that pulls in the BME280 and BH1750 libraries (for example esp32dev_station3).
MVP ESP32 wiring: PMS5003 serial RX→GPIO16, TX→GPIO17. BME280 and BH1750 share I2C (GPIO21=SDA, GPIO22=SCL). Rain sensor analog→GPIO34.
Stripboard matrix + cable list: docs/mvp-assembly-guide.html. Flash & setup: below.
Same firmware as the MVP line — the ENABLE_* flags in the secrets file decide what compiles in; the dashboard toggles what runs.
Minimal air station (esp32dev_aq8): PMS7003 + MQ-135 + MQ-7. Cheap; MQ values are uncalibrated raw ADC (0-4095) — relative trends only.
| Qty | Part |
|---|---|
| 1 | ESP32 dev board |
| 1 | PMS7003 — PM1.0, PM2.5, PM10 |
| 1 | MQ-135 breakout (air quality, analog) |
| 1 | MQ-7 breakout (carbon monoxide, analog) |
| 1 | USB cable + 5 V ≥ 2 A wall charger (two MQ heaters are power-hungry) |
Maximal air station (esp32dev_aq9): PMS7003 + SCD41 + SGP41 + BME680. No per-unit calibration or burn-in.
| Qty | Part |
|---|---|
| 1 | ESP32 dev board |
| 1 | PMS7003 — PM1.0, PM2.5, PM10 |
| 1 | SCD41 — real CO₂ (NDIR) in ppm |
| 1 | SGP41 — VOC + NOx index |
| 1 | BME680 — temp/humidity/pressure + gas resistance |
| 1 | USB cable + 5 V ≥ 1 A wall charger |
AQ ESP32 wiring: PMS7003 serial RX→GPIO16, TX→GPIO17 (5 V power). SCD41 (0x62), SGP41 (0x59) and BME680 (0x76/0x77) share I2C (GPIO21=SDA, GPIO22=SCL, 3.3 V power) — no address clashes, wire in parallel. MQ-135 analog→GPIO36, MQ-7 analog→GPIO35 (5 V for the heaters; the analog out is ADC-safe).
Tags published: pm1/pm25/pm10; co2 (ppm, SCD41); gas (Ω, BME680); carbon_monoxide (raw, MQ-7); air_quality (raw, MQ-135); voc_index/nox_index (unitless 1-500, SGP41 — new sensor types, propose in NIP PR 2163); temp/humidity/pressure (BME680).
Stripboard matrix + cable list for both AQ stations: docs/aq-assembly-guide.html. AQ wire colours: only yellow and brown are untouched by the MVP builds, so they carry the AQ-specific nets — MQ-135 analog yellow, MQ-7 brown (minimal); SDA yellow, SCL brown (maximal) — GND is blue (black stock is depleted), 5V red, 3V3 orange; the PMS UART pair keeps green/grey. Cable tiers: 15 cm stubs, 30 cm risers, 10 cm sensor tails — all F–M.
Use industry-standard colours for power rails, and project theme colours on the nets with the most jumpers. One dupont colour per stripboard row; label GND / 3V3 / 5V on the board edge.
| Net | Dupont colour | Type | Jumpers |
|---|---|---|---|
| GND | Black | standard | 5 |
| 3.3 V | Orange | theme + standard for 3V3 | 4 |
| 5 V | Red | standard | 2 |
| I²C SDA | Purple | theme | 3 |
| I²C SCL | White | theme | 3 |
| PMS TX → ESP RX | Green | other | 2 |
| ESP TX → PMS RX | Grey | theme | 2 |
| Rain AO | Blue | other | 2 |
| Rain pad → MH-RD | Blue | pad sense | 2 |
Theme palette (UI brand + preferred dupont stock): orange, purple, white, grey. Orange does double duty as 3.3 V (common convention). Green and blue are only used on 2-wire nets so all four theme colours land on the busier rows.
ESP8266 (NodeMCU v2):
- DHT11: D7
- PMS5003: TX→D5, RX→D6
- MQ sensor: A0
- OLED: I2C (D1=SCL, D2=SDA)
ESP32:
- DHT11: GPIO4
- PMS5003: TX→GPIO16 (RX2), RX→GPIO17 (TX2)
- MQ sensor: GPIO36 (ADC1_CH0)
- OLED: I2C (GPIO21=SDA, GPIO22=SCL)
Note: ESP8266 has one analog pin. ESP32 has many - great for multiple analog sensors!
-
Install PlatformIO.
-
(Optional) For brand-new boards you do not need to edit any secrets file — the firmware ships with sensible blank defaults and a per-device captive-portal dashboard handles everything. If you want pre-baked factory defaults (handy if you flash a lot of boards), copy
include/secrets.h.exampleto e.g.include/secrets_station_mvp1.hand fill it in. -
Connect the board via USB and flash. For a brand-new or recycled board, erase first so NVS starts clean:
# Erase + flash (new/recycled board — clears all NVS): pio run -e esp32dev_mvp3 -t erase && pio run -e esp32dev_mvp3 -t upload # Flash only (re-flash same board, keep NVS config): pio run -e esp32dev_mvp3 -t upload # Monitor serial output: pio device monitor -e esp32dev_mvp3
Replace
mvp3with the correct env number. All MVP envs (esp32dev_mvp1…esp32dev_mvp5) build the same firmware; only the first-boot defaults differ (station nameN/5, etc.). Track which board is which indocs/mvp-stations.md.Do not use
esptool.pydirectly — it is not on PATH and its bundled copy has missing Python dependencies. Always usepio run -t erase/pio run -t upload.Default Nostr relay on first boot:
wss://relay.relaying.earth.Confirm the right board is connected before flashing. After boot, serial prints
[wifi] AP SSID: WeatherStation-XXXXXXevery 10 s — verifyXXXXXXmatches the board's label indocs/mvp-stations.md.
The station permanently broadcasts its own open WiFi network for configuration. You don't need a router, an app, or an IP address.
- Plug the station in.
- On your phone, join the WiFi named
WeatherStation-XXXXXX(XXXXXXis the last 6 hex of the board's MAC). It has no password. - The "Sign in to network" sheet pops up automatically with the dashboard. (If not, open a browser to
http://192.168.4.1.) - Set your home WiFi, station name, geohash, etc. Toggle the sensors you actually have wired. Hit Save.
- The station joins your home WiFi and starts publishing to Nostr.
You can rejoin WeatherStation-XXXXXX at any time to change anything — including the home WiFi password if it ever changes. Everything you change persists across power loss (stored in flash / NVS).
Once on the home network you can also reach the dashboard at http://weather.local (mDNS).
- WiFi (home) — SSID and password, with a built-in network scan.
- Station identity — name, description, geohash (with a "use my GPS" button that pulls from the phone), elevation, power source, connectivity type.
- Nostr — relay URL (preset dropdown + custom), private key (auto-generated on first boot; reveal / copy / regenerate / paste-an-existing-one).
- Sensors — per-sensor on/off toggles for BME280, BH1750, MH-RD rain, PMS5003/PMS7003. Only sensors you actually have wired need to be on.
- Advanced — post interval, restart, factory reset.
Describes the station hardware, power, and sensors:
{
"tags": [
["name", "Weather Station 1"],
["g", "w5q6u"],
["power", "mains"],
["connectivity", "wifi"],
["sensor", "temp", "DHT11"],
["sensor", "pm25", "PMS5003"]
]
}Power types: Currently mains only. Planned: solar, battery, solar_battery, usb
Connectivity types: Currently wifi only. Planned: cellular, ethernet, lora, satellite
Each tag: [sensor_type, value, model]
{
"tags": [
["t", "weather"],
["a", "16158:<pubkey>:"],
["temp", "22.5", "DHT11"],
["humidity", "65.2", "DHT11"],
["pm25", "12", "PMS5003"],
["air_quality", "627", "MQ-135"]
]
}Tag Structure: Third parameter identifies sensor model for cross-station comparison and multi-sensor setups.
Units: temp=°C, humidity=%, pm1/pm25/pm10=µg/m³, air_quality=0-1023 (raw analog)
├── src/main.cpp # Sensor reads + Nostr publish
├── src/config_store.cpp # NVS-backed user config
├── src/web_dashboard.cpp # Captive-portal dashboard
├── include/config_store.h
├── include/web_dashboard.h
├── include/secrets.h.example # First-boot factory defaults template
├── include/secrets_station_mvpN.h # Per-board factory defaults
├── platformio.ini
└── README.md
- automated tests
- web dashboard
- more modular readings
- MVP
- hardware shopping list (see MVP shopping list under Hardware)
- daylight
- rain
- air pollution
- temperature / humidity
- pressure
- geohash tag for the weather station event per geohash level (nostr-protocol/nips#2163 (comment))
- faulty sensor/data. omit the sensor reading in the 4223 reading, and mark the sensor as 418 in 16158
- document that its a string 9nostr-protocol/nips#2163 (comment))
- nip31 alt tag (for each event?) nostr-protocol/nips#2163 (comment)
- add
"observed_at": <unix timestamp in seconds>for each 16158. - expand past weather to general environmental data (eg soil acidity, soil moisture, etc). think of a more inclusive name. maybe terrametry (telemetry, but earth scoped)
A variant line focused on indoor air quality, now built as the minimal air station (esp32dev_aq8: PMS7003 + MQ-135 + MQ-7) and the maximal air station (esp32dev_aq9: PMS7003 + SCD41 + SGP41 + BME680) — see "Air-quality station variants" above. The maximal variant keeps the original goal: factory-calibrated, plug-and-trust — no per-unit calibration or burn-in. The minimal variant deliberately trades that away (MQ sensors need per-unit calibration and only give relative values) in exchange for cost.
- PMS5003/PMS7003 — PM1/2.5/10 in µg/m³ (UART — the one non-I2C sensor)
- SCD41 — real CO₂ (NDIR) in ppm, plus temp + humidity
- SGP41 — VOC + NOx index (relative; good for spotting change/spikes)
- BME680 — gas resistance in Ω + temp/humidity/pressure
- MQ-135 + MQ-7 — raw uncalibrated analog (minimal variant only)
- propose
voc_index/nox_indexsensor types in NIP PR 2163
- Winsen ZE07-CO / ZE15-CO — carbon monoxide (electrochemical, calibrated; real safety metric). UART, not I²C.
- Sensirion SFA30 — formaldehyde (HCHO); off-gasses from furniture/flooring. I²C/UART.
- Radon detector — serious long-term indoor risk, but needs a dedicated (pricier) unit; not an I²C add-on.
- Sound level (mic) — environmental noise; beyond air quality but useful for an indoor environment station.