Metadata-Version: 2.4
Name: qtpy-datalogger
Version: 1.0.13
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: Programming Language :: Python :: 3.14
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: tksvg>=0.7.4
Requires-Dist: ttkbootstrap>=1.20.2
Requires-Dist: ttkbootstrap-icons>=4.0.0
Requires-Dist: ttkbootstrap-icons-fa>=1.0.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**]

## 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.

## 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 sensor node runtime the 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

    # Ctrl-] to quit
    ```
1. Plot data in the [**Analog Plotter**] demo GUI app
![Screenshot of the Analog Plotter demo](https://raw.githubusercontent.com/wireddown/qtpy-datalogger/refs/heads/main/docs/gallery/ex-analog-plotter-with-dialog.png)
1. Optionally, delete the folder `qtpy-preview` when you are done

**_Note:_** 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 if you want to try [the demo apps] over the network.

## Gallery

In addition to the command line tools, the `qtpy-datalogger` package includes these GUI apps.

### 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
...
```

## Supported systems

**Supported Python versions**

- Host
    - Python 3.11
    - Python 3.12
    - Python 3.13
    - Python 3.14
- Node
    - CircuitPython 9.x
    - CircuitPython 10.x

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

## Questions and help

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

## Contributing

This project manages its Python package 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/
[downtothewire.io/**qtpy-datalogger/welcome**]: https://downtothewire.io/qtpy-datalogger/welcome/

[**Analog Plotter**]: https://wireddown.github.io/qtpy-datalogger/customize/#analog-plotter
[MQTT setup]: https://wireddown.github.io/qtpy-datalogger/eng/intro/mqtt/
[the demo apps]: https://wireddown.github.io/qtpy-datalogger/customize/

[Welcome]: https://wireddown.github.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
