Initial commit: ESP32-C5-EVB and ESP32-C6-EVB Arduino firmware + HA custom components

2026-06-11 00:42:59 +03:00
commit e5fd3645d1
41 changed files with 6637 additions and 0 deletions
@@ -0,0 +1,186 @@
+# 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