Home

Getting Started

1. Download Firmware

Go to the project Releases page and download ramses_esp_esp32_c6.bin.

2. Flash the Device

Option A: In-Browser (No Install)

1. Open Espressif's Web Flasher
2. Connect your ESP32-C6 via USB.
3. Click "Connect" and select the correct serial port (use Windows Device Manager to verify the COM port if needed).
4. Upload ramses_esp_esp32_c6.bin, change the offset to 0x0. Click Program.

3. Configuration

You configure runtime settings over a simple serial command interface.

The easiest way of doing this is via the browser. E.g., with serialterminal

1. Open the page.
2. Click Select Serial Port... and choose the same port used for flashing.
3. Click Connect.

Commands are lowercase, arguments separated by spaces. Press Enter after each line. The device echoes status or OK/ERR responses.

4. Serial, MQTT, or Zigbee

The device supports three communication modes: Serial, MQTT (over Wi-Fi), and Zigbee. Serial is always active. By default the device starts in MQTT/Wi-Fi mode — if that is what you want, skip ahead to sections 4.1 and 4.2. To use Zigbee instead, run the following command in the serial interface first:

network zigbee

Likewise, to switch back to MQTT, you can use:

network wifi

4.1 Serial

4.2 MQTT

4.2.1 Wi-Fi

Set SSID first, then password (order does not strictly matter but keeps things clear):

wifi ssid <your_ssid>
wifi password <your_password>
wifi restart

Note: A wifi restart is required after setting credentials for them to take effect.

4.2.2 Time (SNTP) & Timezone

Reliable time is required before MQTT TLS / timestamps work properly.

sntp server pool.ntp.org
timezone <tz_string>

Find supported timezone strings here: https://github.com/IndaloTech/ramses_esp/wiki/Serial-Interface#wifi-configuration

Example (Central Europe):

timezone CET-1CEST,M3.5.0/02,M10.5.0/03

4.2.3 MQTT

If you use Home Assistant's Mosquitto add-on, create a dedicated user (e.g. ramses) first.

mqtt broker mqtt://192.168.1.49:1883   # Replace with your broker IP/port
mqtt user <your_username>
mqtt password <your_password>

Optional root/topic customization (only if you know you need it):

mqtt root RAMSES/GATEWAY

4.2.4 Reboot

Press the EN button on the device and reconnect to the terminal.

On reboot the device should:

1. Join Wi-Fi.
2. Connect to MQTT and begin publishing.

4.3 Zigbee

4.3.1 Preparation

Zigbee mode currently requires Zigbee Home Assistant (ZHA).

Create a custom_zha_quirks directory next to your configuration.yaml and add two files to it:

configuration.yaml
custom_zha_quirks/
├── __init__.py        ← empty file
└── ramses_esp.py     ← see below

Then tell ZHA where to find the folder by adding this to configuration.yaml:

zha:
  custom_quirks_path: /config/custom_zha_quirks

Paste the following into ramses_esp.py:

"""Device handler for RAMSES ESP32-C6 Zigbee."""

from zigpy import types
from zigpy.profiles import zha
from zigpy.quirks import CustomCluster, CustomDevice
from zigpy.zcl import foundation
from zigpy.zcl.clusters.general import Basic, Identify

from zhaquirks.const import (
    ENDPOINTS,
    INPUT_CLUSTERS,
    MODELS_INFO,
    OUTPUT_CLUSTERS,
    PROFILE_ID,
)

RAMSES_RX_CLUSTER = 0xFC00
RAMSES_TX_CLUSTER = 0xFC01


class RamsesRXCluster(CustomCluster):
    """RAMSES RX cluster (RAMSES_RX_CLUSTER) — ESP32 -> ZHA (device-originated messages)."""

    cluster_id = RAMSES_RX_CLUSTER

    class ClientCommandDefs(foundation.BaseCommandDefs):
        """Commands that ESP32 (client) sends to coordinator (server)."""

        send_text: foundation.ZCLCommandDef = foundation.ZCLCommandDef(
            id=0x00,
            schema={"text": types.CharacterString},
        )

    class ServerCommandDefs(foundation.BaseCommandDefs):
        """Server commands (ACKs) sent in response to `send_text` messages."""

        ack_chunk: foundation.ZCLCommandDef = foundation.ZCLCommandDef(
            id=0x01,
            schema={"text": types.CharacterString},
        )


class RamsesTXCluster(CustomCluster):
    """RAMSES TX cluster (RAMSES_TX_CLUSTER) — ZHA -> ESP32 (coordinator-originated messages)."""

    cluster_id = RAMSES_TX_CLUSTER

    class ClientCommandDefs(foundation.BaseCommandDefs):
        """Client commands (from ZHA to ESP32) — the RAMSES-II message payload."""

        set_text: foundation.ZCLCommandDef = foundation.ZCLCommandDef(
            id=0x00,
            schema={"text": types.CharacterString},
        )

    class ServerCommandDefs(foundation.BaseCommandDefs):
        """Server commands (ACKs) sent by the ESP32 in response to `set_text`."""

        ack_chunk: foundation.ZCLCommandDef = foundation.ZCLCommandDef(
            id=0x01,
            schema={"text": types.CharacterString},
        )


class RamsesESP(CustomDevice):
    """Ramses ESP32-C6 Zigbee."""

    signature = {
        MODELS_INFO: [
            ("ELECRAM", "Ramses_esp32c6"),
        ],
        ENDPOINTS: {
            10: {
                PROFILE_ID: zha.PROFILE_ID,  # Home Automation
                INPUT_CLUSTERS: [
                    Basic.cluster_id,  # 0x0000
                    Identify.cluster_id,  # 0x0003
                    RAMSES_TX_CLUSTER,  # Ramses TX Cluster (server - receives commands from ZHA)
                ],
                OUTPUT_CLUSTERS: [
                    RAMSES_RX_CLUSTER,  # Ramses RX Cluster (client - sends commands to ZHA)
                ],
            }
        },
    }

    replacement = {
        ENDPOINTS: {
            10: {
                PROFILE_ID: zha.PROFILE_ID,
                INPUT_CLUSTERS: [
                    Basic.cluster_id,
                    Identify.cluster_id,
                    RamsesTXCluster,
                ],
                OUTPUT_CLUSTERS: [
                    RamsesRXCluster,
                ],
            }
        },
    }

Restart Home Assistant to load the new quirk.

4.3.2 Pairing

A freshly flashed device starts in pairing mode automatically. To re-pair an already-configured device, either hold the BOOT button for 5 seconds or run:

zigbee pair

At the same time, open ZHA and start a new device search. The interview completes automatically and the device is ready to use.