2. Configuration steps 1‐2

The set-up of this integration requires your attention and a bit of time. Before you go any further, please read this wiki page in full, taking special notice of any warnings. If you are stuck, first look here, then ask for help at the HA forum if you remain stuck.

ramses_cc is configured entirely via the Home Assistant UI (Config Flow).

The config options allow you to:

• set the behaviour of ramses_cc and ramses_rf, including logging
• set the traits of devices (e.g. is the device a HRU (WTW) or a RF remote)
• set the system schemas (which devices play what role in your systems)
• filter out unwanted/ghost devices (i.e. a Known List)

In HomeAssistant, navigate to: Settings > Devices & Services > RAMSES RF and click
(Configure).

From this pane you can access the following sections:

---

Configuration Steps

When adding the integration for the first time, the setup wizard will guide you through these steps sequentially.

If you are modifying an existing installation (clicking CONFIGURE), you will be presented with a Main Menu. You can access the settings below by selecting the corresponding menu option.

1. Serial Port / Connection Type

(Menu Option: Serial port)

First, select how Home Assistant connects to your RF Gateway device (dongle). The integration tries to discover connected USB devices automatically and allows you select one of them, or choose a different connection type lower down the list.

• USB Dongle: Select your device from the list (e.g., /dev/ttyUSB0, /dev/ttyACM0).
• Use Home Assistant MQTT (under development)
• MQTT Broker...: Select this option if you are using a remote dongle via MQTT (e.g., ramses_esp or evofw3).
• Enter Manually: Use this if your device isn't listed, if you use a specific path or to view the complete serial connection string e.g. to copy to a backup.

USB/Serial

As a minimal configuration, just select your dongle's Serial Port from the list of USB-connected devices:

MQTT with Third Party Broker

If you selected MQTT Broker... in the previous step, you will be presented with a dedicated configuration screen. This allows you to easily enter your broker details without manually constructing a complex connection string.

• Broker IP or Hostname: Enter the IP address or hostname of your MQTT broker (e.g., homeassistant.local or 192.168.1.100 or core-mosquitto).
• Port: Default is 1883.
• Username / Password: (Optional) Enter these if your broker requires authentication.

Note 1: For usernames & passwords, some characters will need to be specified using percent encoding (aka URL encoding). Note 2: Starting with ramses_cc v0.51.0 the MQTT broker is expected to support MQTT protocol version 5.0. If you are using the current Mosquitto HA Add-on, you are fine. See this forum post how to edit the code if you run a different broker and need MQTT protocol version v3.1.1.

The integration will automatically construct the connection URL for you (e.g., mqtt://user:pass@192.168.1.100:1883) and pass it to the next step.

HA MQTT App (as Bridge)

Choose Use Home Assistant MQTT to use the MQTT App (if installed). Since the HA MQTT broker password is already known to the app, you don't need to enter it here.

NOTE 1: You must enter the HGI ID in the Gateway Config step, next. NOTE 2: This Bridge option might not work on dongles running ramses_esp firmware.

Confirm Serial Port Config

The next screen allows for advanced configuration of the serial connection.

• Advanced serial port config: This section is used for specific overrides (e.g., setting a custom baudrate).
• For standard USB or MQTT setups: You generally do not need to enter anything here. The connection details you provided in the previous steps are already saved.

Simply click Submit to save.

Advanced serial port config

Only if required, the serial port baud rate, xon/xoff, etc. can be set here. Default baud rate is 115200.

Note: You should only need to set the baud rate for NanoCUL-based devices, which won’t work with the default; it must match the baud rate you used to flash the device from the Arduino IDE.

For evofw3, you can set the baud rate by entering:

baudrate: 57600

For details, see this issue

Note: If you are performing the Initial Setup, you will automatically proceed to the Gateway Configuration step.

If you are Re-configuring, this will save your changes and close the dialog. To proceed, click Configure again and select Gateway configuration from the menu.

2. Gateway Configuration

(Menu Option: Gateway configuration)

In this step you define the core devices in your CH or HVAC system, and some details.

Scan interval

How often HA/Ramses RF polls ramses_rf for a change in state. The default value is 60 seconds. Having it lower than that, or higher than 180, is of little value, except for troubleshooting.

Gateway Device ID (MQTT Bridge only)

This field appears only when using the MQTT Bridge in the previous step. It identifies your RF gateway dongle (ramses_esp/evofw3) on the RF network. It defaults to 18:000730 (the HGI80 placeholder).

For MQTT Bridge users, it should be set to your real dongle ID (e.g. 18:071939) — the one you see in the ramses_log as the source of RX packets. If left as the default 18:000730, commands may be sent with the placeholder ID, causing:

• Duplicate RQ packets in the log (one from 18:000730, one from the real ID)
• Devices ignoring commands (they only respond to the real RF address)

The config flow tries to auto-discover this ID by scanning MQTT topics for 5 seconds during initial setup. If discovery fails, you should set it manually to the ID shown in your ramses_log.

3. System Schema & Known Devices

(Menu Option: System schema and known devices)

Continue to the next page in this wiki for details.