10 KiB
⚙️ Weather API & Timezone Settings - Configuration Guide
Overview
You can now configure weather API settings and timezone directly from the web UI Settings page. These settings control:
- How weather data is fetched and displayed on the HOME page
- What timezone is used for the clock display
- Update frequency for weather data
What Was Added
1. Weather & Time Settings Section in Web UI
A new "Weather & Time" section has been added to the Settings page with:
✅ Timezone Settings
- Dropdown selector with common timezones worldwide
- Timezone applied immediately after saving
- Affects clock display on HOME page and LCD
✅ Weather Provider Selection
- Open-Meteo (Free, no API key required)
- OpenWeather (Requires API key but more features)
✅ Location Configuration
- Enter city name or coordinates (latitude,longitude)
- Examples:
Sofia(for city name)London(for city name)42.6977,23.3219(latitude,longitude format)
✅ API Key (OpenWeather only)
- Shows only when OpenWeather provider is selected
- Password field for security
- Not required for Open-Meteo
✅ Update Interval
- Set how often weather data refreshes (5-60 minutes)
- Default: 5 minutes
- Lower values = more frequent updates, higher bandwidth usage
How to Configure Weather & Timezone
Step 1: Access Settings
- Open web UI:
http://[device-ip]/ - Click "Settings" in navigation menu
Step 2: Configure Timezone
Settings → Weather & Time → Time Zone
- Click the "Time Zone" dropdown
- Select your timezone (e.g., "Europe/Sofia", "America/New_York")
- Click "Save" button
Result: Clock on HOME page and device time will update to selected timezone
Step 3: Configure Weather Provider
Option A: Use Open-Meteo (Recommended for simplicity)
Settings → Weather & Time → Weather Provider
- Select "Open-Meteo (Free, No API Key)"
- Enter Location:
Sofiaor42.6977,23.3219 - Leave API Key empty (not needed)
- Set Update Interval:
5(minutes) - Click "Save"
✅ No API key needed, works immediately
Option B: Use OpenWeather (More features)
Settings → Weather & Time → Weather Provider
- Select "OpenWeather (Requires API Key)"
- The API Key field becomes visible
- Get free API key from: https://openweathermap.org/api
- Enter your API key
- Enter Location:
Sofiaor42.6977,23.3219 - Set Update Interval:
5(minutes) - Click "Save"
✅ More detailed weather data available
Step 4: Verify Configuration
- Go back to HOME page
- Check:
- ✅ Clock shows correct time and timezone
- ✅ Weather panel displays weather data
- ✅ Weather updates every N minutes (based on interval)
Available Timezones
The settings page includes 18 pre-configured timezones:
| Region | Timezone | Format |
|---|---|---|
| UTC | UTC | Coordinated Universal Time |
| Europe | Europe/London | GMT/BST |
| Europe/Paris | CET/CEST | |
| Europe/Berlin | CET/CEST | |
| Europe/Sofia | EET/EEST (Default for Bulgaria) | |
| Europe/Athens | EET/EEST | |
| Europe/Helsinki | EET/EEST | |
| Europe/Moscow | MSK | |
| Asia | Asia/Dubai | GST |
| Asia/Tokyo | JST | |
| Asia/Shanghai | CST | |
| Asia/Bangkok | ICT | |
| Asia/Hong_Kong | HKT | |
| Australia | Australia/Sydney | AEDT/AEST |
| Americas | America/New_York | EST/EDT |
| America/Chicago | CST/CDT | |
| America/Denver | MST/MDT | |
| America/Los_Angeles | PST/PDT |
Want a different timezone? You can edit data/index.html and add custom timezones using POSIX timezone format.
Weather Providers Explained
Open-Meteo (Free, Recommended)
✅ Pros:
- Completely free
- No API key needed
- Good accuracy
- Open-source API
- No rate limiting concerns
❌ Cons:
- Slightly simpler data format
- Fewer additional features
Setup:
- Provider: "Open-Meteo (Free, No API Key)"
- Location: City name or lat,lon
- No API key needed
Example Locations:
Sofia→ Weather for Sofia, Bulgaria42.6977,23.3219→ Weather for Sofia (coordinates)London→ Weather for London, UK51.5074,-0.1278→ Weather for London (coordinates)
OpenWeather (API Key Required)
✅ Pros:
- More detailed weather data
- More features and options
- Good documentation
- Professional API
❌ Cons:
- Requires free API key registration
- Rate limiting on free tier
- More configuration needed
Setup:
- Get free API key: https://openweathermap.org/api
- Provider: "OpenWeather (Requires API Key)"
- Enter API key in the field
- Location: City name or lat,lon
- Save
Example Locations:
Sofia→ Weather for Sofia, BulgariaLondon→ Weather for London, UK42.6977,23.3219→ Weather for Sofia (coordinates)51.5074,-0.1278→ Weather for London (coordinates)
Data Flow
How Weather Data Flows
WEB UI SETTINGS
↓ (User configures)
Save Button → /api/config (POST)
↓
ESP32 Stores Configuration
↓
├─ timeZone
├─ weatherProvider (0=OpenWeather, 1=Open-Meteo)
├─ location
├─ weatherUpdateInterval
└─ apiKey (if OpenWeather)
↓
Configuration Applied Immediately
├─ Timezone updated in system clock
├─ Weather service notified
└─ Next weather fetch uses new settings
↓
Every N Minutes (based on interval)
↓
WeatherService::forceUpdate()
├─ Calls weather API (OpenWeather or Open-Meteo)
├─ Parses response
├─ Updates globalWeather structure
└─ Triggers HOME page refresh
↓
HOME Page Display
├─ Clock shows current time (with timezone)
├─ Weather panel shows conditions
├─ Temperature, humidity, wind displayed
└─ User sees fresh weather data
Configuration Persistence
✅ All settings are saved to device storage
What Happens When You Save
- Settings saved to ESP32 SPIFFS (flash storage)
- Immediately applied without restart needed
- Persist across power cycles
- Survive device reboots
What Gets Saved
- ✅ Timezone
- ✅ Weather provider selection
- ✅ Location
- ✅ Weather update interval
- ✅ API key (encrypted storage)
What's NOT Saved
- ❌ Current weather data (fetched fresh on each update)
- ❌ Temporary cache (cleared on reboot)
Troubleshooting
Weather Data Not Showing
Problem: Weather panel is empty or shows "-- °"
Solutions:
- ✅ Check timezone is set correctly
- ✅ Verify location is entered
- ✅ Check weather provider is selected
- ✅ If using OpenWeather, verify API key is correct
- ✅ Check WiFi connection is active
- ✅ Wait 5 minutes for first weather update (or manually refresh)
Manual Refresh:
- Dashboard page → Look for "Refresh Weather" button
- Or wait for automatic 5-minute update
Time Zone Not Updating
Problem: Clock shows wrong time after changing timezone
Solution:
- Save the timezone setting
- Device should update immediately
- If not, restart the device
Manual Update:
- Go to Settings
- Select new timezone
- Click Save
- Should take effect in seconds
API Key Not Working (OpenWeather)
Problem: "Invalid API key" error or no weather data
Solutions:
- ✅ Verify API key from https://openweathermap.org/api
- ✅ Check if key is active (not expired)
- ✅ Ensure it's the correct API key (free tier)
- ✅ Wait a few minutes - new keys take time to activate
- ✅ Check internet connectivity
Get New API Key:
- Visit https://openweathermap.org/api
- Sign up (free)
- Generate API key
- Copy full key
- Paste into web UI settings
Location Not Found
Problem: Weather shows "Location error" or invalid location
Solutions:
- ✅ Use city name:
Sofia,London,New York - ✅ Or use coordinates:
42.6977,23.3219(latitude,longitude) - ✅ Check spelling is correct
- ✅ Try different location format
- ✅ Check internet connectivity
Format Examples:
- ✅ City:
Sofia - ✅ City with country:
Sofia, Bulgaria - ✅ Coordinates:
42.6977,23.3219 - ✅ Decimal coordinates:
42.697,-23.321
Default Configuration
If you reset all settings to defaults:
Timezone: UTC
Weather Provider: Open-Meteo (1)
Location: (empty)
API Key: (empty)
Update Interval: 5 minutes
To restore custom settings:
- Go to Settings
- Reconfigure weather and timezone
- Click Save
- Settings will persist
Advanced: Manual API Configuration
If you need to add custom timezones or modify endpoints:
Edit: data/index.html
Add Custom Timezone
Find the timezone select element and add:
<option value="Your/Timezone">Your/Timezone (Description)</option>
POSIX Timezone Format (for reference):
UTC= UTC timeEST5EDT= Eastern US timeCET-1CEST= Central European time- Format:
STDoffsetDST(see https://wikipedia.org/wiki/List_of_tz_database_time_zones)
Modify Update Interval Range
Find the weather-update-interval input:
<input type="number" id="weather-update-interval" min="5" max="60" value="5">
Change min and max values as needed.
Features Unlocked by These Settings
Accurate Weather Display
✅ Weather data now fetches with correct location
✅ Temperature displays in correct format
✅ Weather icons update based on conditions
Timezone Awareness
✅ Clock shows correct local time
✅ Respects daylight saving time automatically
✅ Device knows what day/time it is globally
Smart Updates
✅ Configure how often weather refreshes
✅ Balance between accuracy and bandwidth
✅ Settings apply immediately without restart
Summary
| Feature | Status | Location |
|---|---|---|
| Timezone Settings | ✅ Added | Settings → Weather & Time |
| Weather Provider | ✅ Added | Settings → Weather & Time |
| Location Config | ✅ Added | Settings → Weather & Time |
| API Key Input | ✅ Added | Settings → Weather & Time |
| Update Interval | ✅ Added | Settings → Weather & Time |
| Pre-Configured Timezones | ✅ 18 zones | Timezone dropdown |
| Configuration Persistence | ✅ Saves to device | Auto-saved |
| Immediate Application | ✅ No restart needed | Applied on Save |
Next Steps
- ✅ Access web UI:
http://[device-ip]/ - ✅ Go to Settings → Weather & Time
- ✅ Configure your timezone
- ✅ Configure weather provider
- ✅ Click Save
- ✅ Check HOME page - weather should display!
Status: 🟢 Weather & Timezone Settings Now Available in Web UI