{"id":50842802,"url":"https://github.com/t0mer/hebrew-clock","last_synced_at":"2026-06-14T07:34:47.905Z","repository":{"id":364212781,"uuid":"1266752319","full_name":"t0mer/hebrew-clock","owner":"t0mer","description":"ebrew word-clock for e-paper displays — FastAPI server that renders Israel time in natural written Hebrew with weather, date, and analog clock face","archived":false,"fork":false,"pushed_at":"2026-06-12T05:45:32.000Z","size":171,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-12T06:21:18.199Z","etag":null,"topics":["arduino","clock","eink","epaper","esp","esp32","esp32c3","hebrew","hebrew-clock","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/t0mer.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-11T23:23:50.000Z","updated_at":"2026-06-12T05:45:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/t0mer/hebrew-clock","commit_stats":null,"previous_names":["t0mer/hebrew-clock"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/t0mer/hebrew-clock","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t0mer%2Fhebrew-clock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t0mer%2Fhebrew-clock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t0mer%2Fhebrew-clock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t0mer%2Fhebrew-clock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/t0mer","download_url":"https://codeload.github.com/t0mer/hebrew-clock/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/t0mer%2Fhebrew-clock/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34313515,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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","clock","eink","epaper","esp","esp32","esp32c3","hebrew","hebrew-clock","python"],"created_at":"2026-06-14T07:34:46.310Z","updated_at":"2026-06-14T07:34:47.900Z","avatar_url":"https://github.com/t0mer.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hebrew-clock\n\n![hebrew-clock on a Waveshare 7.5\" e-paper display](assets/screenshots/heb-clock.jpeg)\n\nA Hebrew word-clock server that generates 800×480 black-and-white PNG images for e-paper displays. The server expresses the current Israel time in natural written Hebrew, together with an analog clock face, the day/date, and a live weather icon. A companion Arduino sketch drives the image onto a [Waveshare 7.5\" V2 e-paper panel](https://s.click.aliexpress.com/e/_c3SXnojT) via a Seeed XIAO ESP32C3.\n\n---\n\n## How It Works\n\n1. The ESP32 fetches a PNG from the server at a configurable interval.\n2. The server renders the current Israel time as written Hebrew words (e.g. *שֶׁבַע וָרֶבַע בָּעֶרֶב* — \"quarter past seven in the evening\"), draws an analog clock and a weather icon, and returns a 1-bit PNG sized exactly 800×480.\n3. The ESP decodes the PNG in RAM and writes it to the e-paper display using a mix of partial and full refreshes.\n\n---\n\n## Display Modes\n\n### Normal clock\n\nThe main view shows:\n- **Analog clock** at the top centre\n- **Hebrew time** in large text (hour + minute phrase + time-of-day period)\n- **Day name and date** in the bottom-left cell\n- **Time-of-day period** (*בַּבֹּקֶר*, *בָּעֶרֶב*, …) in the centre cell\n- **Weather** (icon + temperature + condition) in the bottom-right cell\n\n![Normal clock — Heebo-Bold, Raanana](assets/screenshots/clock-main-heebo-raanana.png)\n*Heebo-Bold font — Raanana, 22°C partly cloudy*\n\n![Normal clock — NotoSansHebrew-Bold, Tel Aviv](assets/screenshots/clock-main-noto-telaviv.png)\n*NotoSansHebrew-Bold font — Tel Aviv*\n\n![Normal clock — FrankRuhlLibre-Bold, Jerusalem](assets/screenshots/clock-main-frankruh-jerusalem.png)\n*FrankRuhlLibre-Bold font — Jerusalem, 19°C sunny*\n\n### Morning quiet window (06:00 – 07:30)\n\nBetween 06:00 and 07:30 Israel time the display switches to a minimal \"do not disturb\" screen so early risers are not bothered by the full refresh flicker.\n\n![Morning quiet — Heebo-Bold, Raanana](assets/screenshots/clock-heebo-raanana.png)\n*Heebo-Bold font*\n\n![Morning quiet — NotoSansHebrew-Bold, Tel Aviv](assets/screenshots/clock-noto-telaviv.png)\n*NotoSansHebrew-Bold font*\n\n![Morning quiet — FrankRuhlLibre-Bold, Jerusalem](assets/screenshots/clock-frankruh-jerusalem.png)\n*FrankRuhlLibre-Bold font*\n\n### Jewish (Hebrew) calendar mode\n\nWhen `calendar=jewish` is passed, the bottom-left cell shows the full Hebrew date — day numeral, month name, and Hebrew year — fetched from the [hebcal.com](https://www.hebcal.com) converter API and cached for 24 hours.\n\n![Jewish calendar — Heebo-Bold, Raanana](assets/screenshots/clock-jewish.png)\n*Hebrew date: כ״ז בְּסִיוָן תשפ״ו*\n\n### Night / sleep mode\n\nWhen `sleeptime=1` is sent by the ESP (during the configured sleep window), the server returns a dark star-field image with a Hebrew \"time to sleep\" message.\n\n![Night sleep mode](assets/screenshots/clock-sleep.png)\n\n---\n\n## API\n\nThe server exposes a single image endpoint at the root path (also reachable as `/clock` or `/clock.png`).\n\n```\nGET /?font=\u003cname\u003e\u0026sleeptime=\u003c0|1\u003e\u0026location=\u003ccity\u003e\u0026calendar=\u003cgregorian|jewish\u003e\n```\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `font` | `NotoSansHebrew-Bold` | Hebrew font. See [Available Fonts](#available-fonts). |\n| `sleeptime` | `0` | Set to `1` to render the night image. |\n| `location` | `Tel Aviv` | City passed to the weather API. |\n| `calendar` | `gregorian` | `gregorian` for day + Gregorian month; `jewish` for Hebrew date + year (fetched from hebcal.com). |\n\nResponse: `image/png`, 800×480, 1-bit, `Cache-Control: no-cache`.\n\nInteractive API docs: `http://\u003chost\u003e:8765/api/docs`\n\n### Example URLs\n\n```\n# Heebo-Bold, Raanana, normal mode\nhttps://clk.cloudguard.co.il/?font=Heebo-Bold\u0026sleeptime=0\u0026location=Raanana\n\n# Jewish calendar\nhttps://clk.cloudguard.co.il/?font=Heebo-Bold\u0026sleeptime=0\u0026location=Raanana\u0026calendar=jewish\n\n# Night/sleep image\nhttps://clk.cloudguard.co.il/?font=Heebo-Bold\u0026sleeptime=1\n```\n\n---\n\n## Available Fonts\n\n| Font name | Style |\n|-----------|-------|\n| `NotoSansHebrew-Bold` | Clean modern sans-serif (default) |\n| `Heebo-Bold` | Rounded contemporary sans-serif |\n| `FrankRuhlLibre-Bold` | Classic serif |\n| `FrankRuhlLibre` | Classic serif, regular weight |\n| `DavidLibre-Bold` | Traditional Hebrew typeface |\n\nFont files (`.ttf`) must be placed alongside the application (the directory set by the `FONT_DIR` environment variable, default: the project root).\n\n---\n\n## Running with Docker\n\n```yaml\n# docker-compose.yml (already included in the repo)\nservices:\n  hebclk:\n    build: .\n    ports:\n      - \"8765:8765\"\n    environment:\n      PORT: 8765\n      DISPLAY_LAG: 8   # seconds added to displayed time (compensates for refresh delay)\n      LOG_LEVEL: info\n    restart: unless-stopped\n```\n\n```bash\ndocker compose up -d\n```\n\nThe container expects font `.ttf` files and `sleeping.png` to be present at build time (the `Dockerfile` copies `*.ttf sleeping.png*` from the project root into `/app/`).\n\n### Environment variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PORT` | `8765` | Listening port |\n| `DISPLAY_LAG` | `8` | Seconds added to Israel time before rendering (accounts for ePaper refresh time) |\n| `LOG_LEVEL` | `info` | Loguru log level |\n| `FONT_DIR` | app root | Directory containing `.ttf` files |\n\n---\n\n## Running Locally\n\n```bash\npip install -r requirements.txt\nuvicorn app.main:app --host 0.0.0.0 --port 8765\n```\n\n---\n\n## Deploying to Render\n\n[Render](https://render.com) is a managed cloud platform that can run the server for free with zero infrastructure setup.\n\n### Prerequisites — font files\n\nRender deploys directly from the repository, so the Hebrew font `.ttf` files and `sleeping.png` must be committed to the repo root before deploying. Add the files you want to use (any subset is fine; the server falls back gracefully):\n\n```\nNotoSansHebrew-Bold.ttf   ← recommended minimum\nHeebo-Bold.ttf\nFrankRuhlLibre-Bold.ttf\nFrankRuhlLibre.ttf\nDavidLibre-Bold.ttf\nsleeping.png\n```\n\n### Option A — one-click deploy (render.yaml)\n\nThe repo includes a `render.yaml` blueprint. Click the button below, connect your GitHub account, and Render will pre-fill all settings:\n\n[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy)\n\n### Option B — manual setup\n\n1. Log in to [render.com](https://render.com) and click **New → Web Service**.\n2. Connect your GitHub account and select the `hebrew-clock` repository.\n3. Fill in the service settings:\n\n   | Field | Value |\n   |-------|-------|\n   | **Name** | `hebrew-clock` (or any name you like) |\n   | **Runtime** | `Python 3` |\n   | **Build Command** | `pip install -r requirements.txt` |\n   | **Start Command** | `uvicorn app.main:app --host 0.0.0.0 --port $PORT` |\n\n4. Under **Environment Variables**, add:\n\n   | Key | Value | Notes |\n   |-----|-------|-------|\n   | `FONT_DIR` | `.` | Repo root — where the `.ttf` files live |\n   | `DISPLAY_LAG` | `8` | Seconds ahead to render (adjust to match your display's refresh time) |\n   | `LOG_LEVEL` | `info` | |\n\n5. Set the **Health Check Path** to `/health`.\n6. Click **Create Web Service**. Render will build and deploy; the service URL appears in the dashboard.\n\n### Pointing the ESP32 at Render\n\nOnce the service is live, copy its URL from the Render dashboard (e.g. `https://hebrew-clock.onrender.com`) and paste it into the **Image URL** field in the [ePaper config UI](epaper.md).\n\n\u003e **Free-tier note:** Render's free plan spins down a service after 15 minutes of inactivity. Because the ESP32 fetches an image every 60 seconds, the service stays warm continuously during normal use.\n\n---\n\n## ESP32 Firmware\n\nSee **[epaper.md](epaper.md)** for full instructions on:\n- Adding the ESP32 board to Arduino IDE\n- Installing required libraries\n- First-boot Wi-Fi setup\n- Web configuration UI reference\n- Optional DS3231 RTC module (keeps the sleep schedule alive without NTP)\n\n![ePaper Configuration UI](assets/screenshots/esp-config-ui.png)\n*Configuration UI — showing Calendar type dropdown (Gregorian / Jewish) and DS3231 RTC option*\n\n---\n\n## Project Structure\n\n```\napp/\n  main.py              # FastAPI app + lifespan\n  api/v1/router.py     # GET / endpoint\n  core/config.py       # Settings (pydantic-settings)\n  services/\n    clock.py           # Image generation (PIL, Hebrew word-clock logic)\n    weather.py         # wttr.in weather cache\n    jewish_cal.py      # hebcal.com Hebrew date fetch + cache\nsketch/\n  hebclk.ino           # ESP32 Arduino sketch\nassets/screenshots/    # README images\nDockerfile\ndocker-compose.yml\nrequirements.txt\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ft0mer%2Fhebrew-clock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ft0mer%2Fhebrew-clock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ft0mer%2Fhebrew-clock/lists"}