# Raspberry Pi Signal Light API

<video src="https://git.dyna-mo.de/timo/signal-light-api/src/branch/main/assets/demo.mp4?raw=1" 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.
