{"id":31588478,"url":"https://github.com/sfrechette/weather-micro-station","last_synced_at":"2026-04-07T07:47:08.357Z","repository":{"id":317400037,"uuid":"1066374828","full_name":"sfrechette/weather-micro-station","owner":"sfrechette","description":"A modular, high-performance weather display system for the LILYGO T-Display S3, featuring real-time weather data from OpenWeatherMap API with smooth animations and professional UI.","archived":false,"fork":false,"pushed_at":"2026-01-14T19:20:06.000Z","size":383,"stargazers_count":15,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-07T07:47:01.813Z","etag":null,"topics":["arduino","c","cpp","esp32","esp32-s3","lilygo","lilygo-tdisplay-s3","openweathermap-api","platformio","ticker","weather","weather-api"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sfrechette.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY_SETUP.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-29T11:56:38.000Z","updated_at":"2026-03-01T21:25:47.000Z","dependencies_parsed_at":null,"dependency_job_id":"809a4aea-a890-4bfe-b0b1-f84eb326fad6","html_url":"https://github.com/sfrechette/weather-micro-station","commit_stats":null,"previous_names":["sfrechette/weather-micro-station"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/sfrechette/weather-micro-station","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfrechette%2Fweather-micro-station","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfrechette%2Fweather-micro-station/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfrechette%2Fweather-micro-station/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfrechette%2Fweather-micro-station/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sfrechette","download_url":"https://codeload.github.com/sfrechette/weather-micro-station/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sfrechette%2Fweather-micro-station/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31504897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arduino","c","cpp","esp32","esp32-s3","lilygo","lilygo-tdisplay-s3","openweathermap-api","platformio","ticker","weather","weather-api"],"created_at":"2025-10-06T02:09:49.728Z","updated_at":"2026-04-07T07:47:08.347Z","avatar_url":"https://github.com/sfrechette.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Weather Micro Station for T-Display S3\n\nA modular, high-performance weather display system for the LILYGO T-Display S3, featuring real-time weather data from OpenWeatherMap API with smooth animations and professional UI.\n\n![Hardware](https://img.shields.io/static/v1?label=Hardware\u0026message=LilyGO%20T-Display%20S3\u0026color=red)\n![ESP32-S3](https://img.shields.io/badge/ESP32-S3-blue)\n![Platform](https://img.shields.io/badge/Platform-PlatformIO-orange)\n![License](https://img.shields.io/badge/License-MIT-green)\n\n![Lilygo T-Display-S3 Display](docs/images/weather-micro-station.JPEG)\n\nInspired from Volos Projects (YouTube): [Let's make Cheap Internet Weather Station using LilyGo T-Display S3 and OpenWeatherMap.org](https://youtu.be/VntDY9Mg7T0?si=NuUndaefoagmdGl1)\n\n## Features\n\n- **Real-time Weather Data**: Fetches current weather from OpenWeatherMap API every 3 minutes\n- **Weather Icons**: Visual weather condition icons (18 different conditions) displayed on screen\n- **Smooth Animations**: 40 FPS scrolling ticker with professional transitions\n- **Modular Architecture**: Clean, maintainable code structure with separate classes\n- **Secure Credentials**: API keys and WiFi credentials stored in `secrets.h`\n- **Performance Optimized**: Font caching, message buffering, and memory management\n- **Brightness Control**: Hardware button support for display brightness adjustment\n- **Time Synchronization**: Automatic NTP sync every 30 minutes\n- **Error Recovery**: Robust WiFi reconnection and API error handling\n\n## Quick Start\n\n### Prerequisites\n\n- LILYGO T-Display S3 board\n- PlatformIO IDE or Arduino IDE\n- OpenWeatherMap API key (free at [openweathermap.org](https://openweathermap.org/api))\n\n### Installation\n\n1. **Clone the repository:**\n\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd weather-micro-station\n   ```\n\n2. **Create secrets file:**\n\n   ```bash\n   cp include/secrets_template.h include/secrets.h\n   ```\n\n3. **Configure your credentials in `include/secrets.h`:**\n\n   ```c\n   #define OPENWEATHERMAP_API_KEY \"your_api_key_here\"\n   #define WIFI_SSID \"your_wifi_network\"\n   #define WIFI_PASSWORD \"your_wifi_password\"\n   #define OPENWEATHERMAP_CITY \"Your_City\"\n   ```\n\n4. **Build and upload:**\n\n   ```bash\n   pio run --target upload\n   ```\n\n## Architecture Overview\n\n### Project Structure\n\n```\nweather-micro-station/\n├── src/\n│   ├── main.cpp              # Main application entry point\n│   ├── config.h              # Configuration (timing, units, timezone)\n│   ├── weather_data.h        # Data structures and types\n│   ├── weather_display.h/cpp # Display management and UI rendering\n│   └── weather_api.h/cpp     # API client and network operations\n├── include/\n│   ├── secrets.h             # Secure credentials (not in git)\n│   ├── secrets_template.h    # Template for secure credentials\n│   ├── weather_icons.h       # Weather condition icons (RGB565)\n│   └── *.h                   # Font files\n├── docs/\n│   ├── execution_flow.md     # Detailed execution flow documentation\n│   └── images/               # Documentation images\n├── icons/                    # Source PNG files for weather icons\n├── SECURITY_SETUP.md         # Complete security configuration guide\n└── tools/\n    ├── generate_callgraph.py # Call graph generator\n    └── trace_functions.h     # Runtime function tracing\n```\n\n### Key Components\n\n| Component | Purpose | Key Features |\n|-----------|---------|--------------|\n| **WeatherDisplay** | UI rendering and animation | 40 FPS updates, font caching, scrolling ticker |\n| **WeatherAPI** | Network and API operations | HTTP client, JSON parsing, error handling |\n| **WeatherData** | Data structures | Weather info, display state, configuration |\n| **Main Loop** | Orchestration | Timing control, state management |\n\n## Execution Flow\n\n[View detail Weather Station Execution Flow Analysis](https://github.com/sfrechette/weather-micro-station/blob/master/docs/execution_flow.md)\n\n### Startup Sequence (10-15 seconds)\n\n```mermaid\ngraph TD\n    A[Power On/Upload] --\u003e B[Serial Init]\n    B --\u003e C[Display Init]\n    C --\u003e D[WiFi Connection]\n    D --\u003e E[Time Sync]\n    E --\u003e F[Show 'Fetching data...']\n    F --\u003e G[Initial API Call]\n    G --\u003e H[Update Display]\n    H --\u003e I[Enter Main Loop]\n```\n\n### Main Loop (Continuous at 40Hz)\n\n```mermaid\ngraph TD\n    A[Loop Start] --\u003e B{25ms passed?}\n    B --\u003e|No| J[yield]\n    B --\u003e|Yes| C[Update Animation]\n    C --\u003e D{3 minutes passed?}\n    D --\u003e|No| G[Draw Display]\n    D --\u003e|Yes| E[API Fetch Sequence]\n    E --\u003e F[Update Data]\n    F --\u003e G\n    G --\u003e H[Handle Buttons]\n    H --\u003e J\n    J --\u003e A\n```\n\n### API Fetch Sequence (Every 3 minutes)\n\n1. **Clear Animation** → Reset scrolling position\n2. **Show \"Fetching data...\"** → 2-second display\n3. **HTTP API Call** → OpenWeatherMap request\n4. **Parse JSON** → Extract weather data\n5. **Update Display** → Fresh animation with new data\n\n## Configuration\n\nAll configuration is centralized in `src/config.h` for easy customization.\n\n### Unit System (`config.h`)\n\n```c\n// Set to true for metric (°C, km/h, km), false for imperial (°F, mph, mi)\n#define USE_METRIC_UNITS true\n```\n\n### Timezone (`config.h`)\n\n```c\n// Common examples:\n//   Eastern US:  GMT_OFFSET = -5,  TZ = \"EST5EDT,M3.2.0/2,M11.1.0/2\"\n//   Pacific US:  GMT_OFFSET = -8,  TZ = \"PST8PDT,M3.2.0/2,M11.1.0/2\"\n//   UK/London:   GMT_OFFSET = 0,   TZ = \"GMT0BST,M3.5.0/1,M10.5.0/2\"\n//   Europe:      GMT_OFFSET = 1,   TZ = \"CET-1CEST,M3.5.0,M10.5.0/3\"\n//   Japan:       GMT_OFFSET = 9,   TZ = \"JST-9\"\n\n#define GMT_OFFSET_HOURS -5\n#define DAYLIGHT_SAVING_ENABLED 1\n#define TIMEZONE_STRING \"EST5EDT,M3.2.0/2,M11.1.0/2\"\n```\n\n### Timing Settings (`config.h`)\n\n```c\n#define UPDATE_INTERVAL_MS 180000      // 3 minutes - API calls\n#define SYNC_INTERVAL_UPDATES 10       // 30 minutes - time sync\n#define ANIMATION_START_POSITION 100   // Scrolling start position\n```\n\n### Weather Data Format\n\nThe scrolling ticker displays (units adjust based on `USE_METRIC_UNITS`):\n\n```\n\"... [description], visibility is [X] km, wind of [Y] km/h, last updated at [HH:MM:SS] ...\"\n```\n\n### Display Layout\n\n- **Left Panel**: Time, date, temperature, \"Micro Station\" branding\n- **Right Panel**: Weather icon (18 different conditions), humidity, pressure, wind, clouds, visibility\n- **Bottom Ticker**: Scrolling weather summary with real-time updates\n\n### Weather Icons\n\nThe app includes **18 weather condition icons** (9 in reality, using same icon for day(d) and night(n)) that automatically display based on the current weather:\n\n- **Clear sky** (01d/01n)\n- **Few clouds** (02d/02n)\n- **Scattered clouds** (03d/03n)\n- **Broken clouds** (04d/04n)\n- **Shower rain** (09d/09n)\n- **Rain** (10d/10n)\n- **Thunderstorm** (11d/11n)\n- **Snow** (13d/13n)\n- **Mist** (50d/50n)\n\nIcons are 24x24 pixels, stored in RGB565 format, and automatically selected based on the OpenWeatherMap API response. Day and night variants are supported.\n\n## Development Tools\n\n### Function Call Tracing\n\nAdd to your code for runtime analysis:\n\n```cpp\n#include \"tools/trace_functions.h\"\n\nvoid myFunction() {\n    TRACE_FUNCTION();              // Basic tracing\n    MONITOR_PERFORMANCE(\"myFunc\"); // Performance monitoring\n    TRACK_CALL_STACK();           // Call stack depth\n    // ... your code\n}\n```\n\n### Call Graph Generation\n\nGenerate visual call graphs:\n\n```bash\npython3 generate_callgraph.py \u003e callgraph.md\n```\n\n### Static Analysis\n\nRun comprehensive code analysis:\n\n```bash\npio check --verbose\n```\n\n## Performance Metrics\n\n| Metric | Value | Notes |\n|--------|--------|-------|\n| **Display FPS** | 40 Hz | Smooth animation |\n| **API Calls** | Every 3 minutes | Rate limit compliant |\n| **Memory Usage** | ~85% heap | Optimized buffers |\n| **WiFi Reconnect** | 30 second timeout | Automatic recovery |\n| **Time Sync** | Every 30 minutes | NTP synchronization |\n\n## Troubleshooting\n\n### Common Issues\n\n**Display not updating:**\n\n- Check WiFi connection (LED indicators)\n- Verify API key in `secrets.h`\n- Monitor serial output for errors\n\n**Scrolling message stuck:**\n\n- API call might be failing\n- Check internet connectivity\n- Verify OpenWeatherMap service status\n\n**Compilation errors:**\n\n- Ensure all font files are in `include/` directory\n- Check `secrets.h` exists and is properly formatted\n- Verify PlatformIO libraries are installed\n\n### Debug Output\n\nEnable detailed logging by monitoring serial output at 115200 baud:\n\n```\n=== STARTUP: Making initial API call ===\nScrolling: ... Fetching data ...\n=== API FETCH SUCCESS ===\nAPI VALUES:\nTemp: 22.1°C | Feels: 24.3°C | Humidity: 65% | Pressure: 1013 hPa\nWind: 11.1 km/h | Clouds: 75% | Visibility: 10.0 km | few clouds\nUpdated: 14:23:45\n```\n\n## Security Notes\n\n- **Never commit `secrets.h`** - Add to `.gitignore` (see `SECURITY_SETUP.md`)\n- **API Key Protection** - Use environment variables in production\n- **WiFi Security** - Ensure WPA2/WPA3 network encryption\n- **HTTPS Only** - All API calls use secure connections\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- **OpenWeatherMap** - Weather data API\n- **LILYGO** - T-Display S3 hardware\n- **TFT_eSPI** - Display library\n- **ArduinoJson** - JSON parsing\n- **ESP32Time** - Real-time clock management\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/sfrechette/weather-micro-station/issues)\n  \n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsfrechette%2Fweather-micro-station","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsfrechette%2Fweather-micro-station","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsfrechette%2Fweather-micro-station/lists"}