ruuvitag-sensor 2.3.1__tar.gz → 3.1.0__tar.gz

{ruuvitag_sensor-2.3.1/ruuvitag_sensor.egg-info → ruuvitag_sensor-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: ruuvitag_sensor
-Version: 2.3.1
+Version: 3.1.0
 Summary: Find RuuviTag sensors and get decoded data from selected sensors
 Author-email: Tomi Tuhkanen <tomi.tuhkanen@iki.fi>
 License: MIT License
@@ -26,48 +26,43 @@ License: MIT License
         SOFTWARE.
         
 Project-URL: homepage, https://github.com/ttu/ruuvitag-sensor
+Project-URL: documentation, https://ttu.github.io/ruuvitag-sensor/
 Project-URL: source, https://github.com/ttu/ruuvitag-sensor
 Project-URL: changelog, https://github.com/ttu/ruuvitag-sensor/blob/master/CHANGELOG.md
-Project-URL: Bug Tracker, https://github.com/ttu/ruuvitag-sensor/issues
-Keywords: RuuviTag BLE
+Project-URL: issues, https://github.com/ttu/ruuvitag-sensor/issues
+Keywords: RuuviTag,BLE,Bluetooth,IoT,Sensor
 Classifier: Programming Language :: Python
-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
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Intended Audience :: Developers
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Framework :: AsyncIO
 Classifier: Framework :: Pytest
-Requires-Python: >=3.7
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: reactivex
 Requires-Dist: ptyprocess; platform_system == "Linux"
-Requires-Dist: mypy-extensions; python_version < "3.8"
-Requires-Dist: importlib-metadata<4.3,>=1.1.0; python_version < "3.8"
-Requires-Dist: bleak; platform_system == "Windows" or platform_system == "Darwin"
+Requires-Dist: bleak
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-asyncio; extra == "dev"
-Requires-Dist: flake8-pyproject; extra == "dev"
-Requires-Dist: pylint; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
-Requires-Dist: isort; extra == "dev"
-Requires-Dist: black==23.3.0; extra == "dev"
 
 RuuviTag Sensor Python Package
 ---------------------------------
 
 [![Build Status](https://github.com/ttu/ruuvitag-sensor/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/ttu/ruuvitag-sensor/actions/workflows/build.yml)
 [![License](https://img.shields.io/pypi/l/ruuvitag-sensor.svg)](https://pypi.python.org/pypi/ruuvitag-sensor/)
-[![PyPI version](https://img.shields.io/pypi/v/ruuvitag-sensor.svg)](https://pypi.python.org/pypi/ruuvitag_-sensor)
+[![PyPI version](https://img.shields.io/pypi/v/ruuvitag-sensor.svg)](https://pypi.python.org/pypi/ruuvitag-sensor)
 [![PyPI downloads](https://img.shields.io/pypi/dm/ruuvitag-sensor.svg)](https://pypistats.org/packages/ruuvitag-sensor)
-[![Python versions](https://img.shields.io/badge/python-3.7+-blue.svg)](https://pypi.python.org/pypi/ruuvitag-sensor/)
+[![Python versions](https://img.shields.io/badge/python-3.9+-blue.svg)](https://pypi.python.org/pypi/ruuvitag-sensor/)
 
 `ruuvitag-sensor` is a Python package for communicating with [RuuviTag BLE Sensor](https://ruuvi.com/) and for decoding measurement data from broadcasted BLE data.
 
@@ -78,26 +73,30 @@ RuuviTag Sensor Python Package
 * RuuviTag sensor
     * Setup [guide](https://ruuvi.com/quick-start/)
     * Supports [Data Format 2, 3, 4 and 5](https://docs.ruuvi.com/)
-      * __NOTE:__ Data Formats 2, 3 and 4 are _deprecated_ and should not be used
+      * __NOTE:__ Data Formats 2, 3 and 4 are _deprecated_ and should not be used.
 * [Bleak](https://github.com/hbldh/bleak) communication module (Windows, macOS and Linux)
-    * Default adapter for Windows and macOS
+    * Default adapter for all supported operating systems.
     * Bleak supports
       * [Async-methods](#usage)
       * [Observable streams](#usage)
+      * [Fetch history data](#usage)
     * [Install guide](#Bleak)
 * Bluez (Linux-only)
-    * Default adapter for Linux
     * Bluez supports
       * [Sync-methods](#usage)
       * [Observable streams](#usage)
     * [Install guide](#BlueZ)
     * __NOTE:__ The BlueZ-adapter implementation uses deprecated BlueZ tools that are no longer supported.
-      * Even though BlueZ is still the default adapter, it is recommended to use the Bleak-communication adapter with Linux. Bleak will be the default adapter for Linux in the next major release.
       * Bleson-adapter supports sync-methods, but please be aware that it is not fully supported due to the alpha release status of the Bleson communication module. See [Bleson](#Bleson) for more information.
-* Python 3.7+
-    * For Python 2.x or <3.7 support, check [installation instructions](#python-2x-and-36-and-below) for an older version
+* Python 3.9+
+    * For Python 3.7 and 3.8 support, check installation [instructions](#python-37-and-38) for an older version.
+    * For Python 2.x or <3.7 support, check installation [instructions](#python-2x-and-36-and-below) for an older version.
+
+
+__NOTE: Major version changes__ 
+* Version 3.0 changed default BLE adapter for all platforms to Bleak with async-methods. To use `Bluez`and sync-methods, check the installation [instructions](#BlueZ).
+* Version 2.0 contains method renames. When using a version prior to 2.0, check the documentation and examples from [documentation](https://ttu.github.io/ruuvitag-sensor/#/1.2.1/) or in GitHub, switch to the correct release tag from _switch branches/tags_.
 
-__NOTE:__ Version 2.0 contains method renames. When using a version prior to 2.0, check the documentation and examples from [PyPI](https://pypi.org/project/ruuvitag-sensor/) or in GitHub, switch to the correct release tag from _switch branches/tags_.
 
 ## Installation
 
@@ -120,18 +119,35 @@ Full installation guide for [Raspberry PI & Raspbian](https://github.com/ttu/ruu
 
 ## Usage
 
-The package provides 3 ways to fetch data from sensors:
+### Fetch broadcast data from RuuviTags
+
+The package provides 3 ways to fetch broadcasted data from sensors:
 
 1. Asynchronously with async/await
 2. Synchronously with callback
 3. Observable streams with ReactiveX
 
-RuuviTag sensors can be identified using MAC addresses. Methods return a tuple with MAC and sensor data payload.
+RuuviTag sensors can be identified using MAC addresses. Methods return a tuple containing MAC and sensor data payload.
 
 ```py
 ('D2:A3:6E:C8:E0:25', {'data_format': 5, 'humidity': 47.62, 'temperature': 23.58, 'pressure': 1023.68, 'acceleration': 993.2331045630729, 'acceleration_x': -48, 'acceleration_y': -12, 'acceleration_z': 992, 'tx_power': 4, 'battery': 2197, 'movement_counter': 0, 'measurement_sequence_number': 88, 'mac': 'd2a36ec8e025', 'rssi': -80})
 ```
 
+### Fetch stored history data from RuuviTags internal memory
+
+4. Fetch history data with async/await
+
+Each history entry contains one measurement type (temperature, humidity, or pressure) with a Unix timestamp (integer). RuuviTag sends each measurement type as a separate entry.
+
+```py
+[
+    {'temperature': 22.22, 'humidity': None, 'pressure': None, 'timestamp': 1738476581}
+    {'temperature': None, 'humidity': 38.8, 'pressure': None, 'timestamp': 1738476581},
+    {'temperature': None, 'humidity': None, 'pressure': 35755.0, 'timestamp': 1738476581},
+]
+```
+
+
 ### 1. Get sensor data asynchronously with async/await
 
 __NOTE:__ Asynchronous functionality works only with `Bleak`-adapter.
@@ -150,7 +166,7 @@ async def main():
 
 
 if __name__ == "__main__":
-    asyncio.get_event_loop().run_until_complete(main())
+    asyncio.run(main())
 ```
 
 The optional list of MACs can be passed to the `get_data_async` function.
@@ -168,20 +184,22 @@ async def main():
     async for found_data in RuuviTagSensor.get_data_async(macs):
         print(f"MAC: {found_data[0]}")
         print(f"Data: {found_data[1]}")
-        datas.push(found_data)
+        datas.append(found_data)
         if len(datas) > 10:
             break
 
 
 if __name__ == "__main__":
-    asyncio.get_event_loop().run_until_complete(main())
+    asyncio.run(main())
 ```
 
-The line `if __name__ == "__main__":` is required on Windows and macOS due to the way the `multiprocessing` library works. It is not required on Linux, but it is recommended. It is omitted from the rest of the examples below.
+The line `if __name__ == "__main__":` is required on Windows and macOS due to the way the `multiprocessing` library works. While not required on Linux, it is recommended. It is omitted from the rest of the examples below.
+
+For Python 3.9, you must replace `asyncio.run(main())` with `asyncio.get_event_loop().run_until_complete(main())` due to limitations in the RuuviTag package's Bleak adapter. In Python 3.10 and later versions, you can use `asyncio.run(main())`.
 
 ### 2. Get sensor data synchronously with callback
 
-__NOTE:__ Asynchronous functionality works only with `BlueZ`-adapter.
+__NOTE:__ Synchronous functionality works only with `BlueZ`-adapter.
 
 `get_data` calls the callback whenever a RuuviTag sensor broadcasts data. This method is the preferred way to use the library with _BlueZ_.
 
@@ -259,6 +277,54 @@ More [samples](https://github.com/ttu/ruuvitag-sensor/blob/master/examples/react
 
 Check the official documentation of [ReactiveX](https://rxpy.readthedocs.io/en/latest/index.html) and the [list of operators](https://rxpy.readthedocs.io/en/latest/operators.html).
 
+### 4. Fetch history data
+
+__NOTE:__ History data functionality works only with `Bleak`-adapter.
+
+RuuviTags with firmware version 3.30.0 or newer support retrieving historical measurements. The package provides two methods to access this data:
+
+1. `get_history_async`: Stream history entries as they arrive
+2. `download_history`: Download all history entries at once
+
+Each history entry contains one measurement type (temperature, humidity, or pressure) with a Unix timestamp (integer). RuuviTag sends each measurement type as a separate entry.
+
+Example history entry:
+```py
+{
+    'temperature': 22.22,  # Only one measurement type per entry
+    'humidity': None,
+    'pressure': None,
+    'timestamp': 1738476581  # Unix timestamp (integer)
+}
+```
+
+```py
+import asyncio
+from datetime import datetime, timedelta
+
+from ruuvitag_sensor.ruuvi import RuuviTagSensor
+
+
+async def main():
+    # Get history from the last 10 minutes
+    start_time = datetime.now() - timedelta(minutes=10)
+    
+    # Stream entries as they arrive
+    async for entry in RuuviTagSensor.get_history_async(mac="AA:BB:CC:DD:EE:FF", start_time=start_time):
+        print(f"Time: {entry['timestamp']} - {entry}")
+        
+    # Or download all entries at once
+    history = await RuuviTagSensor.download_history(mac="AA:BB:CC:DD:EE:FF", start_time=start_time)
+    for entry in history:
+        print(f"Time: {entry['timestamp']} - {entry}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+__NOTE:__ Due to the way macOS handles Bluetooth, methods uses UUIDs to identify RuuviTags instead of MAC addresses.
+
 ### Other helper methods
 
 #### Get data for specified sensors for a specific duration
@@ -317,7 +383,7 @@ RuuviTagSensor.find_ruuvitags()
 
 ### Using different Bluetooth device
 
-If you have multiple Bluetooth devices installed, a device to be used might not be the default (Linux: `hci0`). The device can be passed with a `bt_device`-parameter.
+If you have multiple Bluetooth devices installed, the device to be used might not be the default (Linux: `hci0`). The device can be passed with a `bt_device` parameter.
 
 ```python
 from ruuvitag_sensor.ruuvi import RuuviTagSensor
@@ -371,41 +437,42 @@ Example data has data from 4 sensors with different firmware.
 
 There is no reason to use Data Format 2 or 4.
 
-The original reason to use the URL-encoded data was to use _Google's Nearby_ notifications to let users view tags without the need to install any app. Since _Google's Nearby_ has been discontinued, there isn't any benefit in using the Eddystone format anymore.
+The original reason to use URL-encoded data was to use _Google's Nearby_ notifications to let users view tags without the need to install any app. Since _Google's Nearby_ has been discontinued, there isn't any benefit in using the Eddystone format anymore.
+
+## Logging
 
-## Logging and printing to the console
+The package uses Python's standard `logging` module. Each module in the package creates its own logger using `logging.getLogger(__name__)`.
 
-Logging can be enabled by importing `ruuvitag_sensor.log`. Console print can be enabled by calling `ruuvitag_sensor.log.enable_console()`. The command line application has console logging enabled by default.
+### Library usage
+
+When using ruuvitag-sensor as a library in your application, you should configure logging according to your application's needs:
 
 ```py
+import logging
 from ruuvitag_sensor.ruuvi import RuuviTagSensor
-import ruuvitag_sensor.log
 
-ruuvitag_sensor.log.enable_console()
+# Configure logging at the application level
+logging.basicConfig(level=logging.INFO)
+# Or set up custom handlers, formatters, etc.
 
 data = RuuviTagSensor.get_data_for_sensors()
-
-print(data)
 ```
 
-To enable debug logging to console, set log-level to `DEBUG`.
+### Command-line and script usage
+
+For command-line and script usage, the package provides convenience functions to enable console output:
 
 ```py
-import logging
-import ruuvitag_sensor.log
-from ruuvitag_sensor.log import log
 from ruuvitag_sensor.ruuvi import RuuviTagSensor
+import ruuvitag_sensor.log
 
+# Enable console logging (defaults to INFO level)
 ruuvitag_sensor.log.enable_console()
 
-log.setLevel(logging.DEBUG)
-
-for handler in log.handlers:
-    handler.setLevel(logging.DEBUG)
+# For debug logging
+ruuvitag_sensor.log.enable_console(level=logging.DEBUG)
 
 data = RuuviTagSensor.get_data_for_sensors()
-
-print(data)
 ```
 
 ### Log all events to log-file
@@ -428,7 +495,7 @@ data = RuuviTagSensor.get_data_for_sensors()
 
 ### A custom event handler for a specific log event
 
-If custom functionality is required when a specific event happens, e.g. exit when a specific sensor is blacklisted, logging event handlers can be utilized for this functionality.
+You can add custom handlers to respond to specific log events. For example, to exit when a specific sensor is blacklisted:
 
 ```py
 from logging import StreamHandler
@@ -439,7 +506,7 @@ from ruuvitag_sensor.ruuvi import RuuviTagSensor
 class ExitHandler(StreamHandler):
 
     def emit(self, record):
-        if (record.levelname != "DEBUG"):
+        if record.levelname != "DEBUG":
             return
         msg = self.format(record)
         if "Blacklisting MAC F4:A5:74:89:16:57E" in msg:
@@ -487,12 +554,20 @@ $ sudo apt-get install bluez bluez-hcidump
 
 `ruuvitag-sensor` package uses internally _hciconfig_, _hcitool_ and _hcidump_. These tools are deprecated. In case tools are missing, an older version of BlueZ is required ([Issue](https://github.com/ttu/ruuvitag-sensor/issues/31))
 
-If you wish to test the library on Windows or macOS, enable it with `RUUVI_BLE_ADAPTER` environment variable.
+Enable Bluez with the `RUUVI_BLE_ADAPTER` environment variable.
 
 ```sh
 $ export RUUVI_BLE_ADAPTER="bluez"
 ```
 
+Or use `os.environ`. __NOTE:__ this must be set before importing `ruuvitag_sensor`.
+
+```py
+import os
+
+os.environ["RUUVI_BLE_ADAPTER"] = "bluez"
+```
+
 And install ptyprocess.
 
 ```sh
@@ -507,29 +582,10 @@ In case of errors, the application tries to exit immediately, so it can be autom
 
 ### Bleak
 
-On Windows and macOS Bleak is installed and used automatically with `ruuvitag-sensor` package. 
+Bleak is automatically installed with `ruuvitag-sensor` package on all platforms.
+It is automatically used with `ruuvitag-sensor` package on all platforms.
 
-On Linux install it manually from PyPI and enable it with `RUUVI_BLE_ADAPTER` environment variable.
-
-```sh
-$ python -m pip install bleak
-```
-
-Add environment variable RUUVI_BLE_ADAPTER with value Bleak. E.g.
-
-```sh
-$ export RUUVI_BLE_ADAPTER="bleak"
-```
-
-Or use `os.environ`. __NOTE:__ this must be set before importing `ruuvitag_sensor`.
-
-```py
-import os
-
-os.environ["RUUVI_BLE_ADAPTER"] = "bleak"
-```
-
-Bleak supports only async methods.
+Bleak only supports asynchronous methods.
 
 ```py
 import asyncio
@@ -542,14 +598,14 @@ async def main():
 
 
 if __name__ == "__main__":
-    asyncio.get_event_loop().run_until_complete(main())
+    asyncio.run(main())
 ```
 
 Check [get_async_bleak](https://github.com/ttu/ruuvitag-sensor/blob/master/examples/get_async_bleak.py) and other async examples from [examples](https://github.com/ttu/ruuvitag-sensor/tree/master/examples) directory.
 
 #### Bleak dummy BLE data
 
-Bleak-adapter has a development-time generator for dummy data, which can be useful during the development, if no sensors are available. Set `RUUVI_BLE_ADAPTER` environment variable to `bleak_dev`.
+Bleak-adapter has a development-time generator for dummy data, which can be useful during development if no sensors are available. Set the `RUUVI_BLE_ADAPTER` environment variable to `bleak_dev`.
 
 ### Bleson
 
@@ -574,6 +630,21 @@ __NOTE:__ On macOS, only Data Format 5 works, as macOS doesn't advertise MAC add
 __NOTE:__ On Windows, Bleson requires _Python 3.6_. Unfortunately on Windows, Bleson doesn't send any payload for the advertised package, so it is still unusable.
 
 
+## Python 3.7 and 3.8
+
+Last version of `ruuvitag-sensor` with Python 3.7 and 3.8 support is [2.3.1](https://pypi.org/project/ruuvitag-sensor/2.3.1/).
+
+[Branch](https://github.com/ttu/ruuvitag-sensor/tree/release/2.3.1) / [Tag / commit](https://github.com/ttu/ruuvitag-sensor/commit/b16c9580d75eafe5508d0551642eb3b022ae1325)
+
+```sh
+$ git checkout release/2.3.1
+```
+
+Install from PyPI
+```sh
+$ python -m pip install ruuvitag-sensor==2.3.1
+```
+
 ## Python 2.x and 3.6 and below
 
 Last version of `ruuvitag-sensor` with Python 2.x and <3.7 support is [1.2.1](https://pypi.org/project/ruuvitag-sensor/1.2.1/).