2.1 Configuration step 3: Schemas

Continue from here

3. 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 of System schema(s):

"01:216136":  # Temperature control system (e.g. evohome)
  orphans_heat: []
  stored_hotwater:
    heating_valve: null
    hotwater_valve: "13:042605"
    sensor: "07:050121"
  system:
    appliance_control: "10:064873"
  underfloor_heating: {}
  zones:
    "00":
      _name: Garden room
      actuators:
        - "04:034720"
        - "04:056673"
      class: radiator_valve
      sensor: "04:056673"
    "01":
      _name: Kitchen
      actuators:
        - "04:034682"
      class: radiator_valve
      sensor: "22:012299"

"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 up to release 0.56.0 was to have just the minimum schema that works. Current releases rely on the information you enter in the schema instead. Updates to make this easier are in the works as of 0.57.7.

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

Note: An upcoming release will include a simple Action to help you fill in the Schema. Stay tuned!

As of current release 0.57.9, you enter a YAML description of your system, starting with the controller, like so:

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

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

Up to Ramses RF release 0.56.3, for CH/DHW systems you had to provide the controller plus details that the integration couldn't 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

If you use an HR92 radiator valve, add the TRV 04:xxxxxx actuator device to the Schema for ramses_cc to show both the sensor and actuator within the Zone.

Zone names are picked up from the Evohome controller so if you also add them to the Schema, take care to enter the same names.

Schemas for HVAC systems

Generally, you do not need to specify ventilation control system schemas. But if they do not promptly reply at startup (e.g. battery operated remotes), you should add their ID in the Schema under orphans_hvac:

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

For HVAC devices, you must indicate the device class in 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 if faking is enabled
• to form a Known List to increase reliability, and filter out other traffic by turning on Accept packets from known device IDs only.

A typical example of a CH/evohome Known device IDs block (sorted by type for easy lookup, class:HGI is required):

"07:050121": {}
"10:064873": {}
"13:042605": {}
"18:191664":
  class: HGI
"22:012299": {}
"34:058721": {}

A typical example of a HVAC Known device IDs block:

"18:123456":   # Honeywell HGI80
  class: HGI
"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 under :>Details will show information for a Known List if devices have been defined or discovered.

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

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

Including a device ID in the Known List will not cause the HA entity to be instantiated: use a Schema or one of the orphans_x lists to do that.

Note: Faked HVAC remotes should be in your Schema's orphans_hvac block because they can't be picked up by any RF traffic.

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, because the Ramses-II protocol defines it by type. 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.

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). NOTE: When you turn on the "Accept from known device_id's only", at the same time clear both caches, and restart.

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. This is because 'ghost' devices will constantly appear from corrupted packets. Without 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 Known List.

The moment you turn this option On, both caches are cleared, because they likely contain unwanted device messages. Restart HA as mentioned in the System Log Warning next.

Log Tx + all MQTT topics

This option will add all these messages to the system log. Good for debugging, but HA will complain Ramses RF is "logging too frequently" as we handle a lot of traffic.

Continue to the next page in this wiki for details.