gilles/froling_S3_modbus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[DOC] update docu

Browse Source 
- HA Modbus interface
- exmaple modbus.yaml and template.yaml
This commit is contained in:
smokyflex
2023-10-29 09:50:06 +01:00
parent a9d54893d1
commit 21c2ccce29
3 changed files with 542 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
README.md
View File

@@ -1,8 +1,10 @@
# pe1-modbus
This project is a work in progress, integrating live data from a Froeling PE1 Heater into Home Assitant via Modbus TCP and MQTT.
This project offers a guideline how a Fröling PE1 / Lambdatronic Pellet boiler can be integrated into Home Assistant (HA - https://www.home-assistant.io) using the builtin Modbus interface.
Opposite to the Service/App "FrolingConnect" this approach keeps all communication in the local network and is therefore offers adjustable / shorter data refresh interval cycles.
This repo also includes python scripts that use a modbus module to read registers from PE1 an then post them via MQTT to use inside Home Assistant but this is not necessary since HA has it's own Modbus interface where we can directly map PE1 registers to HA entities.
At the time of writing the only drawback is that it seems to be impossible to combine those Modbus entites in HA into a Homeassitant device. The MQTT interface supports this so if you want that check the code in /src/pe1modbus.
## Hardware Requirements
The Lambdatronic board offers 2 serial interfaces, which can be configured to Modbus TCP in the settings.
@@ -16,12 +18,102 @@ https://loxwiki.atlassian.net/wiki/spaces/LOX/pages/1704984631/Fr+ling+Pelletske
## Modbus TCP
Using python libraries for ModbusTCP, a connection to the waveshare converter can be established fairly easy. Information on Register addresses etc. can be studied in the ModBus Lambdatronic 3200 Modbus Definition Document (google search should provide a link to download).
After the hardware setup, there are many ways to test the modbus communication. QModMaster is a great tool for exploring Registers via a GUI - https://github.com/zhanglongqi/qModMaster. You could also write some short script in Python using the module pyModbusTCP (https://pypi.org/project/pyModbusTCP/), see **** in this repo for an example.
## MQTT
Now that we have the data available via network and python script, we need a way to publish this data to the Home Assistant Server in our network. This can be done using the MQTT protocol, which is supported by Home Assistant (there is extensive documentation available on how to do this). Python provides libraries e.g. (paho-mqtt) to quickly setup a mqtt communication service.
Information on Register addresses etc. can be studied in the ModBus Lambdatronic 3200 Modbus Definition Document (google search should provide a link to download).
## LINUX service
Lastly we can create a python script like "mqtt.py" in this repo, to automate this pipeline via a linux service that can run on the same host as the Home Assistant server for example. This script aquires the data from the PE1-Heater via Modbus every 30s and then publishes this data via MQTT to the home assistant.
## Home Assitant Modbus
Voila
Home Assitant offers a interface to include entities using the Modbus protocol - https://www.home-assistant.io/integrations/modbus/
The cleanest way to do this would be to create a `modbus.yaml` in your HA home directory (next to the configuration.yaml) and include it into the configuration like so:
```yaml
modbus: !include modbus.yaml
```
This repo includes an example `modbus.yaml` file including a few entities that can be easily extended to suit your needs.
Inside the `modbus.yaml` we first need to specify the `hub` which for this setup is the address of the Waveshare Converter.
The PE1 boiler usues a seperate Ethernet connection which is intended for the Fröling Connect service. Make sure to specify the Waveshare converter address in the yaml.
```yaml
- name: pe1_hub
type: tcp
host: xxx.xxx.xxx.xxx # address of the Waveshare converter
port: 502
sensors:
...
```
In the sensors section, you can spceify the register addresses you want to map to HA entities. For further information on how to address input registers holding registers etc. study the HA Modbus documentation linked above.
The PE1 system offers two input registers that specify the system status and the boiler status which are impelemented via an enum. See the Lambdatronic Modbus Definition PDF for more information on this. If you want to amp those status integer values to the corresponding status strings you can do this in HA via templating.
Example: So lets say we have declared one entity for the system status in our `modbus.yaml` like so:
```yaml
- name: Modbus PE1 System Status Enum
unique_id: modbus_pe1_system_status_enum
slave: 2
input_type: input
address: 4000
scan_interval: 30
device_class: enum
```
We can then create a template entity in e.g. another yaml file used for template entities in the HA config directory `template.yaml` which is again included in the `configuration.yaml` like so:
```yaml
template: !include template.yaml
```
Inside this file we can map the enum values of our entity `modbus_pe1_system_status_enum` to string values that we can use to display in the frontend in some human readable format:
```yaml
- name: "Modbus PE1 System Status"
unique_id: "modbus_pe1_system_status"
state: >
{% set mapper = {
'0' : 'Continuous load',
'1' : 'Domestic hot water',
'2' : 'Automatic',
'3' : 'Firewood operation',
'4' : 'Cleaning',
'5' : 'Boiler off',
'6' : 'Extra heating',
'7' : 'Chimney sweep',
'8' : 'Cleaning' } %}
{% set state = states.sensor.modbus_pe1_system_status_enum.state %}
{{ mapper[state] if state in mapper else 'Unknown' }}
icon: >
{% if this.state == 'Automatic' %}
mdi:refresh-auto
{% elif this.state == 'Domestic hot water' %}
mdi:water-pump
{% elif this.state == 'Continous load' %}
mdi:hours-24
{% else %}
mdi:alert-circle
{% endif %}
```
Here you could also change the icon of the entity based on it's state like shown above.
The same can be done for the boiler/furnace status. See the full `modbus.yaml` and `template.yaml` included in this repo for more info.
## TODO
The Lambdatronic Modbus Definition document describes how to use modbus to remote control the boiler heating mode. I have not yet managed to get that working. According to the document the heating mode register adrresses should reside at 48047 - 48064 in the holding registers.
So theoretically we should be able to write those registers to change the heating mode.
There are 18 registers for that because we could have a max of 18 possible heating-circuits. Those registers should hold values from 0 to 5 for the six different modes:
* 0 ... Aus
* 1 ... Automatik
* 2 ... Extraheizen
* 3 ... Absenken
* 4 ... Dauerabsenken
* 5 ... Partybetrieb
However when experimenting with those registeres I am unable to neither read the correct heating mode value nor write to it. Any help here would be much appreciated.

304
modbus.yaml Normal file
View File

@@ -0,0 +1,304 @@
- name: pe1_test
type: tcp
host: xxx.xxx.xxx.xxx
port: 502
# maybe need 1 second delay after connect for device to get ready
#delay: 1
sensors:
# SYSTEM STATUS
- name: Modbus PE1 System Status Enum
unique_id: modbus_pe1_system_status_enum
slave: 2
input_type: input
address: 4000
scan_interval: 30
device_class: enum
- name: Modbus PE1 Furnace Status Enum
unique_id: modbus_pe1_furnace_status_enum
slave: 2
input_type: input
address: 4001
scan_interval: 30
device_class: enum
#- name: Modbus PE1 Heating Mode Enum
# unique_id: modbus_pe1_heating_mode_enum
# slave: 2
# input_type: holding
# address: 46
# count: 18
# scan_interval: 30
# TEMPERATURES
- name: Modbus PE1 Hotwater Temperature Top
unique_id: modbus_pe1_hotwater_temperature_top
slave: 2
input_type: input
# 31631 - 30001 = 1630
address: 1630
scan_interval: 30
scale: 0.5
precision: 0
device_class: temperature
state_class: measurement
unit_of_measurement: °C
- name: Modbus PE1 Furnace Temperature
unique_id: modbus_pe1_furnace_temperature
slave: 2
input_type: input
address: 0
scan_interval: 30
scale: 0.5
precision: 0
device_class: temperature
state_class: measurement
unit_of_measurement: °C
- name: Modbus PE1 Calculated Heater Target Temperature
unique_id: modbus_pe1_calculated_heater_target_temperature
slave: 2
input_type: input
address: 27
scan_interval: 30
scale: 0.5
precision: 0
device_class: temperature
state_class: measurement
unit_of_measurement: °C
- name: Modbus PE1 Return Flow Temperature
unique_id: modbus_pe1_return_flow_temperature
slave: 2
input_type: input
address: 9
scan_interval: 30
scale: 0.5
precision: 0
device_class: temperature
state_class: measurement
unit_of_measurement: °C
- name: Modbus PE1 Calculated Target Return Flow Temperature
unique_id: modbus_pe1_calculated_target_return_flow_temperature
slave: 2
input_type: input
address: 66
scan_interval: 30
scale: 0.5
precision: 0
device_class: temperature
state_class: measurement
unit_of_measurement: °C
- name: Modbus PE1 Target Flow Temperature At Circulation Line
unique_id: modbus_pe1_return_flow_temperature_at_circulation_line
slave: 2
input_type: input
address: 711
scan_interval: 30
scale: 0.5
precision: 0
device_class: temperature
state_class: measurement
unit_of_measurement: °C
- name: Modbus PE1 Outside Temperature
unique_id: modbus_pe1_outside_temperature
slave: 2
input_type: input
address: 1000
scan_interval: 30
scale: 0.5
precision: 0
device_class: temperature
state_class: measurement
unit_of_measurement: °C
- name: Modbus PE1 Flow Temperature Actual
unique_id: modbus_pe1_flow_temperature_actual
slave: 2
input_type: input
address: 1030
scan_interval: 30
scale: 0.5
precision: 0
device_class: temperature
state_class: measurement
unit_of_measurement: °C
- name: Modbus PE1 Flow Temperature Target
unique_id: modbus_pe1_flow_temperature_target
slave: 2
input_type: input
address: 1031
scan_interval: 30
scale: 0.5
precision: 0
device_class: temperature
state_class: measurement
unit_of_measurement: °C
- name: Modbus PE1 Room Temperature
unique_id: modbus_pe1_room_temperature
slave: 2
input_type: input
address: 1032
scan_interval: 30
scale: 0.5
precision: 0
device_class: temperature
state_class: measurement
unit_of_measurement: °C
- name: Modbus PE1 Buffer Temperature Top
unique_id: modbus_pe1_buffer_temperature_top
slave: 2
input_type: input
address: 2000
scan_interval: 30
scale: 0.5
precision: 0
device_class: temperature
state_class: measurement
unit_of_measurement: °C
- name: Modbus PE1 Buffer Temperature Bottom
unique_id: modbus_pe1_buffer_temperature_bottom
slave: 2
input_type: input
address: 2002
scan_interval: 30
scale: 0.5
precision: 0
device_class: temperature
state_class: measurement
unit_of_measurement: °C
# CONSUMPTION
- name: Modbus PE1 Total Pellet Consumption
unique_id: modbus_pe1_total_pellet_consumption
slave: 2
input_type: input
address: 83
scan_interval: 3600
scale: 0.1
precision: 1
device_class: weight
state_class: total_increasing
unit_of_measurement: mg
- name: Modbus PE1 Pellet Consumption KG
unique_id: modbus_pe1_pellet_consumption_kg
slave: 2
input_type: input
address: 81
scan_interval: 3600
scale: 1
precision: 0
device_class: weight
state_class: total
unit_of_measurement: kg
- name: Modbus PE1 Pellet Fill Level
unique_id: modbus_pe1_pellet_fill_level
slave: 2
input_type: input
address: 21
scan_interval: 3600
scale: 0.005
precision: 1
device_class: battery
state_class: measurement
unit_of_measurement: '%'
# PUMP CONTROLS
- name: Modbus PE1 Return Flow Pump Control
unique_id: modbus_pe1_return_flow_pump_control
slave: 2
input_type: input
address: 36
scan_interval: 30
scale: 1
precision: 0
device_class: power_factor
state_class: measurement
unit_of_measurement: '%'
- name: Modbus PE1 Water Boiler Pump Control
unique_id: modbus_pe1_water_boiler_pump_control
slave: 2
input_type: input
address: 1632
scan_interval: 30
scale: 1
precision: 0
device_class: power_factor
state_class: measurement
unit_of_measurement: '%'
- name: Modbus PE1 Buffer Pump Control
unique_id: modbus_pe1_buffer_pump_control
slave: 2
input_type: input
address: 2003
scan_interval: 30
scale: 1
precision: 0
device_class: power_factor
state_class: measurement
unit_of_measurement: '%'
# BUFFER CHARGE
- name: Modbus PE1 Buffer Charge
unique_id: modbus_pe1_buffer_charge
slave: 2
input_type: input
address: 2006
scan_interval: 30
scale: 1
precision: 0
device_class: battery
state_class: measurement
unit_of_measurement: '%'
# MISC
- name: Modbus PE1 Operating Hours
unique_id: modbus_pe1_operating_hours
slave: 2
input_type: input
address: 20
scan_interval: 3600
scale: 1
precision: 0
device_class: duration
state_class: total_increasing
unit_of_measurement: 'h'
- name: Modbus PE1 Hours Since Last Maintenance
unique_id: modbus_pe1_hours_since_last_maintenance
slave: 2
input_type: input
address: 55
scan_interval: 3600
scale: 1
precision: 0
device_class: duration
state_class: total
unit_of_measurement: 'h'
- name: Modbus PE1 Hours Of Pellets Operation
unique_id: modbus_pe1_hours_of_pellets_operation
slave: 2
input_type: input
address: 62
scan_interval: 3600
scale: 1
precision: 0
device_class: duration
state_class: total_increasing
unit_of_measurement: 'h'
- name: Modbus PE1 Hours Of Heating
unique_id: modbus_pe1_hours_of_heating
slave: 2
input_type: input
address: 63
scan_interval: 3600
scale: 1
precision: 0
device_class: duration
state_class: total_increasing
unit_of_measurement: 'h'
- name: Modbus PE1 Hours Until Ash Removal
unique_id: modbus_pe1_hours_until_ash_removal
slave: 2
input_type: input
address: 86
scan_interval: 3600
scale: 1
precision: 0
device_class: duration
state_class: measurement
unit_of_measurement: 'h'

138
template.yaml Normal file
View File

@@ -0,0 +1,138 @@
- name: "Modbus PE1 System Status"
unique_id: "modbus_pe1_system_status"
state: >
{% set mapper = {
'0' : 'Continuous load',
'1' : 'Domestic hot water',
'2' : 'Automatic',
'3' : 'Firewood operation',
'4' : 'Cleaning',
'5' : 'Boiler off',
'6' : 'Extra heating',
'7' : 'Chimney sweep',
'8' : 'Cleaning' } %}
{% set state = states.sensor.modbus_pe1_system_status_enum.state %}
{{ mapper[state] if state in mapper else 'Unknown' }}
icon: >
{% if this.state == 'Automatic' %}
mdi:refresh-auto
{% elif this.state == 'Domestic hot water' %}
mdi:water-pump
{% elif this.state == 'Continous load' %}
mdi:hours-24
{% else %}
mdi:alert-circle
{% endif %}
- name: "Modbus PE1 Furnace Status"
unique_id: "modbus_pe1_furnace_status_mapped"
state: >
{% set mapper = {
'0' : 'FAULT',
'1' : 'Boiler off',
'2' : 'Heating up',
'3' : 'Heating',
'4' : 'Slumber',
'5' : 'Off',
'6' : 'Door open',
'7' : 'Preparation',
'8' : 'Pre-heating',
'9' : 'Ignition',
'10' : 'Shutdown wait',
'11' : 'Shutdown wait 1',
'12' : 'Shutdown feed 1',
'13' : 'Shutdown wait 2',
'14' : 'Shutdown feed 2',
'15' : 'Cleaning',
'16' : 'Wait 2h',
'17' : 'Suction / Heating',
'18' : 'Ignition fault',
'19' : 'Standby',
'20' : 'Close grate',
'21' : 'Empty stoker',
'22' : 'Pre-Heating',
'23' : 'Suction',
'24' : 'Close BBF',
'25' : 'Open BBF',
'26' : 'Tilt grate',
'27' : 'Warming-Up / Ignition',
'28' : 'Empty feed',
'29' : 'Stoker fill',
'30' : 'Warming-Up Lambda Probe',
'31' : 'FD fan run-on I',
'32' : 'FD fan run-on II',
'33' : 'Stopped',
'34' : 'Additional Ignition',
'35' : 'Ignition wait',
'36' : 'TS: Close BBF',
'37' : 'TS: Ventilate boiler',
'38' : 'TS: Ignition',
'39' : 'TS: min. feed',
'40' : 'Close BBF',
'41' : 'FAULT: HL/ES',
'42' : 'FAULT: Tilting grate',
'43' : 'FAULT: C.C.Overpressure',
'44' : 'FAULT: Door Switch',
'45' : 'FAULT: ID Fan',
'46' : 'FAULT: Heating system',
'47' : 'ERROR: STL/EO',
'48' : 'ERROR: Tilting grate',
'49' : 'ERROR: C.C. Overpressure',
'50' : 'ERROR: Door Switch',
'51' : 'ERROR: ID Fan',
'52' : 'ERROR: Heating system',
'53' : 'ERROR: Stoker',
'54' : 'FAULT: Stoker',
'55' : 'TS: Empty stoker',
'56' : 'Purge',
'57' : 'FAULT: wood chip',
'58' : 'ERROR: Wood chip',
'59' : 'Emerg. Oper.: Door open',
'60' : 'Emerg. Oper.: Heating up',
'61' : 'Emerg. Oper.: Heating',
'62' : 'ERROR: STL/EO',
'63' : 'ERROR: General',
'64' : 'Emerg. Oper.: Shutdown',
'65' : 'Self test active',
'66' : 'Troubleshooting 20min',
'67' : 'ERROR: Drop box',
'68' : 'FAULT: Drop box',
'69' : 'Cleaning possible',
'70' : 'Heating - Cleaning',
'71' : 'LW Heating up',
'72' : 'LW Heating',
'73' : 'LW Heat/Shut down',
'74' : 'FAULT save',
'75' : 'FGR run-on',
'76' : 'Clean FGR',
'77' : 'Igniton OFF',
'78' : 'Cleaning filter',
'79' : 'Heating wizard',
'80' : 'Ignite firewood boiler',
'81' : 'SH fault',
'82' : 'Sensor check' } %}
{% set state = states.sensor.modbus_pe1_furnace_status_enum.state %}
{{ mapper[state] if state in mapper else 'Unknown' }}
icon: >
{% if this.state == 'Standby' %}
mdi:sleep
{% elif this.state == 'Ignition' %}
mdi:fire
{% elif this.state == 'Pre-heating' %}
mdi:fire
{% elif this.state == 'Heating' %}
mdi:fire
{% elif this.state == 'Heating up' %}
mdi:fire
{% elif this.state == 'Preparation' %}
mdi:fire
{% elif this.state == 'Shutdown wait' %}
mdi:sleep
{% elif this.state == 'Shutdown wait 1' %}
mdi:sleep
{% elif this.state == 'Shutdown wait 2' %}
mdi:sleep
{% else %}
mdi:alert-circle
{% endif %}