Metadata-Version: 2.3
Name: esphome-mqtt-timescaledb-ingestor
Version: 0.2.0
Summary: A robust Python service to ingest ESPHome MQTT data into a TimescaleDB multi-table schema.
License: MIT
Keywords: esphome,mqtt,timescaledb,iot,database,ingestor
Author: Ankur Kumar Pandey
Author-email: measure@i-dacs.com
Requires-Python: >=3.7
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: paho-mqtt (>=1.6.1,<2.0.0)
Requires-Dist: psycopg2-binary (>=2.9.1,<3.0.0)
Requires-Dist: typer[all] (>=0.9.0,<0.10.0)
Project-URL: Homepage, https://i-dacs.com
Project-URL: Repository, https://github.com/paandayankur/mqtt-to-timescaledb-ingester
Description-Content-Type: text/markdown

# ESPHome MQTT to TimescaleDB Ingestor

A robust Python service that listens for ESPHome data on an MQTT broker and persists it into a structured, multi-table TimescaleDB database.

This project is designed to work with the standard ESPHome and Home Assistant discovery protocols, handling various message types including device discovery, entity configurations, real-time state updates, and commands.

## Features

* Connects to an MQTT broker and subscribes to all relevant ESPHome and Home Assistant topics.
* Intelligently processes and stores five distinct types of messages.
* Automatically creates the necessary database tables on the first run.
* Uses a multi-threaded, queue-based architecture for high performance and resilience.
* Supports intelligent batch processing for efficient database writes.

## Installation

Install the package directly from PyPI:

```bash
pip install esphome-mqtt-timescaledb-ingestor
```

## Usage

This package includes an interactive command-line interface (CLI) to help you get started.

### 1. Initial Configuration

After installing the package, run the `configure` command. This will launch an interactive setup wizard that will ask for your MQTT and database credentials and save them to a configuration file.

```bash
mqtt-ingestor configure
```

You will be prompted for the following:
-   MQTT Broker Host
-   MQTT Broker Port
-   MQTT Username & Password
-   Database Host
-   Database Port
-   Database Name
-   Database User & Password

### 2. Start the Ingestor Service

Once you have configured your credentials, you can start the ingestor service:

```bash
mqtt-ingestor start
```

The service will load your saved configuration and begin listening for messages.

## Testing

To run the tests, clone the repository, install the development dependencies, and run pytest:

```bash
git clone [https://github.com/paandayankur/mqtt-to-timescaledb-ingester.git](https://github.com/paandayankur/mqtt-to-timescaledb-ingester.git)
cd mqtt-to-timescaledb-ingester
poetry install --with dev
poetry run pytest
```

## Contributing

Contributions are welcome! Please feel free to open an issue or submit a pull request for any improvements or bug fixes.

## License

This project is licensed under the MIT License. See the `LICENSE` file for more details.

