Arduino_code_OLIMEX_Location_Manager/olimex_ESP32-C5-EVB/README.md

# Olimex ESP32-C5-EVB — Home Assistant Integration

This repository contains two components:

## `custom_components/olimex_esp32_c5`
Home Assistant custom integration for the **Olimex ESP32-C5-EVB** board.

- 2 relay switches (250V / 10A, controlled via HTTP POST to the board)
- 2 opto-isolated digital inputs (110VAC-240VAC, state pushed from board to HA via webhook)
- NFC/PN532 card reader for access control (optional, via UEXT connector)
- No polling — fully event-driven for inputs, command-driven for relays

### Installation
Copy `custom_components/olimex_esp32_c5` into your Home Assistant `config/custom_components/` directory and restart HA.

## `esp32_arduino`
Arduino sketch for the ESP32-C5-EVB board.

- Hosts a REST API on port 80
- Registers a callback URL with HA on startup
- POSTs input state changes to HA webhook in real time
- Optional NFC card reader integration for relay trigger automation

### Arduino IDE Settings
| Setting | Value |
|---|---|
| Board | ESP32C5 Dev Module |
| Flash Size | 4MB |
| USB CDC On Boot | Enabled |

See [`esp32_arduino/DEPLOYMENT_GUIDE.md`](esp32_arduino/DEPLOYMENT_GUIDE.md) for full flashing instructions.

## Key Differences from C6-EVB

| Feature | C6-EVB | C5-EVB |
|---------|--------|--------|
| **Relays** | 4 | 2 (250V / 10A) |
| **Inputs** | 4 | 2 (opto-isolated 110VAC-240VAC) |
| **Relay 1** | GPIO 10 | GPIO 24 |
| **Relay 2** | GPIO 11 | GPIO 23 |
| **Input 1** | GPIO 1 | GPIO 4 |
| **Input 2** | GPIO 2 | GPIO 5 |
| **LED** | GPIO 8 | GPIO 27 |
| **Button** | GPIO 9 | GPIO 28 |
| **NFC UART** | GPIO 4/5 (UEXT1) | GPIO 26/25 (UEXT) |

---

## Hardware Overview

### Pin Configuration

**Relays** (250V / 10A AC/DC)
- Relay 1: GPIO24
- Relay 2: GPIO23

**Opto-Isolated Inputs** (110VAC-240VAC)
- Opto Input 1: GPIO4
- Opto Input 2: GPIO5

**LED & Button**
- User LED: GPIO27 (active LOW)
- User Button: GPIO28 (active LOW, internal pull-up)

**UEXT Connector** (for NFC reader / additional peripherals)
- I2C: SDA=GPIO9, SCL=GPIO8
- UART: TX=GPIO26, RX=GPIO25
- SPI: CLK=GPIO2, MOSI=GPIO7, MISO=GPIO6

### Power & Connectivity
- USB-C power input
- WiFi 6 (802.11ax) dual-band (2.4 & 5 GHz)
- Bluetooth 5.0 LE
- Zigbee & Thread capable

---

## API Endpoints

### Status & Control
- `GET  /api/status` — Returns all relay and input states (JSON)
- `POST /relay/on?relay=1-2` — Turn relay on
- `POST /relay/off?relay=1-2` — Turn relay off
- `GET  /relay/status?relay=1-2` — Get relay state

### Inputs
- `GET /input/status?input=1-2` — Get input state

### LED
- `POST /led/on` — Turn LED on
- `POST /led/off` — Turn LED off

### Home Assistant Integration
- `POST /register?callback_url=...` — Register HA webhook (no auth required for bootstrap)

### NFC Access Control
- `GET  /nfc/status` — Get NFC module status
- `GET  /nfc/config` — Get NFC access control settings
- `POST /nfc/config?auth_uid=...&relay=1-2&pulse_ms=5000` — Set NFC access config
- `POST /nfc/enable?state=0|1` — Enable/disable NFC module

### Debug
- `GET /debug` — System info (requires basic auth)

All endpoints except `/register` require **Basic HTTP Authentication** (default: admin/admin) or HMAC-SHA256 request signing.

---

## Setup Instructions

1. **Flash the firmware**
   - See [DEPLOYMENT_GUIDE.md](esp32_arduino/DEPLOYMENT_GUIDE.md)

2. **Configure WiFi**
   - Edit WiFi credentials in `esp32_arduino.ino` (lines ~58-59)
   - Set a static IP (currently 192.168.0.240)
   - Flash the board

3. **Add to Home Assistant**
   - Copy `custom_components/olimex_esp32_c5/` to `~/.homeassistant/custom_components/`
   - Restart Home Assistant
   - Settings → Devices & Services → Create Integration → Olimex ESP32-C5-EVB
   - Enter board IP, port (80), and Home Assistant callback IP

4. **Optional: NFC Card Reader Setup**
   - Attach PN532 breakout to UEXT connector (TX=GPIO26, RX=GPIO25)
   - Open board web UI (`http://<ip>/`)
   - Enable NFC module
   - Scan a card to authorize it
   - Configure trigger relay and timeout

---

## Home Assistant Integration

Once configured, entities appear automatically:

**Switches**
- `switch.olimex_esp32_c5_relay_1`
- `switch.olimex_esp32_c5_relay_2`

**Binary Sensors**
- `binary_sensor.olimex_esp32_c5_input_1` (opto-isolated input)
- `binary_sensor.olimex_esp32_c5_input_2` (opto-isolated input)
- `binary_sensor.olimex_esp32_c5_nfc_card` (NFC card present, if enabled)

**Automations**
Create automations to trigger relays on input events, NFC cards, time schedules, etc.

---

## Troubleshooting

### Board not reachable
1. Check WiFi SSID and password in code
2. Verify board IP with serial console output
3. Check firewall allows port 80

### Inputs not triggering
1. Verify wiring to opto-isolated inputs (GPIO4, GPIO5)
2. Use `/debug` endpoint to check input state
3. Ensure Home Assistant callback URL is registered

### NFC not detecting cards
1. Check PN532 wiring (TX=GPIO26, RX=GPIO25)
2. Set PN532 DIP switches to HSU mode (both = 0)
3. Check serial output for PN532 detection message
4. Try different baud rates (115200, 9600, 57600, 38400)

---

## Security Notes

- Default credentials: admin / admin
- Change WEB_PASSWORD in `secrets.h` before deployment
- Enable API_SECRET for HMAC-SHA256 request signing (optional)
- Only expose board on trusted local networks
- NFC cards trigger relays when authenticated card is present

---

## License & Attribution

- Hardware: [Olimex](https://www.olimex.com/Products/IoT/ESP32-C5/ESP32-C5-EVB/open-source-hardware)
- Firmware: Arduino & ESP-IDF
- Integration: Home Assistant Custom Component