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 a System schema:

"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:123457]
  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 discovering the Schema, but it will ask you to verify before data 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 until 0.57.12 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 by the tool, 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/disabled 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 'Accept' (add to the Schema), or 'Decline' (not for my Ramses RF, filter out) or 'Skip' (review later), .
  • Accept: the device is added to the schema with traits, and will try to find its place in the system
  • Decline: _owner is set to not-me (device goes to block_list, filtered out)
  • Skip: _skipped: true. You can decide later, as item will re-appear in the next review
• All found devices are written to the Schema, with attributes marking what you choose here.
• It's OK to "Accept" TRVs as soon as they are seen, even without a Zone. As long as the Discovery tool runs, it will add more details over the next half hour or so.
• Wake up your thermostats by physically interacting with them; their zones appear in Discovery almost immediately.
• The Evohome DHW sensor may take over 50 minutes to be discovered. I the DHW water temperature is not changing significantly, there's enough traffic for the Discovery, yet.
• The Clear cache pane has a new "Clear discovery state" option. It clears the "memory" of reviewed items, allowing you to decide again.

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. Create a backup (copy/paste) of your current schema and save it to a text file, then Clear your Schema (only leave orphans_hvac/orphans_heat).

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

Note: Ramses RF automatically creates YAML backups of your schema in the ramses_cc_backups/ folder (max 5 retained) before each migration step. If something goes wrong, you can restore from there.

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 List 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. (And you may also see: DTS, DT2, HCW, RND, TR0, PIR, SW2)
• _owner: mark your Ramses RF entities. Rejected items get owner "not-me", e.g. for items nextdoor or on your second RF bridge. On root level defines your system's default owner name. Devices with _owner matching the root value are "ours" (included); devices with any other _owner are "foreign" (blocked).
• _disabled: true/false. exclude from your system
• _skipped: true/false. decide later what to do with this. It will be prompted again on discovery review.
• _name: Human-friendly display name
• _comment: device level comments
• _faked: true/false. For faked devices like a REM
• _bound: FAN: which REM can send 2411 commands
• _scheme: FAN manufacturer (orcon/itho/vasco/nuaire)
• device_comments (root level): feedback from the scan/class assignment routine. Optional, so can be removed
• orphans_heat, orphans_hvac: devices that did not give enough information (messages) to be determine what they are or where they should be placed in the system Note: your system will initialize HA entities just as it did, using the Schema. That’s why you still need the orphans_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.

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.

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 - you don't need to explicitly set that trait. All well-known device type/class pairs can be seen here

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.