Skip to content

2.1 Configuration step 4: Schemas

Jump to bottom Edit New page
Egbert Broerse edited this page Oct 8, 2026 · 2 revisions

Configuration, continued from page 2.

4. System schema

System schema(s)

This section specifies your systems, either:

  • Heat (CH/DHW) systems, such as evohome, hometronics, etc.
  • HVAC systems, such as Itho, Orcon, Vasco 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

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 the Passive Device Scan, a routine to complete your System Schema from RF traffic.

Focus on the Schema

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 tools to do the hard work, and prevent errors.

Upon starting 0.60.0 or later, most of your set-up is migrated from the pre-0.58.x Known List to the Config Schema, where you can edit it. The Known List is no longer visible in the Config UI and only used inside the code.

Passive Device Scan

Enabled by default, this 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 or reject each.

  • 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 will appear in Discovery almost immediately.
  • The Evohome DHW sensor may take over 50 minutes to be discovered. If the DHW water temperature is not changing significantly, there isn’t 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. “Enable passive device scan” is on by default, and will start 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 > System schema.
  6. Below the Schema, edit your default owner name (“me”).
  7. Create a backup (copy/paste) of your current schema and any remote commands and save this to a text file, then Clear your Schema (only leave orphans_hvac/orphans_heat in place).
  8. Click Send

Next time you reopen the Schema pane, you will see items transferred from your prior 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 any imported legacy Known List class entries.
  • “ventilator" vs "FAN”: The old Known List accepted either form, but for the Schema it is converted to the “slug”. So if your Known List contained:
{"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), see below
  • _commands: REM commands to override default format
  • device_comments (root level): feedback from the scan/class assignment routine. Created and overwritten by the system
  • orphans_heat, orphans_hvac: devices that did not give enough information (messages) to determine what they are or where they should be placed in the system Note: your system will initialize HA entities just as it used to, 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:

discovery-heat

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.

discovery-review-2mismatch

HVAC Strategy-Based Commands

Applies to: ramses_cc 0.60.4+ with ramses_rf 0.60.4+ Related PRs: ramses_cc PR 1090 (strategy-based fan_modes in climate entity), ramses_cc PR 1105 (HVAC command cleanup), ramses_rf strategies module

Overview

Starting with ramses_rf 0.60.3, HVAC vendor strategies are built into the library. Each strategy knows the fan mode mapping, payload format, and binding codes for a specific manufacturer (Orcon, Itho, Vasco, Nuaire, ClimaRad).

This means you can send standard fan mode commands (like high, low, boost, away) without defining any _commands in your schema — the strategy translates the mode name to the correct hex payload automatically.

You still need _commands only for non-standard packets (bypass control, filter reset, vendor-specific opcodes) or to override a standard mode with a custom payload.

Caveat: These schemes cover known vendor mode maps. Devices from other brands (Blauberg, Siber, ClimaRad Minibox, etc.) may use any of these schemes depending on the internal chip (Airios-based). Users must try the scheme that matches their device's behaviour — there is no guarantee that a device from a named manufacturer uses that manufacturer's scheme.

The _scheme Schema Trait

The _scheme trait on a FAN device tells ramses_rf which vendor strategy to use. It goes on the FAN entry in your schema, not on the REM.

Valid schemes

Scheme Manufacturer Example devices
orcon Orcon HRC 400, HRU 350
itho Itho Daalderop CVE, HRU 200
vasco Vasco Vento, ClimaRad (also uses vasco map)
nuaire Nuaire DRI-ECO-PIV
climarad ClimaRad ClimaRad units (shares vasco mode map)

Schema example

# FAN with _scheme — strategy handles all standard fan mode commands
32:153289:
  _class: FAN
  _scheme: orcon
  _bound: 29:123456
  _owner: me

# Bound REM — must be faked to send commands
29:123456:
  _class: REM
  _faked: true
  _owner: me

With _scheme: orcon set on the FAN, you can send away, low, medium, high, auto, auto_alt, boost, and off — all without any _commands entry on the REM or FAN.

Supported Fan Modes by Scheme

These mode names are recognised automatically when _scheme is set. No _commands entry needed. Dutch aliases are accepted in addition to the canonical names.

Mode name Orcon Itho Vasco/ClimaRad Nuaire Dutch alias
off 07 00 00 — uit
away 00 — 01 — afwezig
trickle — 01 — — minimaal
low 01 02 02 — laag
medium 02 03 03 — gemiddeld, midden
high 03 04 04 — hoog
auto 04 — 05 — auto
auto_alt 05 — — — —
boost 06 — — 03 boost
normal — — — 02 normaal
heater_off — — — 09 —
heater_auto — — — 0A —

Note: A dash (—) means the mode is not available for that scheme. Dutch aliases resolve to the canonical name before lookup, so laag → low → hex 01 for Orcon, 02 for Itho/Vasco.

Scheme-specific notes

  • Orcon (_scheme: orcon): away is hex 00, off is hex 07 (reversed from Vasco)
  • Itho (_scheme: itho): has trickle (hex 01, Dutch alias minimaal) as the lowest speed (below low — continuous background ventilation) instead of away; no auto or boost. No humidify/dehumidify modes — these brands are ventilation-only; humidity is handled passively by auto mode (responds to RH/CO2 sensors)
  • Vasco / ClimaRad (_scheme: vasco or _scheme: climarad): same mode map; Note this works for ClimaRad MiniBox and Fan. ClimaRad Ventura HRU`s can't bind to a remote, so they can't be controlled via this integration, only report state.
  • Nuaire (_scheme: nuaire): only 4 modes; normal and boost are the main ventilation modes, heater_off/heater_auto control an internal heater

How to Send Commands

There are several ways to send commands to an HVAC device. They differ in what they do (fan modes vs 2411 parameters vs raw packets) and whether they use the strategy.

Command path inventory

Service Entity target What it does Strategy-aware? HGI fallback?
climate.set_fan_mode climate (FAN) Set fan mode (22F1) ✅ Yes ✅ Yes (ramses_rf)
ramses_cc.send_command remote (REM/FAN) Send named command from _commands, with strategy fallback for FAN ✅ Yes ✅ Yes (remote.py)
get_fan_clim_param climate (FAN) Read 2411 parameter N/A ✅ Yes (services.py)
set_fan_clim_param climate (FAN) Write 2411 parameter N/A ✅ Yes (services.py)
get_fan_rem_param remote (REM) Read 2411 param via REM N/A N/A (REM is source)
set_fan_rem_param remote (REM) Write 2411 param via REM N/A N/A (REM is source)
get_fan_param domain service Read 2411 parameter N/A ✅ Yes (services.py)
set_fan_param domain service Write 2411 parameter N/A ✅ Yes (services.py)
update_fan_params domain service Read all 2411 params N/A ✅ Yes (via get)
ramses_cc.send_packet domain service Send raw packet via Gateway.async_send_raw_command() N/A N/A (user provides)

1. Climate Entity — climate.set_fan_mode

The most user-friendly way. The climate entity's fan_modes attribute lists all available modes (strategy modes + custom _commands of type mode).

UI: Go to the climate entity card and select a fan mode from the dropdown. Only fan mode commands (22F1) and strategy mode name overrides appear — 2411 parameters, 22F7 bypass, 22F3 boost timers, etc. are excluded from the dropdown.

#Automation / YAML:

action: climate.set_fan_mode
target:
  entity_id: climate.32_153289
data:
  fan_mode: high
# Selected Dutch aliases also work (strategy resolves it)
action: climate.set_fan_mode
target:
  entity_id: climate.32_153289
data:
  fan_mode: hoog

Priority order (highest first):

  1. FAN's own _commands (schema dict templates) — if the mode name matches a custom command
  2. Bound REM's _commands (schema packet strings) — if the mode name matches
  3. Strategy fallback — self._device.set_fan_mode(fan_mode) uses the strategy to translate the mode name to hex

So if you have both _commands: { high: "..." } and _scheme: orcon, the custom _commands entry wins for "high". All other Orcon modes (away, boost, etc.) use the strategy.

Source-ID resolution: bound REM → HGI gateway → error. The HGI fallback means you can send fan mode commands even without a faked REM, as long as the gateway is detected.

2. Remote (REM) Entity — ramses_cc.send_command

Send a named command via the faked REM entity.

action: ramses_cc.send_command
target:
  entity_id: remote.29_123456
data:
  command: high
  num_repeats: 3
  delay_secs: 0.05

Current behaviour: Uses _commands entries first. If the command name isn't in _commands and the entity is a FAN with _scheme set, falls back to device.set_fan_mode(command_name) which uses the vendor strategy. This makes remote.send_command("high") work the same as climate.set_fan_mode("high") for strategy-supported modes.

Source-ID resolution: explicit src in command template → bound REM → HGI gateway → error.

Command type classification

_commands entries are classified by type, which controls where they appear in the UI:

Code Type Appears in fan_modes dropdown?
22F1 mode Yes
2411 config No
22F7 bypass No
22F3 boost_timer No
10D0 info No
31DA info No

Optional type field: Dict templates can include an explicit type key that overrides code-based inference. This lets you tag commands that don't fit the standard mapping.

Strategy mode name override: If a _commands entry name matches a strategy mode name (e.g. high), it's included in the dropdown regardless of its code — the user is overriding the strategy's high mode.

3. 2411 Parameter Services — get_fan_clim_param / set_fan_clim_param

Read or write configuration parameters (2411 opcode) on a FAN device via the climate entity.

# Read a parameter
action: ramses_cc.get_fan_clim_param
target:
  entity_id: climate.32_153289
data:
  param_id: "31"

# Write a parameter
action: ramses_cc.set_fan_clim_param
target:
  entity_id: climate.32_153289
data:
  param_id: "31"
  value: "5"

Source-ID resolution: explicit from_id → bound REM → HGI gateway → error.

Note: Both get_fan_clim_param and set_fan_clim_param now have HGI fallback (fixed in PR 1105).

4. 2411 Parameter via REM — get_fan_rem_param / set_fan_rem_param

Same as above but targeted at the remote entity. The REM is used as the source, the bound FAN is the destination.

action: ramses_cc.get_fan_rem_param
target:
  entity_id: remote.29_123456
data:
  param_id: "31"

5. Raw Packet — ramses_cc.send_packet

For advanced users: send a completely bespoke packet. This bypasses both _commands and the strategy. Routes through Gateway.async_send_raw_command() — the official public escape hatch for diagnostic packet injection.

action: ramses_cc.send_packet
data:
  device_id: "32:153289"
  from_id: "18:000730"
  verb: "I"
  code: "22F1"
  payload: "000307"

When You Still Need _commands

Scenario Need _commands?
Send standard fan modes (high, low, boost, away, etc.) No — strategy handles it
Send Dutch aliases (laag, hoog, etc.) No — strategy handles it
Bypass control (open/close/auto) Yes — not a fan mode, uses 22F7
Filter reset Yes — uses 10D0
Override a standard mode with a different payload Yes — _commands takes priority
Send to a device without _scheme set Yes — fallback defaults to Orcon, may be wrong

Migration from Manual _commands

If you currently have manual _commands entries that match standard strategy mode names, you can remove them after setting _scheme. The strategy will handle the translation.

Before (manual commands on REM — legacy Phase 3a)

32:123456:
  _class: FAN
  _bound: 29:123456

29:123456:
  _class: REM
  _faked: true
  commands:
    away:   ' I --- 29:123456 32:123456 --:------ 22F1 003 000007'
    low:    ' I --- 29:123456 32:123456 --:------ 22F1 003 000107'
    medium: ' I --- 29:123456 32:123456 --:------ 22F1 003 000207'
    high:   ' I --- 29:123456 32:123456 --:------ 22F1 003 000307'
    auto:   ' I --- 29:123456 32:123456 --:------ 22F1 003 000407'
    boost:  ' I --- 29:123456 32:123456 --:------ 22F1 003 000607'
    bypass_open:  ' W --- 29:123456 32:123456 --:------ 22F7 003 00C8EF'
    bypass_close: ' W --- 29:123456 32:123456 --:------ 22F7 003 0000EF'
    bypass_auto:  ' W --- 29:123456 32:123456 --:------ 22F7 003 00FFEF'
    reset_filter: ' W --- 29:123456 32:123456 --:------ 10D0 002 00FF'

After (strategy-based — _scheme on FAN, _commands on FAN as dict templates)

32:123456:
  _class: FAN
  _scheme: orcon        # <-- strategy handles away/low/medium/high/auto/boost
  _bound: 29:123456
  _commands:
    # Only non-standard packets remain — standard fan modes are handled
    # by the strategy and no longer need _commands entries.
    bypass_open:  { verb: W, code: 22F7, payload: 00C8EF }
    bypass_close: { verb: W, code: 22F7, payload: 0000EF }
    bypass_auto:  { verb: W, code: 22F7, payload: 00FFEF }
    reset_filter: { verb: W, code: 10D0, payload: 00FF }

29:123456:
  _class: REM
  _faked: true
  # No _commands needed — standard fan modes come from the FAN's
  # _scheme strategy, and non-standard packets are on the FAN above.

Note: In Phase 3b, _commands on the FAN uses dict templates ({verb, code, payload}) — addresses are filled at send time from the bound REM or HGI. _commands on the REM uses full packet strings (legacy Phase 3a format). Both still work, but dict templates on the FAN are the preferred format.

Shortening Your _commands List

If you have manual _commands entries that match standard strategy mode names, you can remove them after setting _scheme. The strategy will handle the translation automatically.

How to test safely

  1. Set _scheme on your FAN (e.g. _scheme: orcon)
  2. Rename the commands you think are covered by the strategy by prefixing them with old_: 
    _commands:
  old_high:   { verb: I, code: 22F1, payload: 000307 }
  old_low:    { verb: I, code: 22F1, payload: 000107 }
  # ... etc
  3. Reload the integration and test climate.set_fan_mode with high, low, etc.
  4. If the strategy works, the fan responds — you can then delete the old_ entries.
  5. If the fan doesn't respond, rename them back — the strategy may not match your device.

What can be removed from the schema (after testing)

Any command whose name matches a strategy mode name can be removed (after testing). This includes Dutch aliases — the strategy resolves them too.

See the Supported Fan Modes by Scheme table for the full list of strategy-supported mode names and hex codes per scheme. If your _commands contains any of those names (or the Dutch aliases), and the hex payload matches the strategy's hex code, you can remove the entry after setting _scheme.

What must stay in the schema

  • Non-22F1 commands (bypass control via 22F7, filter reset via 10D0, etc.)
  • Commands with custom payloads that differ from the strategy's hex code
  • Commands for devices without _scheme set

How It Works Internally

  1. You call climate.set_fan_mode with mode name "high"
  2. ramses_cc checks for custom _commands on the FAN and bound REM — none found for "high"
  3. Falls back to self._device.set_fan_mode("high") in ramses_rf
  4. ramses_rf creates an Intent with data={"fan_mode": "high", "strategy": device._get_strategy()}
  5. _get_strategy() looks up _STRATEGY_BY_SCHEME[device._scheme] → OrconStrategy
  6. The command builder calls strategy.fan_mode_to_hex("high") → "03"
  7. The Intent is compiled into a CommandDTO and dispatched via CommandDispatcher.send(intent)
  8. A 22F1 packet with payload 000307 (index=00, mode=03, mode_max=07) is sent

Command bus: Starting with ramses_rf 0.60.4, all high-level entity commands (set_fan_mode, set_setpoint, set_mode) dispatch compiled typed intents via self._gateway.dispatcher.send(intent) instead of the deprecated Gateway.send_cmd(). The CommandDispatcher handles QoS scheduling, rate limiting, and retry backoff. For raw packet injection (diagnostics), Gateway.async_send_raw_command() is the official public API used by ramses_cc.send_packet.

The strategy also handles:

  • Alias resolution — fan_mode_to_hex("hoog") resolves to "03" via the Dutch alias map
  • Mode max byte — each scheme has its own max byte (07 for Orcon, 04 for Itho, 06 for Vasco, 0A for Nuaire)
  • Binding codes — binding_codes() returns the correct codes for the binding process

Command Troubleshooting

"fan_mode is not valid for scheme 'orcon': ..."

You sent a mode name that doesn't exist in the scheme's mode map. Check the Supported Fan Modes table above.

Commands don't reach the FAN

  • Ensure the REM is _faked: true in the schema
  • Ensure the FAN has _bound: <REM_ID> pointing to the faked REM, or a remotes: [<REM_ID>] list (used as fallback if _bound is not set)
  • Check that the FAN has _scheme set correctly
  • 22F1 commands are fire-and-forget (no ack) — the FAN may not respond if it's out of range

Wrong modes in dropdown

If the dropdown shows Orcon modes but you have an Itho device, check that _scheme: itho is set on the FAN, not on the REM.

No _scheme set

If no _scheme is set, the strategy defaults to Orcon. This may produce wrong payloads for non-Orcon devices. Always set _scheme on your FAN devices.

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".

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.

Add a custom footer
Add a custom sidebar

Clone this wiki locally