Initial commit: ESP32-C5-EVB and ESP32-C6-EVB Arduino firmware + HA custom components
This commit is contained in:
ske087
@@ -0,0 +1,299 @@
|
||||
# ESP32-C5 Arduino Deployment Guide
|
||||
|
||||
Complete guide to compile and deploy the firmware to your Olimex ESP32-C5-EVB board.
|
||||
|
||||
---
|
||||
|
||||
## ✓ Pre-Deployment Checklist
|
||||
|
||||
- [ ] Arduino IDE installed (version 2.0+)
|
||||
- [ ] ESP32 board package installed (version 3.0.0+)
|
||||
- [ ] Olimex ESP32-C5-EVB board connected via USB
|
||||
- [ ] USB drivers installed for your OS
|
||||
- [ ] WiFi credentials available
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Install Arduino IDE
|
||||
|
||||
1. Download from: https://www.arduino.cc/en/software
|
||||
2. Install and launch **Arduino IDE 2.0 or later**
|
||||
|
||||
**⚠️ Arduino IDE 1.x (including the system package `arduino` on Linux) will NOT work with ESP32 core 3.x.**
|
||||
Core 3.x uses nested variable references in its build system that only Arduino IDE 2.x resolves correctly.
|
||||
Installing `arduino` via `apt` gives you IDE 1.8.19 — download the AppImage/zip directly from arduino.cc instead.
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Add ESP32 Board Support
|
||||
|
||||
### Windows/Mac/Linux (same process):
|
||||
|
||||
1. **Open Preferences**
|
||||
- File → Preferences (or Arduino IDE → Settings on Mac)
|
||||
|
||||
2. **Add Board URL**
|
||||
- Find "Additional Boards Manager URLs" field
|
||||
- Add this URL:
|
||||
```
|
||||
https://espressif.github.io/arduino-esp32/package_esp32_index.json
|
||||
```
|
||||
- Click OK
|
||||
|
||||
3. **Install ESP32 Board Package**
|
||||
- Tools → Board → Boards Manager
|
||||
- Search: "esp32"
|
||||
- Install "esp32 by Espressif Systems" (version 3.0.0+)
|
||||
- Wait for installation to complete
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Configure Board Settings
|
||||
|
||||
After installation, configure these exact settings in Arduino IDE:
|
||||
|
||||
### Tools Menu Settings:
|
||||
|
||||
| Setting | Value |
|
||||
|---------|-------|
|
||||
| Board | **ESP32C5 Dev Module** |
|
||||
| USB CDC On Boot | **Enabled** ⚠️ **REQUIRED for Serial Monitor** |
|
||||
| Flash Size | **4MB** |
|
||||
| Flash Frequency | **80 MHz** |
|
||||
| Flash Mode | **QIO** (default for C5) |
|
||||
| PSRAM | Disabled |
|
||||
| CPU Frequency | 240 MHz (WiFi) |
|
||||
| Core Debug Level | None |
|
||||
| Partition Scheme | **No OTA (2MB APP/2MB SPIFFS)** |
|
||||
| Port | `/dev/ttyACM0` (Linux) or `/dev/cu.usbserial-*` (Mac) |
|
||||
|
||||
> **Note:** The ESP32-C5 does not have a "USB Mode" menu. Its USB hardware is fixed (Hardware CDC).
|
||||
> The correct partition scheme for 4 MB flash is **No OTA (2MB APP/2MB SPIFFS)** — this gives 2 MB app space vs 1 MB with `noota_3g`.
|
||||
|
||||
**⚠️ IMPORTANT:**
|
||||
- **USB CDC On Boot MUST be ENABLED** for Serial output to work in Arduino IDE Serial Monitor
|
||||
- The device will show 2 serial ports when USB CDC is enabled:
|
||||
- First port: USB CDC (for Serial.print output)
|
||||
- Second port: USB-UART (legacy, can be ignored)
|
||||
|
||||
**⚠️ Important:** USB CDC On Boot must be **Enabled** for serial output to work!
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Install Required Libraries
|
||||
|
||||
The sketch uses these libraries. Install them via Sketch → Include Library → Manage Libraries:
|
||||
|
||||
1. **PN532** (by Elechouse)
|
||||
- Search: "PN532"
|
||||
- Install the official PN532 library by Elechouse
|
||||
- Version: 1.32 or later
|
||||
|
||||
2. Other libraries (WiFi, WebServer, Preferences) are built-in to ESP32 core
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Configure Secrets
|
||||
|
||||
1. Copy `secrets.h.example` to `secrets.h` in the same directory:
|
||||
```bash
|
||||
cp esp32_arduino/secrets.h.example esp32_arduino/secrets.h
|
||||
```
|
||||
|
||||
2. Edit `secrets.h` with your credentials:
|
||||
```cpp
|
||||
const char* WEB_USER = "admin";
|
||||
const char* WEB_PASSWORD = "admin"; // Change this!
|
||||
const char* API_SECRET = ""; // Optional HMAC secret
|
||||
```
|
||||
|
||||
3. Also update WiFi credentials in `esp32_arduino.ino` (around line 58):
|
||||
```cpp
|
||||
const char* ssid = "YOUR_SSID";
|
||||
const char* password = "YOUR_PASSWORD";
|
||||
```
|
||||
|
||||
**⚠️ Never commit `secrets.h` to Git!**
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Flash the Board
|
||||
|
||||
### Connect the Board:
|
||||
1. Plug the Olimex ESP32-C5-EVB into your computer via USB
|
||||
2. Wait for USB drivers to load (Windows: ~30 seconds)
|
||||
|
||||
### In Arduino IDE:
|
||||
1. Open `esp32_arduino.ino`
|
||||
2. Tools → Port → Select your board's port
|
||||
- **Linux:** `/dev/ttyUSB0`, `/dev/ttyUSB1`, or `/dev/ACM0`
|
||||
- **macOS:** `/dev/cu.usbserial-*` or `/dev/cu.SLAB_USBtoUART`
|
||||
- **Windows:** `COM3`, `COM4`, etc.
|
||||
|
||||
3. Sketch → Upload (or press Ctrl+U / Cmd+U)
|
||||
|
||||
4. Wait for compilation and flashing to complete (~30 seconds)
|
||||
|
||||
### Expected Output:
|
||||
```
|
||||
Connecting........___....._____
|
||||
esptool.py v4.5.1
|
||||
Serial port COM3
|
||||
Chip is ESP32-C5...
|
||||
Uploading stub...
|
||||
...
|
||||
Leaving...
|
||||
Hard resetting via RTS pin...
|
||||
```
|
||||
|
||||
### If Upload Fails:
|
||||
|
||||
**Problem:** "Failed to connect to ESP32"
|
||||
- **Solution 1:** Try different baud rates (Tools → Upload Speed)
|
||||
- **Solution 2:** Hold USER button during upload
|
||||
- **Solution 3:** Different USB cable or port
|
||||
- **Solution 4:** Update board drivers for your OS
|
||||
|
||||
**Problem:** "No module named 'serial'"
|
||||
- **Solution:** Update Arduino IDE to latest version
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Verify Installation
|
||||
|
||||
After successful upload, the board will reboot.
|
||||
|
||||
### Check Serial Monitor:
|
||||
1. Tools → Serial Monitor (or Ctrl+Shift+M / Cmd+Shift+M)
|
||||
2. Set baud rate to **115200**
|
||||
3. Should see:
|
||||
```
|
||||
=================================
|
||||
ESP32-C5 Home Assistant Device
|
||||
Arduino Framework
|
||||
=================================
|
||||
GPIO initialized
|
||||
Connecting to WiFi: YOUR_SSID (attempt 1/3)
|
||||
...............................
|
||||
✓ WiFi connected!
|
||||
IP : 192.168.0.240
|
||||
RSSI : -42 dBm
|
||||
MAC : xx:xx:xx:xx:xx:xx
|
||||
✓ HTTP server started on port 80
|
||||
=================================
|
||||
Ready! Try these endpoints:
|
||||
http://192.168.0.240/api/status
|
||||
=================================
|
||||
```
|
||||
|
||||
### Test in Browser:
|
||||
1. Open browser and go to: `http://192.168.0.240/`
|
||||
2. Login with credentials from `secrets.h` (default: admin/admin)
|
||||
3. Should see interactive control panel with relays and inputs
|
||||
|
||||
### Test API:
|
||||
```bash
|
||||
curl http://192.168.0.240/api/status
|
||||
# Expected response:
|
||||
# {"input1":true,"input2":true,"relay1":false,"relay2":false,...}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 8: Add to Home Assistant
|
||||
|
||||
Once the board is verified and WiFi works:
|
||||
|
||||
1. In Home Assistant: Settings → Devices & Services
|
||||
2. Click "Create Automation" → Integration
|
||||
3. Search for "Olimex ESP32-C5"
|
||||
4. Click "Olimex ESP32-C5-EVB"
|
||||
5. Enter:
|
||||
- **Host:** 192.168.0.240
|
||||
- **Port:** 80
|
||||
- **Callback IP:** Your Home Assistant server IP (usually 192.168.0.1 or 192.168.0.100)
|
||||
6. Click "Create Entry"
|
||||
|
||||
Home Assistant will automatically:
|
||||
- Discover relays and inputs
|
||||
- Register a webhook for input events
|
||||
- Create switches and binary sensors
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Board doesn't show in Port menu:
|
||||
- Install drivers: https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers
|
||||
- Try different USB cable
|
||||
- Check Device Manager (Windows) or System Report (Mac)
|
||||
|
||||
### Serial output garbled:
|
||||
- Check baud rate is **115200** in Serial Monitor
|
||||
- Try different baud rates (9600, 57600)
|
||||
|
||||
### WiFi connection fails:
|
||||
- Verify SSID and password in `esp32_arduino.ino`
|
||||
- Check 2.4 GHz WiFi is enabled (C5 may not support 5 GHz yet)
|
||||
- Power cycle board and router
|
||||
|
||||
### NFC not detected:
|
||||
- Check PN532 is soldered correctly to UEXT connector
|
||||
- Verify TX=GPIO26, RX=GPIO25 wiring
|
||||
- Set PN532 DIP switches to HSU mode (both = 0)
|
||||
- Check serial output for baud detection attempts
|
||||
|
||||
### Can't reach board from Home Assistant:
|
||||
- Verify board IP: check serial monitor output
|
||||
- Ping from HA machine: `ping 192.168.0.240`
|
||||
- Check firewall allows port 80
|
||||
- Ensure HA and board are on same network
|
||||
|
||||
---
|
||||
|
||||
## Updating Firmware
|
||||
|
||||
To update code after initial deployment:
|
||||
|
||||
1. Make changes in Arduino IDE
|
||||
2. Edit WiFi credentials if needed
|
||||
3. Sketch → Upload
|
||||
4. Monitor serial output to verify successful flash
|
||||
|
||||
---
|
||||
|
||||
## Protecting Your Device
|
||||
|
||||
**Before deployment to production:**
|
||||
|
||||
1. Change default credentials in `secrets.h`:
|
||||
```cpp
|
||||
const char* WEB_USER = "secure_user";
|
||||
const char* WEB_PASSWORD = "strong_password_123";
|
||||
```
|
||||
|
||||
2. Set an API secret for request signing:
|
||||
```cpp
|
||||
const char* API_SECRET = "my_random_secret_key_xyz123";
|
||||
```
|
||||
|
||||
3. Only expose board on trusted networks (private LAN)
|
||||
|
||||
4. Consider firewall rules to restrict access
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Check [README.md](../README.md) for API endpoints and features
|
||||
- Configure Home Assistant automations with the new switches/sensors
|
||||
- Optional: Add NFC card reader to UEXT connector for access control
|
||||
- Explore [custom_components](../custom_components/) for integration details
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
- Olimex Board: https://github.com/OLIMEX/ESP32-C5-EVB
|
||||
- ESP32 Arduino: https://github.com/espressif/arduino-esp32
|
||||
- PN532 Library: https://github.com/elechouse/PN532
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,20 @@
|
||||
{
|
||||
"folders": [
|
||||
{
|
||||
"path": "."
|
||||
}
|
||||
],
|
||||
"settings": {
|
||||
"files.exclude": {
|
||||
"**/.git": true,
|
||||
"**/.DS_Store": true,
|
||||
"**/secrets.h": true,
|
||||
"**/*.o": true
|
||||
},
|
||||
"search.exclude": {
|
||||
"**/.git": true,
|
||||
"**/node_modules": true,
|
||||
"**/.venv": true
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,40 @@
|
||||
/**
|
||||
* secrets.h — Credentials & API Keys (NOT Version Controlled)
|
||||
*
|
||||
* Instructions:
|
||||
* 1. Copy this file to secrets.h (same directory)
|
||||
* 2. Edit secrets.h with your WiFi credentials and API secret
|
||||
* 3. DO NOT commit secrets.h to Git
|
||||
* 4. Add secrets.h to .gitignore if not already present
|
||||
* 5. Flash the board with Arduino IDE
|
||||
*/
|
||||
|
||||
#ifndef SECRETS_H
|
||||
#define SECRETS_H
|
||||
|
||||
// ─ WiFi Credentials ───────────────────────────────────────────────────────
|
||||
const char* WIFI_SSID = "YourWiFiSSID";
|
||||
const char* WIFI_PASSWORD = "YourWiFiPassword";
|
||||
|
||||
// ─ Static IP Configuration ────────────────────────────────────────────────
|
||||
// Set USE_STATIC_IP = true to use a fixed IP address
|
||||
// Otherwise, board will request IP via DHCP
|
||||
const bool USE_STATIC_IP = false; // true = static IP; false = DHCP
|
||||
const char* STATIC_IP_ADDR = "192.168.0.240"; // e.g., "192.168.0.240"
|
||||
const char* STATIC_GATEWAY = "192.168.0.1"; // e.g., "192.168.0.1"
|
||||
const char* STATIC_SUBNET = "255.255.255.0"; // e.g., "255.255.255.0"
|
||||
const char* STATIC_DNS1 = "8.8.8.8"; // e.g., "8.8.8.8"
|
||||
const char* STATIC_DNS2 = "8.8.4.4"; // e.g., "8.8.4.4"
|
||||
|
||||
// ─ Web Server Credentials ──────────────────────────────────────────────────
|
||||
const char* WEB_USER = "admin";
|
||||
const char* WEB_PASSWORD = "admin";
|
||||
|
||||
// ─ API Authentication Secret ──────────────────────────────────────────────
|
||||
// Used for HMAC-SHA256 request signing (optional)
|
||||
// If empty, API requests do not require authentication.
|
||||
// To enable, set a random string and include X-Request-Time/X-Request-Sig headers.
|
||||
// Example: "my_super_secret_api_key_12345"
|
||||
const char* API_SECRET = "";
|
||||
|
||||
#endif
|
||||
Reference in New Issue
Block a user