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.
python3 -m venv .venv
source .venv/bin/activate
Install the dependencies:
pip install fastapi uvicorn gpiozero
Starting the API
Run the application with Uvicorn:
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:
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:
curl -X POST http://<RASPBERRY_PI_IP>:8000/green
Start the alert relay:
curl -X POST http://<RASPBERRY_PI_IP>:8000/alert
Start demo mode:
curl -X POST http://<RASPBERRY_PI_IP>:8000/demo
Check the current status:
curl http://<RASPBERRY_PI_IP>:8000/status
Turn everything off:
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.