zz (defunct) Tips for the configuration.yaml file

The Problem

Evohome (and the other Honeywell-RF products supported here) use the RAMSES-II protocol. Unfortunately, RAMSES-II is based upon RF, a relatively error-prone medium and has almost no facility for detecting/rejecting invalid packets.

Here is an example of such a packet, which is obviously invalid (it has 3 device addresses):

2021-02-21T09:27:48.425589 056 RP --- 13:237335 01:000730 01:123456 0008 002 000E

ramses_rf has no problem rejecting these.

Here is an example of a similar packet, which is not obviously invalid (although I'd be instantly, highly, suspicious):

2021-02-21T09:27:48.417123 056 RQ --- 01:000730 13:237335 --:------ 0008 002 00
2021-02-21T09:27:48.425589 056 RP --- 13:237335 01:000730 --:------ 0008 002 000E

What has happened is that the address of the source in the first packet is corrupt (it should have been 18:000730), and the corresponding response will cause a CorruptStateError (in this case, a relay has appeared to have 'moved' to another controller).

The problem is that the packets could be valid/correct - there is not way to know with 100% confidence.

Similar issues also occur at the payload level where corrupted, but ostensibly valid, payloads can play havoc with ramses_rf's internal state.

Mitigating the Problem

There are several things you can do to help ramses_rf improve your experience with RAMSES-II, by increasing the number of packets it can detect as invalid. This is done through using:

• a schema
• the max_zones parameter
• an allow_list

ramses_cc:
  serial_port: /dev/ttyUSB1
  config:
    enforce_allowlist: True
    max_zones: 16
  schema:
    controller: 01:145038
  allow_list:
    - 01:145038
    - 04:056053
    - 04:056057
   ...

Schema

By default, ramses_rf will just listen until it picks up a controller, and that can take as much as 3-4 minutes (if everything else is going well).

Unfortunately, if your neighbour also has Evohome, then ramses_rf may pick up their system instead of yours.

Explicitly specifying a controller ID will solve both these problems.

There are two ways to obtain the controller ID, either via the controller UI, or by allowing ramses_rf to run, and seeing it in the resultant schema JSON.

It is strongly recommended to use the feature.

Allow List

In short:

• ramses_rf will never block a packet to/from the gateway device (a HGI80, or a dongle running evofw3)
• if using a allow_list, ramses_rf will ignore packets *not* containing one of those addresses, otherwise
• if using a block_list, ramses_rf will ignore packets containing one of those addresses (even if it is being sent to/from your controller)

If you supply a block_list, it will be used without further configuration. The block_list should not contain any of your system's device IDs.

If you supply a allow_list, it needs to be enabled via enforce_allowlist before it will be used, and any block list will then be ignored. If you're using an allow list, then every device in your system should have its device ID in the allow_list.

WARNING: things may appear to be working OK with an incomplete allow_list, but this will not be the case.

You can obtain a list of device IDs by running ramses_rf without any filtering, and upon reviewing the resultant schema. Please resolve this list against the devices you have around your house as a check.

It is strongly recommended to use the feature.

Max Zones

It can be the case that a bit is flipped in a payload and a zone_idx is created that will cause a 'phantom' zone to appear in the system. This is a payload error, and so the entire packet is also suspect & should be rejected.

This parameter should be set to one more that your highest zone_idx.

WARNING: a system may have only 3 zones, but they could be (say) 00, 01, and 05. In this case, max_zones should be set to 6 (0-5), not 3, and not 5.

Note that zone_idx are zero-indexed, and usually represented as a hex string where 0A is 10 (decimal). The maximum number of zones supported by ramses is 12 (0B), and increasing this parameter beyond that will not improve things for you.

Later, this parameter may be changed to max_zone_idx.