{"id":15043631,"url":"https://github.com/jackd248/clockwork-ai","last_synced_at":"2025-09-26T06:30:35.340Z","repository":{"id":223326104,"uuid":"759929665","full_name":"jackd248/clockwork-ai","owner":"jackd248","description":"Simple DIY clock project to generate AI poems by current time.","archived":false,"fork":false,"pushed_at":"2024-12-09T10:31:58.000Z","size":6968,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-12-09T11:35:15.737Z","etag":null,"topics":["ai","chatgpt","openai","python","raspberrypi","waveshare","waveshare-eink"],"latest_commit_sha":null,"homepage":"https://jackd248.github.io/clockwork-ai/","language":"Python","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/jackd248.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}},"created_at":"2024-02-19T15:56:24.000Z","updated_at":"2024-12-09T10:32:02.000Z","dependencies_parsed_at":"2024-05-17T13:44:23.660Z","dependency_job_id":null,"html_url":"https://github.com/jackd248/clockwork-ai","commit_stats":null,"previous_names":["jackd248/clockwork-1","jackd248/clockwork-ai"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackd248%2Fclockwork-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackd248%2Fclockwork-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackd248%2Fclockwork-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackd248%2Fclockwork-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jackd248","download_url":"https://codeload.github.com/jackd248/clockwork-ai/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234293821,"owners_count":18809579,"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":["ai","chatgpt","openai","python","raspberrypi","waveshare","waveshare-eink"],"created_at":"2024-09-24T20:49:21.676Z","updated_at":"2025-09-26T06:30:29.531Z","avatar_url":"https://github.com/jackd248.png","language":"Python","readme":"# clockwork/ai\n\n![clockwork intro](img/intro.jpg)\n\n\u003e\n\u003e This project is inspired by creative mind Matt Web and his beautiful [Poem/1](https://poem.town/) clock. \n\u003e\n\nSimple DIY clock project to generate AI poems by current time using a raspberry pi zero + e-ink display.\n\n![clockwork demo](img/demo.jpg)\n\n- [General](#general)\n    * [Reuse](#reuse)\n    * [Lock](#lock)\n- [Installation](#installation)\n    * [Hardware](#hardware)\n    * [Preparation](#preparation)\n    * [Prerequirements](#prerequirements)\n    * [Software](#software)\n    * [Permanent setup](#permanent-setup)\n- [Configuration](#configuration)\n    * [Hardware support](#hardware-support)\n    * [Prompt](#prompt)\n    * [Validation](#validation)\n    * [Show time](#show-time)\n    * [Display rotation](#display-rotation)\n    * [Coincidence](#coincidence)\n    * [Font](#font)\n    * [Debug](#debug)\n- [Development](#development)\n- [Project log](#project-log)\n  * [Concept](#concept)\n  * [Prototype](#prototype)\n- [Disclaimer](#disclaimer)\n\n## General\n\nCurrently forced for german language, but can be adjusted for custom usage, see [Configuration](#Configuration). \n\n### Features\n\n- generate an AI poem about the current time and display them on an e-ink display\n- display custom messages on the e-ink display\n- clear the e-ink display\n\n### Demo\n\nSee a live demo here: https://jackd248.github.io/clockwork-ai/.\n\n### Commands\n\nGeneral command line functionalities of the python app:\n\n- `python3 clockwork` - generates ai poem of current time\n- `python3 clockwork 09:41` - generates ai poem of a requested time\n- `python3 clockwork clear` - clear display\n- `python3 clockwork demo` - demo poems to display\n- `python3 clockwork display \u003ctext\u003e` - display custom text\n- `python3 clockwork ask \u003cquestion\u003e` - ask custom question to ai and display answer\n\nThe `--dry-run` option prevent the display process on the e-ink display and generates images instead under `var/debug/`.\n\n### Reuse\n\nThe fs component stores the received poems to json files, e.g. `var/storage/12/1245.json`. If the environment variable `CLOCKWORK_REUSE` is set to true, the algorithm randomly uses stored poems instead of calling the api to reuse them. \n\nThe script also checks if an internet connection is available to call the api. If not so, the script will show a stored poem if available for some kind of offline usage. \n\n### Lock\n\nThe file lock prevents the multiple execution of the python script, because this can result in display issues. \n\n## Installation\n\n### Hardware\n\n- raspberry pi zero wh\n- [waveshare 2.13inch e-Paper](https://www.waveshare.com/wiki/2.13inch_e-Paper_HAT) or [waveshare 7.5inch e-Paper](https://www.waveshare.com/wiki/7.5inch_e-Paper_HAT)\n\n\n\u003cimg src=\"img/insight.jpg\" alt=\"clockwork prototype\" width=\"400\"/\u003e\n\n### Preparation\n\n- based on the waveshare [tutorial](https://www.waveshare.com/wiki/2.13inch_e-Paper_HAT_Manual)\n  - see initialization and installation instructions for the raspberry and the needed libraries\n\n\n### Prerequirements\n\n- get an api key from openai: https://platform.openai.com/api-keys\n\n### Software\n\n```bash\n# get python app\ngit clone https://github.com/jackd248/clockwork-ai.git\ncd clockwork-ai\n# install python requirements\npip3 install -r requirements.txt\n# prepare settings\ncp .env.dist .env\n# run demo\npython3 clockwork demo\n```\n\nYou need to store your openai api key as environment variable within the `.env` file:\n\n```dotenv\nOPENAI_API_KEY='xxx'\n```\n\nRun the clockwork script to generate a poem:\n\n```bash\npython3 clockwork\n```\n\n### Permanent setup\n\nSet up a periodic cronjob to update the poem e.g. every minute:\n\n```bash\ncrontab -e\n```\n\n```cronexp\n* * * * * python3 /path/to/clockwork/dir clockwork\n```\n\nOr set up a cronjob to update the poem on daytime:\n\n```cronexp\n* 06-23 * * * python3 /path/to/clockwork/dir clockwork\n10 23 * * * python3 /path/to/clockwork/dir clockwork clear\n```\n\n\u003e Note that you should clear the e-ink screen to avoid display issues.\n\n\n\u003e I would suggest to clear the screen if the display is not used for a longer time, e.g. at night.\n\n\n## Configuration\n\nAll further configuration options are available within your `.env` file.\n\nThe 3.5 model is stored as default model for the openai api because it's the cheapest one so far. If you want to use another model, adjust the `OPENAI_API_MODEL` environment variable. See https://platform.openai.com/docs/models.\n\n### Hardware support\n\nCurrently, the both displays are supported:\n\n- 2.13inch e-Paper: `epd2in13`\n- 7.5inch e-Paper: `epd7in5`\n\nChange the `CLOCKWORK_DISPLAY` environment variable to the used hardware component.\n\n### Prompt\n\nYou can adjust the default openai prompt to adjust the poem results or the desired language if you edit the environment variable `OPENAI_CLOCKWORK_SYSTEM_PROMPT` within your `.env` file:\n```dotenv\nOPENAI_CLOCKWORK_PROMPT=\"You are a clock that shows the time in a two-line poem.\"\n```\n\n### Validation\n\nTo improve the poem results by the ai, you can validate the response from the api again by the ai enabling the environment variable `CLOCKWORK_VALIDATE`. Therefore, a second request is sent to openai with the initial conversation messages and additional the `OPENAI_CLOCKWORK_VALIDATION_PROMPT`. \n\n### Show time\n\nIf you want to compare current time with the generated poem, activate the `CLOCKWORK_SHOW_TIME` environment variable to display the time in the bottom right corner.\n\n### Display rotation\n\nUse the `CLOCKWORK_ROTATE` environment variable to define the degree of rotation, e.g. 180.\n\n### Font\n\nDownload a custom TrueType font (e.g. at https://fonts2u.com/), save them within the `font` directory and adjust the `CLOCKWORK_FONT` environment variable to adjust the displayed font.\n\n### Coincidence\n\nTo influence the random function for choosing between api request and storage, set and increase the `CLOCKWORK_RANDOM_FACTOR` environment variable with an integer. Normally, it's 1 (api) to 1 (storage) as ratio. To increase the usage of the storage increase the env var, e.g. to 8 for 1 (api) to 8 (storage).\n\n### Debug\n\nUse the environment variable `CLOCKWORK_DEBUG` to enable file log for more debug information under e.g. `var/log/app_2024-02-23.log`. \n\nAlso, a little dot is displayed in the upper right corner if a poem is reused instead of calling the openai api.\n\n## Development\n\nUse [docker](https://www.docker.com/) and [docker-compose](https://docs.docker.com/compose/) for a development context to work on the app.\n\nBuild docker container:\n\n```bash\ndocker compose up --build\n```\n\nRun python app within dev service:\n\n```bash\ndocker-compose run dev\n$ python3 clockwork demo --dry-run\n$ python3 clockwork display \"Test\" --dry-run\n```\n\nUse pylint to improve code quality:\n```bash\ndocker-compose run dev\n$ pylint clockwork\n```\n\n## Project log\n\n### Concept\n\nThis graphic shows the request chain for generating the AI poem by the chatgpt api:\n\n\u003cimg src=\"img/concept.png\" alt=\"clockwork concept\" width=\"400\"/\u003e\n\n### Prototype\n\nThe following pictures show the iterations of the prototype.\n\n*Version 1:* simple prototype with a raspberry pi zero and the 2.13inch e-Paper display\n\n\u003cimg src=\"img/version1.jpg\" alt=\"version1\" width=\"400\"/\u003e\n\n*Version 2:* using a pwnagotchi case\n\n\u003cimg src=\"img/version2.jpg\" alt=\"version2\" width=\"400\"/\u003e\n\n*Version 3:* using a bigger 7.5inch e-Paper display and simple ikea picture frame\n\n\u003cimg src=\"img/version3.jpg\" alt=\"version3\" width=\"400\"/\u003e\n\n## Disclaimer\n\nThe waveshare libraries are part of the [e-Paper](https://github.com/waveshareteam/e-Paper) repository. ","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjackd248%2Fclockwork-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjackd248%2Fclockwork-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjackd248%2Fclockwork-ai/lists"}