2.3 Configuration ‐ Updating - ramses-rf/ramses_cc GitHub Wiki

Updating Ramses RF from an earlier version

[!Note] Page is under construction

For any up- or downgrade

  • Backup HomeAssistant first to have an easy way to restore (in particular for pre-releases with new bugs)
  • If you also use ramses_extras, update it to 0.21.2+ before upgrading Ramses RF to 0.59.9 or later
  • Migration paths:
    • v1 -> v2: reversible (key removal only, no data loss)
    • v2 -> v3: irreversible (schema mutation), backup saved first

From 0.56.x to 0.60.0

  • Install Ramses RF 0.60.0
  • Update ramses_extras via HACS if you haven't yet
  • After restart, the automatic config entry migration will run when it finds an older config. It will:
    • Create a v2 config options backup, saving a deep-copy snapshot of the v2 options to .storage/ramses_cc_migration_v2_backup. This allows manual recovery if you later decide to downgrade (see below).
    • Run the v2->v3 config entry migration, which:
      • adds information to your existing system schema (known_list traits only fill gaps where the schema doesn't already have the _-prefixed key)
      • creates new entries in the schema for devices in your known_list that are not yet in the schema, setting you as the _owner
      • merges your existing known_list traits into the config schema as _-prefixed keys.
      • converts commands configured under your HVAC Remotes (string format) to commands under your FANs (dict format). The REM commands remain as a backup, but they are redundant and can be removed from the Config Schema later on.

The v2 -> v3 conversion is irreversible — HomeAssistant only migrates forward, so a user who downgrades Ramses RF back to 0.59.0 or earlier cannot auto-migrate a v3 entry backwards (the already-published v2 code has no v3->v2 block).

What to expect after updating:

  • The Known List box is no longer visible on the Configuration > Schema tab
  • The Config Schema is the sole source to manage your setup
  • enforce_known_list is always-on, the switch was removed
  • The Passive Device Scan will start running in the background, and prompt you to accept or reject new devices
  • Every device you accept, will be added to the schema and activated in HA
  • Devices you reject are added to the schema (to prevent asking you again), tagged as _owner: "not-me" and not activated in HA
  • The Passive Device Scan makes suggestions but gives the user the final say in it.
    • Until 0.57.12, the Known List filtered which devices you can control in Ramses RF. The Schema (_owner) does that since.
    • Heat/evohome users used a Schema 'eavesdropped' automatically, but had little control over this. Since 0.56.x, they temporarily had to paste the Schema in Config while we wrote the new routine.
    • Before 0.58.0, HVAC users only filled in a Known List with details per device. Their System Schema contained just a simple “orphans_hvac” block.

How to verify the schema after upgrade

  • Open the Integration > Ramses RF configuration > Schema
  • The migrated known_list (and device info added by the passive scan routine) is shown in the Schema box, where it can be edited
  • In case you accepted a device that you do not own, you can edit the _owner: to anything other than the defined name, e.g. "not-me", and the device will disappear from HA
  • After you click Submit, the changes are applied immediately (no restart required)
  • Page 2.1 contains examples of healthy v3 schema's

How to use the Passive device scan to complete an incomplete schema

  • The Passive device scan will discover unknown RF devices from RF traffic
  • Periodically it will notify of new devices (that might be from next-door) or suggest to fix the class (function) of a device
  • The tool is on by default, but you can turn it off under Advanced Options once your setup is complete

How to restore from backups if something goes wrong

  • If you install 0.58.x or earlier, the integration still loads — the v3 migration is additive (known_list is preserved, extra _-prefixed schema keys are ignored by v2 code).
  • HA logs a migration no-op on every restart (entry.version 3 > handler.VERSION 2), but functionality is not broken.
  • To fully restore v2 state, copy the backup file's options back into the config entry's known_list box in a manual edit.

See this issue for background.