Package: tpy357
tpy357tpy357 is an unofficial small cross-platform Python 3 (>3.10) library to interface with ThermoPro TP357 thermo-hygrometers.The module provides a small API to query the thermometer.
It can query TP357 real-time advertising data, or query daily, weekly, or yearly data stored in the device.
The CLI allows to store the results of the queries in a sqlite database, also incrementally, or exported to png plots or csv files. As an example, a Telegram bot is also provided.Installpython3-mpipinstall--upgrade--usertpy357or, using venvspython3-mvenv.venvsource.venv/bin/activate
python3-mpipinstall--upgradetpy357Usingpipxpipxinstalltpy357or even, just run directly with (see below for examples of usage)pipxruntpy357Seepipxdocumentation for more information.Be aware that that bluez is required when using Linux. It is generally included in distros with a desktop environment.Raspberry PiThe installation on the RaspberryPi is slightly more involved, as Debian usesexternally managed environments.
Using venvs orpipxshould work without problems, but might use more storage space
with duplicated module installs.
Some additional options are shown below.System Packages with venvAll the dependencies can be installed usingapt.
This uses the least space and the dependencies are updated with system updates.sudoaptupdate
sudoaptinstallpython3-bleakpython3-tomlipython3-pandaspython3-matplotlibthen a venv can be created with access to system modules:python3-mvenv--system-site-packages.venvsource.venv/bin/activate
python3-mpipinstall--upgradetpy357the installation using apt, also installs other system dependencies as bluez.System Packages with pipxIf not already installed, installpipxsudoaptupdate
sudoaptinstallpipx
sudoaptinstallpython3-bleakpython3-tomlipython3-pandaspython3-matplotlibthen can be installed in a automatically managed venv withpipxpipxinstall--system-site-packagestpy357To upgradepipxupgrade--system-site-packagestpy357Or again, just use run with access to system site packages (see below for examples of usage)pipxrun--system-site-packagestpy357...UsageAPIThe API is basically composed of two async functions.scan_tp357asyncdefscan_tp357(stop_evt:asyncio.Event,queue:asyncio.Queue):"""Scan for TP357 devices.Parameters-----------stop_evt : `asyncio.Event`Setting this event stops the scan for advertising packets.queue : `asyncio.Queue`Each advertising packets is put into this queue."""query_tp357asyncdefquery_tp357(dev,mode:str):"""Query a TP357 device.Parameters-----------dev : `bleak.backends.device.BLEDevice`Bleak device used for the query.Can be obtained using `bleak.BleakScanner` 'Easy methods',eg. `bleak.BleakScanner.find_device_by_address`.mode : `str`The mode of query. One of 'day', 'week', 'year'.Returns--------data : `list(dict)`Data queried from the device.`"""CLIusage:tpy357[-h][--dayADDRESS[ADDRESS...]][--weekADDRESS[ADDRESS...]][--yearADDRESS[ADDRESS...]][--csv][--png][--sqliteDBFILE][--waitWAIT]QueryTP357thermo-hygrometers

options:-h,--helpshowthishelpmessageandexit--dayADDRESS[ADDRESS...]Query'day'data.Ifnomodesarespecified,scanforadvertisingdata.--weekADDRESS[ADDRESS...]Query'week'data.Ifnomodesarespecified,scanforadvertisingdata.--yearADDRESS[ADDRESS...]Query'year'data.Ifnomodesarespecified,scanforadvertisingdata.--csvOptiontosavequeriestoacsvfile.Canbeusedwith['day','week','year'].--pngOptiontoplotqueriestoapngimage.Canbeusedwith['day','week','year'].--sqliteDBFILEWhenafilepathisprovided,createorappendthequerieddatatoasqlitedatabasewiththatname.--waitWAITSecondstowaittoclosetheconnection.Defaulttoinfinitewait(stopwithctrl+c).if venvs are used, it either needs the environment to be activated first, eg:source.venv/bin/activate
tpy357...or a full path to the python executable inside the venv should be provided, eg:.venv/bin/python3-mtpy357...ExamplesQuery advertising data and print it to the terminal (Stop with Ctrl-C). Useful to retrieve the address.tpy357--wait120--sqlitetp357.sqliteQuery advertising data for 120 seconds and store the data to a sqlite database with filenametp357.sqlitein the current directory.tpy357--wait120--sqlitetp357.sqliteQuery daily and yearly device stored data, with a time limit of 60 seconds for each connection,
and store the data in the current directory to a sqlite database with filenametp357.sqlite, a csv file, and a png image.tpy357--dayAD:DR:ES:SX:XX:XX--yearAD:DR:ES:SX:XX:XX--wait60--sqlitetp357.sqlite--csv--pngQuery daily data from two devices, with a time limit of 60 seconds for each connection,
and store the data in the current directory to a sqlite database with filenametp357.sqlite.tpy357--dayAD:DR:ES:S1:XX:XXAD:DR:ES:S2:XX:XX--wait60--sqlitetp357.sqliteTelegram BotThe scriptbot.pyis provided in the telegram-bot folder, with an example simple configuration toml file.
The toml file contains the token used to authenticate on Telegram (which is provided by BotFather), and
the list of users to whom the bot will respond.
If thelog_idhandler is enabled, the/idcommands prints the user data on the terminal, so that it can be easily copied into the toml file.
The example bot uses long polling, so that port-forwarding is not required, for simplicity.The dependencies can be installed using therequirements.txtprovided in the sametelegram-botfolder,
withpython3 -m pip install --upgrade -r requirements.txt.
Be aware of using the correct python3 executable or to activate the venv, also for the installation.Similar projectsThere are other similar projects that can be found over the web:https://github.com/pasky/tp357uses GLib and I believe is mainly for Linux (which is fair...).https://decoder.theengs.io/only provides advertising data and was also failing to install on Windows (which is also fair...).https://www.home-assistant.io/integrations/thermopro/Home Assistant integration, obviously requires Home Assistant to run, and captures advertising data only.LicenseThis project is released under GNU GPLv3, unless agreed or expressed differently.
tpy357 is provided AS-IS, without any warranty or liability.This project is not related or endorsed with ThermoPro brand, and the protocol was mainly found
by reverse-engineering through "packet sniffing" and/or resources publicly available.Changelogv1.1.0 (023.02.2024)Fix battery level indication for advertising packets.v1.0.0 (04.02.2024)First release.