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

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/evohome users need a complete System Schema in Config since 0.56.x, and used the Known List to filter which devices they want to control in Ramses RF. HVAC users before 0.58.0 had a Known List with all details per device, while their System Schema contained just a simple “orphans_hvac” block.

Since 0.58.0, the System Schema is the core configuration element in Ramses RF, the central place the Ramses RF integration turns to.

Instead of entering everything by hand, our developers created new tools to do the hard work, and prevent errors.

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

Enter your gateway’s device ID, starting with 18:, and its _class: HGI in the Schema, or the Passive Device Scan can’t do its job.

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 from skip (review later), enable (add to the Schema), or discard (not my 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 to reset the scanner.

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. In the Schema box, enter the device ID of your HGI as in the example.

7. In between the Schema and Known List boxes, edit your default owner name (“me”).

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

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

“18:120120":
  class: HGI

10. Click Send

Next time you reopen the Schema pane, you will see items transferred from the Known List, as well as the ones you 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

In Ramses-II, HVAC devices do not have consistent device type mappings, so the _class of HVAC devices is deducted from RF traffic, to be confirmed by the user via the dialogs.

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

Valid 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 next door or on your second RF bridge.

With the Passive Device Scan running, you will get a notification in HA (orange dot) whenever a new device was found. From that notification, jump directly to Config, open the Review Discovered Devices pane and confirm what Ramses RF should do:

If Ramses RF expects a device to be of a different class, it will show a line on the same pane. Select Update or Keep it as is.

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

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

The general rule with Heat Schemas up to release 0.56.3 was to have just the minimum schema that works. Later releases rely on the information you enter in the schema instead.

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

For HVAC devices, the device class must be provided using the class: element, as it can’t be derived from RF traffic alone with 100% success. Since 0.58.0 use the Review Discovered Devices tab to choose from the suggested classes.

If HVAC 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"

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

Known device IDs

The Known device IDs (aka Known List) exists for one reason:

• to specify commands for a remote.

Before release 0.58.0 the Known List was also used to:

• specify the class (type) for HVAC devices:
  • CO2 (CO2 sensor),
  • HUM (humidity sensor),
  • FAN (ventilation unit), or
  • REM (RF remote)
• indicate if faking is enabled for relevant devices (e.g. sensors, remotes)
• enter 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.

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. All well-known device type/class pairs can be seen here

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.