222 lines
4.3 KiB
Markdown
222 lines
4.3 KiB
Markdown
# Raspberry Pi Signal Light API
|
|
|
|
<video src="https://git.dyna-mo.de/timo/signal-light-api/raw/commit/f77a0a22640f2a050bf19891311d72c75e0e903a/assets/demo.mp4" width="600" ></video>
|
|
|
|
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.
|