Metadata-Version: 2.4
Name: tuya-telemetry-archive
Version: 0.1.0
Summary: Archive Tuya and Smart Life telemetry locally in SQLite, JSONL, or CSV.
License-Expression: MIT
Project-URL: Homepage, https://github.com/ankushagrawal94/tuya-telemetry-archive
Project-URL: Documentation, https://github.com/ankushagrawal94/tuya-telemetry-archive#readme
Project-URL: Issues, https://github.com/ankushagrawal94/tuya-telemetry-archive/issues
Project-URL: Source, https://github.com/ankushagrawal94/tuya-telemetry-archive
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Home Automation
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3,>=2.31
Requires-Dist: tuya-connector-python<0.2,>=0.1.2
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: ruff<1,>=0.12; extra == "dev"
Dynamic: license-file

# Tuya Telemetry Archive

[![CI](https://github.com/ankushagrawal94/tuya-telemetry-archive/actions/workflows/ci.yml/badge.svg)](https://github.com/ankushagrawal94/tuya-telemetry-archive/actions/workflows/ci.yml)

Keep more than seven days of Tuya temperature and humidity history locally.

Tuya Telemetry Archive copies recent Tuya and Smart Life sensor logs into a local
archive. Repeated collections are deduplicated. If Tuya changes a previously reported
reading, the local record is updated.

The collector currently recognizes devices in category `wsdcg` with the
`temp_current` and `humidity_value` data points. It requires Python 3.11 or newer.

## Why this exists

Tuya's free [Device Log service](https://developer.tuya.com/en/docs/iot/device-log-service?id=Kacpq0nn1bioy)
retains seven days of history. Run the collector regularly to copy readings before they
expire from Tuya's service.

## Install

Install from PyPI in a virtual environment:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install tuya-telemetry-archive
tuya-archive --help
```

## Set up and collect

Follow the [Tuya Cloud setup guide](docs/setup-tuya.md) to create a Smart Home cloud
project, link a Tuya Smart or Smart Life account, authorize log access, and choose the
correct regional endpoint.

Then run:

```bash
tuya-archive setup
tuya-archive doctor
tuya-archive collect
tuya-archive status
```

A successful collection looks like this:

```text
success: 1/1 devices, 48 fetched, 48 inserted, 0 corrected.
```

Run `tuya-archive collect` at least once every seven days. Daily collection leaves
enough overlap to tolerate a missed run.

## Archive storage

SQLite is the default archive backend. JSONL and CSV are available when a text-readable
archive is more useful.

Set the backend during setup or with `TUYA_STORAGE_BACKEND` in the protected environment
file:

```dotenv
TUYA_STORAGE_BACKEND=sqlite
```

Choose `sqlite`, `jsonl`, or `csv`. SQLite remains the default.

| Backend | Use it for | Trade-off |
|---|---|---|
| SQLite | Normal long-running archives | Requires SQLite-aware tools for direct inspection |
| JSONL | Small archives that should remain text-readable | Rewrites the file when changes are committed |
| CSV | Portable archives for spreadsheets and data tools | Uses several related files and rewrites changed yearly partitions |

The CSV backend is a directory named `archive-csv`. Device and collection-run records
have their own CSV files. Observations are partitioned by UTC calendar year as
`observations-YYYY.csv`, so corrections only rewrite the affected yearly partition.
The files work together as one archive and should be backed up or moved as a directory.

## Hourly CSV reports

Run this after collecting data:

```bash
tuya-archive export
```

By default, the command writes one hourly CSV per UTC calendar year in the private data
directory:

```text
csv/hourly-2026.csv
csv/hourly-2027.csv
```

Choose another directory for the annual files:

```bash
tuya-archive export --output-dir ./annual-csv
```

Or write one combined file:

```bash
tuya-archive export --output ./tuya-hourly.csv
```

Each row includes the device label and pseudonym, data-point code, unit, sample count,
and hourly minimum, mean, maximum, first, and last values. UTC and local timestamps are
both included. The local timestamp includes its UTC offset so repeated daylight-saving
hours remain distinct.

## Optional macOS scheduler

Scheduling is optional. You can run `tuya-archive collect` from cron, another scheduler,
or your own automation.

On macOS, the project can install a daily user LaunchAgent:

```bash
tuya-archive schedule install
tuya-archive schedule status
```

Remove it with:

```bash
tuya-archive schedule uninstall
```

The default interval is 86,400 seconds. To choose another interval:

```bash
tuya-archive schedule install --interval-seconds 43200
```

The LaunchAgent uses the Python interpreter that installed it. Reinstall the schedule
after moving or rebuilding that virtual environment. See the
[macOS scheduling guide](docs/macos-scheduling.md) for details.

## Local files and privacy

On macOS, files are stored under:

```text
~/Library/Application Support/tuya-telemetry-archive/
├── config/config.env
└── data/
    ├── identity.key
    ├── archive.sqlite3  (or archive.jsonl or archive-csv/)
    └── csv/
```

Other platforms follow XDG conventions. Override the defaults with
`TUYA_ARCHIVE_CONFIG_DIR` and `TUYA_ARCHIVE_DATA_DIR`.

Raw Tuya device IDs are not written to the archive. They are replaced with stable HMAC
pseudonyms using the local `identity.key`. The archive still contains device labels,
timestamps, and sensor readings, so it should be treated as private household data.

Back up `identity.key` with the archive. If the key is lost, future readings from the
same device will receive a different pseudonym. See [SECURITY.md](SECURITY.md) for
reporting and handling guidance.

## Tested devices and current limitations

Collection has been tested with the
[SENCKIT 4-Pack WiFi Temperature Humidity Sensor](https://www.amazon.com/dp/B0B5DQZTG9)
(Amazon ASIN `B0B5DQZTG9`). These sensors report as category `wsdcg` with
`temp_current` and `humidity_value`.

Tuya also publishes a general
[temperature and humidity sensor solution](https://solution.tuya.com/promotion/video-temp-hum-remoter-en).
That page describes the Tuya platform category, not this exact SENCKIT retail listing.

Other devices that expose the same data points may work, but they have not been verified
against this project yet. Tuya Cloud setup, API authorization, endpoint behavior, and
service availability can also change independently of this repository.

Hourly CSV reports are the only built-in reporting workflow. Arbitrary queries, charts,
and an MCP server are not implemented yet. The built-in scheduler currently supports
macOS only.

## Development

Use synthetic fixtures only. Never add real credentials, device IDs, identity keys,
household labels, telemetry, archives, or exports.

```bash
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m pytest -v
.venv/bin/ruff check .
.venv/bin/python -m build
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the safety requirements and development
workflow.

## Maintenance and contributions

This project will be actively maintained. Contributors are welcome to add more device
integrations, reporting workflows, scheduling platforms, and other improvements.

See the [Tuya Cloud setup guide](docs/setup-tuya.md), [security policy](SECURITY.md),
[contribution guide](CONTRIBUTING.md), [release guide](docs/releasing.md), and
[MIT license](LICENSE).
