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

{ruuvitag_sensor-2.3.0 → 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.0
+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,47 +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; 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/pypi/pyversions/ruuvitag-sensor.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.
 
@@ -77,23 +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
-* Bluez (Linux-only)
-    * Default adapter for Linux
-    * Bluez supports
-      * [Sync-methods](#usage)
-      * [Observable streams](#usage)
-    * [Install guide](#BlueZ)
+      * __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)
-* Python 3.7+
-    * For Python 2.x or <3.7 support, check [installation instructions](#python-2x-and-36-and-below) for an older version
+* Bluez (Linux-only)
+    * 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.
+      * 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.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
 
@@ -116,68 +119,40 @@ 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. Synchronously with callback
-2. Asynchronously with async/await
+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})
 ```
 
-### 1. Get sensor data synchronously with callback
-
-`get_data` calls the callback whenever a RuuviTag sensor broadcasts data. This method is the preferred way to use the library with _BlueZ_.
-
-```python
-from ruuvitag_sensor.ruuvi import RuuviTagSensor
+### Fetch stored history data from RuuviTags internal memory
 
+4. Fetch history data with async/await
 
-def handle_data(found_data):
-    print(f"MAC {found_data[0]}")
-    print(f"Data {found_data[1]}")
+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.
 
-
-if __name__ == "__main__":
-    RuuviTagSensor.get_data(handle_data)
+```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},
+]
 ```
 
-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 optional list of MACs and run flag can be passed to the `get_data` function. The callback is called only for MACs in the list and setting the run flag to false will stop execution. If the run flag is not passed, the function will execute forever.
-
-```python
-from ruuvitag_sensor.ruuvi import RuuviTagSensor, RunFlag
-
-counter = 10
-# RunFlag for stopping execution at desired time
-run_flag = RunFlag()
-
-
-def handle_data(found_data):
-    print(f"MAC: {found_data[0]}")
-    print(f"Data: {found_data[1]}")
-
-    global counter
-    counter = counter - 1
-    if counter < 0:
-        run_flag.running = False
-
 
-# List of MACs of sensors which will execute callback function
-macs = ["AA:2C:6A:1E:59:3D", "CC:2C:6A:1E:59:3D"]
-
-RuuviTagSensor.get_data(handle_data, macs, run_flag)
-```
-
-### 2. Get sensor data asynchronously
+### 1. Get sensor data asynchronously with async/await
 
 __NOTE:__ Asynchronous functionality works only with `Bleak`-adapter.
 
-`get_data_async` returns the data whenever a RuuviTag sensor broadcasts data. `get_data_async` will exceute until iterator is exited. This method is the preferred way to use the library with _Bleak_.
+`get_data_async` returns the data whenever a RuuviTag sensor broadcasts data. `get_data_async` will execute until iterator is exited. This method is the preferred way to use the library with _Bleak_.
 
 ```py
 import asyncio
@@ -191,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.
@@ -209,13 +184,62 @@ 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. 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:__ 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_.
+
+```python
+from ruuvitag_sensor.ruuvi import RuuviTagSensor
+
+
+def handle_data(found_data):
+    print(f"MAC {found_data[0]}")
+    print(f"Data {found_data[1]}")
+
+
+if __name__ == "__main__":
+    RuuviTagSensor.get_data(handle_data)
+```
+
+The optional list of MACs and run flag can be passed to the `get_data` function. The callback is called only for MACs in the list and setting the run flag to false will stop execution. If the run flag is not passed, the function will execute forever.
+
+```python
+from ruuvitag_sensor.ruuvi import RuuviTagSensor, RunFlag
+
+counter = 10
+# RunFlag for stopping execution at desired time
+run_flag = RunFlag()
+
+
+def handle_data(found_data):
+    print(f"MAC: {found_data[0]}")
+    print(f"Data: {found_data[1]}")
+
+    global counter
+    counter = counter - 1
+    if counter < 0:
+        run_flag.running = False
+
+
+# List of MACs of sensors which will execute callback function
+macs = ["AA:2C:6A:1E:59:3D", "CC:2C:6A:1E:59:3D"]
+
+RuuviTagSensor.get_data(handle_data, macs, run_flag)
 ```
 
 ### 3. Get sensor data with observable streams (ReactiveX / RxPY)
@@ -245,7 +269,7 @@ ruuvi_rx.get_subject().pipe(
       ops.distinct_until_changed()
     ).subscribe(lambda x: print(f"Temperature changed: {x}"))
 
-# Close all connections and stop bluetooth communication
+# Close all connections and stop Bluetooth communication
 ruuvi_rx.stop()
 ```
 
@@ -253,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
@@ -311,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
@@ -365,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
@@ -422,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
@@ -433,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:
@@ -481,37 +554,38 @@ $ 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))
 
-#### BlueZ limitations
+Enable Bluez with the `RUUVI_BLE_ADAPTER` environment variable.
 
-`ruuvitag-sensor` package uses BlueZ to listen to broadcasted BL information (uses _hciconf_, _hcitool_, _hcidump_). Implementation does not handle well all unexpected errors or changes, e.g. when the adapter is busy, rebooted or powered down.
+```sh
+$ export RUUVI_BLE_ADAPTER="bluez"
+```
 
-In case of errors, the application tries to exit immediately, so it can be automatically restarted.
+Or use `os.environ`. __NOTE:__ this must be set before importing `ruuvitag_sensor`.
 
-### Bleak
+```py
+import os
 
-On Windows and macOS Bleak is installed and used automatically with `ruuvitag-sensor` package. 
+os.environ["RUUVI_BLE_ADAPTER"] = "bluez"
+```
 
-On Linux install it manually from PyPI and enable it with `RUUVI_BLE_ADAPTER` environment variable.
+And install ptyprocess.
 
 ```sh
-$ python -m pip install bleak
+python -m pip install ptyprocess
 ```
 
-Add environment variable RUUVI_BLE_ADAPTER with value Bleak. E.g.
+#### BlueZ limitations
 
-```sh
-$ export RUUVI_BLE_ADAPTER="bleak"
-```
+`ruuvitag-sensor` package uses BlueZ to listen to broadcasted BL information (uses _hciconf_, _hcitool_, _hcidump_). Implementation does not handle well all unexpected errors or changes, e.g. when the adapter is busy, rebooted or powered down.
 
-Or use `os.environ`. NOTE: this must be set before importing `ruuvitag_sensor`.
+In case of errors, the application tries to exit immediately, so it can be automatically restarted.
 
-```py
-import os
+### Bleak
 
-os.environ["RUUVI_BLE_ADAPTER"] = "bleak"
-```
+Bleak is automatically installed with `ruuvitag-sensor` package on all platforms.
+It is automatically used with `ruuvitag-sensor` package on all platforms.
 
-Bleak supports only async methods.
+Bleak only supports asynchronous methods.
 
 ```py
 import asyncio
@@ -524,25 +598,25 @@ 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
 
 Current state and known bugs in [issue #78](https://github.com/ttu/ruuvitag-sensor/issues/78).
 
-Bleson works with Linux, macOS and partially with Windows.
+[Bleson](https://github.com/TheCellule/python-bleson) works with Linux, macOS and partially with Windows.
 
 Bleson is not installed automatically with `ruuvitag-sensor` package. Install it manually from GitHub.
 
 ```sh
-$ pip install git+https://github.com/TheCellule/python-bleson
+$ python -m pip install git+https://github.com/TheCellule/python-bleson
 ```
 
 Add environment variable `RUUVI_BLE_ADAPTER` with value `bleson`. E.g.
@@ -556,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/).