evoGateway

A local evohome ↔ MQTT integration service

---

---

Overview

evoGateway provides a local, fully independent interface between Honeywell’s evohome RF network and any MQTT-based home automation system.

It receives and decodes RF traffic from evohome devices using the excellent ramses_rf library, publishes structured MQTT topics, and also accepts MQTT commands which are transmitted back onto the RF network as if they originated from an evohome Honeywell HGI80.

The gateway operates without relying on Honeywell’s cloud services, offering a robust and responsive integration path for platforms such as openHAB, Home Assistant, and any system capable of consuming or producing MQTT messages.

All RF communication, schema management, and MQTT publishing is performed locally, providing a reliable and transparent interface to the evohome system.

---

Upgrading from Older Versions

There has been extensive refactoring and reorganisation of evoGateway since the previous version 3.x. Users upgrading from earlier releases should be aware of several important changes:

1. Project Structure

The codebase is now organised into distinct functional components, moving away from the single large script file. This should make it easier to adapt to any future changes in the underlying ramses_rf library:

.
├── config/
│   ├── evogateway.cfg
│   ├── ramses_rf_schema.json
│
├── evogateway/
│   ├── app.py
│   ├── config.py
│   ├── logger.py
│   ├── router.py
│   ├── services.py
│   └── utils.py
│
├── logs/
│   ├── events.log
│   └── packet.log
│
├── README.md
└── evogateway.py

2. The Ramses schema file is now the single source of truth

• The ramses_rf_schema.json file is now the master source for zones/devices.
• devices.json and zones.json have been removed. Device names, zone names, and relationships are now maintained entirely in the schema file.

3. MQTT topic structure has been updated

• A more consistent and hierarchical MQTT layout is now used by default.

• The previous flat/legacy layout is still available by enabling:

  MQTT_LEGACY_TOPIC_STRUCTURE = True
  

• Device and zone categorisation defaults have changed slightly, especially around controllers, HGI devices, and DHW classification.

4. Some configuration file options have changed

• Several older parameters have been renamed or removed.
• A complete sample configuration file is provided (config/evogateway.cfg.sample).

5. Code modularisation

• The old single-file architecture has been replaced with a module-based structure.
• Logging, MQTT handling, routing, serial handling, and formatting logic now live in dedicated modules.

While core functionality should hopefully remain consistent with previous versions, some behaviour will almost certainly differ slightly as compared to previous versions.

---

Installation

Requirements

• Python 3.12.3
• Python dependencies can be installed via:

pip install -r requirements.txt

Includes:

• ramses_rf
• paho-mqtt
• colorama

---

Hardware

NOTE The hardware can be purchased in component form from ebay/Ali Express etc or, fully assembled with a proper PCB, from ebay (search for nanoCUL FTDI 868MHz).

If assembling yourself, you will need:

• 1 x Arduino nano (clone should be fine), preferably with FTDI usb chipset, though the cheaper CH341 chipset also worked. The only issue I had with the CH341 was that the USB port was not always cleanly released when the python script exited. My FTDI based build is much more reliable in this respect.

• 1 x CC1101 radio, 868MHz, e.g. something like this. However, note that there has been some report of issues with the radio crystal's accuracy on some of these boards (discussion on evofw3 board).

• A breadboard or 8 x Dupont fly leads. If using fly leads you need to ensure that sure that you have the correct male/female combination for your arduino and CC1101 card.

Wiring pin connections will depend on the specific CC1101 board. In my case, I used the following:

WIRE COLOUR			CC1101 PIN 	NANO PIN
Red 				Vcc	        3.3V pin
Black 				GND 		GND
Orange 				MOSI		15
Yellow 				SCLK		17
Blue				MISO		16
Dark Red 			GDO2		32
Grey				GDO0 		1
White 				CSN 		14

ANT 				Antenna coil

Although arduinos with the FTDI FT232L chipset are recommended, clone nanos with the CH341 usb chip have also worked reasonably. In my case the radio board is connected directly to the nano using just male/female dupont wires, with the male side soldered directly onto the radio board. Note that actual pin connection points should always follow the requirements of evofw3 (e.g. see the atm328_pins.h file), otherwise corresponding changes may need to be made in in this file before compiling and flashing the firmware.

Arduino Firmware

evoGateway requires the evofw3 arduino firmware by @ghoti57, to decode/encode the radio signals and make the message packets available to/from the ramses_rf framework.

---

Configuration

evoGateway uses two distinct configuration sources, each serving a different purpose:

1. The evoGateway configuration file (evogateway.cfg)

   • Contains all runtime settings for the gateway itself (serial port, MQTT behaviour, logging, file paths, etc.).

2. The Ramses RF schema file (ramses_rf_schema.json)

   • Stores the discovered evohome network structure (devices, zones, controller relationships, metadata, etc.).
   • Automatically generated by evoGateway on first run, and can be modified by hand as required.

Both files live under the config/ directory.

(For those upgrading from an earlier version, the previous devices.json and zones.json files have been retired; the schema file is now the single authoritative source.)

---

1. evoGateway Configuration File (evogateway.cfg)

This file defines the operational parameters for evoGateway. A sample configuration with all available parameters is provided in:

config/evogateway_sample.cfg

Users should copy this to evogateway.cfg and adjust as needed. The key parameters to include are the serial port settings and the mqtt broker details. The rest are optional and can be omitted.

Serial Port Settings

Controls communication with the evofw3 Arduino interface:

• COM_PORT (mandatory)
• COM_BAUD

The COM_PORTparameter can take any format that ramses_rf supports, such as:

• /dev/ttyUSB0
• /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0
• mqtt://username:password@172.16.1.200:1883

MQTT Settings

Broker credentials, topic definitions, and publishing behaviour:

• MQTT server, username, password
• Topic roots and subtopics
• JSON-only vs. JSON+key/value publishing
• Zone grouping or device-flat layout
• Legacy topic compatibility mode

---

2. Ramses RF Schema (ramses_rf_schema.json)

The ramses schema file is the authoritative record of the evohome system as 'discovered' by the ramses_rf framework by listening in on the RF network.

It contains structured data on:

• All devices observed on the network
• Device types and capabilities
• Zones and zone data
• Controller identity
• Temperature ranges, supported features, flow configuration
• A known_list of devices that are permitted to operate via the ramses framework

Schema Creation and Updates

• On first run (or if there is no valid schema file, or if the ENABLE_DISCOVERY config parameter is explicitly set to True), evoGateway begins in both discovery mode + eavesdrop mode, to build the schema incrementally from RF traffic.

• During discovery, the evolving schema is published regularly to MQTT.

• Once sufficient information is collected (this may may take some time to build up, especially if there are any ufh controllers or DHW senders on the network), the schema can be saved either manually via an MQTT command or automatically at system shutdown. The default save location is config/ramses_rf_schema.json.

• On subsequent runs, evoGateway loads this file if available, avoiding repeated discovery (which can be very resource intensive).

• Note that if evoGateway is started with a valid schema file, it will NOT normally re-save the current schema at system shutdown, in order to avoid overwriting any custom modifications in the startup schema. This behaviour can be changed by setting the configuration parameter ALWAYS_SAVE_SCHEMA_ON_SHUTDOWN to True.

Schema Support Commands

Two administrative commands (sent via the MQTT command topic) control schema publishing and persistence:

| Command | Description | | ------------- | ------------------------------------------------------------------------ | | POST_SCHEMA | Publishes the current schema over MQTT to the _gateway_config subtree. | | SAVE_SCHEMA | Publishes the schema and writes it back to the JSON file on disk. |

Editing the Schema

Although it is not normally necessary to modify this file manually, initially it may be easier to add device aliases directly in this file, and/or amend the known_list, as these do not seem to always come through from the automatic discovery.

The schema file can subsequently be regenerated from scratch at any time by either:

1. Deleting the current schema and then starting evoGateway
2. Setting the ENABLE_DISCOVERY to True in the Ramses_rf section of the evoGateway config file.

---

**Operat