tuya-telemetry-archive 0.1.1

Archive Tuya and Smart Life telemetry locally in SQLite, JSONL, or CSV.

Tuya Telemetry Archive

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 either temp_current / humidity_value or va_temperature / va_humidity data points. It accepts Tuya's integer and ASCII integer-string encodings for those values. It requires Python 3.11 or newer.

Why this exists

Tuya's free Device Log service 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:

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 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:

tuya-archive setup
tuya-archive doctor
tuya-archive collect
tuya-archive status

A successful collection looks like this:

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:

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:

tuya-archive export

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

csv/hourly-2026.csv
csv/hourly-2027.csv

Choose another directory for the annual files:

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

Or write one combined file:

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:

tuya-archive schedule install
tuya-archive schedule status

Remove it with:

tuya-archive schedule uninstall

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

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 for details.

Local files and privacy

On macOS, files are stored under:

~/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 for reporting and handling guidance.

Archives from collectors that used a different SQLite schema or device-identity scheme cannot be copied directly into this archive. Keep the existing collector running while you validate a separate archive. See the legacy SQLite import design for the planned identity mapping, validation, backup, and cutover process.

Tested devices and current limitations

Collection has been tested with the SENCKIT 4-Pack WiFi Temperature Humidity Sensor (Amazon ASIN B0B5DQZTG9). Tuya temperature/humidity sensors in category wsdcg have been observed with both temp_current / humidity_value and va_temperature / va_humidity; the test suite covers both families with synthetic fixtures.

Tuya also publishes a general temperature and humidity sensor solution. That page describes the Tuya platform category, not this exact SENCKIT retail listing.

Other devices that expose one of the supported data-point pairs 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.

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 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, security policy, contribution guide, release guide, and MIT license.