Mapping OTthing sensors for SAT

[sergeantd83]

Part I ( Mapping EMS/ESP32 sensors for SAT )

SAT	OT Thing	UOM	Read / Write	Description	MsgID
DATA_FLAME_ACTIVE	flame	Binary	R	Whether the flame is ON or OFF	0:LB3
DATA_DHW_SETPOINT	dhw_set_t	°C	R	The DHW setpoint	56
DATA_CONTROL_SETPOINT	ch_set_t	°C	W	The Boiler flow water temperature setpoint	1
DATA_REL_MOD_LEVEL	rel_mod	%	R	The current boiler modulation	17
DATA_BOILER_TEMPERATURE	flow_t	°C	R	The boiler flow water temperature	25
DATA_RETURN_TEMPERATURE	return_t	°C	R	The return water temperature	28
DATA_DHW_ENABLE	dhw_mode	Binary	R	When the DHW is in use	0:LB2
DATA_CENTRAL_HEATING	ch_mode	Binary	R	When the thermostat asks for heating	0:LB1
DATA_SLAVE_MEMBERID	memberId	Integer	R	The unique number of the Boiler Manufacturer	3:LB
DATA_BOILER_CAPACITY	max_capacity	kW	R	The Rated maximum power in kW of the boiler	15
DATA_REL_MIN_MOD_LEVEL	maxModulation	%	R		15
DATA_MAX_REL_MOD_LEVEL_SETTING	min_modulation	%	W	The maximum allowable power of the boiler	14
DATA_DHW_SETPOINT_MINIMUM	dhwMin	°C	R	The min value for the DHW setpoint	48
DATA_DHW_SETPOINT_MAXIMUM	dhwMax	°C	R	The max value for the DHW setpoint	48

Part II ( Boiler control )

OTGW Command Payload	OT Thing Command Payload	Description
await self._send_command(f"CH={1 if state == DeviceState.ON else 0}")		The CH command starts / stops the heating
await self._send_command(f"CS={value}")		The CS command manipulates the boiler flow water setpoint
await self._send_command(f"MM={value}")		The MM command manipulates the maximum modulation of the boiler
await self._send_command(f"SW={value}")		The SW command changes the DHW setpoint
await self._send_command(f"SH={value}")		The SH command manipulates the max allowable boiler flow water temperature

Part III ( Command Topic )

OTGW Command Topic	OT Thing Command Topic
await mqtt.async_publish(self.hass, f"{self._topic}/set/{self._node_id}/command", payload)

Part IV ( Publish Topic )

OTGW Publish Topic	OT Thing Publish Topic
OTGW/value/{self._node_id}

[Phunkafizer]

OTthing submits all readable status information in a single MQTT topic:

%basetopic%/state
%basetopic% is "otthing/%shortMAC%" by default, but can be configured in OTthing. Exampletopic:

otthing/31F44C/state

Example for the JSON payload sent in this topic:

{
    "runtime": 351450,
    "freeHeap": 158496,
    "resetInfo": 12,
    "fw_version": "2.21",
    "USB_connected": false,
    "reset_reason0": 12,
    "reset_reason1": 1,
    "numWifiDisc": 0,
    "new_fw": "v2.21",
    "dateTime": "22.12.2025 23:21:19",
    "wifi": {
        "status": 3,
        "mode": 1,
        "ipsta": "192.168.178.34",
        "mac": "9C:9E:6E:31:F4:4C",
        "hostname": "otthing",
        "sta_ssid": "abcdefg",
        "rssi": -57
    },
    "mqtt": {
        "connected": true,
        "basetopic": "otthing/31F44C",
        "numDisc": 0
    },
    "slave": {
        "slave_config_member": {
            "value": "4108",
            "dhw_present": true,
            "ctrl_type": false,
            "cooling_config": false,
            "dhw_config": false,
            "master_lowoff_pumpctrl": false,
            "ch2_present": false
        },
        "memberId": 8,
        "status": {
            "value": "30a",
            "fault": false,
            "ch_mode": true,
            "dhw_mode": false,
            "flame": true,
            "cooling": false,
            "ch2_mode": false,
            "diagnostic": false
        },
        "vent_status": null,
        "dhwMax": 65,
        "dhwMin": 5,
        "tr_override": 0,
        "rel_mod": 12,
        "ch_pressure": 1.7,
        "flow_t": 44.7,
        "dhw_t": 35,
        "outside_t": null,
        "unsuccessful_burner_starts": 3,
        "num_flame_signal_low": 188,
        "burner_starts": 13559,
        "burner_op_hours": 19491,
        "dhw_burner_op_hours": 405,
        "fault_flags": null,
        "rp_flags": {
            "value": "101",
            "dhw_setpoint_rw": true,
            "max_ch_setpoint_rw": false,
            "dhw_setpoint_trans": true,
            "max_ch_setpoint_trans": false
        },
        "remote_override_function": {
            "value": "3",
            "manual_change_priority": true,
            "program_change_priority": true
        },
        "connected": true,
        "txCount": 706238,
        "rxCount": 706236,
        "timeouts": 1
    },
    "thermostat": {
        "ch_set_t": 40.6,
        "room_t": 19.8,
        "room_set_t": 22,
        "master_config_member": {
            "value": "116",
            "smartPowerImplemented": false
        },
        "memberId": 22,
        "dhw_set_t": 51,
        "status": {
            "value": "300",
            "ch_enable": true,
            "dhw_enable": true,
            "cooling_enable": false,
            "otc_active": false,
            "ch2_enable": false
        },
        "txCount": 329058,
        "rxCount": 329058,
        "invalidCount": 0,
        "smartPower": "low"
    },
    "heatercircuit": [
        {
            "roomsetpoint": 22,
            "roomtemp": 19.8,
            "ovrdFlow": false,
            "mode": 2
        },
        {
            "ovrdFlow": false,
            "mode": 2
        }
    ],
    "outsideTemp": 0.5,
    "1wire": {
        "2812ba651b1301a4": 33.4,
        "28c070881b130145": 44.7
    }
}

Topics for setting values:
<basetopic>/dwhSetTemp set DHW temperature
<basetopic>/chSetTemp1 set flow temperature channel 1; <basetopic>/chMode1 has to be set to "heat"
<basetopic>/chSetTemp2 set flow temperature channel 2; <basetopic>/chMode2 has to be set to "heat"
<basetopic>/chMode1 "off" switches off channel 1
<basetopic>/chMode2 "off" switches off channel 2
<basetopic>/chMode1 "auto" will let OTthing calculate the flow temperature for channel 1
<basetopic>/chMode2 "auto" will let OTthing calculate the flow temperature for channel 2

[sergeantd83]

@Phunkafizer thanks for your reply and sorry for the delayed response.

I can't find the MsgID14 ( Max-rel-mod-level-setting ) in the example JSON payload, which is crucial to enable the Low-Load Control that SAT offers. Am I missing something?

Moreover, we use the MsgID15 values to calculate the current boiler power and expose it as a sensor in SAT.

/chMode1 "off": switches off channel 1
/chMode1 "auto": will let OTthing calculate the flow temperature for channel 1

If SAT wants to enable heating, should it send the "auto" or "on" value?

[Phunkafizer]

Max. capacity is set in slave.max_capacity and min. modulation is set in slave.min_modulation. According to OpenTherm specification these values are optional, so you can not rely on it. My boiler (Hoval) does not supply these values, also many others don't.

Msg ID 14 is not yet implemented by OTthing, but I will add it under topic:
/maxModulation
But according to OpenTherm specification this should only be used in on/off mode, not for condensation mode boilers.

chModeX: If SAT calculates and sends the flow set temperatures on it's own use "on", otherwise "auto" (OTthing will calculate flow set temp using it's heating curves)

P.S. I saw the part about the basetopic in my previous message was corrupted, I corrected it

[sergeantd83]

Msg ID 14 is not yet implemented by OTthing, but I will add it under topic:
/maxModulation
But according to OpenTherm specification this should only be used in on/off mode, not for condensation mode boilers.

Actually it is very important ( almost as the Control Setpoint ). Which was the hardest part of the SAT's control algorithms development.

Based on Schelte Bron's background information:

Capacity control
In capacity control mode, the thermostat calculates a modulation level and sends that to the boiler (message ID 14). It sets the control setpoint (message ID 1) to the maximum value it obtained from the boiler (message ID 57) or some internal default.
This mode is most frequently used when even the minimum boiler capacity is more than what is needed at the time. In that case the max relative modulation level (message ID 14) is set to 0% to make the boiler run at its minimum capacity. The room temperature is then maintained by turning the boiler on and off over time at its minimum capacity, similar to how an old-fashioned on/off thermostat controls a boiler. This method of controlling a boiler is also known as low load control.

Source: https://otgw.tclcode.com/background.html

[Phunkafizer]

DATA_CONTROL_SETPOINT -> it is write only, not available from boiler
DATA_RETURN_TEMPERATURE -> return_t
DATA_REL_MIN_MOD_LEVEL -> min_modulation
DATA_MAX_REL_MOD_LEVEL_SETTING -> it is write only, not available from boiler

[sergeantd83]

@Phunkafizer, could you please review the "Part I (Mapping EMS/ESP32 Sensors for SAT)" table and verify its accuracy?

[Phunkafizer]

as ov OTthing v2.24 this topic is available for controlling max. modulation:

%basetopic%/maxModulation

[sergeantd83]

Ok thanks! I think now we have all the necessary ingredients to build the OT thing coordinator!

[sergeantd83]

Another question. maxModulation will be able to take any value between 0% and 100%?

[Phunkafizer]

Yes, integer values between 0..100, but minimal "working" value depends on boiler.

[sergeantd83]

According to OpenTherm specifications and proper OpenTherm implementation, the relative modulation should always be between 0% -> 100%. Actually this is the reason that is called relative and not absolute. 0% means the boiler is running at its minimum capacity while 100% means it is running at its maximum capacity.