# MQTT to SQLite Logger
[![PyPI version](https://badge.fury.io/py/mqtt-logger.svg)](https://badge.fury.io/py/mqtt-logger)
[![Python package](https://github.com/Blake-Haydon/mqtt-logger/actions/workflows/python-package.yml/badge.svg)](https://github.com/Blake-Haydon/mqtt-logger/actions/workflows/python-package.yml)
[![Upload Python Package](https://github.com/Blake-Haydon/mqtt-logger/actions/workflows/python-publish.yml/badge.svg)](https://github.com/Blake-Haydon/mqtt-logger/actions/workflows/python-publish.yml)
## Table of Contents
- [MQTT to SQLite Logger](#mqtt-to-sqlite-logger)
- [Table of Contents](#table-of-contents)
- [Description](#description)
- [Installation](#installation)
- [Example Usage](#example-usage)
- [Recording MQTT Messages](#recording-mqtt-messages)
- [Playback Recorded MQTT Messages](#playback-recorded-mqtt-messages)
- [Database](#database)
- [`LOG` Table](#log-table)
- [`RUN` Table](#run-table)
## Description
`mqtt-logger` allows for asynchronous data logging of MQTT messages to a SQLite database. It also allows for the playback of previously recorded MQTT messages.
## Installation
To install `mqtt-logger` you can simply use `pip`.
```bash
pip install mqtt-logger
```
## Example Usage
### Recording MQTT Messages
This example records messages to the `test/#` topic using a public MQTT broker. It will record for 10 seconds. If you
are using a private broker, you may need to set the `username` and `password` parameters.
<!-- poetry run python examples/10s_recording.py -->
_Example recorder taken from [examples/10s_recording.py](examples/10s_recording.py)_
```python
import mqtt_logger
import os
import time
# Initalise mqtt recorder object
rec = mqtt_logger.Recorder(
sqlite_database_path=os.path.join(os.path.dirname(__file__), "MQTT_log.db"),
topics=["test/#"],
broker_address="broker.hivemq.com",
verbose=True,
)
# Start the logger, wait 10 seconds and stop the logger
rec.start()
time.sleep(10)
rec.stop()
```
### Playback Recorded MQTT Messages
This example plays back previously recorded MQTT messages from `mqtt_logger.Recorder`. If you are using a private
broker, you may need to set the `username` and `password` parameters.
<!-- poetry run python examples/10s_playback.py -->
_Example recorder taken from [examples/10s_playback.py](examples/10s_playback.py)_
```python
import mqtt_logger
import os
# Initalise playback object
playback = mqtt_logger.Playback(
sqlite_database_path=os.path.join(os.path.dirname(__file__), "MQTT_log.db"),
broker_address="broker.hivemq.com",
verbose=True,
)
# Start playback at 2x speed (twice as fast)
playback.play(speed=2)
```
## Database
The SQLite database has two tables called `LOG` and `RUN`. The `LOG` table contains the messages that are being logged. The `RUN` table contains the information about the current run of the program.
### `LOG` Table
| ROW NAME | DESCRIPTION |
| --------- | ------------------------------------------------------ |
| ID | Unique number assigned to each message (ascending int) |
| RUN_ID | ID of the current run (ascending int) |
| UNIX_TIME | Time when the message was received |
| TOPIC | MQTT topic |
| MESSAGE | MQTT message received |
---
### `RUN` Table
| ROW NAME | DESCRIPTION |
| --------------- | --------------------------------------------- |
| ID | Unique number assigned to run (ascending int) |
| START_UNIX_TIME | Time when logger was started |
| END_UNIX_TIME | Time when logger was stopped |
---
Raw data
{
"_id": null,
"home_page": "https://github.com/Blake-Haydon/mqtt-logger",
"name": "mqtt_logger",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "MQTT,SQLite3",
"author": "Blake Haydon",
"author_email": "blake.a.haydon@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/06/02/a696ce08cf17b0404b67150aba1a76e495b0d2a4dddb6202ac9aa001749d/mqtt_logger-0.3.5.tar.gz",
"platform": null,
"description": "# MQTT to SQLite Logger\n\n[![PyPI version](https://badge.fury.io/py/mqtt-logger.svg)](https://badge.fury.io/py/mqtt-logger)\n[![Python package](https://github.com/Blake-Haydon/mqtt-logger/actions/workflows/python-package.yml/badge.svg)](https://github.com/Blake-Haydon/mqtt-logger/actions/workflows/python-package.yml)\n[![Upload Python Package](https://github.com/Blake-Haydon/mqtt-logger/actions/workflows/python-publish.yml/badge.svg)](https://github.com/Blake-Haydon/mqtt-logger/actions/workflows/python-publish.yml)\n\n## Table of Contents\n\n- [MQTT to SQLite Logger](#mqtt-to-sqlite-logger)\n - [Table of Contents](#table-of-contents)\n - [Description](#description)\n - [Installation](#installation)\n - [Example Usage](#example-usage)\n - [Recording MQTT Messages](#recording-mqtt-messages)\n - [Playback Recorded MQTT Messages](#playback-recorded-mqtt-messages)\n - [Database](#database)\n - [`LOG` Table](#log-table)\n - [`RUN` Table](#run-table)\n\n## Description\n\n`mqtt-logger` allows for asynchronous data logging of MQTT messages to a SQLite database. It also allows for the playback of previously recorded MQTT messages.\n\n## Installation\n\nTo install `mqtt-logger` you can simply use `pip`.\n\n```bash\npip install mqtt-logger\n```\n\n## Example Usage\n\n### Recording MQTT Messages\n\nThis example records messages to the `test/#` topic using a public MQTT broker. It will record for 10 seconds. If you\nare using a private broker, you may need to set the `username` and `password` parameters.\n\n<!-- poetry run python examples/10s_recording.py -->\n\n_Example recorder taken from [examples/10s_recording.py](examples/10s_recording.py)_\n\n```python\nimport mqtt_logger\nimport os\nimport time\n\n# Initalise mqtt recorder object\nrec = mqtt_logger.Recorder(\n sqlite_database_path=os.path.join(os.path.dirname(__file__), \"MQTT_log.db\"),\n topics=[\"test/#\"],\n broker_address=\"broker.hivemq.com\",\n verbose=True,\n)\n\n# Start the logger, wait 10 seconds and stop the logger\nrec.start()\ntime.sleep(10)\nrec.stop()\n```\n\n### Playback Recorded MQTT Messages\n\nThis example plays back previously recorded MQTT messages from `mqtt_logger.Recorder`. If you are using a private\nbroker, you may need to set the `username` and `password` parameters.\n\n<!-- poetry run python examples/10s_playback.py -->\n\n_Example recorder taken from [examples/10s_playback.py](examples/10s_playback.py)_\n\n```python\nimport mqtt_logger\nimport os\n\n# Initalise playback object\nplayback = mqtt_logger.Playback(\n sqlite_database_path=os.path.join(os.path.dirname(__file__), \"MQTT_log.db\"),\n broker_address=\"broker.hivemq.com\",\n verbose=True,\n)\n\n# Start playback at 2x speed (twice as fast)\nplayback.play(speed=2)\n```\n\n## Database\n\nThe SQLite database has two tables called `LOG` and `RUN`. The `LOG` table contains the messages that are being logged. The `RUN` table contains the information about the current run of the program.\n\n### `LOG` Table\n\n| ROW NAME | DESCRIPTION |\n| --------- | ------------------------------------------------------ |\n| ID | Unique number assigned to each message (ascending int) |\n| RUN_ID | ID of the current run (ascending int) |\n| UNIX_TIME | Time when the message was received |\n| TOPIC | MQTT topic |\n| MESSAGE | MQTT message received |\n\n---\n\n### `RUN` Table\n\n| ROW NAME | DESCRIPTION |\n| --------------- | --------------------------------------------- |\n| ID | Unique number assigned to run (ascending int) |\n| START_UNIX_TIME | Time when logger was started |\n| END_UNIX_TIME | Time when logger was stopped |\n\n---\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python based MQTT to SQLite3 logger",
"version": "0.3.5",
"project_urls": {
"Homepage": "https://github.com/Blake-Haydon/mqtt-logger"
},
"split_keywords": [
"mqtt",
"sqlite3"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9e589f38b7d1150fe172bf3ff8784af12d35a1cc88f38a7abf1e75010ba82649",
"md5": "6b9108bf240558d65831bef76438bccd",
"sha256": "1cd80e0d7fd730f9992a430d8481a4c785214b88adef077f65e1354fe5463685"
},
"downloads": -1,
"filename": "mqtt_logger-0.3.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6b9108bf240558d65831bef76438bccd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 7428,
"upload_time": "2024-01-04T06:12:49",
"upload_time_iso_8601": "2024-01-04T06:12:49.723004Z",
"url": "https://files.pythonhosted.org/packages/9e/58/9f38b7d1150fe172bf3ff8784af12d35a1cc88f38a7abf1e75010ba82649/mqtt_logger-0.3.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0602a696ce08cf17b0404b67150aba1a76e495b0d2a4dddb6202ac9aa001749d",
"md5": "d6524817bb1bacdd9050889e29e6d0ab",
"sha256": "2da8811468ec627bbf483d3692109830a5ee07f27c19629ec24659318056a091"
},
"downloads": -1,
"filename": "mqtt_logger-0.3.5.tar.gz",
"has_sig": false,
"md5_digest": "d6524817bb1bacdd9050889e29e6d0ab",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 6441,
"upload_time": "2024-01-04T06:12:54",
"upload_time_iso_8601": "2024-01-04T06:12:54.309613Z",
"url": "https://files.pythonhosted.org/packages/06/02/a696ce08cf17b0404b67150aba1a76e495b0d2a4dddb6202ac9aa001749d/mqtt_logger-0.3.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-04 06:12:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Blake-Haydon",
"github_project": "mqtt-logger",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "mqtt_logger"
}