ESP32S3 Weather Display

A weather icon display system for a 6x10 RGB LED matrix powered by an ESP32S3, showing current conditions fetched from NOAA/NWS.

Features

• WiFi-enabled weather display - Fetches real-time weather from NOAA API
• 6x10 RGB LED matrix - Displays weather icons with customizable brightness
• Auto-updating - Refreshes weather every 30 minutes
• Geolocation - Converts US ZIP codes to coordinates via Nominatim
• Error handling - Shows red X for network errors
• 180° rotation - Optional display rotation setting
• Configuration file - Separate config file (not committed to git)

Hardware

• Board: Seeed XIAO ESP32-S3
• Display: 6x10 RGB LED matrix (60 NeoPixel/WS2812B LEDs)
• Connection: Pin A0 (SDA)

Setup

1. Configure Your Settings

Copy the configuration template and edit with your details:

cp include/config.example.h include/config.h

Then edit include/config.h:

// WiFi credentials
#define WIFI_SSID "YOUR_NETWORK_NAME"
#define WIFI_PASSWORD "YOUR_PASSWORD"

// US ZIP code for weather
#define TARGET_ZIP_CODE "98133"

// Display brightness (0.0 - 1.0)
#define BRIGHTNESS_SCALE 0.5f

// Rotate display 180 degrees
#define ROTATE_DISPLAY false

// Hardware pins/count
#define NEOPIXEL_PIN A0
#define NEOPIXEL_COUNT 60

2. Install PlatformIO

If not already installed:

Use the VSCode extension

Or if you prefer command line...

pip install platformio

3. Build and Upload

Click the Update task to build & upload to the ESP32.

Or if you prefer command line...

# Build the project
platformio run --environment seeed_xiao_esp32s3

# Upload to device (ensure board is connected)
platformio run --target upload --environment seeed_xiao_esp32s3

Configuration File

The include/config.h file contains all user-configurable settings and is excluded from git via .gitignore to prevent accidental commits of credentials.

• WiFi credentials: Edit WIFI_SSID and WIFI_PASSWORD
• Location: Update TARGET_ZIP_CODE to your location
• Display: Adjust BRIGHTNESS_SCALE (0.0–1.0) and ROTATE_DISPLAY
• Hardware: Change NEOPIXEL_PIN or NEOPIXEL_COUNT if your wiring differs

How It Works

1. Startup: Connects to WiFi, displays blue WiFi icon
2. Geolocation: Converts ZIP code to latitude/longitude using Nominatim
3. NOAA Integration:
   • Queries /points/{lat},{lon} to get grid coordinates
   • Fetches /gridpoints/{grid_id}/forecast for current weather
4. Rendering: Maps weather conditions to RGB patterns, displays on matrix
5. Updates: Refreshes weather every 30 minutes
6. Errors: Shows red X if network/API fails

Weather Icons

• ☀️ Sunny - Yellow sun
• ☁️ Cloudy - White cloud
• 🌧️ Rainy - Cloud with blue drops
• ❄️ Snowy - Cloud with white snowflakes
• ⛅ Partly Cloudy - Sun behind cloud
• ❌ Error - Red X

Project Structure

├── include/
│   ├── config.h              # Your configuration (git-ignored)
│   ├── config.example.h      # Configuration template
├── lib/
│   ├── MatrixDisplay.h       # 6x10 matrix rendering
│   ├── WeatherIcons.h        # Weather icon patterns
│   ├── WiFiManager.h         # WiFi connection
│   ├── GeolocationClient.h   # ZIP → coordinates (Nominatim)
│   └── NOAAClient.h          # Weather API client
├── src/
│   └── main.cpp              # Main application
└── platformio.ini            # PlatformIO config

APIs Used

• Nominatim (OpenStreetMap) - Free ZIP code geocoding
• NOAA/NWS - Free US weather data

Both are free, require no API keys, and are perfect for embedded systems.

Troubleshooting

• WiFi won't connect: Check SSID/password in include/config.h
• Wrong location: Verify ZIP code format (5 digits for US)
• Display too bright/dim: Adjust BRIGHTNESS_SCALE in config.h
• Upside-down display: Set ROTATE_DISPLAY true in config.h