This wiki page is a WIP based on prerelease 0.50.1.

The configuration of the Ramses RF integration, since release 0.41.x, is done in the web UI by filling in a couple of fields.

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

From this pane you can access the following sections:

Serial port config

As a minimal configuration, just fill in the Serial device path to your dongle, for example connected to the serial port of the device running Home Assistant:

  /dev/ttyUSB0

The ramses_rf library has some auto-discovery features, and the above may be sufficient for many users, especially if only sensors are required.

If you are not sure of the name of your serial port, in the Home Assistant Console execute:

ls /dev/serial/by-id/

Something similar to the below will be returned:

  usb-SHK_NANO_CUL_868-if00-port0
  usb-SparkFun_evofw3_atmega32u4-port0
  usb-Texas_Instruments_TUSB3410_Boot_Device_TUSB3410-if00-port0

As you see, the NanoCUL is easily identifiable. The TUSB3410 is a HGI80. The SparkFun_evofw3 is the SSM-D.

So the NanoCUL serial_port entry becomes:

  /dev/serial/by-id/usb-SHK_NANO_CUL_868-if00-port0

The benefit of using the 'by-id' path is that it will not change if the devices re-numerate or the port utilized changes.

The serial port can be any of the following types (although by-id is recommended):

  /dev/serial/by-id/usb-SHK_X
  /dev/ttyACM0                  # e.g. evofw3-based device
  /dev/ttyUSB0                  # e.g. HGI80, or similar
  COM7                          # windows-based serial port

MQTT

If you're using the RAMSES_ESP dongle that supports MQTT and it is located away from your Home Assistant box, Ramses RF can communicate using MQTT using for example:

mqtt://mqtt_user:[email protected]

or mqtt://username:[email protected]:1883

or mqtt://username:[email protected]

Note: For usernames & passwords, some characters will need to be specified using percent encoding (aka URL encoding).

Advanced serial port config

Only if absolutely 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; 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

Gateway configuration

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.

System schema and known devices

System schema(s)

This section specifies your systems, either:

• Heat (CH/DHW) systems, such as evohome, hometronics, etc.
• HVAC systems, such as Itho, Orcon and Nuaire

This is an example fragment for System schema(s):

"01:111111":  # Temperature control system (e.g. evohome)
  system:
    appliance_control:
      "10:123446"
  zones:
    "07":
      sensor: "01:111111"
"29:123456": # HRU system
  remotes: [29:123456]
  sensors:
    "29:111111"
    "29:222222"

orphans_hvac:
  - "30:111111"
  - "32:333333"
  - "32:555555"
  - "32:666666"

The device IDs (e.g. 01:111111) specify schemas - the internal structure of Heat/HVAC systems.

Note: The general rule with schemas is to have just the minimum schema that works.

Having a device in a schema (or one of the orphan lists) will cause it to be instantiated when ramses_rf is started.

Schemas for Heat systems

As a minimum, for CH/DHW systems, you should list the controller like so:

  "01:145038":

If you know your evohome controller's device id, you should be able to see its schema via this Jinga template. An easy place to experiment with templates in Home Assistant is under the Developer > Templates section.

{{ state_attr("binary_sensor.01_145038_schema", "schema") }}

If that is empty, check your gateway status:

{{ state_attr("binary_sensor.18_123456_status", "schema") }}

ramses_rf is very good at discovering Heat schemas, and it is acceptable to allow it to construct the remainder via eavesdropping/discovery.

Unfortunately, ramses_rf cannot discover:

• when the appliance_control: is an OTB (OpenTherm bridge)
• when the zone sensor: is the controller

"01:111111":
    system:
      appliance_control:
        "10:123446"  # an OTB
    zones:
      "07":
        sensor:
          "01:111111"  # controller is the sensor

Tip: The OTB is discoverable with the system setting Enable discovery, but do not leave this feature enabled longer than required.

Schemas for HVAC systems

Generally, you do not need to specify ventilation control system schemas. Instead, you can just cause them to be instantiated:

orphans_hvac:
  "30:123456"
  "32:222222"
  "32:444444"

However, for HVAC devices, you must indicate the device class via the known device IDs block, see next paragraph.

Known device IDs

The Known device IDs (aka known_list) exists for three reasons:

• for HVAC devices, to specify the class (type): CO2 (CO2 sensor), HUM (humidity sensor), FAN (ventilation unit), or REM (RF remote)
• for relevant devices (e.g. sensors, remotes), to indicate is faking is enabled
• to form an allow list (a whitelist) to increase reliability, using enforce_known_list: true

A typical example of a known list:

"18:123456":   # Honeywell HGI80
"30:111111:
  class: FAN   # a HRU, CVE or PIV
"32:333333:
  class: REM   # RF remote
  faked: true  # an impersonatable remote
"32:555555:
  class: CO2
  faked: true  # a fully faked sensor
"32:666666:
  class: HUM

Tip: The 18:xxxxxx status binary sensor will provide information for a known list.

If you know the device id of your gateway, you can use a Jinga template to extract this data via the web UI (Developer Tools), TEMPLATE:

{{ state_attr("binary_sensor.18_140805_status", "known_list") }}

Including a device ID will not cause it to be instantiated: use a schema or one of the orphans lists to do that.

Note: Faked HVAC remotes should be in the orphans_hvac list because HVAC systems, unlike CH/DHW (heat) systems, do not have a schema.

Strictly speaking, the known_list is a dict, not a list:

    02:145038:                # will be a UFH controller (`UFC`)
    02:145038: {class: REM}   # will be a RF remote
    03:123456: {faked: true}  # will be a thermostat (`THM`)
    18:123456: {class: RFS}   # will be a Spider gateway

Heat (CH/DHW) devices (e.g. CTL, BDR, OTB, etc.) do not require their class to be specified. In the above example, type 03: is always class THM - you don't need to explicitly set that trait. All well-known device type/class pairs can be seen here

Unfortunately, HVAC devices do not have consistent device type mappings, so you will generally need to indicate the class of HVAC devices. In the absence of an explicit specification, ramses_rf will try to determine the class of such devices heuristically (this should not be relied upon).

Note: All gateways and some HVAC kit have device ids starting with 18:; all such devices should have their class explicitly stated.

Accept packets from known device IDs only

If logging is enabled, every packet seen by ramses_rf, valid or not, ends up in the packet log. So, if there is a device which is visible to the gateway, any packet sent by it will end up in the log, regardless of the configuration, device lists, schemas, etc.

The device id filtering, if any, simply determines which valid packets are processed (the others are ignored). If turned off, ramses_rf still enforces the block_list (set where?)

The known_list is not an allowlist (whitelist), until you turn on the switch at the bottom of this pane. However, keeping this on is strongly recommended as soon as every device you wish to control is in your known_list.

Note: the known_list does not cause devices to be instantiated (created) - it merely tells ramses_rf what to do with the device if/when it is instantiated for whatever reason, such as being heard on the ether, or being in a schema somewhere (which includes being listed as an orphan).

Due to the poor/absent ECC of the underlying RAMSES II protocol, there are a lot of invalid packets that nonetheless appear valid - a common problem is corrupted device IDs. Without enforcement of the known list, the system will accumulate a never-ending list of these 'ghost' devices.

Best practice is to enforce the known_list (i.e. use it as a whitelist) as soon as you can - it is much better than using the block_list (blacklist). This is because 'ghost' devices will constantly appear in corrupted packets. In the absence of enforcing the known list, these devices will be instantiated.

Note: Don't enforce the known list until all your devices (including the gateway) show up in RAMSES RF and are included in the list.

Advanced features

Enable send_packet service is an advanced feature. By turning on this switch, you will have the send_packet service call available in HA. It allows you to broadcast bespoke packets via RF. It may not have value to many, especially as it does not yet allow impersonation (i.e. you can set the destination device ID, but not the source ID).

The only parameters this service call currently accepts are:

service: ramses_cc.send_packet
data:
  device_id: '01:123456'
  verb: RQ
  code: 1F09
  payload: FF

By setting up the following expression in the Advanced field, you will have an event triggered whenever a matching message is seen by the integration.

"RP.* 10:"  # regex that matches all packets from an OTB (OpenTherm Bridge)

The value is a regex. Clearing the field disables this feature.

In the HA log, you should see:

2022-11-03 11:26:33.236 DEBUG (MainThread) [homeassistant.core] Bus:Handling <Event ramses_cc_message[L]: dtm=2022-11-03T11:26:33.234940, src=10:048122, dst=18:006402, verb=RP, code=3200, payload=temperature=34.8, packet=RP --- 10:048122 18:006402 --:------ 3200 003 000D98>

Use a HA automation to listen to the event bus for ramses_cc_message:

trigger:
  - platform: state
    entity_id: event.ramses_cc_message
...

Or you can create a sensor of a parameter that is not currently exposed to HA by Ramses RF (here, the parameter is temperature_2):

template:
  - trigger:
      - platform: event
        event_type: "ramses_cc_message"
    sensor:
      - name: "temperature_2"
        state: "{{ trigger.event.data.payload.temperature_2}}"

Packet log

A packet log is not required, but can aid troubleshooting and help development.

If your packet log is being populated with packets, you know that your USB gateway is receiving packets OK). To determine if the gateway is transmitting packets OK, you'll have to look for 'echo' packets (note the digits 000 in the RQ):

2023-11-29T11:24:21.764290 000 RQ --- 18:006402 10:048122 --:------ 3220 005 0080730000  # echo packet
2023-11-29T11:24:21.791060 073 RP --- 10:048122 18:006402 --:------ 3220 005 00B0730000  # reply packet

Tip: The first 3-digit number is the RSSI. Anything below 070 is good.

If you use Hass OS, the file path is relative to the config folder. So if you enter

  packet.log

files by that name will appear in the `/config/ folder. You might create a dedicated directory for the log files, as in the example screen shot.

If you use a local repo, enter:

  ~/home-assistant/.config/packet.log

The packet log can be further configured by setting the maximum file size and the number of log files to keep. Unless a maximum size is configured, the packet log is rolled over every midnight and the last 7 logs are retained by default.

Clear cache

Ramses RF will periodically save the current schema and the latest state (the most recent packets). During startup, this data can be restored, and provide for significant gains in performance/UX. It saves this data, even if it is not configured to restore it upon startup of HA.

For troubleshooting, you can try disabling the restore of one or the other by turning off one or both switches here.

Note: Don't forget to set them back to true after restart!

Permanently disabling this feature is ill-advised.

Behind the scenes

If you want to see the JSON in .storage/core.config_entries, open the file and search for 'ramses_cc':

{
  "version": 1,
  "minor_version": 1,
  "key": "core.config_entries",
  "data": {
    "entries": [
      {
        "entry_id": "e16dd713122857453e961025a1653816",
        "version": 1,
        "minor_version": 1,
        "domain": "ramses_cc",
        "title": "RAMSES RF",
        "data": {},
        "options": {
          "ramses_rf": {
            "disable_qos": false,
            "enforce_known_list": true,
            "use_native_ot": "always"
          },
          "serial_port": {
            "port_name": "/dev/ttyACM0"
          },
          "scan_interval": 5,
          "advanced_features": {
            "send_packet": true
          },
          "known_list": {
            "18:006402": {
...

Migrating a legacy configuration

You can migrate from the older scheme to the current method at any time, and the ramses_cc: section in the configuration.yaml is automatically migrated to a Ramses RF config flow entry.

The section is called ramses_cc:, as it is based upon the old name for the integration, RAMSES CC.

NOTE: Migrating back from config_flow is not impossible, but is not a supported procedure (see below).

After migration, the configuration is stored in a JSON-formatted file, at .storage/core.config_entries.

Until the defunct configuration is removed from configuration.yaml, every time HA restarts, there will be a warning message:

2024-05-08 17:32:56.949 WARNING ... [homeassistant.helpers.config_validation] 
   The 'ramses_cc' option near .../configuration.yaml:3 is deprecated, please remove it from your configuration

Best practice is to remove the ramses_cc: section from your configuration.yaml file to avoid any confusion, although leaving it there won't cause any issues, other than the warning message.

When you are having trouble during migration and the fragment is still in place, a trick is to remove the Ramses RF config entry in the UI and restart HA - then it will re-import from configuration.yaml to create a new entry.