5. Faking & Impersonation - zxdavb/ramses_cc GitHub Wiki

NOTE: Faking v2 was first released in version 0.31.x.

For some RAMSES II-compatible devices, ramses_cc can send packets as if from such a device. This is called 'faking', and can be very useful.

There are two classes of fakable devices:

  • temperature / humidity / CO2 / presence sensors
  • switches / remotes

These faked devices can physically exist (are 'impersonated'), or be a virtual construct (aka 'fully-faked').

Note: You need an evofw3-compatible gateway for this feature: HGI80s are incapable of supporting impersonation, and their support for faking is very limited.

Once a device is faked, service calls are used to send the relevant packets. For example, for a temperature sensor to report its current reading:

service: ramses_cc.put_temperature
  data:
    entity_id: ramses_cc_03_123456
    temperature: 19.5

Introduction

Devices that can be faked include: temperature/CO2/humidity sensors (CH/DHW & HVA) and remotes & switches (HVAC). Specific use-cases include:

  • faking vendor devices that are expensive/unavailable, e.g. CO2 sensors for HVAC system
  • automating HVAC systems with faked remotes, e.g. enabling boost mode during showers/cooking
  • improving the accuracy of your system, e.g. adding zone sensors for CH/DHW systems (instead of TRV sensors)
  • improving the reliability of your system, e.g. faking DHW sensors for CH/DHW systems (instead of the vendor sensors)

Generally, this is called faking, but is sometimes referred to as impersonation if the faked device physically exists. Usually, impersonated devices should not remain active on the RF network: the only exception would be a switch (and not a remote).

NOTE: Impersonated devices should be turned off (to stop them transmitting), unless they are stateless (e.g. a switch).

Faking vs Impersonation

When faking a device, it may either:

  • never have existed: the device was unavailable/too expensive to purchase
  • once existed/no longer active: the device has been replaced with a faked version
  • still exist/remain active: the device is being impersonated (it is likely a switch)

Note: If the device never existed, then you will have to bind that device to your system.

You should only impersonate devices that are stateless (e.g. switches). Breaking this rule will cause unexpected issues:

  • good practice: impersonating a stateless switch (it is still 'active', but no-one is pressing it's buttons presently)
  • bad practice: impersonating a sensor will not stop that sensor from sending its own readings (which will likely differ from those sent by ramses_cc)

Creating faked devices

Note: However RAMSES RF is configured by you (i.e. its schema), that won't alter your Heating/HVAC system's opinion of reality. Any mismatches could cause odd errors.

Prerequisites

Before going any further, you must:

  • be using a evofw3-compatible gateway
  • have a fully-populated known_list, and be enforcing it
  • have a minimal schema that correlates with your system configuration

Tip: You will come to grief if you are not fully aware of the purpose and function of the Known device IDs list and the Schema.

For each faked device, you will either need to select an appropriate device ID. Such IDs are similar to 07:0045678 (note the leading zeros to create a 2 digit part and a 7 digit part).

Note that:

  • devices must have a unique IDs, so ensure you don't utilize an existing id (unless you're impersonating that device)
  • the two digits before the colon, the device 'type', should be between 01 and 62, and HVAC device classes must use a specific type
  • the six digits after the colon have to be less than 0x3FFFF, and for other reasons are best kept between 002000 and 256999

-- insert a link to the well-known device types here --

Step 1: Configure filtering and Enable faking

You will have to add the device's id to the Known device IDs list so that:

  • its packets are not ignored by ramses_rf, and
  • ramses_cc is aware the device is faked

Devices are not instantiated simply because they are in Known device IDs; for that, they need to be in the Schema (required for HVAC), or be discovered (sufficient for CH/DHW).

Known device IDs:

"03:123456":
  faked: true

Turn on Accept packets from known Device IDs only.

After making any changes to the configuration, as above, HA must be restarted to make them effective.

NOTE: Devices are not instantiated simply because they are in the known_list. Instead, the known_list tells ramses_rf how to instantiate the device should it do so.

Step 2: Ensure the device is instantiated

There are several ways that a device can be instantiated (come into existence) by ramses_rf:

  • a packet is received from that device (packets sent to a device don't count)
  • a packet received from a controller indicates that the device exists (e.g. evohome)
  • a schema is loaded that indicates the device exists
  • a service call is used to manually instantiate the device

NOTE: Be wary of cached packets, and cached schemas. You may need to disable loading these whilst establishing a faked device.

Generally, the best option is for you to place the device in the schema. The exception to this is if it is a CH/DHW device, such as used by evohome, since the controller will indicate, when asked by RAMSES RF, that the device exists.

Step 3: Bind the device (if required)

You can create a new virtual device, or replace an existing physical device (the real device may have to be switched off to avoid confusing the system). The advantage of the latter approach is that all binding might already be in place.

If you are not replace an existing physical device with a faked virtual dice, then you will need to bind the new device to the controller as you would any new zone sensor.

Use the ramses_cc.fake_device service call to cause the faked device to bind with the controller. It will also instantiate the faked device if required.

Use this service call to send the pairing code:

service: ramses_cc.fake_device
data:
  device_id: "03:123456"
  start_binding: true

This should result in a successful "Paired" message on the evohome controller screen.

This step is not required if faking a real device that has been deactivated.

After making the above changes, HA must be restarted for RAMSES RF to load the new schema. You will probably need to start without a cache:

Turn off Clear cache > Clear discovered system schema.

Make sure you set it back to ON after you have restarted HA.

Check the schema

Before the next step, review the system schema to confirm that you know which device is the sensor for your zone. For example:

"01:054173":
  system:
    heating_control:
      "10:049798"
...
  zones:
    "01":
      sensor:
        "03:123456"

Step 4: Final steps

If all is as expected, then you can resume restoring the cache, so turn on Clear cache > Clear discovered system schema.

After making the above change, there is no need to restart HA.

Using faked devices

Finally, you then use the appropriate service call to cause the faked device to broadcast the relevant packet:

  • with HA automations (e.g. using the output from another sensor)
  • via the HA UI (e.g. pressing a button in HA's web UI)