{"id":23673598,"url":"https://github.com/0015/fridge-calendar","last_synced_at":"2025-04-11T00:31:54.700Z","repository":{"id":269000569,"uuid":"905558954","full_name":"0015/Fridge-Calendar","owner":"0015","description":"E-Paper Google Calendar Display","archived":false,"fork":false,"pushed_at":"2024-12-21T05:32:59.000Z","size":2115,"stargazers_count":18,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-05T05:03:34.431Z","etag":null,"topics":["diy-project","e-paperdisplay","epdiy","esp32","esp32-idf","esp32-s3","google-calendar-api","iot-application","thatproject"],"latest_commit_sha":null,"homepage":"https://youtu.be/2Iy_9JYkWGs","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/0015.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":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-19T04:35:34.000Z","updated_at":"2025-04-01T17:13:28.000Z","dependencies_parsed_at":"2025-04-11T00:31:34.326Z","dependency_job_id":null,"html_url":"https://github.com/0015/Fridge-Calendar","commit_stats":null,"previous_names":["0015/fridge-calendar"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0015%2FFridge-Calendar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0015%2FFridge-Calendar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0015%2FFridge-Calendar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0015%2FFridge-Calendar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0015","download_url":"https://codeload.github.com/0015/Fridge-Calendar/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248322433,"owners_count":21084334,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["diy-project","e-paperdisplay","epdiy","esp32","esp32-idf","esp32-s3","google-calendar-api","iot-application","thatproject"],"created_at":"2024-12-29T12:30:02.235Z","updated_at":"2025-04-11T00:31:54.680Z","avatar_url":"https://github.com/0015.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fridge Calendar (E-Paper Google Calendar Display)\n\nThis project is an e-paper-based calendar display that integrates with Google Calendar to fetch and display daily events. It uses the ESP32-S3 microcontroller, the EPDiy library for e-paper control, and the Google Calendar API to retrieve event data. The device connects to WiFi for API calls and keeps track of local time for accurate scheduling and updates.\n\n[![Showcase](https://raw.githubusercontent.com/0015/Fridge-Calendar/refs/heads/main/misc/fridge_calendar.jpeg)](https://youtu.be/2Iy_9JYkWGs)\n\n---\n\n## Features\n\n- **9.7-inch Black and White E-Paper Display**: Displays a monthly calendar and upcoming events using the EPDiy library.\n- **WiFi Connectivity**: Required for API calls to fetch Google Calendar events.\n- **Local Time Management**: Synchronizes and maintains local time for accurate scheduling.\n- **Google Calendar Integration**: Fetches events using Google Calendar API in JSON format.\n- **Automatic Daily Updates**: Refreshes the display at 00:10 every day.\n- **Deep Sleep Mode**: Saves power by putting the ESP32 into deep sleep between updates.\n- **Robust Retry Mechanism**: Handles API call failures with a retry mechanism and enters indefinite deep sleep after repeated failures.\n\n---\n\n## Table of Contents\n\n- [Hardware Requirements](#hardware-requirements)\n- [Software Requirements](#software-requirements)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Configuration](#configuration)\n- [System Workflow](#system-workflow)\n- [Troubleshooting](#troubleshooting)\n- [License](#license)\n\n---\n\n## Hardware Requirements\n\n- ESP32-S3 Based, [Epdiy V7 board](https://vroland.github.io/epdiy-hardware/) \n   - Support for high-resolution displays with 16 data lines\n   - Much faster updates thanks to the ESP32S3 SOC and the LCD peripheral\n   - An on-board RTC, LiPo charging   \n- 9.7-inch black and white e-paper display(ED097TC2) compatible with the [EPDiy library](https://github.com/vroland/epdiy)\n- Power supply (battery or USB)\n\n![hardware](https://raw.githubusercontent.com/0015/Fridge-Calendar/refs/heads/main/misc/hardware.jpeg)\n\n---\n\n## Software Requirements\n\n- [ESP-IDF](https://github.com/espressif/esp-idf): ESP32 development framework (v5.3.1)\n- [EPDiy library](https://github.com/vroland/epdiy): For e-paper control\n- [nlohmann/json](https://github.com/nlohmann/json): For JSON parsing\n- Google Calendar API key and OAuth credentials\n   - [Learn about authentication and authorization](https://developers.google.com/workspace/guides/auth-overview)\n   - [How to access Google APIs using OAuth 2.0 in Postman](https://blog.postman.com/how-to-access-google-apis-using-oauth-in-postman/)\n\n---\n\n## Installation\n\n### 1. Clone the Repository\n```bash\ngit clone https://github.com/0015/Fridge-Calendar.git\ncd Fridge-Calendar\n```\n\n### 2. Create a Components Folder\nInside your project directory, create a `components` folder:\n```bash\nmkdir components\n```\n\n### 3. Add EPDiy Library\nClone the [EPDiy](https://github.com/vroland/epdiy) library into the `components` folder:\n```bash\ncd components\ngit clone https://github.com/vroland/epdiy.git\n```\n\n### 4. Install JSON Parsing Library\nInstall the `nlohmann-json` library using the ESP-IDF dependency manager:\n```bash\nidf.py add-dependency \"johboh/nlohmann-json^3.11.3\"\n```\n\n### 5. Configure Project\nSet your WiFi credentials, Google API credentials, and other configurations in `app_config.h`:\n```cpp\n#define WIFI_SSID \"your_wifi_ssid\"\n#define WIFI_PASS \"your_wifi_password\"\n#define CLIENT_ID \"your_client_id\"\n#define CLIENT_SECRET \"your_client_secret\"\n#define ACCESS_TOKEN \"your_access_token\"\n#define REFRESH_TOKEN \"your_refresh_token\"\n#define CALENDAR_IDS \"\u003cmultiple_calendar_ids\u003e\"\n#define TIMEZONE \"your_time_zone\"\n```\n\n### 6. Build and Flash\n```bash\nidf.py build\nidf.py flash\n```\n\n---\n\n## Usage\n\n- Upon powering up, the device connects to WiFi, synchronizes local time, and fetches Google Calendar events.\n- Displays a monthly calendar and a list of upcoming events.\n- Automatically updates at 00:30 every day or after a successful fetch of calendar events.\n- If the API call fails twice in a row, the device enters indefinite deep sleep.\n\n---\n\n## Configuration\n\n### Google Calendar API Setup\n\n1. Go to the [Google Cloud Console](https://console.cloud.google.com/).\n2. Create a new project and enable the **Google Calendar API**.\n3. Create OAuth credentials for your project.\n4. Obtain the API key(Access Token), Refresh Token, client ID, and client secret.\n5. Add the credentials to your `app_config.h` file.\n\n![Renew Access Token](https://raw.githubusercontent.com/0015/Fridge-Calendar/refs/heads/main/misc/renewed_access_token.png)\n\n\n### WiFi Credentials\n\n- Update the WiFi SSID and password in the `app_config.h` file.\n\n---\n\n## System Workflow\n\n### Initialization\n1. Initialize Non-Volatile Storage (NVS) to store state information.\n2. Display a splash screen and progress bar if this is the first run.\n3. Connect to WiFi and synchronize local time.\n\n### Main Operation\n1. Fetch events from Google Calendar using the REST API.\n2. Parse JSON data into a usable format.\n3. Display the calendar and events on the e-paper screen.\n\n### Retry and Sleep Logic\n- On a failed API call:\n  - Increment a retry counter stored in NVS.\n  - Reboot and retry the operation.\n- After two failed attempts:\n  - Enter deep sleep indefinitely to save power.\n- On success:\n  - Reset the retry counter and schedule a wakeup for 00:30 the next day.\n\n---\n\n## Troubleshooting\n\n### Common Issues\n\n1. **WiFi Connection Fails**:\n   - Check your WiFi SSID and password in `app_config.h`.\n   - Ensure the ESP32 is within range of the WiFi router.\n\n2. **Google API Fails**:\n   - Verify your Access Token, Refresh Token and OAuth credentials.\n   - Check if the Google Calendar API is enabled in your Google Cloud Console.\n\n3. **NVS Errors**:\n   - Ensure NVS is initialized properly during startup.\n   - Erase NVS if necessary using `idf.py erase_flash`.\n\n4. **E-paper Display Issues**:\n   - Verify the connection between the ESP32 and e-paper display.\n   - Check if the EPDiy library is installed correctly.\n\n---\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0015%2Ffridge-calendar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0015%2Ffridge-calendar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0015%2Ffridge-calendar/lists"}