# 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.
Raw data
{
"_id": null,
"home_page": "https://i-dacs.com",
"name": "esphome-mqtt-timescaledb-ingestor",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "esphome, mqtt, timescaledb, iot, database, ingestor",
"author": "Ankur Kumar Pandey",
"author_email": "measure@i-dacs.com",
"download_url": "https://files.pythonhosted.org/packages/9d/bf/c00672df30d7f85f8a7bfde73563c8f5e4aaa873bc19acb80584315a2876/esphome_mqtt_timescaledb_ingestor-0.3.0.tar.gz",
"platform": null,
"description": "# ESPHome MQTT to TimescaleDB Ingestor\n\nA robust Python service that listens for ESPHome data on an MQTT broker and persists it into a structured, multi-table TimescaleDB database.\n\nThis 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.\n\n## Features\n\n* Connects to an MQTT broker and subscribes to all relevant ESPHome and Home Assistant topics.\n* Intelligently processes and stores five distinct types of messages.\n* Automatically creates the necessary database tables on the first run.\n* Uses a multi-threaded, queue-based architecture for high performance and resilience.\n* Supports intelligent batch processing for efficient database writes.\n\n## Installation\n\nInstall the package directly from PyPI:\n\n```bash\npip install esphome-mqtt-timescaledb-ingestor\n```\n\n## Usage\n\nThis package includes an interactive command-line interface (CLI) to help you get started.\n\n### 1. Initial Configuration\n\nAfter 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.\n\n```bash\nmqtt-ingestor configure\n```\n\nYou will be prompted for the following:\n- MQTT Broker Host\n- MQTT Broker Port\n- MQTT Username & Password\n- Database Host\n- Database Port\n- Database Name\n- Database User & Password\n\n### 2. Start the Ingestor Service\n\nOnce you have configured your credentials, you can start the ingestor service:\n\n```bash\nmqtt-ingestor start\n```\n\nThe service will load your saved configuration and begin listening for messages.\n\n## Testing\n\nTo run the tests, clone the repository, install the development dependencies, and run pytest:\n\n```bash\ngit clone [https://github.com/paandayankur/mqtt-to-timescaledb-ingester.git](https://github.com/paandayankur/mqtt-to-timescaledb-ingester.git)\ncd mqtt-to-timescaledb-ingester\npoetry install --with dev\npoetry run pytest\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to open an issue or submit a pull request for any improvements or bug fixes.\n\n## License\n\nThis project is licensed under the MIT License. See the `LICENSE` file for more details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A robust Python service to ingest ESPHome MQTT data into a TimescaleDB multi-table schema.",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://i-dacs.com",
"Repository": "https://github.com/paandayankur/mqtt-to-timescaledb-ingester"
},
"split_keywords": [
"esphome",
" mqtt",
" timescaledb",
" iot",
" database",
" ingestor"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bda7f5ef49a80f1515f245515febb36e2a46efe9bec248d3c2ec0269490699da",
"md5": "009ca5621648907150ec73a9e905f99f",
"sha256": "a9715adb3129a685ed4d4934e6dee8f0d1582a934ecdb673fc257f999eb240f0"
},
"downloads": -1,
"filename": "esphome_mqtt_timescaledb_ingestor-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "009ca5621648907150ec73a9e905f99f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 7569,
"upload_time": "2025-08-11T17:04:17",
"upload_time_iso_8601": "2025-08-11T17:04:17.957292Z",
"url": "https://files.pythonhosted.org/packages/bd/a7/f5ef49a80f1515f245515febb36e2a46efe9bec248d3c2ec0269490699da/esphome_mqtt_timescaledb_ingestor-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9dbfc00672df30d7f85f8a7bfde73563c8f5e4aaa873bc19acb80584315a2876",
"md5": "baced52d53eade44f902dabc25333d33",
"sha256": "bc9af432bbeeef4cab1091c7729df7a41689dc6438e48ab5856067533b45e10b"
},
"downloads": -1,
"filename": "esphome_mqtt_timescaledb_ingestor-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "baced52d53eade44f902dabc25333d33",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 6165,
"upload_time": "2025-08-11T17:04:19",
"upload_time_iso_8601": "2025-08-11T17:04:19.073080Z",
"url": "https://files.pythonhosted.org/packages/9d/bf/c00672df30d7f85f8a7bfde73563c8f5e4aaa873bc19acb80584315a2876/esphome_mqtt_timescaledb_ingestor-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-11 17:04:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "paandayankur",
"github_project": "mqtt-to-timescaledb-ingester",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "esphome-mqtt-timescaledb-ingestor"
}
JSON
