From 90001675cef6fee8ba37c89635c5ff9814176702 Mon Sep 17 00:00:00 2001
From: Markus Graf <info@marksugraf.ch>
Date: Sat, 9 May 2026 22:18:43 +0200
Subject: [PATCH] docs: update README with graphql api documentation and uv
 setup

---
 README.md | 75 +++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 62 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 1cd7480..db57588 100644
--- a/README.md
+++ b/README.md
@@ -10,15 +10,23 @@ Instead of simply pressing a button to stop the alarm, this clock requires you t
 *   **External Speakers** (connected via 3.5mm jack or a USB Soundcard for better audio quality)
 
 ## Software Requirements
-This project uses Python 3. The required dependencies are:
-*   `RPi.GPIO` (usually pre-installed on Raspberry Pi OS)
-*   `pygame` (used for optimized audio playback)
+This project uses Python 3 and `uv` for dependency management. To set up the environment:
 
-You can install the required packages via:
+1. Install `uv` if you haven't already:
+   ```bash
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   ```
+2. The project contains a `pyproject.toml` file with all dependencies.
+   ```bash
+   uv sync
+   ```
+
+Note: The system also requires `python3-pygame` and `python3-rpi.gpio` which should be installed via system packages:
 ```bash
 sudo apt-get install python3-pygame python3-rpi.gpio
 ```
 
+
 ## Wiring
 Please refer to the [arcade-button-wiring.md](arcade-button-wiring.md) file for detailed instructions on how to connect the arcade button and its LED to the Raspberry Pi's GPIO pins.
 
@@ -29,20 +37,61 @@ Please refer to the [arcade-button-wiring.md](arcade-button-wiring.md) file for
    python3 wecker.py
    ```
 
-## Automating with Cron
-To have the alarm start automatically at a specific time (e.g., 6:45 AM on weekdays), you can set up a cronjob.
+## Automating and Managing Alarms (GraphQL API)
 
-1. Open your crontab configuration:
+Instead of manually editing your crontab, this project provides a simple GraphQL API to List, Get, Set, and Delete your alarms.
+
+### API Setup & Authentication
+
+1. Create a `.env` file in the project root to set up your Static API Key:
    ```bash
-   crontab -e
+   cp .env.example .env
+   # Edit .env and set your own secure API_KEY
    ```
-2. Add the following line at the end of the file (adjust the paths if your setup differs):
+2. Start the API server:
    ```bash
-   45 6 * * 1-5 cd /home/pi/workspace/wecker && /usr/bin/python3 wecker.py > /home/pi/workspace/wecker/cron.log 2>&1
+   uv run uvicorn api.main:app --host 0.0.0.0 --port 8000
    ```
-   * `45 6`: Runs at 6:45 AM.
-   * `* * 1-5`: Runs from Monday (1) to Friday (5). Skips the weekend.
-   * It ensures the script runs in the correct directory so it can find the audio file.
+3. The API will be available at `http://<YOUR_PI_IP>:8000/graphql`.
+
+**Authentication:** All requests to the `/graphql` endpoint require a custom header:
+`X-API-Key: <YOUR_API_KEY>`
+
+### Example API Usage
+
+**Get all alarms:**
+```graphql
+query {
+  getAlarms {
+    id
+    cronExpression
+    command
+    isEnabled
+  }
+}
+```
+
+**Set an alarm:**
+```graphql
+mutation {
+  setAlarm(
+    cronExpression: "45 6 * * 1-5", 
+    command: "cd /home/pi/workspace/wecker && /usr/bin/python3 wecker.py > wecker.log 2>&1",
+    isEnabled: true
+  ) {
+    id
+    cronExpression
+  }
+}
+```
+
+**Delete an alarm:**
+```graphql
+mutation {
+  deleteAlarm(id: "YOUR-ALARM-ID")
+}
+```
+
 
 ## How the Puzzle Works
 1. **Ringing:** The music plays in an endless loop.