|
| 1 | +# 🖤 BleakHeart |
| 2 | + |
| 3 | +An asynchronous BLE Heart Monitor library that supports additional measurements (such as ECG and accelerometer data) available from Polar sensors through the Polar Measurement Data interface. |
| 4 | + |
| 5 | +BleakHeart is written in Python using the [asyncio](https://docs.python.org/3/library/asyncio.html) framework; BLE communication is based on [Bleak](https://bleak.readthedocs.io/en/latest/#). |
| 6 | + |
| 7 | +## Installation |
| 8 | + |
| 9 | +Place the ```bleakheart.py``` file in the same directory as your program, or in a directory in your ```PYTHONPATH```. |
| 10 | +BleakHeart requires [Bleak](https://bleak.readthedocs.io/en/latest/#); the current version was tested with Bleak v0.20.2. |
| 11 | + |
| 12 | +## Features |
| 13 | + |
| 14 | +* Supports heart rate acquisition for devices supporting the standard BLE [heart rate service](https://www.bluetooth.com/specifications/specs/heart-rate-service-1-0/), including RR intervals, instant heart rate, energy expenditure and (client-based) time stamps; |
| 15 | +* Reads Accelerometer and ECG signals from the Polar H10 chest strap; |
| 16 | +* Offers partial support for measurements available from other Polar devices through the Polar Measurement Data interface; |
| 17 | +* Normalises Polar sensor timestamps to Epoch time; |
| 18 | +* Reads the battery charge state through the standard BLE [battery service](https://www.bluetooth.com/specifications/specs/battery-service/) (also available on other types of BLE devices). |
| 19 | + |
| 20 | +## Usage |
| 21 | + |
| 22 | +BleakHeart supports a variety of software design choices. Specifically: |
| 23 | +* A data producer/consumer model can be easily implemented by asking BleakHeart to push sensor data onto asynchronous queues; |
| 24 | +* Alternatively, data can be sent to a callback. Simple tasks such as sensor logging can be accomplished with only a minimal understanding of ```asyncio```; |
| 25 | +* All data are tagged with their measurement type; thus the same queue or callback can be used to handle different types of measurements if desired. |
| 26 | + |
| 27 | +Please see the examples directory for detailed examples of some of the possible workflows, and use the ```help``` function on BleakHeart objects for more information. |
| 28 | + |
| 29 | +## Limitations |
| 30 | + |
| 31 | +BleakHeart has only been tested on a Polar H10 chest strap (under Linux), since that is what I have available. Other Polar devices are only partly supported; measurements other than ECG and acceleration are returned as raw bytearrays. Offline recording to the internal Polar H10 memory is not supported. |
| 32 | + |
| 33 | +## Credits and contributing |
| 34 | + |
| 35 | +This software was developed by [Fabrizio Smeraldi](http://www.eecs.qmul.ac.uk/~fabri/). |
| 36 | +If you would like to contribute, please [get in touch ](mailto:[email protected]). |
| 37 | + |
| 38 | +## Academic use |
| 39 | + |
| 40 | +If you use this software for academic research, please reference this repository and [let me know ](mailto:[email protected]). I will cite your paper! :) |
| 41 | + |
| 42 | +## Disclaimer and license |
| 43 | + |
| 44 | +Polar is a trademark of Polar Electro Oy; [Bleak](https://bleak.readthedocs.io/en/latest/#) is an open-source BLE library developed by Henrik Blidh. The author is not affiliated with either. |
| 45 | + |
| 46 | +This software is provided subject to the terms of the [Mozilla Public License version 2.0](https://www.mozilla.org/en-US/MPL/2.0/), in the hope that it will be useful; see the ```LICENSE``` file for details. |
| 47 | + |
| 48 | +## Resources |
| 49 | + |
| 50 | +* The official [Polar BLE SDK](https://github.com/polarofficial/polar-ble-sdk), contains software for Android and iOS and some interesting documentation, in particular: |
| 51 | + * An explanation of [ECG on the Polar H10](https://github.com/polarofficial/polar-ble-sdk/blob/master/technical_documentation/H10_ECG_Explained.docx) |
| 52 | + * A specification of the proprietary [Polar Measurement Data](https://github.com/polarofficial/polar-ble-sdk/blob/52ef4c4b77e5f83b0839f0f4f72623a9b9d79372/technical_documentation/Polar_Measurement_Data_Specification.pdf) service |
| 53 | + * An explanation of the [time system](https://github.com/polarofficial/polar-ble-sdk/blob/master/documentation/TimeSystemExplained.md) in Polar devices (BleakHeart transparently normalises this to Epoch time). |
| 54 | +* The [Heart Rate service](https://www.bluetooth.com/specifications/specs/heart-rate-service-1-0/) specification, on the BLE SIG website. |
| 55 | +* The [Battery service](https://www.bluetooth.com/specifications/specs/battery-service/) specification, on the BLE SIG website. |
0 commit comments