Skip to content

Add flash script and documentation for XIAO ESP32-C6 #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gonzague wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add flash script and documentation for XIAO ESP32-C6 #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
281 changes: 281 additions & 0 deletions HOWTO-FLASH.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,281 @@
# How to Flash ESPSomfy-RTS to a XIAO ESP32-C6

A step-by-step guide to flashing the ESPSomfy-RTS firmware to a Seeed Studio XIAO ESP32-C6 for controlling Somfy RTS motorized blinds and shades.

## What is ESPSomfy-RTS?

ESPSomfy-RTS is an open-source project that turns an ESP32 with a CC1101 radio transceiver into a controller for Somfy RTS blinds and shades. It provides:

- Web interface for controlling up to 32 shades and 16 groups
- MQTT integration for home automation
- Home Assistant integration via HACS
- Support for RTS, RTW, and RTV protocols on 433MHz

This guide uses a fork specifically optimized for the ESP32-C6 chip.

## Hardware Requirements

### Components

| Component | Description |
|-----------|-------------|
| **XIAO ESP32-C6** | Seeed Studio XIAO ESP32-C6 development board |
| **CC1101 Module** | 433MHz radio transceiver module |
| **Jumper Wires** | Dupont wires for connections |
| **USB-C Cable** | For programming and power |

### Wiring: XIAO ESP32-C6 to CC1101

The firmware uses these default pin mappings for the XIAO ESP32-C6:

| CC1101 Pin | XIAO ESP32-C6 Pin | Function |
|------------|-------------------|----------|
| VCC | 3V3 | Power (3.3V) |
| GND | GND | Ground |
| MOSI | D10 (GPIO18) | SPI Data Out |
| MISO | D9 (GPIO20) | SPI Data In |
| SCK | D8 (GPIO19) | SPI Clock |
| CSN | D2 (GPIO2) | Chip Select |
| GDO0 | D3 (GPIO17) | TX Data |
| GDO2 | D6 (GPIO16) | RX Data |

> **Note**: These pins can be reconfigured via the web interface after flashing.

## Software Requirements

- **macOS, Linux, or Windows** with USB drivers
- **PlatformIO** (we'll install it below)
- **Python 3.8+** with `uv` or `pip`

## Step-by-Step Flashing Guide

### Step 1: Clone the Repository

```bash
git clone https://github.com/your-username/ESPSomfy-RTS.git
cd ESPSomfy-RTS
```

### Step 2: Install PlatformIO

Using `uv` (recommended):
```bash
uv tool install platformio
```

Or using `pip`:
```bash
pip install platformio
```

Or using `pipx`:
```bash
pipx install platformio
```

Verify installation:
```bash
pio --version
```

### Step 3: Connect the XIAO ESP32-C6

1. Connect the XIAO ESP32-C6 to your computer via USB-C
2. The device should appear as a serial port:
- **macOS**: `/dev/cu.usbmodem*`
- **Linux**: `/dev/ttyACM0` or `/dev/ttyUSB0`
- **Windows**: `COM3` (or similar)

Verify the connection:
```bash
# macOS/Linux
ls /dev/cu.usb* /dev/tty.usb* 2>/dev/null

# Or use PlatformIO
pio device list
```

### Step 4: Build the Firmware

```bash
pio run
```

This will:
- Download the ESP32-C6 toolchain
- Install required libraries (ArduinoJson, WebSockets, CC1101 driver, etc.)
- Compile the firmware

Expected output:
```
RAM: [=== ] 26.3% (used 86228 bytes from 327680 bytes)
Flash: [========= ] 88.8% (used 1396240 bytes from 1572864 bytes)
========================= [SUCCESS] Took XX.XX seconds =========================
```

### Step 5: Upload the Firmware

```bash
pio run -t upload
```

PlatformIO will automatically detect the serial port and flash the firmware.

Expected output:
```
Uploading .pio/build/debug/firmware.bin
...
Writing at 0x00010000... (100 %)
Wrote 1505136 bytes (824256 compressed) at 0x00010000 in 4.7 seconds
...
========================= [SUCCESS] Took XX.XX seconds =========================
```

### Step 6: Upload the Filesystem

The web interface files are stored in a LittleFS partition. Upload them with:

```bash
pio run -t uploadfs
```

Expected output:
```
Building FS image from 'data' directory to .pio/build/debug/littlefs.bin
/appversion
/icon.png
/index.html
...
Wrote 983040 bytes (96657 compressed) at 0x00310000 in 1.4 seconds
========================= [SUCCESS] Took XX.XX seconds =========================
```

### Step 7: Verify the Device

Monitor the serial output to confirm the device is running:

```bash
pio device monitor
```

Or using `screen`:
```bash
screen /dev/cu.usbmodem2101 115200
```

Press `Ctrl+]` then `q` to exit screen, or `Ctrl+C` to exit PlatformIO monitor.

## First Boot Configuration

1. **Connect to the WiFi AP**: On first boot, the device creates a WiFi access point named `ESPSomfy-RTS`

2. **Open the Configuration Portal**: Connect to the AP and navigate to `http://192.168.4.1`

3. **Configure WiFi**: Enter your home WiFi credentials

4. **Access the Web Interface**: After connecting to your network, find the device's IP address (check your router or use mDNS: `http://espsomfy-rts.local`)

## Build Environments

The project includes multiple build configurations:

| Environment | Command | Description |
|-------------|---------|-------------|
| `debug` | `pio run` | Debug build with logging (default) |
| `release` | `pio run -e release` | Optimized release build |
| `debugSSDP` | `pio run -e debugSSDP` | Debug with SSDP discovery enabled |
| `releaseSSDP` | `pio run -e releaseSSDP` | Release with SSDP discovery enabled |

For production use, consider the release build:
```bash
pio run -e release -t upload
pio run -e release -t uploadfs
```

## Partition Layout

The firmware uses a custom partition scheme optimized for ESP32-C6:

| Partition | Type | Size | Purpose |
|-----------|------|------|---------|
| nvs | data | 20KB | Non-volatile storage |
| otadata | data | 8KB | OTA update metadata |
| app0 | app | 1.5MB | Main application |
| app1 | app | 1.5MB | OTA update slot |
| spiffs | data | 960KB | LittleFS filesystem |

This layout supports Over-The-Air (OTA) updates while maximizing space for the web interface.

## Troubleshooting

### Device not detected

1. Try a different USB cable (some are charge-only)
2. Check if the USB port provides enough power
3. On macOS, check System Information > USB
4. Try pressing the BOOT button while connecting

### Upload fails with timeout

1. Hold the **BOOT** button on the XIAO
2. Press and release the **RESET** button
3. Release the **BOOT** button
4. Run the upload command immediately

### Build errors

```bash
# Clean and rebuild
pio run -t clean
pio run
```

### Serial monitor shows garbage

Verify the baud rate is set to `115200`:
```bash
pio device monitor --baud 115200
```

## Useful Commands Reference

```bash
# Build firmware
pio run

# Upload firmware
pio run -t upload

# Upload filesystem
pio run -t uploadfs

# Monitor serial output
pio device monitor

# Clean build files
pio run -t clean

# Build specific environment
pio run -e release

# List connected devices
pio device list

# Full rebuild and upload
pio run -t clean && pio run -t upload && pio run -t uploadfs
```

## Resources

- [ESPSomfy-RTS Wiki](https://github.com/rstrouse/ESPSomfy-RTS/wiki) - Original project documentation
- [Home Assistant Integration](https://github.com/rstrouse/ESPSomfy-RTS-HA) - HACS integration
- [XIAO ESP32-C6 Pinout](https://wiki.seeedstudio.com/xiao_esp32c6_getting_started/) - Seeed Studio documentation
- [PlatformIO Documentation](https://docs.platformio.org/) - Build system docs

## License

This project is open source. See the repository for license details.

---

*Last updated: January 2025*
Loading