Gridworks Proactor

This packages provides "live actor" and "application monitored communication" infrastructure for the GridWorks SpaceHeat SCADA project. This separation allows the scada code to be more focussed on on application specific details and provides the potential to re-use the "live actor" and "application monitored" infrastructure.

Features

• Proactor, a single threaded event loop running on asyncio, for exchanging messages between the main application object, "live actor" subobjects and MQTT clients.
• A communication state ("active" or not) for each external communications link is available to the proactor and sub-objects. "Active" communications is defined as ALL of the following:
  • The underlying communications mechanism (MQTT) is connected.
  • All input channels of underlying mechanism (MQTT topics) are established.
  • A application messages requiring acknowledgement have been ACKed in timely fashion (by default 5 seconds).
  • A message has been received "recently" (by default within 1 minute).
• Reliable delievery of "Events" generated locally. Generated Events are stored locally until they are acknowledged and unacknowledged Events are retransmitted when the "Active" communication state is restored.
• gwproactor_test, a package providing a "live test" infrastructure enabling tests that simulate communication between Proactors.

Requirements

Mosquitto

Testing requires an MQTT broker. The Mosquitto broker can be installed with:

brew install mosquitto
brew services restart mosquitto

TLS

Testing uses TLS by default. The tests require the path to the CA certificate and private key used to sign the certificate of the MQTT broker. To set up TLS:

Install gridworks-cert (gwcert):

uv tool install gridworks-cert

Create a local Certificate Authority:

gwcert ca create NAME_OF_YOUR_LOCAL_CA

Create certificate and key for the Mosquitto MQTT broker:

gwcert key add --dns localhost mosquitto

• NOTE: This command will generate a broker certificate that only allow connections to localhost. See External connections below to create a broker certificate which can accept connections from external devices.

Find the path to mosquitto.conf in the output of:

brew services info mosquitto -v

Modify mosquitto.conf with the TLS configuration in example-test-mosquitto.conf, fixing up the paths with real absolute paths to certificate, key and CA certificate files. These paths can be found with:

gwcert ca info

Restart the Mosquitto server:

brew services restart mosquitto

Test Mosquitto 'clear' port:

# in one window
mosquitto_sub -h localhost -p 1883 -t foo
# in another window
mosquitto_pub -h localhost -p 1883 -t foo -m '{"bla":1}'

Test Mosquitto TLS port:

gwcert key add pubsub
# in one window
mosquitto_sub -h localhost -p 8883 -t foo \
     --cafile $HOME/.local/share/gridworks/ca/ca.crt \
     --cert $HOME/.local/share/gridworks/ca/certs/pubsub/pubsub.crt \
     --key $HOME/.local/share/gridworks/ca/certs/pubsub/private/pubsub.pem
# in another window
mosquitto_pub -h localhost -p 8883 -t foo \
     --cafile $HOME/.local/share/gridworks/ca/ca.crt \
     --cert $HOME/.local/share/gridworks/ca/certs/pubsub/pubsub.crt \
     --key $HOME/.local/share/gridworks/ca/certs/pubsub/private/pubsub.pem \
     -m '{"bar":1}'

Troubleshooting Mosquitto

Mosquitto logging can be enabled in the mosquitto.conf file with the lines:

log_dest stderr
log_type all

To see the console output, stop the Mosquitto service and start it explicitly on the command line:

brew services stop mosquitto
mosquitto -c /opt/homebrew/etc/mosquitto/mosquitto.conf

External connections

The broker certificate must be created with the hostname the client will use to connect to it. For example, to create a broker certificate reachable at localhost, MyMac.local, 192.168.1.10 and foo.bar.baz use the command:

gwcert key add \
  --dns localhost \
  --dns MyMac.local \
  --dns 192.168.1.10 \
  --dns foo.bar.baz \
  mosquitto

Pre-existing key files

If CA or Mosquito certificate can key files already exist, their paths can be specified in mosquitto.conf as above and for the tests with there GWPROACTOR_TEST_CA_CERT_PATH and GWPROACTOR_TEST_CA_KEY_PATH environment variables.

Disabling TLS

To disable testing of TLS, modify the the file tests/.env-gwproactor-test with:

GWCHILD_PARENT_MQTT__TLS__USE_TLS=false
GWPARENT_CHILD_MQTT__TLS__USE_TLS=false

Installation

You can install Gridworks Proactor via pip from PyPI:

$ pip install gridworks-proactor

Contributing

Contributions are very welcome. The project is developed with uv, which can be installed from here.

The development environment requires the gwproactor_test package. Install with:

uv sync --all-extras

The created environment can be explicitly activated with:

source .venv/bin/activate

Run with:

uv run pytest

Or run the whole test swuite with:

uv run nox

To learn more, see the Contributor Guide.

License

Distributed under the terms of the MIT license, Gridworks Proactor is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Credits

This project was generated from @cjolowicz's Hypermodern Python Cookiecutter template.