share

ENGINEERING

5min read

RxAndroidBLE - your most powerful tool for Bluetooth Low Energy coding!

​Some time ago we published here, a tutorial on how to work with Bluetooth Low Energy in Android. As you might have noticed, the whole process required many (many!) asynchronous callbacks, handling different numeric statuses, threading knowledge and more. Because at Polidea, our customer’s products become more and more intelligent and connected it was natural for us to simplify all this code duplication and complexity.

​So we did it, and here it is! Let us introduce you to our new powerful toy, the RxAndroidBLE library. ​ RxAndroidBle is the painkiller for Android’s Bluetooth Low Energy headaches. It is backed with RxJava, it basically implements complicated APIs as handy reactive observables. Long story short, the library can: ​

  • Fancy asynchronous operations support (read, write, notifications)
  • Thread management in order to meet Android contracts
  • Connection and operation error handling, etc.

In the following post, we will give you tips to get started with RxAndroidBLE library. ​ ​

Including into the project

The library is available for your convenience as Maven dependency on Central. Depending on your build system choice you use either: ​

Maven

<dependency>
  <groupId>com.polidea.rxandroidble</groupId>
  <artifactId>rxandroidble</artifactId>
  <version>1.0.1</version>
  <type>aar</type>
</dependency>

or

Gradle

compile "com.polidea.rxandroidble:rxandroidble:1.0.1"

Obtaining the client

Your entry point to the library is the RxBleClient class. For connection and operation handling we require that single instance of the client is used per app. It’s a good idea to use some dependency injection like Dagger and it’s scoped components but it’s up to you. Simple singletons and Application based containers are alright to use as well. The client itself can be obtained by simply call to: ​

RxBleClient rxBleClient = RxBleClient.create(context);

Finding a device

Device discovery is very simple and handy. Scan lifecycle management is linked to the Observable lifecycle. It is safe to subscribe more subscribers to the same observable so you don’t have to worry if there are any scans already taking place, as long as they are initiated through the library. There are some future plans for more advanced filtering. ​ By default there is no filtering but you can pass single or many service UUIDs through the var-arg. You can also safely use your own 128-bit UUIDs as we handle the Android’s bug for you. ​

Subscription scanSubscription = rxBleClient.scanBleDevices()
	.subscribe(rxBleScanResult -> {
	    // Process scan result here.
	});

// When done, just unsubscribe.
scanSubscription.unsubscribe();

​ Note: It’s a good idea to chain it with the RxLifecycle. ​

Connecting to the device

In order to connect you will need the RxBleDevice instance. It can be taken from the scan result or created manually with a mac address of the Bluetooth device. All you need to do is to call establishConnection method and get the RxBleConnection, which is a handle, used to process BLE operations with a connected device. ​

String macAddress = "AA:BB:CC:DD:EE:FF";
RxBleDevice rxBleDevice = rxBleClient.getBleDevice(macAddress);
​
Subscription subscription = rxBleDevice.establishConnection(context, false) // <-- autoConnect flag
	.subscribe(rxBleConnection -> {
		// All GATT operations are done through the rxBleConnection.
	});

// When done... unsubscribe and forget about connection teardown :)
subscription.unsubscribe();

​ By default there can be only one connection call at time. Head to examples and the ConnectionSharingAdapter to learn how to share it. ​

Discovering services

Although it is not require to do it manually in order to read/write, you can always discover supported services with the following call. ​

rxBleDevice.establishConnection(this, false)
    .flatMap(RxBleConnection::discoverServices)
    .subscribe(RxBleDeviceServices discoveryResult -> {
    	// Process service discovery result on your own.
    });

Reading / writing to the device

Almost no BLE device is useful if it cannot be interacted. Once you are connected you can operate as presented below: ​

Read

device.establishConnection(context, false)
	.flatMap(rxBleConnection -> rxBleConnection.readCharacteristic(characteristicUUID))
	.subscribe(characteristicValue -> {
		// Read characteristic value.
	});

Write

device.establishConnection(context, false)
	.flatMap(rxBleConnection -> rxBleConnection.writeCharacteristic(characteristicUUID, bytesToWrite))
	.subscribe(characteristicValue -> {
		// Characteristic value confirmed.
	});

Multiple reads

 device.establishConnection(context, false)
    .flatMap(rxBleConnection -> Observable.combineLatest(
        rxBleConnection.readCharacteristic(firstUUID),
        rxBleConnection.readCharacteristic(secondUUID),
        YourModelCombiningTwoValues::new
    ))
	.subscribe(model -> {
	    // Process your model.
	});

Read and write combined

 device.establishConnection(context, false)
    .flatMap(rxBleConnection -> rxBleConnection.readCharacteristic(characteristicUuid)
	    .doOnNext(bytes -> {
	        // Process read data.
	    })
	    .flatMap(bytes -> rxBleConnection.writeCharacteristic(characteristicUuid, bytesToWrite))
	.subscribe(writeBytes -> {
		// Written data.
	});

You can also listen to change notifications

 device.establishConnection(context, false)
    .flatMap(rxBleConnection -> rxBleConnection.setupNotification(characteristicUuid))
    .doOnNext(notificationObservable -> {
    	// Notification has been set up
    })
    .flatMap(notificationObservable -> notificationObservable) // <-- Notification has been set up, now observe value changes.
    .subscribe(bytes -> {
    	// Given characteristic has been changes, here is the value.
    });

Closing connection

Do not worry about complex connection teardown. Disconnect, closing the GATT is managed for you. The only thing you need to do is to unsubscribe. As simple as that! ​

Conclusion

IoT is no longer a future but it is all over the place and Bluetooth programming became our reality. Fortunately thanks to reactive concepts it does not have to be a headache anymore. We believe that open source is a part of our mission so here we are, sharing our battlefield tested knowledge to you. For more great tutorials follow our blog and subscribe to our newsletter. Do not forget to check the repository on Github as new features are coming!

share


PawełSenior Software Engineer

LEARN MORE

Contact us if you have any questions regarding the article or just want to chat about technology, our services, job offers and more!

POLIDEA NEWSLETTER

Sign in and expect sharp insights, recommendations, ebooks and fascinating project stories delivered to your inbox

The controller of the personal data that you are about to provide in the above form will be Polidea sp. z o.o. with its registered office in Warsaw at ul. Przeskok 2, 00-032 Warsaw, KRS number: 0000330954, tel.: 0048 795 536 436, email: hello@polidea.com (“Polidea”). We will process your personal data based on our legitimate interest and/or your consent. Providing your personal data is not obligatory, but necessary for Polidea to respond to you in relation to your question and/or request. If you gave us consent to call you on the telephone, you may revoke the consent at any time by contacting Polidea via telephone or email. You can find detailed information about the processing of your personal data in relation to the above contact form, including your rights relating to the processing, HERE.

Data controller:

The controller of your personal data is Polidea sp. z o.o. with its registered office in Warsaw at ul. Przeskok 2, 00-032 Warsaw, KRS number: 0000330954, tel.: [0048795536436], email: [hello@polidea.com] (“Polidea”)

Purpose and legal bases for processing:

 

Used abbreviations:

GDPR – Regulation (EU) 2016/679 of the European Parliament and of the Council of 27 April 2016
on the protection of natural persons with regard to the processing of personal data and on the free movement
of such data, and repealing Directive 95/46/EC (General Data Protection Regulation)

ARES – Polish Act on Rendering Electronic Services dated 18 July 2002

TL – Polish Telecommunications Law dated 16 July 2004

1)        sending to the given email address a newsletter including information on Polidea’s new projects, products, services, organised events and/or general insights from the mobile app business world |art. 6.1 a) GDPR, art. 10.2 ARES and art. 172.1 TL (upon your consent)

Personal data:name, email address

2)       statistical, analytical and reporting purposes |art. 6. 1 f) GDPR (based on legitimate interests pursued by Polidea, consisting in analysing the way our services are used and adjusting them to our clients’ needs, as well as developing new services)

Personal data:name, email address

Withdrawal of consent:

You may withdraw your consent to process your personal data at any time.

Withdrawal of the consent is possible solely in the scope of processing performed based on the consent. Polidea is authorised to process your personal data after you withdraw your consent if it has another legal basis for the processing, for the purposes covered by that legal basis.

Categories of recipients:

Your personal data may be shared with:

1)       authorised employees and/or contractors of Polidea

2)       persons or entities providing particular services to Polidea (accounting, legal, IT, marketing and advertising services) – in the scope required for those persons or entities to provide those services to Polidea

 

Retention period:

1)       For the purpose of sending newsletter to the given email address – for as long as the relevant consent is not withdrawn

2)       For statistical, analytical and reporting purposes – for as long as the relevant consent is not withdrawn

Your rights:

 

Used abbreviation:

GDPR – Regulation (EU) 2016/679 of the European Parliament and of the Council of 27 April 2016
on the protection of natural persons with regard to the processing of personal data and on the free movement
of such data, and repealing Directive 95/46/EC (General Data Protection Regulation)

According to GDPR, you have the following rights relating to the processing of your personal data, exercised by contacting Polidea via [e-mail, phone].

1)       to access to your personal data (art. 15 GDPR) by requesting sharing and/or sending a copy of all your personal data processed by Polidea

2)       to request rectification of inaccurate personal data
(art. 16 GDPR) by indicating the data requiring rectification

3)       to request erasure of your persona data (art. 17 GDPR); Polidea has the rights to refuse erasing the personal data in specific circumstances provided by law

4)       to request restriction of processing of your personal data (art. 18 GDPR) by indicating the data which should be restricted

5)       to move your personal data (art. 20 GDPR) by requesting preparation and transfer by Polidea of the personal data that you provided to Polidea to you or another controller in a structured, commonly used machine-readable format

6)       to object to processing your personal data conducted based on art. 6.1 e) or f) GDPR, on grounds relating to your particular situation (art. 21 GDPR)

7)       to lodge a complaint with a supervisory authority,
in particular in the EU member state of your habitual residence, place of work or place of the alleged infringement if you consider that the processing
of personal data relating to you infringes the GDPR
(art. 77.1 GDPR)

No obligation to provide data:

Providing your personal data is not obligatory, but necessary for Polidea to provide you the newsletter service

Refusal to provide the above data will result in inability to receive the newsletter service.

Profiling

In the process of providing the newsletter service, we make decisions in an automated way, including profiling, based on the data you provide.

 

“Profiling” means automated processing of personal data consisting of the use of your personal data to evaluate certain personal aspects relating to you, in particular to analyze or predict aspects concerning your personal preferences and interests.

 

The automated decisions are taken based on the analysis of clicked and viewed content. They affect the targeting of specific newsletter content to selected users registered to receive the newsletter service, based on the anticipated interests of the recipient.