<commit_before># ACR Reactive BluetoothLE Plugin for Xamarin & Windows
Easy to use, cross platform, REACTIVE BluetoothLE Plugin for Xamarin (Windows UWP COMING SOON)

## PLATFORMS

* Android 4.3+
* iOS 6+
* tvOS / Mac (support is here, I haven't had the means to fully test these yet)
* Windows UWP (COMING SOON)

## FEATURES

* Scan for advertisement packets and devices
* Monitor adapter status
* Connect to device and monitor status
* Discover services, characteristics, & descriptors
* Read, write, & receive notifications for characteristics
* Read & write descriptors
* Monitor all aspects of the BLE plugin via CreateLogging extension
* Connect to heart rate monitors


## SETUP

Be sure to install the Acr.Ble nuget package in all of your main platform projects as well as your core/PCL project

[![NuGet](https://img.shields.io/nuget/v/Acr.Ble.svg?maxAge=2592000)](https://www.nuget.org/packages/Acr.Ble/)

**Android**

Add the following to your AndroidManifest.xml

```xml
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
```

__In Android v6, you should also request permissions for 

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

**iOS**

If you want to use background BLE periperhals, add the following to your Info.plist

```xml    
<array>
<string>bluetooth-central</string>
</array>

To add a description to the Bluetooth request message (on iOS 10 this is required!)
```xml    
<key>NSBluetoothPeripheralUsageDescription</key>
<string>YOUR CUSTOM MESSAGE</string>
```

**Windows**

Add to your app manifest file
```xml
<Capabilities>
    <Capability Name="internetClient" />
    <DeviceCapability Name="bluetooth" />
</Capabilities>
```

## HOW TO USE BASICS

```csharp

// discover some devices
BleAdapter.Current.Scan().Subscribe(scanResult => {});

// Once finding the device/scanresult you want
await scanResult.Device.Connect();

Device.WhenAnyCharacteristicDiscovered().Subscribe(characteristic => {
    // read, write, or subscribe to notifications here
    var bytes = await characteristic.Read();
    await characteristic.Write(bytes);

    characteristic.SubscribeToNotifications(bytes => {
    
    });
});

```

## DOCUMENTATION

* [Adapter](docs/adapter.md)
* [Device](docs/device.md)
* [Services](docs/services.md)
* [Characteristics](docs/characteristics.md)
* [Descriptors](docs/descriptors.md)
* Plugins
    * [Logging](docs/logging.md)
    * [Heart Rate](docs/heartrate.md)

## FAQ

Q. Why is everything reactive instead of events/async

> I wanted event streams as I was scanning devices.  I also wanted to throttle things like characteristic notification feeds.  Lastly, was the proper cleanup of events and resources.   

Q. Why are Device.Connect, Characteristic.Read, and Descriptor.Read observable when async would do just fine?

> True, but observables with RX are actually awaitable as well and far easier to chain into other things.

Q. Why have a Adapter.BackgroundScan with a service UUID?  This is not a problem on Android

> Also, true, but consistency is what I was aiming for.  iOS only allows you to scan in the background with a serviceUUID and on Android, I set the scanmode to low power.

Q. Why are devices cleared on a new scan?

> Some platforms yield a "new" device and therefore new hooks.  This was observed on some android devices.

Q. My characteristic read/writes/notifications are not working
> If you store your discovered characteristics in your own variables, make sure to refresh them with each (re)connect
<commit_msg>doc fix<commit_after># ACR Reactive BluetoothLE Plugin for Xamarin & Windows
Easy to use, cross platform, REACTIVE BluetoothLE Plugin for Xamarin (Windows UWP COMING SOON)

## PLATFORMS

* Android 4.3+
* iOS 6+
* tvOS / Mac (support is here, I haven't had the means to fully test these yet)
* Windows UWP (COMING SOON)

## FEATURES

* Scan for advertisement packets and devices
* Monitor adapter status
* Connect to device and monitor status
* Discover services, characteristics, & descriptors
* Read, write, & receive notifications for characteristics
* Read & write descriptors
* Monitor all aspects of the BLE plugin via CreateLogging extension
* Connect to heart rate monitors


## SETUP

Be sure to install the Acr.Ble nuget package in all of your main platform projects as well as your core/PCL project

[![NuGet](https://img.shields.io/nuget/v/Acr.Ble.svg?maxAge=2592000)](https://www.nuget.org/packages/Acr.Ble/)

**Android**

Add the following to your AndroidManifest.xml

```xml
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>

<!--this is necessary for Android v6+ to get the device name and address-->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
```

**iOS**

If you want to use background BLE periperhals, add the following to your Info.plist

```xml    
<array>
<string>bluetooth-central</string>
</array>

To add a description to the Bluetooth request message (on iOS 10 this is required!)
```xml    
<key>NSBluetoothPeripheralUsageDescription</key>
<string>YOUR CUSTOM MESSAGE</string>
```

**Windows**

Add to your app manifest file
```xml
<Capabilities>
    <Capability Name="internetClient" />
    <DeviceCapability Name="bluetooth" />
</Capabilities>
```

## HOW TO USE BASICS

```csharp

// discover some devices
BleAdapter.Current.Scan().Subscribe(scanResult => {});

// Once finding the device/scanresult you want
await scanResult.Device.Connect();

Device.WhenAnyCharacteristicDiscovered().Subscribe(characteristic => {
    // read, write, or subscribe to notifications here
    var bytes = await characteristic.Read();
    await characteristic.Write(bytes);

    characteristic.SubscribeToNotifications(bytes => {
    
    });
});

```

## DOCUMENTATION

* [Adapter](docs/adapter.md)
* [Device](docs/device.md)
* [Services](docs/services.md)
* [Characteristics](docs/characteristics.md)
* [Descriptors](docs/descriptors.md)
* Plugins
    * [Logging](docs/logging.md)
    * [Heart Rate](docs/heartrate.md)

## FAQ

Q. Why is everything reactive instead of events/async

> I wanted event streams as I was scanning devices.  I also wanted to throttle things like characteristic notification feeds.  Lastly, was the proper cleanup of events and resources.   

Q. Why are Device.Connect, Characteristic.Read, and Descriptor.Read observable when async would do just fine?

> True, but observables with RX are actually awaitable as well and far easier to chain into other things.

Q. Why have a Adapter.BackgroundScan with a service UUID?  This is not a problem on Android

> Also, true, but consistency is what I was aiming for.  iOS only allows you to scan in the background with a serviceUUID and on Android, I set the scanmode to low power.

Q. Why are devices cleared on a new scan?

> Some platforms yield a "new" device and therefore new hooks.  This was observed on some android devices.

Q. My characteristic read/writes/notifications are not working
> If you store your discovered characteristics in your own variables, make sure to refresh them with each (re)connect

{'fraction_non_alphanumeric': 0.09521829521829522, 'fraction_numerical': 0.0036036036036036037, 'mean_word_length': 4.567901234567901, 'pattern_counts': {'":': 0, '<': 34, '<?xml version=': 0, '>': 50, 'https://': 4, 'lorem ipsum': 0, 'www.': 2, 'xml': 10}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2292818', 'n_tokens_mistral': 2143, 'n_tokens_neox': 2027, 'n_words': 803}