Metadata-Version: 2.4
Name: moat-dev-heat
Version: 1.0.2
Summary: Heating controller for a heat pump, a pellet burner and a buffer, on MoaT-Link
Author-email: Matthias Urlichs <matthias@urlichs.de>
Project-URL: homepage, https://m-o-a-t.org
Project-URL: repository, https://github.com/M-o-a-T/moat
Keywords: MoaT
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AnyIO
Classifier: Framework :: Trio
Classifier: Framework :: AsyncIO
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Developers
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: anyio~=4.2
Requires-Dist: asyncclick~=8.3
Requires-Dist: attrs
Requires-Dist: pydantic~=2.12
Requires-Dist: moat-util~=0.64.8
Requires-Dist: moat-dev~=0.1.0
Requires-Dist: moat-lib-config~=0.2.5
Requires-Dist: moat-lib-path~=0.4.1
Requires-Dist: moat-lib-pid~=0.8.5
Requires-Dist: moat-lib-run~=0.2.4
Requires-Dist: moat-link~=0.11.4
Requires-Dist: moat-link-schema~=0.0.5
Requires-Dist: moat-modbus~=0.9.17
Dynamic: license-file

# Turn on the Heat

% start synopsis
% start main

A heating controller for a hybrid system: a Solvis buffer and heating
circuit, a heat pump, and a KWB pellet burner. Independent units on
MoaT-Link compute the heating curve, pick the heat source, and drive the
heat pump, the burner, the heating valve and the water pump.

% end synopsis

The controller consists of these units, each a separate MoaT-Link
service:

| Unit | Role |
| --- | --- |
| `target` | heating curve and heat demand |
| `heat_valve` | heating circuit on/off |
| `flow` | the heat pump's water pump (PWM) |
| `pump` | the heat pump's state machine and load |
| `pellet` | the pellet burner's load and temperature |
| `selector` | which heat sources may run |
| `errors` | the heat pump's errors and their severity |
| `frost` | frost protection of the idle heat-pump loop |
| `passthru` | handing the heat pump to its original controller for maintenance, and back |
| `watchdog` | shuts the heat pump down when the pump unit dies (optional, on another host) |

`moat dev heat run` runs all units but the watchdog in one process;
`moat dev heat run UNIT…` runs some of them. Each unit waits until no
other process runs it, so a second instance is a hot standby. The
units read their sensors from, and write their commands to, the Modbus
pollers (`moat modbus dev poll`) of the heat pump and the Solvis
controller; `moat dev heat pwm` drives the water pump's PWM output, and
`moat dev heat modbus_mon` restarts a stuck Solvis poller. The package
`moat-dev-heat-service` has systemd units for all of these.

Other commands:

- `moat dev heat stop` stops the units in an orderly way: the heat
  pump is switched off and cooled down before the water pump stops.
- `moat dev heat off` shuts the heat pump down at once (emergency).
- `moat dev heat override` sets or clears an operator override, e.g.
  to keep the heat pump off.
- `moat dev heat migrate` converts the legacy controller's
  configuration and state to the units' MoaT-Link items (once).
- `moat dev heat record` records MoaT-Link data for tests.
  `moat dev heat sim`, in the separate `moat-dev-heat-sim` package,
  runs a plant simulator on MoaT-Link.

The units' configuration lives in MoaT-Link (`cfg.app.heat.UNIT`),
overlaid on the package defaults, and takes effect without a restart.

Safety depends on the `flow` unit: an emergency shutdown, whether by
the pump unit, the watchdog or `moat dev heat off`, asks the flow unit
to keep the water running until the heat pump has cooled down. If the
flow unit is dead too, the water pump keeps its last PWM. That protects
the heat pump from overheating, but nothing stops the water pump
afterwards.

% end main
