Skip to content

2. Configuration

Jump to bottom Edit New page
David Bonnes edited this page Aug 26, 2024 · 18 revisions

This integration has a somewhat complicated configuration. 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.

The configuration file

Regarding the configuration of the ramses_cc integration, the traditional scheme, up to/including versions 0.31.x, was to edit the configuration.yaml file. The latest releases, from 0.41.x of the integration, use config flow instead.

See here for the differences when using config flow.

The config options, explained below, are the same for both schemes.

The configuration.yaml file is used 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. an allow list)

See: https://www.home-assistant.io/docs/configuration/

This file can get very complex. This an example of an absolute minimum configuration.yaml:

ramses_cc:
  serial_port: /dev/ttyUSB0  # or some other serial port name

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

Schemas, Orphans, Lists and Logging

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).

The known_list is not an allowlist (whitelist), until you have enforce_known_list: true. However, enforcing this is strongly recommended once every device you have 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.

The above is also why the block_list is of little value to most users.

Basic configuration

This is a fragment of an example of a typical configuration.yaml:

ramses_cc:
  serial_port: /dev/serial/by-id/usb-SHK_NANO_CUL_868-if00-port0

  packet_log:
    file_name: packet.log
    rotate_backups: 28

  ramses_rf:
    enforce_known_list: true

  01:111111:  # Temperature control system (e.g. evohome)
    system:
      appliance_control: 10:123446
    zones:
      "07": {sensor: 01:111111}

  orphans_hvac: [30:111111, 32:333333, 32:555555, 32:666666]

  known_list:
    18:123456:                            # Honeywell HGI80
    30:111111: {class: FAN}               # Orcon HRU
    32:333333: {class: REM, faked: true}  # an impersonatable remote
    32:555555: {class: CO2, faked: true}  # a fully faked sensor
    32:666666: {class: HUM}

The top-level keys of the configuration consists of well-known keys (e.g. packet_log:, known_list: & orphans_hvac:) and device identifiers (01:111111). The device IDs specify schemas - the internal structure of Heat/HVAC systems.

serial_port:

ramses_cc:
  serial_port: /dev/serial/by-id/usb-SHK_NANO_CUL_868-if00-port0

If you are not sure of the name of your serial port, execute:

ls /dev/serial/by-id/

For evofw3, you can set the baud rate as follows (default is 115200):

ramses_cc:
  serial_port: 
    port_name: /dev/ttyUSB0
    baudrate: 57600

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 via Arduino IDE.

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

  serial_port: /dev/ttyACM0                  # e.g. evofw3-based device
  serial_port: /dev/ttyUSB0                  # e.g. HGI80, or similar
  serial_port: COM7                          # windows-based serial port
  serial_port: rfc2217://192.168.1.100:5001  # for ser2net

RFC2217 support is experimental and requires ser2net or similar, YMMV.

Something similar to the below will be returned. Here, a NanoCUL is easily identifiable:

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

The TUSB3410 is a HGI80. The SparkFun_evofw3 is the SSM-D.

So the serial_port becomes:

ramses_cc:
  serial_port: /dev/serial/by-id/usb-SHK_NANO_CUL_868-if00-port0

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

Only if absolutely required, the serial port can be further configured with baud rate, xon/xoff, etc.

MQTT

If you're using the new RAMSES_ESP dongle that supports MQTT, use one the standard URL format, for example:

    serial_port: "mqtt://mqtt_user:mqtt_p%[email protected]"  # password is 'mqtt_p@ss'
    serial_port: "mqtt://username:[email protected]:1883"
    serial_port: "mqtt://username:[email protected]"

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

packet_log:

ramses_cc:
  packet_log: 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 000):

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 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. I use a local repo, so:

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

The packet log can be further configured with a retention policy thus:

ramses_cc:
  packet_log: 
    file_name: packet.log
    rotate_bytes: null
    rotate_backups: 7

Other than the file_name, the other parameters have default values as shown above. Unless a maximum size is configured, the packet log is rolled over every midnight; in any case, the last 7 logs are retained by default.

restore_cache:

ramses_cc:
  restore_cache: true

ramses_cc 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:

ramses_cc:
  restore_cache:
    restore_schema: false
    restore_state: true

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

Permanently disabling this feature is ill-advised.

known_list:

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) are in the list.

The 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

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") }}

Having a device ID in the known list will not cause it to be instantiated: use a schema, or one of the orphan lists to do that.

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

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

ramses_cc:
  known_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.

ramses_rf:

ramses_cc can pass parameters to ramses_rf to modify it's behaviour.

The following are available (all default values are false):

ramses_cc:
  ramses_rf:
    enforce_known_list: false  # if not true, still enforces the block_list
    disable_discovery: false
    disable_sending: false  # do not transmit any packets, ever
    enable_eavesdrop: false  # can be used to create an initial system schema

Note: Do not routinely leave enable_eavesdrop: set to true, it may cause problems.

Tip: Initially, you may prefer enforce_known_list: false, but setting it to true is strongly recommended, once you have a complete known_list:.

It is now possible to configure how ramses_rf polls an OTB for its state.

ramses_cc:
  ramses_rf:
    use_native_ot: prefer  # always, prefer (default), avoid, never

The essential choice is between native OTB messages, or the RAMSES equivalent. If you are having difficulties retrieving OTB state attrs with prefer, try avoid, always, or never (in that suggested order). YMMV.

System schemas

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

ramses_cc:
  01:145038:  # CH/DHW system (evohome)
    system:
      appliance_control: 10:048122
  29:123456: # HRU system
    remotes: [29:123456]
    sensors: [29:111111, 29:222222]

This section specifies your systems, either:

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

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

Schemas for Heat systems

If you know your evohome controller's device id, you should be able to see its schema via this Jinga template. A 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") }}

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

ramses_cc:
  01:145038: {}

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

Unfortunately, ramses_rf cannot discover:

  • when the appliance_control: is an OTB (OpenTherm bridge)
  • when the zone sensor: is the controller
ramses_cc:
  01:111111:
    system:
      appliance_control: 10:123446  # an OTB
    zones:
      "07": {sensor: 01:111111}  # controller is the sensor

Tip: The OTB is discoverable with enable_eavesdrop: true, 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:

ramses_cc:
  orphans_hvac: [30:123456, 32:222222, 32:444444]

However, for HVAC devices, you must indicate the device class via the known_list::

ramses_cc:
  orphans_hvac: [30:123456, 32:222222, 32:444444, 32:666666]
  known_list:
    30:123456: {class: FAN}               # a HRU a CVE or a PIV
    32:222222: {class: REM}               # RF remote
    32:444444: {class: CO2, faked: true}  # CO2 sensor
    32:666666: {class: HUM, faked: true}  # humidity sensor

Other configuration options

scan_interval:

ramses_cc:
  scan_interval: 60

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

advanced_features:

By setting up the following send_packet parameter in your configuration.yaml, you will have the send_packet service call available in HA.

It allows you to broadcast bespoke packets via RF. I doubt it would be of 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).

ramses_cc:
  advanced_features:
    send_packet: true

The only parameters this service call presently accepts are:

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

By setting up the following message_events parameter in your configuration.yaml, you will have an event triggered whenever a matching message is seen by the integration.

ramses_cc:
  advanced_features:
    message_events: "RP.* 10:"  # regex that matches all packets from an OTB

The value is a regex. Setting it to None (the default value) 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_cc (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}}"
Add a custom footer
Add a custom sidebar
Clone this wiki locally