Metadata-Version: 2.4
Name: qtpy-datalogger
Version: 1.0.8
Summary: A remote control and data acquisition system using Adafruit QT Py S3
Keywords: acquisition,circuitpython,control,daq,qtpy,remote
Author: Down to the Wire
Author-email: Down to the Wire <all.wired.down@gmail.com>
License-Expression: Apache-2.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Software Development :: User Interfaces
Requires-Dist: beautifulsoup4>=4.14.3
Requires-Dist: circup>=3.0.1
Requires-Dist: click>=8.3.2
Requires-Dist: findimports>=3.0.0
Requires-Dist: gmqtt>=0.7.0
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: packaging>=26.1
Requires-Dist: pandas>=3.0.2
Requires-Dist: psutil>=7.2.2
Requires-Dist: pyserial>=3.5
Requires-Dist: tkfontawesome>=0.3.2
Requires-Dist: ttkbootstrap>=1.20.2
Requires-Dist: wmi>=1.5.1
Requires-Dist: circuitpython-stubs==9.2.1
Requires-Dist: adafruit-circuitpython-adxl37x>=1.2.4
Requires-Dist: adafruit-circuitpython-connectionmanager>=3.1.4
Requires-Dist: adafruit-circuitpython-minimqtt>=8.0.0
Requires-Dist: adafruit-circuitpython-neopixel>=6.3.16
Requires-Python: >=3.11, <4.0
Project-URL: Changelog, https://github.com/wireddown/qtpy-datalogger/releases
Project-URL: Documentation, https://wireddown.github.io/qtpy-datalogger/develop/
Project-URL: Homepage, https://wireddown.github.io/qtpy-datalogger/
Project-URL: Issues, https://github.com/wireddown/qtpy-datalogger/issues
Project-URL: Source, https://github.com/wireddown/qtpy-datalogger
Description-Content-Type: text/markdown

# QT Py Datalogger

**`qtpy-datalogger`** -- A remote control and data acquisition system using the [Adafruit QT Py S3] and [CircuitPython]

## Documentation

Available at [downtothewire.io/**qtpy-datalogger/welcome**](https://downtothewire.io/qtpy-datalogger/welcome)

## Status

[![CI: Tests and Analyzers](https://github.com/wireddown/qtpy-datalogger/actions/workflows/ci.yml/badge.svg)](https://github.com/wireddown/qtpy-datalogger/actions/workflows/ci.yml)
[![Dependabot Updates]](https://github.com/wireddown/qtpy-datalogger/actions/workflows/dependabot/dependabot-updates)
[![Publish: Release on PyPI](https://github.com/wireddown/qtpy-datalogger/actions/workflows/publish.yml/badge.svg)](https://github.com/wireddown/qtpy-datalogger/actions/workflows/publish.yml)

## [Structure](https://github.com/wireddown/qtpy-datalogger#structure)

```mermaid
graph LR
    AP(🛜 Access Point)
    App(🐍 App)
    MQTT(📨 MQTT)
    QTPy(🐍 QT Py S3)

    subgraph "🌐 Network"
        AP
    end

    subgraph "💻 PC Host"
        App<-.->MQTT
        MQTT<-.->AP
    end

    subgraph "🧪 Test Zone"
        AP<-.->|🛜 WiFi|QTPy
    end
```

The PC host controls and communicates with any number of sensor nodes on the wireless network.

**Supported Python versions**

- Host
    - Python 3.11
    - Python 3.12
    - Python 3.13
- Node
    - CircuitPython 9.0

**Supported host platforms**

- Windows

**Supported connection types**

- Serial / UART
- Network / MQTT

**Entry points**

- Host program: [`qtpy_datalogger/console.py`](https://github.com/wireddown/qtpy-datalogger/blob/main/src/qtpy_datalogger/console.py)
- QT Py program: [`qtpy_datalogger/sensor_node/code.py`](https://github.com/wireddown/qtpy-datalogger/blob/main/src/qtpy_datalogger/sensor_node/code.py)

## Preview in 90 seconds

1. Connect your QT Py device with USB
    - _(Optional)_ Back up its `code.py` file
1. Preview the program in a deletable Python virtual environment

```pwsh
# Create and enter a new Python virtual environment
mkdir qtpy-preview
cd qtpy-preview
python -m venv --upgrade-deps .venv
.\.venv\Scripts\activate.ps1

# Install
pip install qtpy-datalogger

# Show the package help
qtpy-datalogger --help

# Search for devices
qtpy-datalogger connect --discover-only

# Install the node runtime on a device
qtpy-datalogger equip

# Open a serial connection, use Ctrl-] to quit
qtpy-datalogger connect

qtpycmd get_apps

qtpycmd stats

qtpycmd read A0 A1 A2 A3
```

This preview does not demonstrate MQTT communication over WiFi

In order to communicate on the WiFi network, the QT Py sensor node must also have

- an MQTT broker
- WiFi credentials

Visit the [MQTT setup] page for more details

## Gallery

### Scanner

```
qtpy-datalogger run scanner
```

Scan for nodes by group.
Select a node to send it messages.

![Screenshot of the scanner app](https://raw.githubusercontent.com/wireddown/qtpy-datalogger/refs/heads/main/docs/gallery/app-scanner.png)

### Data Viewer

```
qtpy-datalogger run data-viewer
```

Open a CSV file for time series data.

![Screenshot of the data viewer app](https://raw.githubusercontent.com/wireddown/qtpy-datalogger/refs/heads/main/docs/gallery/app-data-viewer.png)

CSV format

- Series data are in columns
- Series names are in the first row
- The time axis is in the first column
    - ISO timestamps and floating point values both accepted

```csv
Time,Sensor 1,Sensor 2
0.0,1.284,2.713
0.22,1.302,5.536
...
```

## Questions and help

Please go to the [Welcome] page for questions and help.

## Contributing

This project manages its Python programs with `uv`.

The environment setup instructions are on the [Develop] page.

The design documentation is in the wiki under the [Design Doc] pages.

## Legacy system

This project replaces a legacy system that uses Python and JeeNodes.

See the [summary and source code] in the `docs/legacy` folder for details.


[Dependabot Updates]: https://github.com/wireddown/qtpy-datalogger/actions/workflows/dependabot/dependabot-updates/badge.svg

[Adafruit QT Py S3]: https://learn.adafruit.com/adafruit-qt-py-esp32-s3
[CircuitPython]: https://circuitpython.org/

[MQTT setup]: https://wireddown.github.io/qtpy-datalogger/eng/intro/mqtt/

[Welcome]: https://downtothewire.io/qtpy-datalogger/welcome/
[Develop]: https://wireddown.github.io/qtpy-datalogger/develop/
[Design Doc]: https://github.com/wireddown/qtpy-datalogger/wiki/Design-Doc-1-Overview
[summary and source code]: https://github.com/wireddown/qtpy-datalogger/blob/main/docs/legacy/README.md
