{"id":15578302,"url":"https://github.com/ttu/ruuvitag-sensor","last_synced_at":"2025-05-15T11:06:28.484Z","repository":{"id":37580353,"uuid":"67077297","full_name":"ttu/ruuvitag-sensor","owner":"ttu","description":"Python package for communicating with RuuviTag BLE Sensor and for decoding sensor data from broadcasted data","archived":false,"fork":false,"pushed_at":"2025-03-01T06:11:56.000Z","size":443,"stargazers_count":201,"open_issues_count":7,"forks_count":79,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-05-15T08:11:59.029Z","etag":null,"topics":["bluetooth-le","pypi","python","python-package","reactive-extensions","ruuvitag","rxpy"],"latest_commit_sha":null,"homepage":"https://ttu.github.io/ruuvitag-sensor/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ttu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-08-31T22:13:49.000Z","updated_at":"2025-04-26T12:10:51.000Z","dependencies_parsed_at":"2023-02-10T06:01:07.309Z","dependency_job_id":"60bea8e9-f295-4c14-b450-5866ca2678e9","html_url":"https://github.com/ttu/ruuvitag-sensor","commit_stats":{"total_commits":335,"total_committers":28,"mean_commits":"11.964285714285714","dds":"0.21791044776119406","last_synced_commit":"b2b826fb08013c20b6a92c23ffba26df141de675"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ttu%2Fruuvitag-sensor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ttu%2Fruuvitag-sensor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ttu%2Fruuvitag-sensor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ttu%2Fruuvitag-sensor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ttu","download_url":"https://codeload.github.com/ttu/ruuvitag-sensor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254328385,"owners_count":22052632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bluetooth-le","pypi","python","python-package","reactive-extensions","ruuvitag","rxpy"],"created_at":"2024-10-02T19:08:02.318Z","updated_at":"2025-05-15T11:06:28.463Z","avatar_url":"https://github.com/ttu.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"RuuviTag Sensor Python Package\n---------------------------------\n\n[![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)\n[![License](https://img.shields.io/pypi/l/ruuvitag-sensor.svg)](https://pypi.python.org/pypi/ruuvitag-sensor/)\n[![PyPI version](https://img.shields.io/pypi/v/ruuvitag-sensor.svg)](https://pypi.python.org/pypi/ruuvitag-sensor)\n[![PyPI downloads](https://img.shields.io/pypi/dm/ruuvitag-sensor.svg)](https://pypistats.org/packages/ruuvitag-sensor)\n[![Python versions](https://img.shields.io/badge/python-3.9+-blue.svg)](https://pypi.python.org/pypi/ruuvitag-sensor/)\n\n`ruuvitag-sensor` is a Python package for communicating with [RuuviTag BLE Sensor](https://ruuvi.com/) and for decoding measurement data from broadcasted BLE data.\n\n**Documentation website:** [https://ttu.github.io/ruuvitag-sensor/](https://ttu.github.io/ruuvitag-sensor/)\n\n## Requirements\n\n* RuuviTag sensor\n    * Setup [guide](https://ruuvi.com/quick-start/)\n    * Supports [Data Format 2, 3, 4 and 5](https://docs.ruuvi.com/)\n      * __NOTE:__ Data Formats 2, 3 and 4 are _deprecated_ and should not be used.\n* [Bleak](https://github.com/hbldh/bleak) communication module (Windows, macOS and Linux)\n    * Default adapter for all supported operating systems.\n    * Bleak supports\n      * [Async-methods](#usage)\n      * [Observable streams](#usage)\n      * [Fetch history data](#usage)\n    * [Install guide](#Bleak)\n* Bluez (Linux-only)\n    * Bluez supports\n      * [Sync-methods](#usage)\n      * [Observable streams](#usage)\n    * [Install guide](#BlueZ)\n    * __NOTE:__ The BlueZ-adapter implementation uses deprecated BlueZ tools that are no longer supported.\n      * 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.\n* Python 3.9+\n    * For Python 3.7 and 3.8 support, check installation [instructions](#python-37-and-38) for an older version.\n    * For Python 2.x or \u003c3.7 support, check installation [instructions](#python-2x-and-36-and-below) for an older version.\n\n\n__NOTE: Major version changes__ \n* 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).\n* 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_.\n\n\n## Installation\n\nInstall the latest released version\n```sh\n$ python -m pip install ruuvitag-sensor\n```\n\nInstall the latest development version\n```sh\n$ python -m venv .venv\n$ source .venv/bin/activate\n$ python -m pip install git+https://github.com/ttu/ruuvitag-sensor\n\n# For development, clone this repository and install for development in editable mode\n$ python -m pip install -e .[dev]\n```\n\nFull installation guide for [Raspberry PI \u0026 Raspbian](https://github.com/ttu/ruuvitag-sensor/blob/master/install_guide_pi.md)\n\n## Usage\n\n### Fetch broadcast data from RuuviTags\n\nThe package provides 3 ways to fetch broadcasted data from sensors:\n\n1. Asynchronously with async/await\n2. Synchronously with callback\n3. Observable streams with ReactiveX\n\nRuuviTag sensors can be identified using MAC addresses. Methods return a tuple containing MAC and sensor data payload.\n\n```py\n('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})\n```\n\n### Fetch stored history data from RuuviTags internal memory\n\n4. Fetch history data with async/await\n\nEach history entry contains one measurement type (temperature, humidity, or pressure) with a Unix timestamp (integer). RuuviTag sends each measurement type as a separate entry.\n\n```py\n[\n    {'temperature': 22.22, 'humidity': None, 'pressure': None, 'timestamp': 1738476581}\n    {'temperature': None, 'humidity': 38.8, 'pressure': None, 'timestamp': 1738476581},\n    {'temperature': None, 'humidity': None, 'pressure': 35755.0, 'timestamp': 1738476581},\n]\n```\n\n\n### 1. Get sensor data asynchronously with async/await\n\n__NOTE:__ Asynchronous functionality works only with `Bleak`-adapter.\n\n`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_.\n\n```py\nimport asyncio\nfrom ruuvitag_sensor.ruuvi import RuuviTagSensor\n\n\nasync def main():\n    async for found_data in RuuviTagSensor.get_data_async():\n        print(f\"MAC: {found_data[0]}\")\n        print(f\"Data: {found_data[1]}\")\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\nThe optional list of MACs can be passed to the `get_data_async` function.\n\n```py\nimport asyncio\nfrom ruuvitag_sensor.ruuvi import RuuviTagSensor\n\nmacs = [\"AA:2C:6A:1E:59:3D\", \"CC:2C:6A:1E:59:3D\"]\n\n\nasync def main():\n    # Get data only for defineded MACs. Exit after 10 found results\n    datas = []\n    async for found_data in RuuviTagSensor.get_data_async(macs):\n        print(f\"MAC: {found_data[0]}\")\n        print(f\"Data: {found_data[1]}\")\n        datas.append(found_data)\n        if len(datas) \u003e 10:\n            break\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\nThe 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.\n\nFor 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())`.\n\n### 2. Get sensor data synchronously with callback\n\n__NOTE:__ Synchronous functionality works only with `BlueZ`-adapter.\n\n`get_data` calls the callback whenever a RuuviTag sensor broadcasts data. This method is the preferred way to use the library with _BlueZ_.\n\n```python\nfrom ruuvitag_sensor.ruuvi import RuuviTagSensor\n\n\ndef handle_data(found_data):\n    print(f\"MAC {found_data[0]}\")\n    print(f\"Data {found_data[1]}\")\n\n\nif __name__ == \"__main__\":\n    RuuviTagSensor.get_data(handle_data)\n```\n\nThe 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.\n\n```python\nfrom ruuvitag_sensor.ruuvi import RuuviTagSensor, RunFlag\n\ncounter = 10\n# RunFlag for stopping execution at desired time\nrun_flag = RunFlag()\n\n\ndef handle_data(found_data):\n    print(f\"MAC: {found_data[0]}\")\n    print(f\"Data: {found_data[1]}\")\n\n    global counter\n    counter = counter - 1\n    if counter \u003c 0:\n        run_flag.running = False\n\n\n# List of MACs of sensors which will execute callback function\nmacs = [\"AA:2C:6A:1E:59:3D\", \"CC:2C:6A:1E:59:3D\"]\n\nRuuviTagSensor.get_data(handle_data, macs, run_flag)\n```\n\n### 3. Get sensor data with observable streams (ReactiveX / RxPY)\n\n`RuuviTagReactive` is a reactive wrapper and background process for RuuviTagSensor `get_data`. An optional MAC address list can be passed on the initializer and execution can be stopped with the stop function.\n\n```python\nfrom ruuvitag_sensor.ruuvi_rx import RuuviTagReactive\nfrom reactivex import operators as ops\n\nruuvi_rx = RuuviTagReactive()\n\n# Print all notifications\nruuvi_rx.get_subject().\\\n    subscribe(print)\n\n# Print only last data every 10 seconds for F4:A5:74:89:16:57\nruuvi_rx.get_subject().pipe(\n      ops.filter(lambda x: x[0] == \"F4:A5:74:89:16:57\"),\n      ops.buffer_with_time(10.0)\n    ).subscribe(lambda data: print(data[len(data) - 1]))\n\n# Execute only every time when temperature changes for F4:A5:74:89:16:57\nruuvi_rx.get_subject().pipe(\n      ops.filter(lambda x: x[0] == \"F4:A5:74:89:16:57\"),\n      ops.map(lambda x: x[1][\"temperature\"]),\n      ops.distinct_until_changed()\n    ).subscribe(lambda x: print(f\"Temperature changed: {x}\"))\n\n# Close all connections and stop Bluetooth communication\nruuvi_rx.stop()\n```\n\nMore [samples](https://github.com/ttu/ruuvitag-sensor/blob/master/examples/reactive_extensions.py) and a simple [HTTP server](https://github.com/ttu/ruuvitag-sensor/blob/master/examples/http_server_asyncio_rx.py) under the examples directory.\n\nCheck 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).\n\n### 4. Fetch history data\n\n__NOTE:__ History data functionality works only with `Bleak`-adapter.\n\nRuuviTags with firmware version 3.30.0 or newer support retrieving historical measurements. The package provides two methods to access this data:\n\n1. `get_history_async`: Stream history entries as they arrive\n2. `download_history`: Download all history entries at once\n\nEach history entry contains one measurement type (temperature, humidity, or pressure) with a Unix timestamp (integer). RuuviTag sends each measurement type as a separate entry.\n\nExample history entry:\n```py\n{\n    'temperature': 22.22,  # Only one measurement type per entry\n    'humidity': None,\n    'pressure': None,\n    'timestamp': 1738476581  # Unix timestamp (integer)\n}\n```\n\n```py\nimport asyncio\nfrom datetime import datetime, timedelta\n\nfrom ruuvitag_sensor.ruuvi import RuuviTagSensor\n\n\nasync def main():\n    # Get history from the last 10 minutes\n    start_time = datetime.now() - timedelta(minutes=10)\n    \n    # Stream entries as they arrive\n    async for entry in RuuviTagSensor.get_history_async(mac=\"AA:BB:CC:DD:EE:FF\", start_time=start_time):\n        print(f\"Time: {entry['timestamp']} - {entry}\")\n        \n    # Or download all entries at once\n    history = await RuuviTagSensor.download_history(mac=\"AA:BB:CC:DD:EE:FF\", start_time=start_time)\n    for entry in history:\n        print(f\"Time: {entry['timestamp']} - {entry}\")\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n__NOTE:__ Due to the way macOS handles Bluetooth, methods uses UUIDs to identify RuuviTags instead of MAC addresses.\n\n### Other helper methods\n\n#### Get data for specified sensors for a specific duration\n\n`get_data_for_sensors` and `get_data_for_sensors_async` will collect the latest data from sensors for a specified duration.\n\n```python\nfrom ruuvitag_sensor.ruuvi import RuuviTagSensor\n\n# List of MACs of sensors which data will be collected\n# If list is empty, data will be collected for all found sensors\nmacs = [\"AA:2C:6A:1E:59:3D\", \"CC:2C:6A:1E:59:3D\"]\n# get_data_for_sensors will look data for the duration of timeout_in_sec\ntimeout_in_sec = 4\n\ndata = RuuviTagSensor.get_data_for_sensors(macs, timeout_in_sec)\n# data = await RuuviTagSensor.get_data_for_sensors_async(macs, timeout_in_sec)\n\n# Dictionary will have latest data for each sensor\nprint(data[\"AA:2C:6A:1E:59:3D\"])\nprint(data[\"CC:2C:6A:1E:59:3D\"])\n```\n\n__NOTE:__ These methods shouldn't be used for a long duration with a short timeout. Methods will start and stop a new BLE scanning process with every method call. For long-running processes, it is recommended to use the `get_data`- and `get_data_async`-method.\n\n#### Get data from a sensor\n\n__NOTE:__ For a single sensor it is recommended to use `RuuviTagSensor.get_data` or `RuuviTagSensor.get_data_async` methods instead of `RuuviTag`- or `RuuviTagAsync`-class. `RuuviTagAsync`-class doesn't work with macOS, due to the way how macOS returns MAC address.\n\n```python\nfrom ruuvitag_sensor.ruuvitag import RuuviTag\n\nsensor = RuuviTag(\"AA:2C:6A:1E:59:3D\")\n\n# update state from the device\nstate = sensor.update()\n\n# get latest state (does not get it from the device)\nstate = sensor.state\n\nprint(state)\n```\n\n#### Find sensors\n\n`RuuviTagSensor.find_ruuvitags` and `RuuviTagSensor.find_ruuvitags_async` methods will execute forever and when a new RuuviTag sensor is found, it will print its MAC address and state at that moment. This function can be used with command-line applications. Logging must be enabled and set to print to the console.\n\n```python\nfrom ruuvitag_sensor.ruuvi import RuuviTagSensor\nimport ruuvitag_sensor.log\n\nruuvitag_sensor.log.enable_console()\n\nRuuviTagSensor.find_ruuvitags()\n```\n\n### Using different Bluetooth device\n\nIf 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.\n\n```python\nfrom ruuvitag_sensor.ruuvi import RuuviTagSensor\nfrom ruuvitag_sensor.ruuvitag import RuuviTag\n\nsensor = RuuviTag(\"F4:A5:74:89:16:57\", \"hci1\")\n\nRuuviTagSensor.find_ruuvitags(\"hci1\")\n\ndata = RuuviTagSensor.get_data_for_sensors(bt_device=\"hci1\")\n\nRuuviTagSensor.get_data(lambda x: print(f\"{x[0]} - {x[1]}\"), bt_device=device))\n```\n\n### Parse data\n\n```python\nfrom ruuvitag_sensor.data_formats import DataFormats\nfrom ruuvitag_sensor.decoder import get_decoder\n\nfull_data = \"043E2A0201030157168974A51F0201060303AAFE1716AAFE10F9037275752E76692F23416A5558314D417730C3\"\ndata = full_data[26:]\n\n# convert_data returns tuple which has Data Format type and encoded data\n(data_format, encoded) = DataFormats.convert_data(data)\n\nsensor_data = get_decoder(data_format).decode_data(encoded)\n\nprint(sensor_data)\n# {'temperature': 25.12, 'identifier': '0', 'humidity': 26.5, 'pressure': 992.0}\n```\n\n## RuuviTag Data Formats\n\nExample data has data from 4 sensors with different firmware.\n* 1st is Data Format 2 (URL), the identifier is None as the sensor doesn't broadcast any identifier data\n* 2nd is Data Format 4 (URL) and it has an identifier character\n* 3rd is Data Format 3 (RAW)\n* 4th is Data Format 5 (RAW v2)\n\n```python\n{\n'CA:F7:44:DE:EB:E1': { 'data_format': 2, 'temperature': 22.0, 'humidity': 28.0, 'pressure': 991.0, 'identifier': None, 'rssi': None },\n'F4:A5:74:89:16:57': { 'data_format': 4, 'temperature': 23.24, 'humidity': 29.0, 'pressure': 991.0, 'identifier': '0', 'rssi': None },\n'A3:GE:2D:91:A4:1F': { 'data_format': 3, 'battery': 2899, 'pressure': 1027.66, 'humidity': 20.5, 'acceleration': 63818.215675463696, 'acceleration_x': 200.34, 'acceleration_y': 0.512, 'acceleration_z': -200.42, 'temperature': 26.3, 'rssi': None },\n'CB:B8:33:4C:88:4F': { 'data_format': 5, 'battery': 2.995, 'pressure': 1000.43, 'mac': 'cbb8334c884f', 'measurement_sequence_number': 2467, 'acceleration_z': 1028, 'acceleration': 1028.0389097694697, 'temperature': 22.14, 'acceleration_y': -8, 'acceleration_x': 4, 'humidity': 53.97, 'tx_power': 4, 'movement_counter': 70, 'rssi': -65 }\n}\n```\n\n### Note on Data Format 2 and 4\n\nThere is no reason to use Data Format 2 or 4.\n\nThe 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.\n\n## Logging\n\nThe package uses Python's standard `logging` module. Each module in the package creates its own logger using `logging.getLogger(__name__)`.\n\n### Library usage\n\nWhen using ruuvitag-sensor as a library in your application, you should configure logging according to your application's needs:\n\n```py\nimport logging\nfrom ruuvitag_sensor.ruuvi import RuuviTagSensor\n\n# Configure logging at the application level\nlogging.basicConfig(level=logging.INFO)\n# Or set up custom handlers, formatters, etc.\n\ndata = RuuviTagSensor.get_data_for_sensors()\n```\n\n### Command-line and script usage\n\nFor command-line and script usage, the package provides convenience functions to enable console output:\n\n```py\nfrom ruuvitag_sensor.ruuvi import RuuviTagSensor\nimport ruuvitag_sensor.log\n\n# Enable console logging (defaults to INFO level)\nruuvitag_sensor.log.enable_console()\n\n# For debug logging\nruuvitag_sensor.log.enable_console(level=logging.DEBUG)\n\ndata = RuuviTagSensor.get_data_for_sensors()\n```\n\n### Log all events to log-file\n\nBy default only errors are logged to `ruuvitag_sensor.log`-file. The level can be changed by changing FileHandler's log level.\n\n```py\nimport logging\nfrom ruuvitag_sensor.log import log\nfrom ruuvitag_sensor.ruuvi import RuuviTagSensor\n\nlog.setLevel(logging.DEBUG)\n\nfor handler in log.handlers:\n    if isinstance(handler, logging.FileHandler):\n        handler.setLevel(logging.DEBUG)\n\ndata = RuuviTagSensor.get_data_for_sensors()\n```\n\n### A custom event handler for a specific log event\n\nYou can add custom handlers to respond to specific log events. For example, to exit when a specific sensor is blacklisted:\n\n```py\nfrom logging import StreamHandler\nfrom ruuvitag_sensor.log import log\nfrom ruuvitag_sensor.ruuvi import RuuviTagSensor\n\n\nclass ExitHandler(StreamHandler):\n\n    def emit(self, record):\n        if record.levelname != \"DEBUG\":\n            return\n        msg = self.format(record)\n        if \"Blacklisting MAC F4:A5:74:89:16:57E\" in msg:\n            exit(1)\n\n\nexit_handler = ExitHandler()\nlog.addHandler(exit_handler)\n\ndata = RuuviTagSensor.get_data_for_sensors()\n```\n\n## Command line application\n\n```\n$ python ruuvitag_sensor -h\n\nusage: ruuvitag_sensor [-h] [-g MAC_ADDRESS] [-d BT_DEVICE] [-f] [-l] [-s] [--version]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -g MAC_ADDRESS, --get MAC_ADDRESS\n                        Get data\n  -d BT_DEVICE, --device BT_DEVICE\n                        Set Bluetooth device id (default hci0)\n  -f, --find            Find broadcasting RuuviTags\n  -l, --latest          Get latest data for found RuuviTags\n  -s, --stream          Stream broadcasts from all RuuviTags\n  --version             show program's version number and exit\n```\n\n## BLE Communication modules\n\n### BlueZ\n\nBlueZ works only on __Linux__. When using BlueZ, Windows and macOS support is only for testing with hard-coded data and for data decoding.\n\nBlueZ tools require __superuser__ rights.\n\nInstall BlueZ.\n\n```sh\n$ sudo apt-get install bluez bluez-hcidump\n```\n\n`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))\n\nEnable Bluez with the `RUUVI_BLE_ADAPTER` environment variable.\n\n```sh\n$ export RUUVI_BLE_ADAPTER=\"bluez\"\n```\n\nOr use `os.environ`. __NOTE:__ this must be set before importing `ruuvitag_sensor`.\n\n```py\nimport os\n\nos.environ[\"RUUVI_BLE_ADAPTER\"] = \"bluez\"\n```\n\nAnd install ptyprocess.\n\n```sh\npython -m pip install ptyprocess\n```\n\n#### BlueZ limitations\n\n`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.\n\nIn case of errors, the application tries to exit immediately, so it can be automatically restarted.\n\n### Bleak\n\nBleak is automatically installed with `ruuvitag-sensor` package on all platforms.\nIt is automatically used with `ruuvitag-sensor` package on all platforms.\n\nBleak only supports asynchronous methods.\n\n```py\nimport asyncio\nfrom ruuvitag_sensor.ruuvi import RuuviTagSensor\n\n\nasync def main():\n    async for data in RuuviTagSensor.get_data_async():\n        print(data)\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\nCheck [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.\n\n#### Bleak dummy BLE data\n\nBleak-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`.\n\n### Bleson\n\nCurrent state and known bugs in [issue #78](https://github.com/ttu/ruuvitag-sensor/issues/78).\n\n[Bleson](https://github.com/TheCellule/python-bleson) works with Linux, macOS and partially with Windows.\n\nBleson is not installed automatically with `ruuvitag-sensor` package. Install it manually from GitHub.\n\n```sh\n$ python -m pip install git+https://github.com/TheCellule/python-bleson\n```\n\nAdd environment variable `RUUVI_BLE_ADAPTER` with value `bleson`. E.g.\n\n```sh\n$ export RUUVI_BLE_ADAPTER=\"bleson\"\n```\n\n__NOTE:__ On macOS, only Data Format 5 works, as macOS doesn't advertise MAC address and only DF5 has MAC in sensor payload. `RuuviTag`-class doesn't work with macOS.\n\n__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.\n\n\n## Python 3.7 and 3.8\n\nLast 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/).\n\n[Branch](https://github.com/ttu/ruuvitag-sensor/tree/release/2.3.1) / [Tag / commit](https://github.com/ttu/ruuvitag-sensor/commit/b16c9580d75eafe5508d0551642eb3b022ae1325)\n\n```sh\n$ git checkout release/2.3.1\n```\n\nInstall from PyPI\n```sh\n$ python -m pip install ruuvitag-sensor==2.3.1\n```\n\n## Python 2.x and 3.6 and below\n\nLast version of `ruuvitag-sensor` with Python 2.x and \u003c3.7 support is [1.2.1](https://pypi.org/project/ruuvitag-sensor/1.2.1/).\n\n[Branch](https://github.com/ttu/ruuvitag-sensor/tree/release/1.2.1) / [Tag / commit](https://github.com/ttu/ruuvitag-sensor/commit/12ca3cfcb7fbed28477bb34f3bffd3eee0f9888d)\n\n```sh\n$ git checkout release/1.2.1\n```\n\nInstall from PyPI\n```sh\n$ python -m pip install ruuvitag-sensor==1.2.1\n```\n\n## Examples\n\nExamples are in [examples](https://github.com/ttu/ruuvitag-sensor/tree/master/examples) directory, e.g.\n\n* Keep track of each sensor's current status and send updated data to the server. [Sync](https://github.com/ttu/ruuvitag-sensor/blob/master/examples/send_updated_sync.py) and [async](https://github.com/ttu/ruuvitag-sensor/blob/master/examples/send_updated_async.py) version.\n* Send found sensor data to InfluxDB. [Reactive](https://github.com/ttu/ruuvitag-sensor/blob/master/examples/post_to_influxdb_rx.py) and [non-reactive](https://github.com/ttu/ruuvitag-sensor/blob/master/examples/post_to_influxdb.py) version. The naming convention of sent data matches [RuuviCollector library](https://github.com/scrin/ruuvicollector).\n* Simple HTTP Server for serving found sensor data. [Flask](https://github.com/ttu/ruuvitag-sensor/blob/master/examples/http_server.py), [aiohttp](https://github.com/ttu/ruuvitag-sensor/blob/master/examples/http_server_asyncio.py) and [aiohttp with ReactiveX](https://github.com/ttu/ruuvitag-sensor/blob/master/examples/http_server_asyncio_rx.py).\n\n## Changelog\n\n[Changelog](https://github.com/ttu/ruuvitag-sensor/blob/master/CHANGELOG.md)\n\n## Developer notes\n\n[Notes for developers](https://github.com/ttu/ruuvitag-sensor/blob/master/developer_notes.md) who are interested in developing `ruuvitag-sensor` package or are interested in its internal functionality.\n\n## Contributing\n\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.\n\n## License\n\nLicensed under the [MIT](https://github.com/ttu/ruuvitag-sensor/blob/master/LICENSE) License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fttu%2Fruuvitag-sensor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fttu%2Fruuvitag-sensor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fttu%2Fruuvitag-sensor/lists"}