Develop¶

Use in your project¶

If you want to add this package to your own project and use it in your code, add qtpy-datalogger using your project's dependency manager.

uvpdmpoetry

Powershell

uv add qtpy-datalogger

Powershell

pdm add qtpy-datalogger

Powershell

poetry add qtpy-datalogger

Then import the package like any other in your source code.

my_program.py

from qtpy_datalogger import guikit as gk

Setup for development¶

The rest of this page is a crash course introducing the tools and libraries used in the project. Continue reading if you want to contribute to or customize qtpy-datalogger.

Software requirements¶

Windows 11 or Windows 10
git
Python and uv
MQTT broker

New to git and Python?

If these tools and commands are not on your system, follow the introductory Guide pages.

Do once¶

Before you can start developing, you need to download the source and install the software requirements on your workstation.

1. Get the source

Powershell

# Clone from GitHub
git clone https://github.com/wireddown/qtpy-datalogger.git
cd qtpy-datalogger

2. Initialize the environment

Powershell

# Install the package's dependencies
uv sync

3. Setup the MQTT broker

Run these commands to install and configure the Mosquitto MQTT broker.

For details, see the MQTT page

Powershell

# Install Mosquitto Broker
winget install --exact --id=EclipseFoundation.Mosquitto

# Configure Mosquitto
$mqttSettings = @(
    "listener 1883"
    "allow_anonymous true"
)
Add-Content -Path "C:\Program Files\mosquitto\mosquitto.conf" -Value $mqttSettings

# Configure Windows firewall
netsh advfirewall firewall add rule `
  name='Mosquitto MQTT: allow inbound on port 1883 from local subnet' `
  program='C:\Program Files\mosquitto\mosquitto.exe' dir=in action=allow service=any `
  description='Allow MQTT clients on the local subnet to connect to this host' `
  profile=private localip=any remoteip=localsubnet `
  localport=1883 remoteport=any protocol=tcp interfacetype=any

4. Initialize the QT Py

Connect the QT Py to your workstation with USB

Powershell

# Install and configure the sensor node runtime
uv run qtpy-datalogger equip --secrets -

When prompted:

set the WiFi SSID and password
set the broker IP address

Ready check¶

Connect the QT Py to your workstation with USB

Run these commands to confirm that your workstation is ready to develop.

Powershell

# Get latest source and dependencies from upstream
git switch main
git pull
uv sync

# Confirm dependencies are satisfied
uv sync --check

# Confirm GUI component readiness
uv run qtpy-datalogger run data-viewer

# Confirm MQTT server readiness
uv run qtpy-datalogger server

# Confirm QT Py detection
uv run qtpy-datalogger connect --discover-only

# Confirm sensor node readiness
uv run qtpy-datalogger equip --compare

# Send a message to the QT Py sensor node over WiFi
uv run qtpy-datalogger run scanner

Workflows¶

Create a branch¶

Powershell

# Get upstream changes
git switch main
git pull

# Create a new branch from main
git switch --create users/__YOU__/__NEW_TOPIC__

# Or update an existing branch
# 1. Switch to your branch
#    git switch users/__YOU__/__EXISTING_TOPIC__
# 2. Rebase or merge
#    A. Replay and resolve your changes on the latest main
#       git rebase origin/main
#    B. Merge and resolve your changes with the latest main
#       git merge origin/main

# Install dependency updates
uv sync

# Run the program
uv run qtpy-datalogger [OPTIONS]

PC dev loop¶

Monitor the messages sent between sensor nodes and the host

uv run qtpy-datalogger server --observe

Powershell

# ✍️ Save source code changes

# Run the new code
uv run qtpy-datalogger [OPTIONS]

# Run the tests
uv run poe test

# Run the analyzers
uv run poe lint

# Apply the safe analyzer fixes
uv run poe fix

QT Py dev loop¶

Connect the QT Py to your workstation with USB

Monitor the messages sent between sensor nodes and the host

uv run qtpy-datalogger server --observe

Monitor the main run loop on the sensor node

uv run qtpy-datalogger connect --port COMxx

Powershell

# ✍️ Save source code changes

# Update the code on the QT Py
uv run qtpy-datalogger equip --newer-files-only

# When changes require new support libraries
uv run qtpy-datalogger equip [--force]

# Run new code
uv run qtpy-datalogger [OPTIONS]

# Run the tests
uv run poe test

# Run the analyzers
uv run poe lint

# Apply the safe analyzer fixes
uv run poe fix

Documentation dev loop¶

Powershell

# Build the documentation site
uv run poe docs

# Locally serve the documentation site
uv run zensical serve

# Confirm and observe changes in the site
start http://localhost:8000

# ✍️ Save documentation changes

References¶

For this project¶

Design documents for this project are in the wiki under the Design Doc X series.

For support libraries¶

Name	Purpose	Link

Host PC
Python	Language	python.org
	Language reference	python.org
	Standard library	python.org
uv	Core tool	astral.sh
poe	Core tool	natn.io
ruff	Code analyzer	astral.sh
pyright	Code analyzer	github.io
pytest	Test runner	pytest.org
zensical	Documentation	zensical.org
click	Command line interface	palletsprojects.com
pySerial	Serial port IO	readthedocs.io
wmi	Windows system inspection	me.uk
psutil	System and process utilities	readthedocs.io
gmqtt	MQTT client	github.com
mosquitto	MQTT server	mosquitto.org
ttkbootstrap	GUI extension	readthedocs.io
pandas	Data processing	pydata.org
matplotlib	Plotting	matplotlib.org
circup	QT Py tool	readthedocs.io

Sensor node
MicroPython	Supervisor	micropython.org
CircuitPython	Language	adafruit.com
	Standard library	circuitpython.org
	Core modules	circuitpython.org
Drivers	Sensor support	circuitpython.org
MiniMQTT	MQTT client	circuitpython.org
ASCII	Binary codes for characters	ss64.com
XTerm	Code sequences for terminals	invisible-island.net

Pull requests and Issues¶

See the sections under the Project Workflows wiki page for outlines.