Build Instructions

Collapse

• 1

  Setup

  LilyGo T-Display S3 Weather Station

  A beautiful, real-time weather display showing current conditions and 3-day forecast using the LilyGo T-Display S3 and OpenWeatherMap API.

  ## Features

  - **Current Temperature** - Large, easy-to-read display in cyan
  - **3-Day Forecast** - Today's high/low plus next 2 days
  - **Weather Conditions** - Real-time weather descriptions
  - **Auto-Update** - Refreshes every 30 minutes
  - **Stale Data Warning** - Red asterisk if data is >2 hours old
  - **Clean UI** - Horizontal tile layout with optimized fonts
  - **WiFi Connected** - Automatic connection on startup
  - **Automatic Timezone** - Detects timezone from location coordinates (works worldwide!)
  - **Smart Day Names** - Accurate day-of-week that updates properly

  ## What You'll Need

  ### Hardware
  - LilyGo T-Display S3 (ESP32-S3 with 170x320 ST7789 display)
  - USB-C cable for programming

  ### Software
  - PlatformIO (or Arduino IDE)
  - OpenWeatherMap API key (free tier works great - 1,000 calls/day)

  ## Installation Instructions

  ### Step 1: Get Your OpenWeatherMap API Key

  1. Sign up at https://openweathermap.org/
  2. Navigate to **API Keys** in your account
  3. Copy your API key (or generate a new one)
  4. Free tier allows 1,000 calls/day (plenty for 30-min updates)

  ### Step 2: Clone the Repository

  ```bash
  git clone https://github.com/johnsonfarmsus/lilygo-weather-station.git
  cd lilygo-weather-station
  ```

  Or download directly from: https://github.com/johnsonfarmsus/lilygo-weather-station

  ### Step 3: Configure Your Settings

  **Edit `src/pin_config.h`** - Update WiFi credentials:

  ```cpp
  #define WIFI_SSID "YOUR_WIFI_SSID"
  #define WIFI_PASSWORD "YOUR_WIFI_PASSWORD"
  ```

  **Edit `src/main.cpp`** (lines 14-18) - Update API key and location:

  ```cpp
  #define OPENWEATHER_API_KEY "YOUR_API_KEY_HERE"
  #define LATITUDE "47.4771" // Your latitude
  #define LONGITUDE "-118.2472" // Your longitude
  ```

  **How to find your coordinates:**
  - Go to Google Maps: https://maps.google.com
  - Right-click on your location
  - Click on the coordinates to copy them
  - Or use: https://www.latlong.net/

  **Example coordinates:**
  - Seattle, WA: `47.6062, -122.3321`
  - London, UK: `51.5074, -0.1278`
  - Tokyo, Japan: `35.6762, 139.6503`

  **Why coordinates instead of city names?**
  - More accurate, especially for small towns
  - No ambiguity (many cities share the same name)
  - Automatic timezone detection works worldwide
  - Better data quality from OpenWeatherMap

  ### Step 4: Upload to Device

  **Using PlatformIO (Recommended):**

  ```bash
  # Install PlatformIO if you haven't already
  pip install platformio

  # Connect your T-Display S3 via USB-C
  # Compile and upload
  pio run --target upload

  # Optional: Monitor serial output
  pio device monitor --baud 115200
  ```

  **Using Arduino IDE:**

  1. Install ESP32 board support
  2. Select board: **ESP32S3 Dev Module** or **LilyGo T-Display-S3**
  3. Copy all files to Arduino sketch folder
  4. Install required libraries: - LVGL 8.3+ - ArduinoJson 7.0+
  5. Upload to board

  **If Upload Fails:**

  Put the device in programming mode:
  1. Hold down the **BOOT** button
  2. Press and release the **RESET** button
  3. Release the **BOOT** button
  4. Try the upload command again

  ## Configuration Options

  ### Change Update Frequency

  Edit line 20 in `src/main.cpp`:

  ```cpp
  #define UPDATE_INTERVAL_MS (30 * 60 * 1000) // 30 minutes (default)
  // Examples:
  // 15 minutes: (15 * 60 * 1000)
  // 1 hour: (60 * 60 * 1000)
  ```

  ### Change Temperature Units

  Edit line 19 in `src/main.cpp`:

  ```cpp
  #define UNITS "imperial" // Fahrenheit (default)
  // or
  #define UNITS "metric" // Celsius
  ```

  ## Display Layout

  ```
  ┌─────────────────────────────────────┐
  │ 62°F Fri Sat │ ← Current temp (cyan) | Day/Date
  │ 10-04 10-05 │
  │ │
  │ 72/58°F 68/52°F 61/48°F │ ← High/Low temps (yellow)
  │ │
  │ Clear sky Overcast Scattered │ ← Conditions
  │ clouds clouds │
  └─────────────────────────────────────┘
  ```

  ## Color Scheme

  - **Cyan**: Current temperature and conditions
  - **Yellow**: High/Low temperatures (when data is fresh)
  - **Red**: Temperatures when data is stale (>2 hours old, with asterisk)
  - **White**: Day/Date labels
  - **Gray**: Future forecast descriptions

  ## Troubleshooting

  ### Display Not Working
  - The T-Display S3 uses parallel I80 interface (not SPI)
  - GPIO15 must be powered (handled automatically in code)
  - Check that LVGL is properly configured

  ### WiFi Connection Issues
  - Verify SSID and password in `pin_config.h`
  - Check WiFi signal strength
  - Ensure 2.4GHz network (ESP32 doesn't support 5GHz)
  - Serial monitor will show connection status

  ### API Errors
  - Verify API key is correct and activated (can take a few minutes)
  - Check you haven't exceeded free tier limits (1,000 calls/day)
  - Ensure coordinates are in decimal format (not degrees/minutes/seconds)

  ### Stale Data Warning
  - Red asterisk (*) appears on temps if data hasn't updated in 2+ hours
  - Usually indicates WiFi connection lost or API issues
  - Device will auto-retry on next update cycle

  ## Technical Details

  ### Libraries Used
  - **LVGL 8.3+** - Graphics library for display
  - **ArduinoJson 7.0+** - JSON parsing for API responses
  - **WiFi** - ESP32 WiFi connection
  - **HTTPClient** - API requests

  ### Display Specs
  - **Controller**: ST7789V
  - **Resolution**: 320x170 pixels
  - **Interface**: 8-bit parallel I80
  - **Backlight**: GPIO38
  - **Power**: GPIO15

  ### API Usage
  Uses two OpenWeatherMap APIs:
  1. **Current Weather API** - Real-time conditions
  2. **5-Day Forecast API** - 3-hour interval forecasts (grouped by day)

  Both use latitude/longitude for precise location targeting and automatic timezone detection.

  ### Memory Usage
  - **RAM**: ~47KB (14% of 327KB)
  - **Flash**: ~1.1MB (17% of 6.5MB)

  ## How It Works

  1. **Startup**: Device connects to WiFi and syncs time via NTP (UTC)
  2. **Weather Fetch**: - Calls OpenWeatherMap Current Weather API for current conditions - Calls Forecast API for 3-day predictions - Extracts timezone offset from API response
  3. **Data Processing**: - Converts all timestamps from UTC to local time using timezone offset - Groups forecast entries by calendar date - Calculates daily high/low temperatures - Determines day-of-week from actual dates
  4. **Display Update**: - Shows current temp and conditions (from forecast API for reliability) - Displays today's high/low plus next 2 days - Updates every 30 minutes automatically
  5. **Smart Features**: - If current temp exceeds forecast high, uses current as high - Shows red asterisk if data becomes stale (>2 hours) - Adapts to any timezone worldwide automatically

  ## Future Enhancements

  Potential features for future versions:
  - Weather icons/symbols
  - Hourly forecast view
  - Multiple location support
  - Touch screen controls
  - Battery level indicator
  - Dark/light mode toggle

  ## Credits

  - Built for the LilyGo T-Display S3: https://www.lilygo.cc/
  - Weather data from OpenWeatherMap: https://openweathermap.org/
  - Uses LVGL graphics library: https://lvgl.io/
  - GitHub Repository: https://github.com/johnsonfarmsus/lilygo-weather-station

  ## License

  This project is open source and available under the MIT License.

  ## Version History

  **v1.2.0** (Current) - Automatic timezone detection
  - Added automatic timezone detection from API (works worldwide!)
  - Fixed day-of-week calculation using actual dates
  - All forecast times converted to local timezone
  - Today's high/low now uses actual forecast data

  **v1.1.0** - Coordinate-based location
  - Coordinate-based location for precise weather data
  - Proper calendar-day grouping for forecasts
  - Better handling of late-day scenarios

  **v1.0.0** - Initial release
  - Current temperature and conditions display
  - 3-day forecast with high/low temps
  - Auto-refresh every 30 minutes
  - Stale data warning indicator

  ---

  **Questions?** Visit the GitHub repository or leave a comment on this project page!

View all instructions