============
bluetti_mqtt
============
This tool provides an MQTT interface to Bluetti power stations. State will be
published to the ``bluetti/state/[DEVICE NAME]/[PROPERTY]`` topic, and commands
can be sent to the ``bluetti/command/[DEVICE NAME]/[PROPERTY]`` topic.
Installation
------------
.. code-block:: bash
$ pip install bluetti_mqtt
Usage
-----
.. code-block:: bash
$ bluetti-mqtt --scan
Found AC3001234567890123: address 00:11:22:33:44:55
$ bluetti-mqtt --broker [MQTT_BROKER_HOST] 00:11:22:33:44:55
If your MQTT broker has a username and password, you can pass those in.
.. code-block:: bash
$ bluetti-mqtt --broker [MQTT_BROKER_HOST] --username username --password pass 00:11:22:33:44:55
By default the device is polled as quickly as possible, but if you'd like to
collect less data, the polling interval can be adjusted.
.. code-block:: bash
# Poll every 60s
$ bluetti-mqtt --broker [MQTT_BROKER_HOST] --interval 60 00:11:22:33:44:55
If you have multiple devices within bluetooth range, you can monitor all of
them with just a single command. We can only talk to one device at a time, so
you may notice some irregularity in the collected data, especially if you have
not set an interval.
.. code-block:: bash
$ bluetti-mqtt --broker [MQTT_BROKER_HOST] 00:11:22:33:44:55 00:11:22:33:44:66
Background Service
------------------
If you are running on a platform with systemd, you can use the following as a
template. It should be placed in ``/etc/systemd/system/bluetti-mqtt.service``.
Once you've written the file, you'll need to run
``sudo systemctl start bluetti-mqtt``. If you want it to run automatically after
rebooting, you'll also need to run ``sudo systemctl enable bluetti-mqtt``.
.. code-block:: bash
[Unit]
Description=Bluetti MQTT
After=network.target
StartLimitIntervalSec=0
[Service]
Type=simple
Restart=always
RestartSec=30
TimeoutStopSec=15
User=your_username_here
ExecStart=/home/your_username_here/.local/bin/bluetti-mqtt --broker [MQTT_BROKER_HOST] 00:11:22:33:44:55
[Install]
WantedBy=multi-user.target
Home Assistant Integration
--------------------------
If you have configured Home Assistant to use the same MQTT broker, then by
default most data and switches will be automatically configured there. This is
possible thanks to Home Assistant's support for automatic MQTT discovery, which
is enabled by default with the discovery prefix of ``homeassistant``.
This can be controlled with the ``--ha-config`` flag, which defaults to
configuring most fields ("normal"). Home Assistant MQTT discovery can also be
disabled, or additional internal device fields can be configured with the
"advanced" option.
Reverse Engineering
-------------------
For research purposes you can also use the ``bluetti-logger`` command to poll
the device and log in a standardised format.
.. code-block:: bash
$ bluetti-logger --log the-log-file.log 00:11:22:33:44:55
While the logger is running, change settings on the device and take note of the
time when you made the change, waiting ~ 1 minute between changes. Note that
not every setting that can be changed on the device can be changed over
bluetooth.
If you're looking to add support to control something that the app can change
but cannot be changed directly from the device screen, both iOS and Android
support collecting bluetooth logs from running apps. Additionally, with the
correct hardware Wireshark can be used to collect logs. With these logs and a
report of what commands were sent at what times, this data can be used to
reverse engineer support.
For supporting new devices, the ``bluetti-discovery`` command is provided. It
will scan from 0 to 12500 assuming MODBUS-over-Bluetooth. This will take a
while and requires that the scanned device be in close Bluetooth range for
optimal performance.
.. code-block:: bash
$ bluetti-discovery --scan
Found AC3001234567890123: address 00:11:22:33:44:55
$ bluetti-discovery --log the-log-file.log 00:11:22:33:44:55
Raw data
{
"_id": null,
"home_page": "http://github.com/warhammerkid/bluetti_mqtt",
"name": "bluetti-mqtt",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Stephen Augenstein",
"author_email": "perl.programmer@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/17/78/ab0f25ef9e197d85b271b6511608878ac4d91811cfb2e4dfc349e632f323/bluetti_mqtt-0.15.0.tar.gz",
"platform": null,
"description": "============\nbluetti_mqtt\n============\n\nThis tool provides an MQTT interface to Bluetti power stations. State will be\npublished to the ``bluetti/state/[DEVICE NAME]/[PROPERTY]`` topic, and commands\ncan be sent to the ``bluetti/command/[DEVICE NAME]/[PROPERTY]`` topic.\n\nInstallation\n------------\n\n.. code-block:: bash\n\n $ pip install bluetti_mqtt\n\nUsage\n-----\n\n.. code-block:: bash\n\n $ bluetti-mqtt --scan\n Found AC3001234567890123: address 00:11:22:33:44:55\n $ bluetti-mqtt --broker [MQTT_BROKER_HOST] 00:11:22:33:44:55\n\nIf your MQTT broker has a username and password, you can pass those in.\n\n.. code-block:: bash\n\n $ bluetti-mqtt --broker [MQTT_BROKER_HOST] --username username --password pass 00:11:22:33:44:55\n\nBy default the device is polled as quickly as possible, but if you'd like to\ncollect less data, the polling interval can be adjusted.\n\n.. code-block:: bash\n\n # Poll every 60s\n $ bluetti-mqtt --broker [MQTT_BROKER_HOST] --interval 60 00:11:22:33:44:55\n\nIf you have multiple devices within bluetooth range, you can monitor all of\nthem with just a single command. We can only talk to one device at a time, so\nyou may notice some irregularity in the collected data, especially if you have\nnot set an interval.\n\n.. code-block:: bash\n\n $ bluetti-mqtt --broker [MQTT_BROKER_HOST] 00:11:22:33:44:55 00:11:22:33:44:66\n\nBackground Service\n------------------\n\nIf you are running on a platform with systemd, you can use the following as a\ntemplate. It should be placed in ``/etc/systemd/system/bluetti-mqtt.service``.\nOnce you've written the file, you'll need to run\n``sudo systemctl start bluetti-mqtt``. If you want it to run automatically after\nrebooting, you'll also need to run ``sudo systemctl enable bluetti-mqtt``.\n\n.. code-block:: bash\n\n [Unit]\n Description=Bluetti MQTT\n After=network.target\n StartLimitIntervalSec=0\n\n [Service]\n Type=simple\n Restart=always\n RestartSec=30\n TimeoutStopSec=15\n User=your_username_here\n ExecStart=/home/your_username_here/.local/bin/bluetti-mqtt --broker [MQTT_BROKER_HOST] 00:11:22:33:44:55\n\n [Install]\n WantedBy=multi-user.target\n\n\n\nHome Assistant Integration\n--------------------------\n\nIf you have configured Home Assistant to use the same MQTT broker, then by\ndefault most data and switches will be automatically configured there. This is\npossible thanks to Home Assistant's support for automatic MQTT discovery, which\nis enabled by default with the discovery prefix of ``homeassistant``.\n\nThis can be controlled with the ``--ha-config`` flag, which defaults to\nconfiguring most fields (\"normal\"). Home Assistant MQTT discovery can also be\ndisabled, or additional internal device fields can be configured with the\n\"advanced\" option.\n\nReverse Engineering\n-------------------\n\nFor research purposes you can also use the ``bluetti-logger`` command to poll\nthe device and log in a standardised format.\n\n.. code-block:: bash\n\n $ bluetti-logger --log the-log-file.log 00:11:22:33:44:55\n\nWhile the logger is running, change settings on the device and take note of the\ntime when you made the change, waiting ~ 1 minute between changes. Note that\nnot every setting that can be changed on the device can be changed over\nbluetooth.\n\nIf you're looking to add support to control something that the app can change\nbut cannot be changed directly from the device screen, both iOS and Android\nsupport collecting bluetooth logs from running apps. Additionally, with the\ncorrect hardware Wireshark can be used to collect logs. With these logs and a\nreport of what commands were sent at what times, this data can be used to\nreverse engineer support.\n\nFor supporting new devices, the ``bluetti-discovery`` command is provided. It\nwill scan from 0 to 12500 assuming MODBUS-over-Bluetooth. This will take a\nwhile and requires that the scanned device be in close Bluetooth range for\noptimal performance.\n\n.. code-block:: bash\n\n $ bluetti-discovery --scan\n Found AC3001234567890123: address 00:11:22:33:44:55\n $ bluetti-discovery --log the-log-file.log 00:11:22:33:44:55\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MQTT interface to Bluetti power stations",
"version": "0.15.0",
"project_urls": {
"Homepage": "http://github.com/warhammerkid/bluetti_mqtt"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ef24a727263af949d4e180835ba8148b24a70240d55d16a9f5e38819735ff804",
"md5": "e3978a38f2840b04e6a0a1189b7211e5",
"sha256": "02843a1862fe16f274506d5ff0d1c8eff1eadde30e16982fbda32a331f1f80e3"
},
"downloads": -1,
"filename": "bluetti_mqtt-0.15.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e3978a38f2840b04e6a0a1189b7211e5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 33312,
"upload_time": "2023-05-13T19:33:29",
"upload_time_iso_8601": "2023-05-13T19:33:29.625786Z",
"url": "https://files.pythonhosted.org/packages/ef/24/a727263af949d4e180835ba8148b24a70240d55d16a9f5e38819735ff804/bluetti_mqtt-0.15.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1778ab0f25ef9e197d85b271b6511608878ac4d91811cfb2e4dfc349e632f323",
"md5": "156fc080438f0be635a3c2f457a6654d",
"sha256": "abcfa22f43d5ecbf541d22e390a15fab1acb19e2df596f87545bf35c36655c03"
},
"downloads": -1,
"filename": "bluetti_mqtt-0.15.0.tar.gz",
"has_sig": false,
"md5_digest": "156fc080438f0be635a3c2f457a6654d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 22226,
"upload_time": "2023-05-13T19:33:31",
"upload_time_iso_8601": "2023-05-13T19:33:31.302027Z",
"url": "https://files.pythonhosted.org/packages/17/78/ab0f25ef9e197d85b271b6511608878ac4d91811cfb2e4dfc349e632f323/bluetti_mqtt-0.15.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-13 19:33:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "warhammerkid",
"github_project": "bluetti_mqtt",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "asyncio-mqtt",
"specs": [
[
"==",
"0.12.1"
]
]
},
{
"name": "bleak",
"specs": [
[
"==",
"0.14.3"
]
]
},
{
"name": "crcmod",
"specs": [
[
"==",
"1.7"
]
]
},
{
"name": "dbus-next",
"specs": [
[
"==",
"0.2.3"
]
]
},
{
"name": "paho-mqtt",
"specs": [
[
"==",
"1.6.1"
]
]
}
],
"lcname": "bluetti-mqtt"
}
JSON
