{"id":34599227,"url":"https://github.com/niradler/github-dashboard-esp32-epaper","last_synced_at":"2026-05-25T18:32:27.068Z","repository":{"id":324624432,"uuid":"1097850389","full_name":"niradler/github-dashboard-esp32-epaper","owner":"niradler","description":null,"archived":false,"fork":false,"pushed_at":"2025-11-17T00:21:01.000Z","size":243,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-11-17T02:22:12.650Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/niradler.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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-11-16T23:28:20.000Z","updated_at":"2025-11-17T00:21:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/niradler/github-dashboard-esp32-epaper","commit_stats":null,"previous_names":["niradler/github-dashboard-esp32-epaper"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/niradler/github-dashboard-esp32-epaper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niradler%2Fgithub-dashboard-esp32-epaper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niradler%2Fgithub-dashboard-esp32-epaper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niradler%2Fgithub-dashboard-esp32-epaper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niradler%2Fgithub-dashboard-esp32-epaper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/niradler","download_url":"https://codeload.github.com/niradler/github-dashboard-esp32-epaper/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/niradler%2Fgithub-dashboard-esp32-epaper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33488813,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T14:31:05.219Z","status":"ssl_error","status_checked_at":"2026-05-25T14:31:02.878Z","response_time":57,"last_error":"SSL_read: 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":[],"created_at":"2025-12-24T12:07:47.918Z","updated_at":"2026-05-25T18:32:27.050Z","avatar_url":"https://github.com/niradler.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitHub Notification Dashboard - E-Paper Edition\n\nA smart notification dashboard for GitHub notifications running on ESP32 with an e-paper display. This device fetches your GitHub notifications and displays them in a clean, categorized format on a 2.13\" e-paper display.\n\n## Features\n\n- **Multi-Screen Dashboard**: Three screens accessible via button press:\n  - **Notifications**: Real-time unread GitHub notifications with category breakdown\n  - **Profile**: GitHub profile statistics (repos, stars, open PRs, followers)\n  - **PR Overview**: Your open pull requests with merge status, CI checks, and review state - quickly identify PRs ready to merge\n- **Smart Screen Cycling**: Button on GPIO 39 cycles through screens with 4-second debounce\n- **Efficient API Usage**:\n  - REST API for notifications\n  - GraphQL API for profile and PR overview (minimized payload size)\n- **Category Breakdown**: Organizes notifications by type:\n  - Review Requests\n  - Mentions\n  - Assignments\n  - Other notifications\n- **E-Paper Display**: Low-power 2.13\" black \u0026 white e-paper screen\n- **Optimized Refresh**: Only updates display when data actually changes\n- **Deep Sleep Support**: Energy-efficient operation with configurable wake intervals\n- **Web Interface**: Configure WiFi, API tokens, and settings via browser\n- **WiFi Auto-Connect**: Remembers your WiFi credentials\n- **Persistent Storage**: All settings saved to flash memory\n\n## Hardware Requirements\n\n- **ESP32** development board\n- **GxEPD2_213_BN** 2.13\" e-paper display (250x122 pixels)\n  - Tested with: [LilyGo T5 2.13\" E-Paper](https://lilygo.cc/products/t5-2-13inch-e-paper)\n- **Wiring**:\n  - CS: GPIO 5\n  - DC: GPIO 17\n  - RST: GPIO 16\n  - BUSY: GPIO 4\n- **Optional Buttons**:\n  - Refresh: GPIO 0\n  - Wake: GPIO 39\n- **Status LED**: GPIO 2\n\n## Getting Started\n\n### Initial Setup\n\n1. Upload the firmware to your ESP32\n2. The device will start in **Setup Mode** (creates WiFi AP)\n3. Connect to WiFi network: `NotificationHub` (password: `configure`)\n4. Open browser and navigate to: `http://192.168.4.1`\n\n### Configuration\n\n#### WiFi Setup\n\n1. Go to the **WiFi** tab in the web interface\n2. Enter your WiFi SSID and password\n3. Set an admin password for security\n4. Click **Save WiFi** (device will reboot)\n\n#### GitHub Integration\n\n1. Generate a GitHub Personal Access Token:\n   - Go to GitHub Settings → Developer settings → Personal access tokens\n   - Create a **Classic token** with the following scopes:\n     - `notifications` - For fetching notifications\n     - `read:user` - For profile and activity data\n2. In the web interface, go to **Providers** tab\n3. Enable GitHub provider\n4. Enter your GitHub username\n5. Paste your token\n6. Enter admin password and click **Save Providers**\n\n#### Settings\n\n- **Update Interval**: How often to check for notifications (default: 10 minutes)\n- Adjust in the **Settings** tab\n\n## Usage\n\n### Display Screens\n\nThe device has three screens that you can cycle through by pressing the button on GPIO 39:\n\n#### 1. Notifications Screen\n\n![Notifications Screen](screenshots/notifications.jpg)\n\n- GitHub logo\n- Total notification count\n- Category breakdown with icons:\n  - 🔍 Reviews\n  - @ Mentions\n  - 👤 Assignments\n  - ! Other\n- Footer with WiFi SSID and connection status\n\n#### 2. Profile Screen\n\n![Profile Screen](screenshots/profile.jpg)\n\n- GitHub logo\n- Profile title\n- Statistics with icons:\n  - 📦 Public Repos\n  - ⭐ Total Stars (across all repos)\n  - 🔀 Open Pull Requests\n  - 👥 Followers\n- Footer with WiFi SSID and connection status\n\n#### 3. PR Overview Screen\n\n![PR Overview Screen](screenshots/activity.jpg)\n\n- GitHub logo\n- PR Overview title\n- Your open pull requests with:\n  - ✅ Mergeable status\n  - 🔄 CI/Check status\n  - 👀 Review state\n  - 📝 PR title and number\n- Helps quickly identify PRs ready to merge without opening GitHub\n- Footer with WiFi SSID and connection status\n\n### Screen Cycling\n\n- Press the **button on GPIO 39** to cycle through screens:\n  - Notifications → Profile → PR Overview → (back to) Notifications\n- Button has **4-second debounce** to prevent accidental double-presses\n- **Instant visual feedback**: Screen switches immediately, then fetches fresh data\n- Each screen only updates its data when active (saves API calls)\n\n### Manual Refresh\n\n- Press the **Refresh button** (GPIO 0) to force update current screen\n- Press the **Screen Cycle button** (GPIO 39) to switch screens (also refreshes data)\n- Use the **Refresh Now** button in the web interface\n\n### Web Interface\n\nThe device provides a full-featured web interface for configuration and monitoring:\n\n#### Dashboard Tab\n\n![Dashboard](screenshots/admin-dashboard.png)\n\n- Real-time connection status\n- Current notification count\n- Manual refresh button\n\n#### WiFi Tab\n\n![WiFi Configuration](screenshots/admin-wifi.png)\n\n- WiFi SSID and password configuration\n- Admin password setup\n- Network settings\n\n#### Providers Tab\n\n![Providers Configuration](screenshots/admin-providers.png)\n\n- Enable/disable GitHub provider\n- GitHub API token configuration\n- Provider management\n\n#### Settings Tab\n\n![Settings](screenshots/admin-settings.png)\n\n- Update interval configuration\n- Admin password management\n- System settings\n\n### Web Interface Endpoints\n\n- `GET /` - Main configuration page\n- `GET /api/status` - Current status and notification counts\n- `POST /api/config` - Save WiFi/settings\n- `GET /api/providers` - List configured providers\n- `POST /api/providers` - Update provider settings\n- `POST /api/refresh` - Trigger manual refresh\n- `POST /api/reset` - Factory reset (requires admin password)\n\n## Power Management\n\n### Deep Sleep Mode\n\nWhen enabled (default), the device:\n\n1. Wakes up every N minutes (configurable)\n2. Connects to WiFi\n3. Fetches data for current active screen (Notifications/Profile/PR Overview)\n4. Updates display if data changed\n5. Enters deep sleep\n\n**Wake Sources**:\n\n- Timer (based on update interval)\n- Button press on GPIO 39 (cycles to next screen and updates)\n\n**Web Server Timeout**: Device stays awake for 30 seconds after boot to allow web access, then sleeps\n\n### Smart Display Updates\n\nThe device implements intelligent display refresh logic:\n\n- Only updates display when data actually changes\n- Tracks last displayed values for each screen\n- Prevents unnecessary e-paper refreshes (reduces flicker and extends display life)\n- Each screen maintains its own update state independently\n\n### Disabling Sleep\n\nSet `SLEEP_ENABLED false` in the code to disable deep sleep (useful for debugging)\n\n## Configuration Constants\n\n```cpp\nUPDATE_INTERVAL_MS      = 9 * 60 * 1000  // Main loop interval (deprecated in favor of config)\nGITHUB_MAX_PAGES        = 25              // Max pages to fetch from GitHub\nGITHUB_PER_PAGE         = 13              // Notifications per page\nJSON_BUFFER_SIZE        = 8192            // JSON parsing buffer\nHTTP_TIMEOUT_MS         = 10000           // HTTP request timeout\nWEB_SERVER_TIMEOUT      = 30000           // Stay awake time (ms)\n```\n\n## Default Credentials\n\n**Initial Config** (stored in Preferences):\n\n- WiFi SSID: _(empty - configure in setup mode)_\n- WiFi Password: _(empty - configure in setup mode)_\n- Admin Password: `admin`\n\n**AP Mode** (when not configured):\n\n- SSID: `NotificationHub`\n- Password: `configure`\n\n**⚠️ WARNING**: Change default admin password immediately in production!\n\n## Serial Monitor Output\n\nConnect at **115200 baud** to see detailed logs:\n\n- System initialization\n- WiFi connection status\n- API requests and responses\n- Notification parsing\n- Display updates\n- Power management events\n\n## Troubleshooting\n\n### WiFi Connection Issues\n\n- Verify SSID and password in web interface\n- Check signal strength (device may be too far from router)\n- Monitor Serial output for connection errors\n\n### GitHub API Issues\n\n- **401 Error**: Invalid token - regenerate GitHub token\n- **403 Error**: Rate limited - wait or check token permissions\n- **Empty Response**: Network issue or API down\n\n### Display Not Updating\n\n- Check wiring connections (CS, DC, RST, BUSY)\n- Verify `ENABLE_DISPLAY` is defined\n- Look for display errors in Serial monitor\n\n### Memory Issues\n\n- Reduce `GITHUB_MAX_PAGES` if running out of heap\n- Monitor \"Free Heap\" in Serial output\n- Consider reducing `JSON_BUFFER_SIZE`\n\n### Factory Reset\n\n1. Go to web interface\n2. Use `/api/reset` endpoint\n3. Provide admin password\n4. Device will clear all settings and reboot\n\n## Dependencies\n\n### Arduino Libraries\n\n- **WiFi.h** - ESP32 WiFi support\n- **WiFiClientSecure.h** - HTTPS/TLS connections\n- **HTTPClient.h** - HTTP client for API requests\n- **WebServer.h** - Configuration web interface\n- **Preferences.h** - Non-volatile storage\n- **ArduinoJson** - JSON parsing and serialization\n- **GxEPD2_BW** - E-paper display driver\n- **U8g2_for_Adafruit_GFX** - Advanced font rendering\n\nAll libraries can be installed via Arduino Library Manager.\n\n## Development Tools\n\nThis project was built using:\n\n- **[Arduino MCP Server](https://github.com/niradler/arduino-mcp)** - Model Context Protocol server for Arduino CLI interactions, enabling AI-assisted development with seamless board detection, sketch compilation, and serial monitoring.\n\n## Contributing\n\nContributions are welcome! This project is open source and we appreciate:\n\n- Bug reports and fixes\n- Feature suggestions and implementations\n- Documentation improvements\n- Hardware compatibility reports\n\nSee `llm.md` for detailed development documentation.\n\n## License\n\nMIT License - Feel free to use, modify, and distribute this project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniradler%2Fgithub-dashboard-esp32-epaper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fniradler%2Fgithub-dashboard-esp32-epaper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniradler%2Fgithub-dashboard-esp32-epaper/lists"}