2.1 Configuration step 3: Schemas

Configuration, continued from page 2.

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 and HVAC systems.

Since release 0.58.0 Ramses RF supports filling in the Schema, but it will ask you to verify before it is copied and stored.

Schema Creation & Discovery

HEAT users need a complete System Schema in Config since 0.56.x, and used the Known List to select the devices they want to control in Ramses RF. HVAC users used to have a Known List with details per device, while their System Schema contained just a simple “orphans_hvac” block. Release 0.58.0 introduced a slick routine to fill in your System Schema from the Known List and RF traffic.

Focus on the Schema

HEAT users need a complete System Schema in Config since 0.56.x, and used the Known List to select the devices they want to control in Ramses RF. HVAC users used to have a Known List with details per device, while their System Schema contained just a simple “orphans_hvac” block . Instead of entering everything by hand, our developers created two new tools to do the hard work, and prevent errors. Since 0.58.0, the System Schema is the core configuration element in Ramses RF, the central place the Ramses RF integration turns to.

Most of your Known List will be migrated to the System Schema box, where you can edit it (and store). The Known List is still used, but we expect its contents to gradually all flow into the Schema.

Passive Device Scan

Once enabled, this new action runs in the background, alerting you what new devices have appeared on the RF network. It will present a list of discovered devices, allowing you to accept them or reject them.

• The passive scan can be enabled in the Ramses RF > Advanced options pane.
• On a clean system it will discover devices by scanning in the background (listening on RF traffic). It takes time to “see” every device (it helps to press a remote’s button).
• Config has a new "Review discovered devices" pane: it lists all new found devices (with info) in a table, select All or Per device 'skip (review later), enable (add to the Schema), or discard (not for Ramses RF, filter out).
• The found devices are written to the Schema, with attributes marking what you choose here.
• The Clear cache pane has a new "Clear discovery state" option, and a new “Clear Known Devices List”.

How to build the Schema

1. Go to Integrations > Ramses RF > Configuration /Cogwheel > Advanced Options

2. Turn On “Enable passive device scan to discover unknown RF devices”

3. Turn On “Send persistent notifications when new devices are found”

4. Click Send

5. Go to Integrations > Ramses RF > Configuration /Cogwheel > Schema and Known List

6. Between Schema and Known List, edit your default owner name

7. Clear your Schema (only leave orphans_hvac/orphans_heat) > Copy to a safe place text file

8. Enter at least your HGI in the Known List, as:

“18:130140":
  class: HGI

9. Click Send

Next time you reopen the Schema pane, you will see items transferred from the Known List as well as Accepted in the Review dialog.

_owner: me
orphans_hvac:
  - "29:123123"
  - “29:345345"
"37:125482":
  _owner: not-me
"18:120120":
  _class: HGI
  _owner: me
"29:345345”:
  _alias: My remote
  _class: REM
  _faked: true
  _owner: me
"29:123123":
  _alias: my fan
  _bound: "29:345345”
  _class: FAN
  _owner: me

Rules applied

• Schema _class wins over Known List class entries.
• Known Lst is used to fill the gaps — e.g. traits not already in the Schema.
• Once the trait is in the Schema, the Known List entry is redundant and can be removed.
• “ventilator" vs "FAN”, The Known List accepts either form, but for the Schema it is converted to the “slug”. So if your Known List contains:

{"32:153289": {"class": "ventilator"}}):

the scanner will transfer this to your Schema as:

"32:153289":
  _owner: me
  _class: FAN

Schema Elements:

• _alias: name to describe the item
• _class: role of the device. Valid slugs: BDR, CO2, CTL, DEV, DHW, DIS, FAN, HEA, HGI, HUM, HVC, JIM, JST, OTB, OUT, PRG, REM, RFG, RFS, THM, TRV, UFC.
• _device_comments: feedback from the scan/class assignment routine. Optional, so can be removed
• _owner: mark your Ramses RF entities. Rejected items get owner “not-me”, e.g. for items nextdoor or on your second RF bridge.

Note: your system will initialize HA entities just as it did, using the Schema. That’s why you still need the orpans_hvac: list for items that never show up during a scan. You could try to remove items from orphans_x if they’re already defined in full in the Schema. Having a device in the Schema (or one of the orphan lists) will cause it to be instantiated when ramses_rf is started.

Schema for earlier releases

Note: The general rule with schemas up to release 0.56.0 was to have just the minimum schema that works. Later releases rely on the information you enter in the schema instead. Since 0.58.0 Config has a built-in tools to fill in the Schema (see above).

Schemas for Heat systems

From 0.56.0 up to 0.57.12, you must enter a YAML description of your System Schema, 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 RF to show both the sensor and actuator within the Zone.

Zone names are picked up from the Evohome controller and added to the Schema.

Schemas for HVAC systems

If ventilation system items do not promptly reply at startup (e.g. battery operated remotes), add their ID in the Schema under orphans_hvac:

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

For HVAC devices, the device class must be confirmed, 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.) specify their class by type in the Ramses-II protocol. 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

In Ramses-II, HVAC devices do not have consistent device type mappings, so the class of HVAC devices is deducted from RF traffic, and can be corrected via the dialogs.

Note: All gateways and some HVAC kit have device ids starting with 18:; all such devices should have their class explicitly stated, most often that is "HGI".

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 for the final configuration steps.