![Logo](images/logo.png)
This repo is a template of how to build on IQT Labs EdgeTech-Core functionality to instantiate an MQTT client. The philosophy behind EdgeTech-Core is to minimize development requirements for standing up the software stack of an "edge" system. The template includes all of the files and code scaffolds required to build in the EdgeTech framework. All of this functionality is wrapped in a Docker container for cross-platform compatibility.
You'll need to rename various files and directories as well as customize based on your functional needs, but the EdgeTech framework and scaffolding should minimize the development requirements. If you don't find that to be the case, submit a pull request and help us make this repository better!
Make Contribution
·
Report Bug
·
Request Feature
- edgetech-daisy
- edgetech-filesaver
- edgetech-audio-recorder
- edgetech-c2
- edgetech-telemetry-pinephone
- edgetech-s3-uploader
- edgetech-couchdb-startup
- edgetech-couchdb-saver
- edgetech-http-uploader
- aisonobuoy-collector-pinephone
Running this repo requires that you have Docker for containerization, Poetry for dependency management, and Python 3.11.1 is the version we've been building with.
Hit Use this template
and Create a new repository
to get started. Name it edgetech-
plus whatever functionality you're adding. You'll also want to rename everything that says template
in this repository with that name.
Please use README_TEMPLATE.md
as a template for your own README.md
file. You'll want to delete this README.md
and rename the README_TEMPLATE.md
to README.md
.
Within the template
directory, you should find several files: a Dockerfile
, pyproject.toml
, poetry.lock
, and template_pub_sub.py
. These files are the core of the template and are required to build your own module, though you'll want to rename the template_pub_sub.py
file to whatever your module is called.
pyproject.toml
is generated by running poetry init
as we recommend using poetry
to manage dependencies.
Once the pyproject.toml
has been created, use poetry install
to generate the poetry.lock
file. You'll want to run poetry config virtualenvs.create false
and poetry install --no-dev
before calling poetry install
.
The core module that is a python wrapper around interacting with MQTT system, heartbeats and tests. The template_pub_sub.py
file includes examples of recommended usage of the BaseMQTTPubSub
module and how to build a child class using it.
An outline of the basic functionality can be found below.
Inheriting BaseMQTTPubSub
:
from base_mqtt_pub_sub import BaseMQTTPubSub
class TemplatePubSub(BaseMQTTPubSub):
def __init__(
self: Any,
...
**kwargs: Any,
):
super().__init__(**kwargs)
The use of **kwargs
allows you to override any of the class parameters set in the BaseMQTTPubSub
constructor.
In the constructor of the child class, it is recommended that you connect to the MQTT client and publish a message to the /registration
topic upon successful connection.
self.connect_client()
sleep(1)
self.publish_registration("Template Module Registration")
Every child class should include a main()
function which includes a publishing to the /heartbeat
channel to keep the connection alive and any subscriptions to other topics in the system. It should also include a while True
loop to keep the main thread alive and flush all scheduled function calls.
def main(self: Any) -> None:
schedule.every(10).seconds.do(
self.publish_heartbeat, payload="Template Module Heartbeat"
)
self.add_subscribe_topic(self.example_topic, self._example_callback)
...
while True:
try:
schedule.run_pending()
sleep(0.001)
except Exception as e:
if self.debug:
print(e)
To call the child class see that the environment variables are passed via docker-compose
and passed to the constructor. The main()
function is then called.
template = TemplatePubSub(
...,
mqtt_ip=os.environ.get("MQTT_IP"),
)
template.main()
Examples of a Dockerfile
and docker-compose.yaml
can also be found in this repo. Adding whatever environment variables that your class needs should go into your .env
file after renaming the template.env
and paths/names will need to be adjusted as well. The Dockerfile
should only require script name/path changes as well.
Recommended topic names should follow the format specified below.
f"{DEVICE}/{HOST_NAME}/{DATA_TYPE}/{CONTAINER_NAME}/{TYPE_LITERAL}"
Example:
f"/AISonobuoy/{HOST_NAME}/AIS/edgetech-daisy/bytestring
- how to write tests for a child class of the core module
See the open issues for a full list of proposed features (and known issues).
- Fork the Project
- Create your Feature Branch (
git checkout -b dev
) - Commit your Changes (
git commit -m 'adding some feature'
) - Run (and make sure they pass):
black --diff --check *.py
pylint --disable=all --enable=unused-import *.py
mypy --allow-untyped-decorators --ignore-missing-imports --no-warn-return-any --strict --allow-subclassing-any *.py
If you do not have them installed, you can install them with pip install "black<23" pylint==v3.0.0a3 mypy==v0.991
.
- Push to the Branch (
git push origin dev
) - Open a Pull Request
See CONTRIBUTING.md
for more information.
Distributed under the Apache 2.0. See LICENSE.txt
for more information.
- Twitter: @iqtlabs
- Email: [email protected]
See our other projects: https://github.com/IQTLabs/