Initial commit

2026-07-25 20:47:48 +02:00
commit 58be310d63
4 changed files with 910 additions and 0 deletions
@@ -0,0 +1,219 @@
+# Raspberry Pi Signal Light API
+
+A REST API for controlling a Raspberry Pi equipped with a 4-channel relay HAT.
+
+The API controls four relays connected to the following GPIO pins:
+
+| Function | GPIO |
+| -------- | ---: |
+| Green    |   26 |
+| Yellow   |   19 |
+| Red      |   13 |
+| Alert    |    6 |
+
+## Features
+
+* REST API built with **FastAPI**
+* Interactive Swagger UI
+* Green, Yellow and Red are mutually exclusive
+* Alert relay blinks independently of the color relays
+* Demo mode continuously cycles:
+
+```
+Green → Yellow → Red → Yellow → ...
+```
+
+* Automatic relay reset during startup and shutdown
+* Status endpoint for monitoring the current state
+
+---
+
+# Requirements
+
+* Raspberry Pi
+* Python 3.10 or newer
+* 4-channel relay HAT
+* Raspberry Pi OS
+
+---
+
+# Installation
+
+Clone the repository and create a virtual environment.
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+Install the dependencies:
+
+```bash
+pip install fastapi uvicorn gpiozero
+```
+
+---
+
+# Starting the API
+
+Run the application with Uvicorn:
+
+```bash
+uvicorn relay_api:app --host 0.0.0.0 --port 8000
+```
+
+If your Python file has a different name, replace `relay_api` with the filename (without the `.py` extension).
+
+Example:
+
+```bash
+uvicorn signal_api:app --host 0.0.0.0 --port 8000
+```
+
+The API will then be available on port **8000**.
+
+---
+
+# API Documentation
+
+FastAPI automatically provides interactive documentation.
+
+## Swagger UI
+
+```
+http://<RASPBERRY_PI_IP>:8000/docs
+```
+
+Swagger allows you to:
+
+* View all available endpoints
+* Execute requests directly from your browser
+* Inspect request and response schemas
+
+## ReDoc
+
+```
+http://<RASPBERRY_PI_IP>:8000/redoc
+```
+
+---
+
+# Endpoints
+
+## Colors
+
+Only one color can be active at a time.
+
+| Method | Endpoint  | Description           |
+| ------ | --------- | --------------------- |
+| POST   | `/green`  | Activate green relay  |
+| POST   | `/yellow` | Activate yellow relay |
+| POST   | `/red`    | Activate red relay    |
+
+Selecting a color automatically turns the other two color relays off.
+
+---
+
+## Alert
+
+The alert relay operates independently from the color relays.
+
+| Method | Endpoint     | Description                |
+| ------ | ------------ | -------------------------- |
+| POST   | `/alert`     | Start blinking alert relay |
+| POST   | `/alert/off` | Stop blinking alert relay  |
+
+The alert relay blinks continuously:
+
+* 1 second ON
+* 1 second OFF
+
+The currently active color remains unchanged.
+
+---
+
+## Demo Mode
+
+Demo mode automatically cycles through the colors.
+
+```
+Green
+↓
+Yellow
+↓
+Red
+↓
+Yellow
+↓
+(repeat)
+```
+
+| Method | Endpoint    | Description     |
+| ------ | ----------- | --------------- |
+| POST   | `/demo`     | Start demo mode |
+| POST   | `/demo/off` | Stop demo mode  |
+
+Starting demo mode overrides manual color selection until demo mode is stopped.
+
+The alert relay continues to operate independently during demo mode.
+
+---
+
+## System
+
+| Method | Endpoint  | Description                                   |
+| ------ | --------- | --------------------------------------------- |
+| POST   | `/off`    | Turn off all relays and stop demo/alert modes |
+| GET    | `/status` | Retrieve the current relay status             |
+
+---
+
+# Example Usage
+
+Activate the green relay:
+
+```bash
+curl -X POST http://<RASPBERRY_PI_IP>:8000/green
+```
+
+Start the alert relay:
+
+```bash
+curl -X POST http://<RASPBERRY_PI_IP>:8000/alert
+```
+
+Start demo mode:
+
+```bash
+curl -X POST http://<RASPBERRY_PI_IP>:8000/demo
+```
+
+Check the current status:
+
+```bash
+curl http://<RASPBERRY_PI_IP>:8000/status
+```
+
+Turn everything off:
+
+```bash
+curl -X POST http://<RASPBERRY_PI_IP>:8000/off
+```
+
+---
+
+# Relay Logic
+
+| Relay  | Behavior                                           |
+| ------ | -------------------------------------------------- |
+| Green  | Mutually exclusive with Yellow and Red             |
+| Yellow | Mutually exclusive with Green and Red              |
+| Red    | Mutually exclusive with Green and Yellow           |
+| Alert  | Blinks independently of the color relays           |
+| Demo   | Cycles Green → Yellow → Red → Yellow until stopped |
+
+---
+
+# License
+
+This project is provided as-is for educational and personal use.