share

ENGINEERING

5min read

Maintaining Open-Source RxAndroidBle Library (Readability)

The third part of the series about maintaining RxAndroidBle library deals with descriptive signatures. If you want to come back to the introductory article, you can find it here.

Descriptive signatures

At the beginning, the RxJava framework was in the 1.1.0. version, meaning that the only production-ready interface was the Observable. All good, except for one thing…

Observable is quite vague. It is possible that it will emit events indefinitely:

|-----o-----o-----o-----o-----o----->

It can also complete on its own after several emissions:

|-----o-----o-----o-----o-----|----->

Or emit just a single event:

|-----o----------------------------->

Single event and complete:

|-----o-|--------------------------->

Single event and error:

|-----o-----------------------x----->

Or even more… Either way, there are multiple behaviors that an Observable may demonstrate. The problem is that most of the users coming to use a library API often have little to no domain knowledge about what they are about to use. They usually don’t have any idea how the Observable acts either. The initial API of the library’s RxBleConnection used to look like this:

interface RxBleConnection {
    Observable<RxBleDeviceServices> discoverServices();
    Observable<byte[]> readCharacteristic(UUID characteristicUuid);
    Observable<byte[]> writeCharacteristic(UUID characteristicUuid, byte[] data);
    Observable<Observable<byte[]>> setupNotification(UUID characteristicUuid);
    Observable<Observable<byte[]>> setupIndication(UUID characteristicUuid);
    Observable<byte[]> readDescriptor(UUID serviceUuid, UUID characteristicUuid, UUID descriptorUuid);
    Observable<byte[]> writeDescriptor(UUID serviceUuid, UUID characteristicUuid, UUID descriptorUuid, byte[] data);
    Observable<Integer> readRssi();
}

At some point users asked for the clarification of the behavior, so the following table was added to the documentation:

Interface Function Number of values Completes
RxBleClient scanBleDevices()* Infinite false
RxBleClient observeStateChanges() Infinite** false**
RxBleDevice observeConnectionStateChanges() Infinite false
RxBleDevice establishConnection()* Single false
RxBleConnection discoverServices() Single true
RxBleConnection setupNotification()* Single false
RxBleConnection setupNotification() emitted Observable Infinite false
RxBleConnection setupIndication()* Single false
RxBleConnection setupIndication() emitted Observable Infinite false
RxBleConnection getCharacteristic() Single true
RxBleConnection readCharacteristic() Single true
RxBleConnection writeCharacteristic() Single true
RxBleConnection readDescriptor() Single true
RxBleConnection writeDescriptor() Single true
RxBleConnection readRssi() Single true
RxBleConnection requestMtu() Single true
RxBleConnection queue() User defined User defined
LongWriteOperationBuilder build() Single true

Definitely not the perfect solution. The problem lies in the fact that the table is available only in the documentation and Javadoc but it should be clear just by looking on the API. Fortunately, RxJava framework has matured and now has more interfaces than only the Observable:

  • Single — emits only a single event or an error
  • Completable — does not emit any values but completes or emits an error at some point in time
  • Maybe — may emit a single event or complete without emitting (and of course it can emit an error)

So, the new API that is under development will make the understanding easier by simply looking at the code:

interface Connection {
    Single<RxBleDeviceServices> discoverServices();
    Single<byte[]> readCharacteristic(UUID characteristicUuid);
    Completable writeCharacteristic(UUID characteristicUuid, byte[] data);
    Observable<Observable<byte[]>> setupNotification(UUID characteristicUuid);
    Observable<Observable<byte[]>> setupIndication(UUID characteristicUuid);
    Single<byte[]> readDescriptor(UUID serviceUuid, UUID characteristicUuid, UUID descriptorUuid);
    Completable writeDescriptor(UUID serviceUuid, UUID characteristicUuid, UUID descriptorUuid, byte[] data);
    Single<Integer> readRssi();
}

everywhere.jpg

One could see that there is a peculiar case of Observable<Observable<byte[]>> setupNotification(UUID characteristicUuid). That seems odd! And actually this API has a good explanation:

Making a characteristic to send notifications to the mobile device is (as most actions in BLE) asynchronous so it takes time to be finished. Additionally, the pool for characteristic notifications is fixed (max 4 on Android 4.3 / 7 on 4.4 / 15 on 5.0) and managing them could be done the same way as managing the RxBleConnection. All as long as the user is interested in (subscribed to) .setupNotification(), the notification is active and it is torn down as soon as the user unsubscribes. Additionally, when the notification is established, it is able to transmit an infinite amount of data—that is why the API has Observable<Observable<byte[]>> return type.

Wrap up: the User

It is very important to provide users with clear info. They need to know what they can achieve by using a particular library and what to expect from it. The abstraction they are about to touch should fit into what they already know and shouldn’t require learning new concepts. Concise API also helps users in understanding what they would get without the need of digging through the documentation.

Perspective: the Developer

We are creating abstractions and APIs for the users but we are not omniscent. This means that we sometimes need to iterate over what we have already published. The original API was not perfect for the user and we needed to introduce a better one. But the users are not happy with rewriting their code. It is better to give them time to change—and provide with something that comes in handy and is already well established in the industry.

Stay tuned for the next part about API development!

share


DarekSenior 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.: [0048795536436], 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.