========
This code is intended for running a heat pump thermal storage space heating system in a house, and doing this transactively. That means the heating system is capable of dynamically responding to local electric grid conditions and buying energy at the lowest cost times, while keeping the house warm. We believe this repo may be instrumental in effectively and efficiently reaching a low-carbon future. For an architectural overview of the code, and why it has something to do with a low-carbon future, please go here.
This code is part of a larger framework. In particular it assumes there is a cloud-based actor which it refers to as the AtomicTNode (short for Atomic Transactive Node) that is calling the shots on its control decisions most of the time. In addition, the code is structured in an actor-based way, with a collection of actors each responsible for an important but limited set of functionality communicating to each other via messages. For a more specific description of both how these internal actors work with each other and how this repo fits into the larger transactive energy framework please go here; this page describes typical sequences of messages between relevant actors in the system.
We are indebted to Efficiency Maine, who spearheaded and funded the initial pilot using this code. As per the requirements of the initial pilot, the code is intended to: 1) run on a raspberry Pi 4; and 2) to be able to use a variety of off-the-shelf actuating and sensing devices.
For information on setting up an SD card that will run this code on a Pi 4 with the correct configuration and attached devices, please go here
Follow the directions below for creating a dev environment (assumes mac or Pi).
In one terminal window:
cd spaceheat
python run_local.py
WE NEED A BETTER LOCAL DEV DEMO
python -m venv venv
source venv/bin/activate
pip install -r requirements/dev.txt
Run the tests from the root directory of the repo with:
pytest
A hardware layout file is necessary to run the scada locally. Find the default path the layout file with:
python -c "import config; print(config.Paths().hardware_layout)"
For initial experiments the test layout file can be used. The test layout file is located at:
tests/config/hardware-layout.json
Display the hardware layout with:
python gw_spaceheat/show_layout.py
Display current settings with:
python gw_spaceheat/show_settings.py
There are some scratch notes on Pi-related setup (like enabling interfaces) in docs/pi_setup.md
python -m pip install pip-tools
pip-compile --output-file=base.txt base.in
pip-compile --output-file=dev.txt dev.in
pip-compile --output-file=drivers.txt drivers.in
The .in
files clarify the key modules (including which ones are important to pin and which ones can be set to the latest release) and then the corresponding .txt
files are generated via pip-tools. This means we always run on pinned requirements (from the .txt files) and can typically upgrade to the latest release, except for cases where the code requires a pinned older version.
The pip-tools also allow for building layers of requirements on top of each other. This allows us to have development tools that are not needed in production to show up for the first time in dev.txt
, for example (like the pip-tool itself).
SETTING UP SECRETS.
Configuration variables (secret or otherwise) use dotenv module in a gitignored .env
file, copied over from .env-template
. These are accessed via config.ScadaSettings
.
See instructions here to set up a local MQTT broker using Mosquitto.
TLS is used by default. Follow these instructions to set up a local self-signed Certificate Authority to create test certificates and to create certificates for the Mosquitto broker. Note that this section is relevant if you will connect to the Mosquitto broker from a Raspberry PI.
gwcert key add --certs-dir $HOME/.config/gridworks/atn/certs scada_mqtt
cp $HOME/.local/share/gridworks/ca/ca.crt $HOME/.config/gridworks/atn/certs/scada_mqtt
gwcert key add --certs-dir $HOME/.config/gridworks/scada/certs gridworks_mqtt
cp $HOME/.local/share/gridworks/ca/ca.crt $HOME/.config/gridworks/scada/certs/gridworks_mqtt
In one terminal run:
mosquitto_sub -h localhost -p 8883 -t foo \
--cafile $HOME/.config/gridworks/atn/certs/scada_mqtt/ca.crt \
--cert $HOME/.config/gridworks/atn/certs/scada_mqtt/scada_mqtt.crt \
--key $HOME/.config/gridworks/atn/certs/scada_mqtt/private/scada_mqtt.pem
In another terminal run:
mosquitto_pub -h localhost -p 8883 -t foo -m '{"bar":1}' \
--cafile $HOME/.config/gridworks/scada/certs/gridworks_mqtt/ca.crt \
--cert $HOME/.config/gridworks/scada/certs/gridworks_mqtt/gridworks_mqtt.crt \
--key $HOME/.config/gridworks/scada/certs/gridworks_mqtt/private/gridworks_mqtt.pem
Verify you see {"bar":1}
in the first window.
Use getkeys.py to create and copy TLS to keys to a scada such that it can communicate with the actual GridWorks MQTT broker. For details run:
python gw_spaceheat/getkeys.py --help
The overview of this process is that you need:
certbot
.getkeys.py
command line per its help. This command will show information about what scada would do if started locally:
python gw_spaceheat/run_scada.py --dry-run
This command will will start the scada locally:
python gw_spaceheat/run_scada.py
These commands will start the local test ATN:
python tests/atn/run.py
Distributed under the terms of the [MIT license][license], this repository is free and open source software.
Contributions are very welcome. To learn more, see the [Contributor Guide].