Xamarin and MvvMCross plugin for accessing the bluetooth functionality. The plugin is based on the BLE implementation of Monkey Robotics.

Important Note: With the term "vanilla" we mean the non MvvmCross/pure Xamarin version. You can use it without MvvmCross, if you download the vanilla package.

Vanilla

// stable
Install-Package Plugin.BLE
// or pre-release
Install-Package Plugin.BLE -Pre


MvvmCross

Install-Package MvvmCross.Plugin.BLE
// or (recommended for now until we release 1.0.0 stable)
Install-Package MvvmCross.Plugin.BLE -Pre

 

Android

Add these permissions to AndroidManifest.xml. For Marshmallow, please follow Requesting Runtime Permissions in Android Marshmallow

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

Add this line to your manifest if you want to declare that your app is available to BLE-capable devices only:

<uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/>

We provide a sample Xamarin.Forms app, that is a basic bluetooth LE scanner. With this app, it's possible to

• check the ble status
• discover devices
• connect/disconnect
• discover the services
• discover the characteristics
• see characteristic details
• read/write and register for notifications of a characteristic

Have a look at the code and use it as starting point to learn about the plugin and play around with it.

Vanilla

var ble = CrossBluetoothLE.Current;
var adapter = CrossBluetoothLE.Current.Adapter;

MvvmCross

The MvvmCross plugin registers IBluetoothLE and IAdapter as lazy initialized singletons. You can resolve/inject them as any other MvvmCross service. You don't have to resolve/inject both. It depends on your use case.

var ble = Mvx.Resolve<IBluetoothLE>();
var adapter = Mvx.Resolve<IAdapter>();

or

MyViewModel(IBluetoothLE ble, IAdapter adapter)
{
    this.ble = ble;
    this.adapter = adapter;
}

var state = ble.State;

You can also listen for State changes. So you can react if the user turns on/off bluetooth on you smartphone.

ble.StateChanged += (s, e) => 
{
    Debug.WriteLine($"The bluetooth state changed to {e.NewState}");
};

adapter.DeviceDiscovered += (s,a) => deviceList.Add(a.Device);
await adapter.StartScanningForDevicesAsync();

ConnectToDeviceAync returns a Task that finishes if the device has been connected successful. Otherwise a DeviceConnectionException gets thrown.

try 
{
    await _adapter.ConnectToDeviceAync(device);
}
catch(DeviceConnectionException e)
{
    // ... could not connect to device
}

var services = await connectedDevice.GetServicesAsync();

or get a specific service:

var service = await connectedDevice.GetServiceAsync(Guid.Parse("ffe0ecd2-3d16-4f8d-90de-e89e7fc396a5"));

var characteristics = await service.GetCharacteristicsAsync();

or get a specific characteristic:

var characteristic = await service.GetCharacteristicAsync(Guid.Parse("d8de624e-140f-4a22-8594-e2216b84a5f2"));

var bytes = await characteristic.ReadAsync();

await characteristic.WriteAsync(bytes);

characteristic.ValueUpdated += (o, args) =>
{
    var bytes = args.Characteristic.Value;
};

characteristic.StartUpdates();

• Surround Async API calls in try-catch blocks. Most BLE calls can/will throw an exception in cetain cases, this is especiialy true for Android. We will try to update the xml doc to reflect this.

    try
    {
        await _adapter.ConnectToDeviceAsync(device);
    }
    catch(DeviceConnectionException ex)
    {
        //specific
    }
    catch(Exception ex)
    {
        //generic
    }

• Avoid caching of Characteristic or Service instances between connection sessions. This includes saving a reference to them in you class etc. After a device has been disconnected all Service & Characteristic instances become invalid. Allways use GetServiceAsync and GetCharacteristicAsync to get a valid instance.

• Scanning: Avoid performing ble device operations like Connect, Read, Write etc while scanning for devices. Scanning is battery-intensive.
  • try to stop scanning before performint device operations
  • try to stop scanning as soon as you find the desired device
  • never scan on a loop, and set a time limit on your scan

• Characteristic Properties
• Changelog

• Android Bluetooth LE guideline
• iOS CoreBluetooth Best Practices
• MvvmCross
• Monkey Robotics

Apache 2.0