Skip to content

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

1 watching

Forks

Latest commit

 

History

64 Commits

Folders and files

Repository files navigation

Nostr Weather Station

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

Hardware

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

MVP shopping list

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.

Air-quality station variants

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.

MVP wire colours

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.

Pin Connections

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!

Setup

  1. Install PlatformIO.

  2. (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.example to e.g. include/secrets_station_mvp1.h and fill it in.

  3. 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 mvp3 with the correct env number. All MVP envs (esp32dev_mvp1 … esp32dev_mvp5) build the same firmware; only the first-boot defaults differ (station name N/5, etc.). Track which board is which in docs/mvp-stations.md.

    Do not use esptool.py directly — it is not on PATH and its bundled copy has missing Python dependencies. Always use pio 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-XXXXXX every 10 s — verify XXXXXX matches the board's label in docs/mvp-stations.md.

Configure from your phone (the dashboard)

The station permanently broadcasts its own open WiFi network for configuration. You don't need a router, an app, or an IP address.

  1. Plug the station in.
  2. On your phone, join the WiFi named WeatherStation-XXXXXX (XXXXXX is the last 6 hex of the board's MAC). It has no password.
  3. The "Sign in to network" sheet pops up automatically with the dashboard. (If not, open a browser to http://192.168.4.1.)
  4. Set your home WiFi, station name, geohash, etc. Toggle the sensors you actually have wired. Hit Save.
  5. 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).

What's configurable from the dashboard

  • 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.

Events Published

kind:16158 (replaceable) — Station Metadata

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

kind:4223 (regular) — Sensor Readings

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)

Project Structure

├── 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

todo

  • 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)

Air quality station

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_index sensor types in NIP PR 2163

Possible future sensors

  • 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.

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages