thermocktat

Thermocktat

A lightweight thermostat emulator, primarily designed for BMS software testing (Building Management Systems).

Attributes

Regulation - ambient temperature simulation

The regulation of ambient temperature is simulated using a PID regulator and hysteresis (see diagram below).

Regulation simulates the effect of heating or cooling systems controlled by the thermostat that will actually heat and cool the room in order to reach the desired temperature (setpoint).

This example is for the heating mode. If the ambient temperature is above setpoint, or below within a hysteresis range (- TargetHysteresis, 1°C in this example), heating is not triggered. When it is lower with a difference greater than the target hysteresis, heating start until the target temperature is reached. The target is the setpoint temperature plus the target hysteresis.

In auto mode, a second hysteresis ModeChangeHysteresis (greater than TargetHysteresis) can trigger switching regulation direction between cooling and heating. For example, if the TargetHysteresis is 1 and the ModeChangeHysteresis is 2 (default values):

• if temperature setpoint is 20, and ambient temperature is above 22 (setpoint + ModeChangeHysteresis), regulation will switch to cooling, and cool until 19 (setpoint - TargetHysteresis);
• if temperature setpoint is 20, and ambient temperature is below 18 (setpoint - ModeChangeHysteresis), regulation will switch to heating, and cool until 21 (setpoint + TargetHysteresis).

Regulation params can be set in the config.yaml file (see cmd/app/config_defaults.yaml). Regulation can also be disabled (in this case, ambient temperature will remain constant).

Heat losses (or gains) through room walls are also simulated and simply modeled by a conduction coefficient. A temperature delta proportional to the difference between outdoor and ambient temperatures and to this coefficient is added to the ambient temperature every second. The heat loss coefficient represents the room's thermal condictivity (the higher the coefficient, the higher the loss). It can be configured in the heat_loss section of the config file (see cmd/app/config_defaults.yaml). Set to 0 for no heat loss.

The outdoor temperature is supplied by a configurable weather provider (weather_provider section):

• static (default): a fixed outdoor temperature, taken from weather_provider.static.outdoor_temperature, or from heat_loss.outdoor_temperature when unset.
• open-meteo: fetches the current temperature for a latitude/longitude from the free Open-Meteo API (no key required), refreshed every refresh_interval (default 1h). The last known value is kept if a refresh fails.

weather_provider:
  type: open-meteo        # static | open-meteo
  refresh_interval: 1h
  open_meteo:
    latitude: 48.8566
    longitude: 2.3522

All keys can also be set via env vars, e.g. TMK_WEATHER_PROVIDER_TYPE, TMK_WEATHER_PROVIDER_OPEN_METEO_LATITUDE.

API Documentation

• HTTP Controller API
• MQTT Controller API
• Modbus Controller API
• BACnet Controller API
• KNX Controller API

Configuration

Thermocktat can be configured from a file (see cmd/app/config_defaults.yaml).

Configuration can also be passed using environment variables with the TMK_ prefix. Environment variables have priority over config file.

If no config is provided, default values will be used (values from cmd/app/config_defaults.yaml).

For each controller, the addr field is in the format host:port (host will be localhost by default). For most controllers, it is used to set the url that the server will expose. For mqtt, addr is the address of the broker.

Running with Docker

Thermocktat is primarily distributed as a Docker image.

# Run with default params
docker run -p 8080:8080 thermocktat

# Set controller and address using environment variables
docker run --rm -e TMK_CONTROLLER=http -e TMK_ADDR=:8080 -p 8080:8080 thermocktat

docker run --rm -e TMK_CONTROLLER=mqtt -e TMK_ADDR=tcp://host.docker.internal:1883 -e TMK_DEVICE_ID=my-thermocktat thermocktat

docker run --rm -e TMK_CONTROLLER=modbus -e TMK_ADDR=0.0.0.0:1502 -e TMK_DEVICE_ID=my-thermocktat -p 1502:1502 thermocktat

# Run with a config file mounted as a volume
docker run -v $(pwd)/config.yaml:/config.yaml -p 8080:8080 thermocktat -config /config.yaml

Contributing

Want to build from source, run the tests, or open a pull request? See CONTRIBUTING.md.

License

MIT