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!