Gridworks Proactor#

PyPI Status Python Version [License][license]

Read the documentation at https://gridworks-proactor.readthedocs.io/ Tests Codecov

pre-commit Black

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 test package for development and test environments of projects that implement a class derived from Proactor, allowing the derived class to be tested with the base-class tests.

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):

pipx install gridworks-cert

Create a local Certificate Authority:

gwcert ca create

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. In order to develop, do this:

$ poetry install --all-extras

To learn more, see the [Contributor Guide].

License#

Distributed under the terms of the [MIT license][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.