HQ Trivia needs no introduction. It has had its ups and downs but one cannot deny the fact that when released, it was a completely new type of experience on our mobile devices and it took the market by storm notching 10 million downloads on Android and iOS devices.

How HQ Trivia works?

HQ Trivia has been all about questions and answers. And the question you may be asking yourself right now is how it all looks like under the hood?

There are a lot of moving parts inside the app’s engine, but one that plays the most crucial role is the producer panel that controls all sorts of stuff happening during the game.

It all starts with the creation of the new game, selecting what type of game it should be, and scheduling when should it happen.

The next step is, of course, adding a set of questions for which you can select a category, add possible answers, and then select which one of them is the correct answer. But that’s just the beginning.

Some questions, as you may know, have videos, photos, or audio files attached to them, and this is the place where the producer can add all of those things to the questions.

Then there is also a matter of not all questions being created equal from a reward standpoint.

After some questions, there are checkpoints that allow players to finish the game and get some bonuses or continue if they’re feeling lucky. This is also something that will be set during the process of creating questions.

The producer can also specify how many coins a specific checkpoint offers to the players. He basically designs the whole in-game reward/gamification system as he plunges in more questions for the day ahead.

Another feature that is a part of the process of game creation is adding gift drops. They won’t be appearing in every game, but have to be prepared and attached to specific questions in advance.

The challenges of HQ Trivia mechanics

As you can see there is a lot happening before the game even begins, but what happens when questions start to pop up on your screen. How do they even get there? Are they being sent to devices in advance? Or maybe there’s a way to take a look at them before they are asked?

It’s not that simple. It turns out the only safe haven for trivia questions to queue before they appear on players’ screens is the backend.

HQ knows this very well and that’s why they send each question only when the time is right, which is when the question is being asked. The way it’s being done is through socket connections which keep each player connected to the server for the entire duration of the game.

Sockets vs REST API

Let’s have a quick look at what sockets are and how they differ from REST APIs, which are used by most apps on our phones.

REST APIs are interfaces that allow us to get specific data from the server. It may be weather, recipes, or photos on Instagram, but the way the communication between devices works is the same: the app asks the server for some data, the server then answers by sending the requested data and the connection is closed.

You can read more about REST API in our article on integrating Google Fit with an Android app.

Sockets on the other hand keep the connection between the app and the server alive for as long as it’s needed, and this allows messages to go back and forth with no need to re-establish the connection.

Those messages, like in HQ Trivia’s example, may contain different kinds of data. For instance, when the presenter is ready to ask the new question, the producer simply clicks the “Start question” button which causes the server to send a message containing said question to all of the players, who then see the question appearing on their screens. Such a message doesn't contain the answer to the question, in case you were wondering, which makes this type of connection the safest for HQ Trivia's purpose.

This is how it works in practice:

1. 10 seconds after a question pops up on the screen, all the players are given the answer.

2. The results are being sent in the exact same way as questions, using a socket connection.

3. The producer selects the option to send the question summary which triggers the server to send each participating player a message with data such as:

• What was the correct answer?
• Was a player correct or not?
• How many points the correct answer has awarded the player?
• How many players selected particular answers?
• How many players are advancing to the next question?
• How many were eliminated? 

4. In the event of a player being wrong, the message will also contain the info whether the player should be saved by an extra life or a free pass or if he or she was eliminated.

Conclusion

I hope you enjoyed this behind the scenes of how HQ Trivia creates its quizzes. And hopefully, learning about it will help you come up with your idea for the next big thing.

If that’s the case, then we - at intent - will be happy to help you bring the product to life, using our extensive knowledge and experience. Don’t hesitate to contact us.

With the influx of health-conscious customers, ensuring that your fitness product delivers a holistic, integrated service is growing ever more important.

Every creator of a health-oriented application is practically obliged to connect it to a fitness service to facilitate the seamless transfer of data between various (often competing) applications. In the Android world, that solution is the Google Fit API.

REST API vs SDK

As is standard for Google’s server APIs, there are two ways to communicate with the server:

• classic REST API
• through SDK, which connects to the server on its own

These solutions do not share a code base, so for example, slightly different fitness activity (as in “rowing” or “kayaking”, not MainActivity) types are available:

Google Fit activity types list

Google APIs for Android documentation list

(Note the lack of “Guided breathing” activity type for SDK.)

The choice between the two mainly depends on the level of technical sophistication of the SDK - if it’s advanced enough, well maintained, and documented, it is almost always more convenient to use than raw REST endpoints.

However, some optimization techniques, especially in using cached data, might mean that the data provided by the SDK is less reliable than acquired directly. At least until recently, this was the case with the Fit APIs (plural), with its Local Storage (described below), so that is something worth testing before deciding on an approach. 

Local Storage vs Fit server

In order to improve performance and reduce server load, most API calls do not connect to the Google Fit server, using the local store for a reading and writing data instead. Unless explicitly demanded, data propagation happens only every few hours. This can lead to confusion if, for example, you expect the changed data to be immediately available on another device. On the other hand, this does make the data accessible to any local Fit-integrated applications even without a network. 

This is particularly important to keep in mind when testing the application since with data sync not happening immediately, false negatives can be reported.

On the other hand, all local changes will be available immediately, even if the device doesn’t have a network connection at the moment. This is a great solution performance-wise, but quite confusing (and currently under-documented) during testing. With that, of great help will be the Playground:

Oauth 2.0 Playground

One feature of Google APIs I personally found particularly useful was the possibility of seamless online testing of its REST APIs. Not just for Fit - the list is astonishingly long and only keeps growing. With real data underneath, the Playground allows for quick verification of the stored data, before writing a single line of code. 

Recognizing custom activities

As is often the case, an application might need to separate the Fit activities created by it from the remaining activities. There are two approaches to achieve that:

• using the app package name
• using a unique activity session identifier pattern

The first one is straightforward - simply call setAppPackageName when creating an activity, and verify that value when checking the downloaded activity’s type. The obvious downside is that this value will be identical for all activities an app creates, so if a more sophisticated separation is required, the package name alone is not enough. That’s when the naming pattern comes in - set the session identifier according to the chosen pattern and then verify, like below:

private fun activityIsCustomActivity(session: Session): Boolean {
   return session.activity == FitnessActivities.KITESURFING
    && CUSTOM_SESSION_KEY_REGEX.matches(session.identifier)
}

Data type permissions

In times when user’s privacy is an ever-growing concern, it is increasingly important to guarantee that an application will know about the user only as much (or as little) as it is required for it to function. It is entirely feasible for a user to wish to allow an app’s access to his basic biological data, but withhold some more sensitive data such as heart rate. In response, Fit allows very detailed compartmentalization of the accessed data. 

fun syncOptions(): GoogleSignInOptionsExtension =  FitnessOptions.builder()
             .addDataType(DataType.TYPE_ACTIVITY_SEGMENT, FitnessOptions.ACCESS_READ)
             .addDataType(DataType.TYPE_ACTIVITY_SEGMENT, FitnessOptions.ACCESS_WRITE) 
 

                   .addDataType(DataType.TYPE_HEART_RATE_BPM, FitnessOptions.ACCESS_READ)

 
             .addDataType(DataType.TYPE_HEART_RATE_BPM, FitnessOptions.ACCESS_WRITE)

 
              .addDataType(DataType.TYPE_HEIGHT, FitnessOptions.ACCESS_READ)
             .addDataType(DataType.TYPE_HEIGHT, FitnessOptions.ACCESS_WRITE)
             .addDataType(DataType.TYPE_WEIGHT, FitnessOptions.ACCESS_READ)
             .addDataType(DataType.TYPE_WEIGHT, FitnessOptions.ACCESS_WRITE)
             .build()

 

List of Google Fit datatypes.

Read data - example

For a simple example, let’s read the user’s height data from the server. First, we need a working Google Account object:

val signInAccount = GoogleSignIn.getLastSignedInAccount(context)

If the signInAccount value is not null, the app is authenticated, but not yet authorized. We need to request the permission to read/write data of the required data types.

fun syncOptions(): GoogleSignInOptionsExtension = FitnessOptions.builder()
              .addDataType(DataType.TYPE_HEIGHT, FitnessOptions.ACCESS_READ)
             .build()

val requestCode = 123
GoogleSignIn.requestPermissions(activity, requestCode, googleSignInAccount, syncOptions())

The SDK will display a permissions dialog to the user. The result of the user’s action will be returned in a standard onActivityResult callback. To use the SDK later, we only need to check if the permissions are still granted (as in they have not been revoked)

val hasSyncPermission = GoogleSignIn.hasPermissions(signInAccount, syncOptions())

If permitted, it is finally time to read the data from the server. We only need the latest height data, so the limit will be set to 1. We want to make sure that we get data from the server and not just from the local storage, so we set the “enableServerQueries” flag. And of course with the full-time limit, to get even the oldest data.

fun readPersonalProperty(
signInAccount: GoogleSignInAccount, dataType: DataType): Task<DataReadResponse> =
        Fitness.getHistoryClient(context, signInAccount)
                .readData(DataReadRequest.Builder()
                        .read(dataType)
                        .setTimeRange(1L, Instant.now().epochSecond, TimeUnit.SECONDS)
                        .setLimit(1)
                        .enableServerQueries()
                        .build())

readPersonalProperty(signInAccount, DataType.TYPE_HEIGHT)

Sensors data

Of all the APIs that compose the full fitness solution, Sensors Api is of particular importance. For all health applications that do not have a backing hardware device (like a bracelet or ring), the smartphone will be the source of all new data. 

In general, sensors on Android devices belong to three categories:

• Motion sensors - measure acceleration and rotation along three axes
• Environmental sensors - measure i.e. light, temperature, ambiance or air pressure
• Position sensors - measure the physical position of a device

The availability of sensor data depends on the presence of sensors of different types inside the device, hence the need to verify that in your application, before querying for the data. Therefore, a fallback mechanism needs to be implemented to provide a satisfying user experience even if most sensors are absent or malfunctioning.

Most of these sensors can have varying accuracy, of which the application will be notified by the onAccuracyChanged callback - particularly important for uses that require fine-grained data.

Photo by Ketut Subiyanto from Pexels

Arduino has been around for years, and you've probably heard the term. It is an open-source electronics platform that allows developers to connect hardware with software easily. The popularity of Arduino is vast because it offers a simple and accessible user experience. As an iOS developer, I wanted to play around with this platform, so I've built a toy car that can be controlled with a mobile app. Read this article to find out how I did it.

Project outline

There are two key components in this project:

• Arduino based toy car.
• iOS application for controlling it (connected via Bluetooth Low Energy)

You can see the final result in the picture below. On the left side is an iOS application, on the right side, a toy car.

iOS application

Let’s start with the car controller (iOS application). In this article, I won't go into details about iOS application implementation. I will describe briefly how it works from the user perspective.

The application connects to Arduino using BLE (Bluetooth Low Energy).

After launching it, the device discovery screen is displayed. The application starts searching for Bluetooth devices automatically and displays devices with matching service UUID. User can restart device discovery by pressing the Search button (in case of network errors). The application can automatically connect to the last selected device by checking the Auto-connect checkbox.

The controller screen has four controls:

• Drive forward and backward (bottom left corner)
• Turn left and right (bottom right corner)
• Change gear (buttons 1-5)
• Headlights on/off (top right corner)

It shows connection status in the top right corner. By pressing the back button, the application disconnects from the car and navigates back to the device discovery screen.

Toy car

The toy car was built using mechanical parts from an old toy: chassis with wheels and 2 DC motors (one for driving, the other one for turning).

The custom components are Arduino, DC motor controller, Bluetooth, LEDs.

How to build it?

Hardware components

1. Arduino Due

Arduino is an open-source electronics platform based on easy-to-use hardware and software. It can be used for prototyping hardware devices. Implementation is very fast and in a few days, we can have a working device for real-world testing.

It is responsible for controlling hardware components (motors, sensors, LEDs), Bluetooth communication, and handling iOS application commands.

Arduino Due main characteristics:

• 32-bit ARM core microcontroller (84 MHz clock)
• 54 digital input/output pins (of which 12 can be used as PWM outputs)
• 12 analog inputs
• 4 UARTs (hardware serial ports)
• Board runs at 3.3V (unlike most Arduino boards that run at 5V)
• Compatible with all Arduino shields that work at 3.3V

2. Waveshare Motor Control Shield L293D

It is capable of driving 4 DC motors or 2 stepper motors at one time.

When using an external power supply of 9V it allows you to adjust the speed and direction of the motors with current consumption up to 600mA (1.2A peak) and a voltage between 1.25V - 6.45V.

Toy car has two DC motors: the first one is used for driving, the second one for turning.

3. Bluetooth module HM-10

HM-10 is a Bluetooth 4.0 module. It works with voltage from 3.3V to 5V, it communicates over a serial UART interface (RX, TX pins). The maximum transmitter power is +6 dBm, the receiver sensitivity is -23 dBm.

4. Two DC motors

DC motor for driving (operation Voltage of 3-6V, free-run current of 200mA).

Mini DC motor for turning (operation Voltage of 3-6V, free-run current of 30mA).

Choose your DC motors depending on the weight of the car.

5. LED lights

4 x red LEDs for turn signals

4 x white LEDs for headlights

6. Other components

• 8 resistors 220Ω
• Potentiometer 10kΩ
• 6 AA batteries (1.5V)
• Wires
• Breadboard
• Old toy car chassis

How to connect everything?

The photo below shows how components are connected. It doesn’t look pretty, but I assure you that it works 🙂

And here is a schematic diagram:

Let’s examine each and every component individually.

1. Bluetooth and the main application loop

One of the biggest advantages of Arduino is that there is a vast set of ready to use components and libraries available. They are very easy to use and don’t require us to write much code. They are named Shields. In this project, I used a Bluetooth Module and a DC Motor Control Shield. 

Let’s start with the Bluetooth module first. It communicates with the Arduino board using the Serial port.

Connect Bluetooth module HM-10 pins to Arduino board:

• VCC > VCC (5V or 3.3V)
• GND > GND
• RX > TX3
• TX > RX3

Main application setup

Define a helper macro named HC06 that points to a Serial3. configureBle() method starts Bluetooth connection.

#define HC06 Serial3

void configureBle() {
  HC06.setTimeout(100);
  HC06.begin(9600);
}

Define Bluetooth commands for controlling the toy car. iOS application sends commands to the Arduino. Currently, the application supports the following commands: drive, turn on headlights, change gear, turn.

Command length is 3 bytes.

First byte is a command code defined as an enum BleApiCommand.

Second byte is an additional parameter, depending on the command code:

• cmdDrive - speed: 0-127 (drive backwards), 127 (stop), 128-255 (drive forward).
• cmdHeadlights - 1 (turn headlights on), 0 (turn headlights off).
• cmdGear - gear integer between 1-5.
• cmdTurn - turn angle: 0-126 (left), 127 (straight), 128-255 (right).

Third byte is a command terminator 0x0f.

const int commandTerminator = 0x0f;
const int commandLength = 3;

enum BleApiCommand {
    cmdDrive = 0x23,
    cmdHeadlights = 0x24,
    cmdGear = 0x25,
    cmdTurn = 0x40
};

Main application setup method.

void setup() {
    configureLightsPins();
    configureMotorPins();
    configureBle();
}

Main application loop

Main application loop responsibilities:

• Read the Bluetooth command. If it is valid, invoke a handleCommand() method. It supports the following commands: drive, turn headlights on and off, change gear, turn.
• Turn signals work automatically when car turns, it is handled inside a turnSignalControllerTick() method.
• handleTurn() method positions front wheels to the given angle.
• stopIfDisconnected() stop car if controller is disconnected.

void loop() {
    int tickTime = millis();
    // Command loop
    while(HC06.available()) {
        byte buffer[commandLength];
        int size = HC06.readBytes(buffer, commandLength);
        if (size != commandLength) {
            continue;
        }
        lastCommandTimestamp = tickTime;
        handleCommand(buffer);
    }
    handleTurn();
    turnSignalControllerTick(tickTime);
    stopIfDisconnected(tickTime);
}

Handling commands

Extract command code and parameter, then handle each command in a separate method.

void handleCommand(byte data[]) {
    byte code = data[0];
    byte param = data[1];
    byte terminator = data[2];
    if (terminator != commandTerminator) {
        return;
    }
    switch (code) {
        case cmdHeadlights: {
            bool on = param == 0x02;
            setHeadlights(on);
            break;
        }
        case cmdGear: {
            setGear(param);
            break;
        }
        case cmdTurn: {
            turnWheels(param);
            break;
        }
        case cmdDrive: {
            drive(param);
            break;
        }
    }
}

2. Headlights and turn signals

Headlights

Headlights (white LEDs) can be turned on and off manually by the user using a button in the top-right corner of an iOS application.

 Connect each LED to a separate digital PIN through a resistor (220Ω) as shown in the diagram above.

Declare 4 headlights and 4 turn signals pins as constants and set their mode to OUTPUT.

const int pinHeadlightsRight1 = 22; // Remaining headlights pin numbers: 24, 26, 28
const int pinTurnSignalLeftFront = 31; // Remaining turn signals pin numbers: 33, 35, 37
void configureLightsPins() {
    pinMode(pinHeadlightsRight1, OUTPUT);
    pinMode(pinTurnSignalLeftFront, OUTPUT);
    ...
}

void setHeadlights(bool on) {
  int value = on ? HIGH : LOW;
  digitalWrite(pinHeadlightsRight1, value);
  digitalWrite(pinHeadlightsRight2, value);
  digitalWrite(pinHeadlightsLeft1, value);
  digitalWrite(pinHeadlightsLeft2, value);
}

Turn signals

Turn signals (red LEDs) work automatically - they blink every 0.5 seconds when the car is turning. They work in four modes: disabled, blink left, blink right, blink both sides.

Define mode as an enum and tick interval as constant.

Use turnSignalControllerSetMode() method to change the blinking mode.

enum Modes {
    idle = 0,
    blinkLeft = 1,
    blinkRight = 2,
    blinkBoth = 3
};

const int tickInterval = 500; // milliseconds
int lastTickTimestamp = 0;
int mode = idle;
bool ledOn = false;

void turnSignalControllerSetMode(int newMode) {
    if (newMode == mode) {
      return;
    }
    mode = (Modes)newMode;
    lastTickTimestamp = 0;
    updateState();
}

turnSignalControllerTick() method is called from the main application loop. lastTickTimestamp stores the last timestamp (number of milliseconds passed since the Arduino board began running the current program) and compares it with the current timestamp. The result is a timer with a 500ms interval.

void turnSignalControllerTick(int currentTimestamp) {
    if (mode == idle) { return; }
    if ((currentTimestamp - lastTickTimestamp) > tickInterval) {
      lastTickTimestamp = currentTimestamp;
      updateState();
    }
}

Method updateState() turns LEDs on and off depending on the current mode.

void updateState() {
  if (mode == idle) {
    ledOn = false;
  } else {
    ledOn = !ledOn;
  }
  int value = ledOn ? HIGH : LOW;
  switch (mode) {
  case idle:
  case blinkBoth:
    digitalWrite(pinTurnSignalLeftFront, value);
    digitalWrite(pinTurnSignalLeftRear, value);
    digitalWrite(pinTurnSignalRightFront, value);
    digitalWrite(pinTurnSignalRightRear, value);
    break;
  case blinkLeft:
    digitalWrite(pinTurnSignalLeftFront, value);
    digitalWrite(pinTurnSignalLeftRear, value);
    digitalWrite(pinTurnSignalRightFront, LOW);
    digitalWrite(pinTurnSignalRightRear, LOW);
    break;
  case blinkRight:
    digitalWrite(pinTurnSignalLeftFront, LOW);
    digitalWrite(pinTurnSignalLeftRear, LOW);
    digitalWrite(pinTurnSignalRightFront, value);
    digitalWrite(pinTurnSignalRightRear, value);
    break;
  }

3. Driving

Connect DC motors to the Motor Control Shield L293D:

• DC motor for driving to M3 interface.
• DC motor for turning to M4 interface.

Define and configure DC the motor pins

const int pinMotorDrive_dir1 = 8;
const int pinMotorDrive_dir2 = 7;
const int pinMotorDriveSpeed_pwm = 10;
const int pinMotorTurn_dir1 = 12;
const int pinMotorTurn_dir2 = 13;
const int pinMotorTurnSpeed_pwm = 11;

void configureMotorPins() {
    pinMode(pinMotorDrive_dir1, OUTPUT);
    pinMode(pinMotorDrive_dir2, OUTPUT);
    pinMode(pinMotorDriveSpeed_pwm, OUTPUT);
    pinMode(pinMotorTurn_dir1, OUTPUT);
    pinMode(pinMotorTurn_dir2, OUTPUT);
    pinMode(pinMotorTurnSpeed_pwm, OUTPUT);
    digitalWrite(pinMotorDrive_dir1, 1); // set forward direction
    digitalWrite(pinMotorDrive_dir2, 0); // set forward direction
    digitalWrite(pinMotorDriveSpeed_pwm, HIGH); // set to high to enable the L293 driver chip
    analogWrite(pinMotorDriveSpeed_pwm, 0); // set speed to 0
    digitalWrite(pinMotorTurn_dir1, 1); // set forward direction
    digitalWrite(pinMotorTurn_dir2, 0); // set forward direction
    digitalWrite(pinMotorTurnSpeed_pwm, HIGH);  // set to high to enable the L293 driver chip
    analogWrite(pinMotorTurnSpeed_pwm, 0);  // set speed to 0
}

Handle the drive command

Speed parameter (0-127 - drive backwards, 127 - stop, 128-255 - drive forward) must be converted into a speed (0-255) and direction. Choose the minimum speed/voltage depending on the car weight and DC motor parameters.

void drive(byte value) {
    int minSpeedValue = 100;
    int maxSpeedValue = 255;  
    if (value < 127) { // backwards
        digitalWrite(pinMotorDrive_dir1, 0);
        digitalWrite(pinMotorDrive_dir2, 1);
        int speedValue = minSpeedValue + (maxSpeedValue - minSpeedValue) * (127 - value) / 127;
        analogWrite(pinMotorDriveSpeed_pwm, speedValue);
    } else if (value > 127) { // forward
          digitalWrite(pinMotorDrive_dir1, 1);
          digitalWrite(pinMotorDrive_dir2, 0);
          int speedValue = minSpeedValue + (maxSpeedValue - minSpeedValue) * (value - 127) / 127;
         analogWrite(pinMotorDriveSpeed_pwm, speedValue);
    } else { // 127 stop
          digitalWrite(pinMotorDrive_dir1, 1);
          digitalWrite(pinMotorDrive_dir2, 0);
          analogWrite(pinMotorDriveSpeed_pwm, 0);
    }
}

4. Turning

Read current front wheels angle using a potentiometer

Connect potentiometer pins to the board:

• First outer pin to the ground
• Second outer pin to 5V
• Middle pin to the Arduino analog pin number A0

const int pinPotentiometer = A0;

int readPotentiometer() {
    int sensorValue = analogRead(pinPotentiometer);
    return sensorValue;
}

Convert the target angle

Convert target angle received from an iPhone (0-255) to integer (0-1024) in order to compare it with the potentiometer reading.

void turnWheels(byte value) {
    int minLeft = 300; // it means that the wheels are turned all the way to the left
    int maxRight = 900; // wheels turned all the way to the right
    int center = 600; // wheels are straight
    if (value < 127) { // turn left
        turnSignalControllerSetMode(1);
        float factor = ((float)value)/127.0;
        targetTurnValue = minLeft + factor * (center - minLeft);
    } else if (value == 127) { // straight
          turnSignalControllerSetMode(0);
          targetTurnValue = center;
      } else if (value > 127) { // turn right
          turnSignalControllerSetMode(2);
          float factor = ((float)value - 127.0) / 128.0;
          targetTurnValue = center + 1 + factor * (maxRight - center - 1);

      }

}

Turn wheels

Method handleTurn() does a few things:

• Reads the current wheels angle using the potentiometer. analogRead() returns integer value between 0-1024 which represents an angle.

• Calculates which direction to turn the wheels to - left, right, or stop when the angle is reached. 
• Starts/stops turn signals.

Choose the speed/voltage depending on the DC motor parameters.

  void handleTurn() {
    int sensorValue = readPotentiometer();
    const int tolerance = 20;
    const int speed = 130;
    if (abs(sensorValue - targetTurnValue) < tolerance) {
        // value reached, stop motor
        analogWrite(pinMotorTurnSpeed_pwm, 0);
    } else if (sensorValue > targetTurnValue) {
        // turn left
        digitalWrite(pinMotorTurn_dir1, 0);
        digitalWrite(pinMotorTurn_dir2, 1);
        analogWrite(pinMotorTurnSpeed_pwm, speed);
    } else if (sensorValue < targetTurnValue) {
        // turn right
        digitalWrite(pinMotorTurn_dir1, 1);
        digitalWrite(pinMotorTurn_dir2, 0);
        analogWrite(pinMotorTurnSpeed_pwm, speed);
    }
}

That’s pretty much everything. I hope you enjoyed this article and you will build your toy car!

I recently had an opportunity to work on adapting a media application to Android Automotive OS. This was challenging for unusual reasons, which I’ll try to outline in the rest of this article. First, though I’ll try to explain what Android Automotive OS is and how it is different from Android Auto.

Android Automotive vs Android Auto

The most significant difference is that Android Automotive is an operating system running directly on your car’s infotainment hardware, while Android Auto is an application projected from smartphone to Head Unit. This means applications run directly on Automotive without connecting your smartphone to it.

If you had an opportunity to use Android Auto, you might be aware of its limitations when it comes to supported application types - only media, messaging and navigation apps are available. Initially Automotive will support exactly the same application types, but Google already announced plans to extend this. 

On a side-note, currently, it’s possible to run any Android app on Automotive by installing it via ADB. This shouldn’t be a surprise, because Automotive is nothing more than modified Android OS, but it also raises some questions about types of restrictions Google will impose to limit this on actual infotainment systems in the future.

Coming back to the topic, because with Android Automotive your smartphone is out of the picture, some things that were previously managed by your mobile device will have to be done directly on the Head Unit. For instance, you will have to add sign in and settings screens to the app running on HU. The same goes for managing user permissions and requesting them from the user and showing notifications - this will have to be done directly by an app running on Automotive.

Automotive release roadmap

Google revealed Android Automotive OS in March 2017 and since then few car manufacturers officially announced adapting Automotive to their infotainment systems. The first one was Volvo in 2018 with their Polestar 2. So far it looks like they are going to meet their 2020 release schedule. If you are interested in trying it out, you can find the Polestar 2 emulator in the stable Android Studio release.

Next was Renault-Nissan-Mitsubishi Alliance in September 2018. At first, 12 car models will come equipped with Automotive, and sales are planned to start in 2021. Alliance predicts at least 14 million sales by the end of 2022.

We then had to wait a full year for the next announcement, which came from General Motors in September 2019. There is not much information available here, other than the known release date planned for 2021. General Motors and Renault-Nissan-Mitsubishi Alliance didn’t provide any official emulator yet to test your apps on.

It’s hard to measure how big will be the interest in cars equipped with Automotive. Unfortunately, I wasn’t able to find the usage statistics of Android Auto, so the only data we can refer to is sales figures. The only information I found on this topic is a study done by Canalys in 2018. According to their data, 46% of cars sold in Europe and 52% of cars sold in the USA in Q1 2018 came with Head Unit that supports Android Auto and/or Apple CarPlay. This gives a total of 8.4 million new cars in the first quarter of 2018 alone. Now, it’s not possible to tell what percentage of drivers actually use those capabilities, but the market is potentially quite big.

It’s difficult to estimate current Android Auto usage for one more reason. There are lots of radios, which you can find on e-commerce websites, that offer Android Auto and Apple CarPlay capabilities. Those sales are not included in Canalys’ study, as it covers only new car sales. On the other hand, people who use this hardware in their 30 years old Audi 100 might not be the target audience of brand new cars with Automotive on-board.

Adapting existing app to Automotive

I can only speak from my experience with media applications. It already had integration with Android Auto in place, which made lots of work much easier. We worked on this for a few months in a team of 3 developers, 1 QA engineer, product owners, and with assistance from the UI design team. 

When it comes to UI, Google gave us mock-ups of sign in flow and settings screen. Those were then adjusted by designers to fit different, known at that time, automotive screen configurations and to match the brand. I’m sure those instructions for designers also had to be taken into consideration. Google didn’t take them out of the blue, in fact, they are a direct result of guidelines proposed by different countries and regions in the world, i.e. by NHTSA in the USA.

Now, you might have noticed that I used the word “guidelines” and not “law” or “regulations”. You are indeed not required to follow them, but at the same time, the whole industry tries to do so. Actually lots of the guidelines proposed by NHTSA were first introduced by car manufacturers. 

You can tell Google paid lots of attention to them when designing Android Auto and Automotive. This is why lots of actions are forbidden when driving and your interaction with a Head Unit sometimes is interrupted by a full-screen modal asking you to focus on the road for a moment. This is also why fonts are so big, images are so scarce, animations are non-existent, and so on. You should also consider that Google has a final say if your application is fit for their system and if it blatantly isn’t, then it’s more than likely your app will be taken down from Play Store or not even admitted to it.

To sum this part up, try your best to follow the instructions provided by Google when designing screens, it will save you some troubles in the future.

With QA the challenge was a little bit different. At the time, it wasn’t always clear if issues or bugs were the result of dev team errors or problems with the platform itself. Especially since there were some differences between the emulators provided by various car manufacturers. This required close cooperation between QA and developers for most efficiency, but it also increased the effort required to implement new features. 

You might consider this as an additional tax when working on a platform in its early stages. Right now the situation might be different - emulators are available in the stable channel of Android Studio instead of beta and documentation is much more detailed. One thing won’t change for sure - QA is needed on all available types of emulators and their number will most likely increase in the near future. 

Product owners also had an important role in mitigating issues. Any time we were stuck, encountered potential platform problems, or were not sure if our approach was acceptable, product owners had to manage those issues with 3rd parties in a timely manner. This resolved lots of potential showstoppers, improved the app, and also provided valuable feedback to Google and car manufacturers. This was at early beta stages, so lots of the issues we encountered are probably already addressed in documentation as well.

Speaking purely from the developer’s perspective, most of the stuff works exactly the same way it does on Android Auto right now. There is some additional overhead due to testing on different emulators, but it’s no different than verifying your standard Android app on various devices. Emulators worked pretty smoothly and most issues could be resolved by wiping their data and cold boot.

New sign in and settings screens shouldn’t be complex, at least if you followed guidelines, so this on its own makes implementing those screens quite easy. I think it’s also very helpful to go through the official documentation. From what I see, the UAMP sample has also been updated with the Automotive target. I think checking those places is valuable because some things on Automotive are done a little bit differently than what Android developers might be used to.

UAMP sample sign-in screen

It’s also important to remember that an Automotive app is built as a separate target in your project. Depending on the structure of the existing codebase, the project can be prepared for this better or worse. It’s best if the codebase is already split into business logic and view modules at least. This way you can add an Automotive target as a new module which will reuse the business logic one. This will vary from project to project of course and depends on the approach the team has chosen. Still I think it's an important factor when trying to estimate the effort of adapting your app to Automotive.

Final words

In the end, working with the Automotive platform went pretty smoothly. The team had some challenges to overcome, but they mainly stemmed from the fact that this wasn't a stable and fully documented product at the time of integration. To me, it’s interesting how many car manufacturers are switching over to Automotive. It’s gradual of course and might be just an attempt to test the waters. Still, the potential market is quite big here. It’s unfortunate that applications will be limited to the same types as on Android Auto, but at the same time I’m curious what direction Google will take here in the future.

Cover image: Polestar

So, you are an ardent believer in the gospel of Reactive Revolution. You know your flatMaps and switchMaps, breathe in zips, exhale in debounces, you start your Singles and Maybes with a capital letter in every single sentence, but one thing bothers you - there actually exists a part of the (programming) world that is not yet reactive!

Well, despair no more, for here you will find a selection of Android libraries that will RX-ify even the ugliest, plainest procedurally projected piece of programming.

1. RxKotlin

RxJava bindings for Kotlin 

Yes, we all know this library, but there is certain propriety about writing these articles. Some formalities can’t be omitted - when writing about adding RX-value to applications written in Kotlin, every Uncle Bob-fearing programmer knows that a library actually called RxKotlin goes first, no contest. 

RxKotlin is actually just a set of useful extensions, instead of a proper library - mostly various castings and conversions. Close to 50% of the API count are just different variants of toObservable, toFlowable, and toCompletable. Still, it’s very soothing to know that with any standard, procedural object you are just one method away from your safe RX haven.

2. Lives 

RxJava operators for LiveData

Back in the ancient past of 2017, Google introduced MVVM as the suggested architecture for an Android project. While currently it is (Maybe) being slowly phased out in favor of MVI, still a lot of projects were created according to this design. Projects often too large to be rewritten, so you are forced to live with all these LiveData, a travesty of a proper RX object, with their nearly non-existent set of reactive methods. But why ride a Buick if you can ride a Ferrari? 

Or, in this case, at least paint your Buick so it sort of looks like a Ferrari.

For example:

liveDataVar
.distinctUntilChanged()
.map { /* do the RX magic */}
.nonNull()
.take(3)

3. RxBroadcastReceiver

RxJava binding for BroadcastReceiver

A simple tool for a simple task - instead of creating a boilerplate class extending BroadcastReceiver you need just a few following lines of code.

RxBroadcastReceivers
   .fromIntentFilter(
      context, 
      IntentFilter(LocationManager.MODE_CHANGED_ACTION))
   .subscribe {
      // react to broadcast
}

4. RxRelay

Combining Observable and Consumer

Good ol’ Jake Wharton - as always taking an existing imperfect concept and putting his spin on it, so it makes a programmer’s daily struggle just a little bit easier. Timber, ButterKnife (R.I.P), ThreeTenABP (that’s a lifesaver), and Maybe one or two more 🙂 We all know, cherish, use and abuse his work. But this time? An object that is both Observable and Consumer... did Jake just invent a Subject?

Not quite. Relay is indeed a Subject, but a limited one - it can’t call onComplete or onError. That means it will never end. Never stop the signal, regardless of what you will be feeding it, including invalid data. Very useful for “bridging the gap between non-Rx APIs”.As with Subjects, we have:

• BehaviorRelay - observer gets the last item before subscription plus all the subsequent ones
• PublishRelay - observer gets only items emitted after it subscribes
• ReplayRelay - buffers and emits all items to all observers

No AsyncRelay, since it requires a completion, which Relay by design doesn’t do.

For code samples, please check the library’s GitHub page.

5. RxDownload

Classic file downloader

With everything being in the cloud now, and likely to stay there, instead of a smart sync or REST API call, sometimes an app needs to perform an old school download. Wouldn’t it be nice if there was an RX Army Knife for that as well?

Example (from the library’s readme):

disposable = url.download()
    .observeOn(AndroidSchedulers.mainThread())
    .subscribeBy(
        onNext = { progress ->
            //download progress
            button.text = "${progress.downloadSizeStr()}/${progress.totalSizeStr()}"
            button.setProgress(progress)
        },
        onComplete = {
            //download complete
            button.text = "Open"
        },
        onError = {
            //download failed
            button.text = "Retry"
        }
    ) 

6. MvRx

MVVM with an MVI twist

That’s all nice if you are civilizing an old-school project, but what if you start a new one? You’re all familiar with MVVM, looking perhaps for something better, but MVI doesn’t feel battle-proven yet? Well, in that case, how about employing Airbnb as your quality assurance team and giving their praised solution a try? Formally it is an MVVM, but with its immutable state and Single invalidate method called after state is copied it smells suspiciously MVI-like. Covering this entire library would exceed the scope of this entry, so, for now, it is just an FYI that it is there.

Summary

As you can see, there are plenty of RX-friendly libraries that help to civilize those non-RX projects. With their help, you have hopefully been able to get your project a little closer to completion.

And that’s before we take a closer look at the elephant in the room - the co-routines and the RX support they provide. Describing that in detail would require an entirely new article, so stay tuned and in the meantime, you can check out the Kotlin co-routines module on Github.

Cover photo source: Pexels

AWS Cognito is one of many services available on the Amazon cloud platform. Using this service you can easily connect it with other available services on AWS such as API Gateway, AppSync, or Lambdas. It can store user data like given name, family name, email, username, password, and any other data which your users usually keep in the web or mobile application.

What is AWS Cognito for

If you want to allow users to register and log into your page, store their personal information, and some of the features like two-factor authentication or password recovery procedure, this service is something worth using. Not only does it allow you to avoid writing a backend service, but it also requires less code on the frontend. On the other hand, it’s not a silver bullet, so it’s good to know most of the pros and cons of using it before you make a decision.

Getting started

Connection with AWS Cognito service on the application side can be done by importing the AWS Amplify module, available to download as an NPM module (Node Package Manager). It gives your application the ability to connect with the AWS Cognito service, and implement the native user interface forms for authentication, password recovery, etc.

The pros of AWS Cognito

1. Fully configurable via the AWS control panel
2. Easy to connect with your application via provided AWS Amplify module (available for most popular frameworks/libraries, like Vue, Angular, React)
3. No need for an additional global state management solution in your app. AWS Amplify will check if the user is already logged for you. It provides its own global state which can be used across the whole application.
4. Out-of-the-box, UI forms for logging in, registration, password recovery, password change, federated authentication, MFA (Multi-Factor Authentication) e.g. SMS, Email, and TOTP (Temporary One Time Password) Confirm MFA Code’s and Provide QR codes for TOTP
5. All the data will be automatically stored in cloud AWS Cognito service (users information)
6. Confirmation emails (after user registration) will be automatically sent to the user as well as text messages to verify the user’s phone number
7. You can store custom attributes for users like address, phone number, city and any custom field which you want to
8. Data sent from the application is already encrypted and secured by the AWS Amplify module
9. Easy to connect with other AWS services like AWS AppSync
10. UI Form validations managed by AWS control panel
11. Integration with Social identity providers e.g. “Log in with Google” (or Facebook).
12. Error messages already provided by service
13. Several ways to handle forms on the application side
14. AWS Amplify allows for making HTTP requests (it’s using Axios module under the hood)
15. Out of the box security features like throttling (to prevent brute force attacks) or refresh tokens (to allow revoking access tokens)

The cons of AWS Cognito

1. It’s a paid solution
2. Documentation is rarely updated and not much detailed
3. Some of the options can be only set during the creation of an AWS Cognito user pool in the AWS administration panel. After that those options are disabled and if you want to change them you need to delete the whole instance and create a new one. This can be painful in the very beginnings of the project — when you are not sure which options you will eventually use in production.
4. Aligning provided UI forms with some of the designs can sometimes be problematic, then probably the fastest way is to create your own form components
5. Error messages provided by AWS Cognito are not very user friendly. Sometimes they are too technical, so you need to provide some kind of an error mapper in the application, to show more user-friendly messages. For example when a user tries to login with the wrong password.
6. There are no error messages for specific form fields, only general error messages
7. Confirmation emails (after user registration) are very limited. You need to create custom HTML email templates if you want more than just a plain text email with a verification link
8. There are limitations in the number of custom field attributes. You can’t create more than 25 custom attributes.
9. AWS Amplify module is a little heavy (minified + gzipped version is around 180 kB)

Final thoughts

Using AWS Cognito for user authentication along AWS Amplify on the application side is probably a faster solution than creating the whole authentication service on your own. In addition, you don’t need to take care of the backend, because this will be already provided by AWS Cognito. Also, some of the error messages, connection with service, UI forms will be provided out of the box. This is a good choice if you want to use advanced security features like phone number verification, two-factor authentication or log in with Google/Facebook.

But if your application does not use any other service from AWS (besides Cognito), connecting it with third-party services will take some time and require custom solutions. In this situation, it’s definitely better to consider building a dedicated authentication service or use an alternative solution that will fit with the rest of the application services/features.

Photo by Kevin Ku from Pexels

During the last year alone all of the cryptocurrencies’ market cap boomed from $17B in January 2017 up to a whopping $830B in January 2018. It was a very sudden surge in interest and adoption taking into account that it took almost four years to reach $17B mark (May 2013 — January 2017). But cryptocurrencies are not only about coins and money.

There’s also a blockchain part which can be even more interesting in terms of technology. Seeing the growing interest in the community, I decided to take a closer look at it, learn how to develop decentralized applications, and see how does it differ from developing in Java and Kotlin in which I had been writing code every day.

Ethereum blockchain applications

With a launch of the Ethereum platform creating your own blockchain applications (so-called dapps) and writing smart contracts (in short: pieces of code residing on the blockchain) became much simpler. The most popular way of doing so became via Solidity — a new programming language created specifically for this purpose. After simplicity, adoption followed — people started creating hundreds of decentralized applications. The most popular of them all is CryptoKitties, which lets you buy and breed virtual kittens. At one point it was so widely used that it slowed down the whole Ethereum network. People were buying and selling their virtual pets so quickly that all of the transactions amassed to over $24M. The most expensive kitten was sold for over $100K. Seeing how fast this environment grows, I tried to learn Solidity. To do this, I dropped Android development for a few months and started writing smart contracts full time.

Object-oriented programming vs Design by contract

Solidity is a programming language created to follow the “design by contract” approach to creating software. It is not a new concept — it was first created by Bertrand Meyer in 1986 while working on a new programming language: Eiffel. It encourages developers to define formal preconditions, postconditions, and invariants for every software component. These formal specifications are called “contracts”. In Solidity, they are named that as well and are very similar to Java Classes. They both can have constructors, private and public methods, global and local variables, and can be instantiated. However, Solidity contracts also have public addresses in the blockchain (after being deployed) and can store and send value.

Similarities and differences between Solidity and Java

The biggest difference in how the code looks in these two languages are modifiers and events. Both are usually declared at the beginning of a contract.

Modifiers

Modifiers are used to restrict who can make modifications to the contract’s state or call the contract’s functions and are reusable (can be used in multiple functions). They are also a tool to enforce the function’s pre- and post-conditions.

contract NumberContract {
  address private contractIssuer;
  uint private number;
  
  modifier onlyContractIssuer {       
      require(contractIssuer == msg.sender);
      _;
  }
  
  function NumberContract() public {
      contractIssuer = msg.sender;    
  } 
  
  function setNumber(uint newNumber) onlyContractIssuer public {
      number = newNumber;
  }
}

Events

Events allow the usage of the Ethereum Virtual Machine (EVM) logging facilities and can be used to call callbacks that listen for them.

Events are inheritable members of contracts. When they are called, they cause the arguments to be stored in the transaction’s log — a special data structure in the blockchain. These logs are associated with the address of the contract and will be incorporated into the blockchain and stay there as long as a block is accessible. Log and event data is not accessible from within contracts (not even from the contract that created them).

contract NumberContract {
  address private contractIssuer;
  uint private number;
  
  event NumberSet(uint number);
  
  modifier onlyContractIssuer {       
      require(contractIssuer == msg.sender);
      _;
  }
  
  function NumberContract() public {
      contractIssuer = msg.sender;    
  } 
  
  function setNumber(uint newNumber) onlyContractIssuer public {
      number = newNumber;
      NumberSet(newNumber);
  }
}

Multiple inheritance

Solidity supports multiple inheritance by copying code including polymorphism. All function calls are virtual, which means that the most derived function is called, except when the contract name is explicitly given. When a contract inherits from multiple contracts, only a single contract is created on the blockchain, and the code from all the base contracts is copied into the created contract. The general inheritance system is very similar to Python’s, especially concerning multiple inheritance.

Function visibility: external

While in Solidity almost all types of function visibility (private, public, and internal) are intuitive and similar to these in Java, one is different. A function can be declared as external which means it can be called only from other contracts and by transactions. Calling it internally is impossible.

Function modifiers: pure, view, payable

When a function is declared as pure, it cannot modify or even access the state (variables, mappings, arrays, etc.). It’s the most restrictive modifier but it is the most secure and saves the most gas when applied.

The view is slightly more allowing modifier. It basically acts the same as pure but allows access to the state (but it still cannot modify it though).

When we want a function to be able to receive Ether together with a call, we declare it as payable. It allows for money transfers, deposits, and basically handling money in every way needed.

contract NumberContract {
  address private contractIssuer;
  uint private number;
  mapping(address => uint256) public availableWithdrawals;
  
  modifier onlyContractIssuer {       
      require(contractIssuer == msg.sender);
      _;
  }
  
  modifier hasPositiveBalance(address user) {
    require(availableWithdrawals[user] > 0);
    _;
  }
  
  function NumberContract() public {
      contractIssuer = msg.sender;
  } 
  
  function deposit() public payable {
      availableWithdrawals[msg.sender] = 
            safeAdd(availableWithdrawals[msg.sender], msg.value)
  }
  
  function withdraw() public payable hasPositiveBalance(msg.sender) {
    uint256 amount = availableWithdrawals[msg.sender];
    availableWithdrawals[msg.sender] = 0;
    msg.sender.transfer(amount);
  }
  
  function getAmountToWithdraw() public view returns (uint256) {
    return availableWithdrawals[msg.sender];
  }
  
  function safeAdd(uint256 a, uint256 b) internal pure returns (uint256) {
    uint256 c = a + b;
    assert(c >= a);
    return c;
  }
  
  function setNumber(uint newNumber) onlyContractIssuer public {
      number = newNumber;
  }
}

Additional data

When a function is called via a transaction, it can access additional information about the caller that is passed automatically, e.g. sender’s address (msg.sender), amount of Ether send (msg.value) or remaining gas (msg.gas) (see the code above for the usage examples).

Data structures

While Java has many complex and simple data structures built-in, in Solidity there are only two of them: mapping and array. The first one is a simplified version of Java map, meaning it can store key-value pairs and retrieve the value stored under a given key, but not much else. It cannot be iterated over and both key and value sets are not retrievable. The latter will be talked about in the next paragraph (see the code above for the example of a mapping).

Optimizations

Writing in Solidity requires paying attention to many more details than when writing in Java. Each transaction is an execution of a contract’s function which triggers operations. Each operation, in turn, costs gas which we need to pay in Ether (besides any Ether we want to send along). When the gas limit is exceeded, the whole function is being reverted and everything is restored to the state from before the function was called. In Java, however, even the code which is not optimized in any way will execute properly and the only side effect would be a longer runtime of the application.

Pitfalls to avoid

If you are used to writing code in Java, there are many different and unintuitive things in Solidity. Knowing about them is crucial if you want to avoid running into bugs that are hard to reproduce. I’ll list some of them below:

Overflow errors

In Solidity, all operations on integers can create an overflow error. What’s more, there are no overflow-safe operations which means you have to check for it manually every time using the require command (it is basically an assert which reverts the whole function when the condition is not fulfilled)

‘Byte’ and ‘Bytes’ confusion

Byte type is 256-bits wide which means that byte array (byte[]) takes 32x more space than expected (it’s very bad, considering the gas limit, and hard to debug keeping in mind that storage space is extremely limited). An actual byte array which takes as much space as expected should be declared as bytes.

Strings

Solidity doesn’t natively support any string manipulation. At the time of writing, even basic operations like concatenation of two strings have to be done manually after casting them to byte arrays. Length can be checked also only after conversion to a byte array. What’s more, there are no methods like indexOf() which are given in Java — they have to be written by hand, copied in from a different project, or reference a function from a library already on the blockchain.

Arrays

Array access syntax looks like in Java but declaration syntax is reversed — int8[][5] creates 5 dynamic arrays of bytes. Unfortunately only statically sized arrays can be returned by functions — there is no way to return a dynamically sized one. Also, multi-dimensional dynamic arrays cannot be created which means that declaring an array of strings (which are dynamically sized arrays of chars) is not possible.

‘For’ loops

Solidity was created to resemble JavaScript, but literal 0 type infers to byte, not int. That means writing:

for (var i = 0; i < a.length; i++) { a[i] = i; }

will enter an infinite loop if the "a" array is longer than 255 elements (the iterator will wrap around back to 0). This is despite the underlying VM using 256 bits to store this byte. You should just know about this and declare "i" as uint instead of var.

Operator’s semantics

Operators have different semantics depending on whether the operands are literals or not. For example, 1/2 is 0.5, but x/y for x==1 and y==2 is 0. Precision of the operation is also determined in this manner — literals are arbitrary-precision, other values are constrained by their types.

Mapping

Mappings, unlike maps in Java, don’t throw an exception on non-existing keys. They just return the default value depending on the key type (when keys are integers, 0 will be returned). What’s more, there is no way to check if an element exists (like contains() in Java) — when 0 is returned we don’t know if a key was added to the mapping with value 0 or is it the default value being returned because there is no such key in the mapping. There’s also no built-in method of extracting a key or value sets from a mapping which means iterating over a key set is not possible.

Summary

Solidity represents a unique and one of the first approaches to writing contracts on the blockchain. This language is still at very early stages and is nowhere near being complete and fully functioning. However, it evolves very quickly, so I’m sure that in the future many mistakes will be fixed and functionalities added.

Unfortunately during the designing phase, there have been some decisions made that I’m not sure are fully fixable. The biggest ones affect code security — this language should care and enforce security since all blockchain applications work with money. However, functions are public by default, integer operations can overflow, loops could never finish, updating code is problematic, etc.

The most fundamental problem is that it’s optimized to be user-friendly and look like a language people are used to and should be intuitively able to deduce what’s going on in EVM. It often does a completely different thing which can cause developer’s confusion, or worse yet memory leaks and security holes.

A new language that handles money transactions that are designed to be easy to learn should be intuitive. However, in its current shape it’s easy to learn how to do something wrong, but hard to do something right.

Ever wondered how to improve the quality of our iOS apps and become a more productive developer? This is the first article in a series that fully focuses on the problem of shared state and how to possibly reduce it.

Mobile applications are becoming more and more popular every day. There are also many tools becoming available to develop apps, we have both Swift for iOS and Kotlin for Android that promise us more compile-time checks so that there’ll be fewer issues runtime.

However, despite sophisticated tools, it’s still tricky to write a stable application. In this article, I’ll share some tips from my personal experience on how to improve the quality of our software and make our lives a little easier.

Shared state and side effects

When developing modern mobile apps, we tend to use object-oriented programming. We create objects, these objects can have fields that can be altered from many parts of our program. This can cause issues due to some part of the program expecting an object in a specific state and receiving something unexpected, leading to bugs. These bugs can be hard to reproduce on our local environment since a specific set of steps need to be taken in order to reproduce the issue. Modern programming languages like Swift or Kotlin favor immutable data structures to reduce the issue. If we have an object whose fields are immutable, then once it’s created the object is in a stable state.

Let’s take a look at some practical examples. Assume that we’re asked to implement a class which fetches user’s location in the world. Since this article is not a tutorial about how to use CLLocationManager, I’m going to focus on the interface only. One of the simplest ways to tackle the problem, is to use the delegate pattern, so it’d look something like this:

protocol LocationFetchterDelegate: class {
  func locationFetcher(_ fetcher: LocationFetcher, didUpdateLocation location: CLLocation)
}

final class LocationFetcher {
  weak var delegate: LocationFetcherDelgate?
  
  //Class implementation goes here
}

This solution has a few problems:

1. The field delegate can be freely modified by other components. One place can set a delegate and another one can choose to assign it to another object, which can cause one of the components not receiving results whatsoever.
2. We don’t know on which thread the results can be delivered on, without looking into the implementation. If we received this class as part of a closed-source library, we’d either need to disassemble the binary or check it in runtime.
3. What if we wanted multiple objects receiving the location updates? We’d need to change the class implementation, which would lead to public interface change and all relying components would need to update.

The solution

Okay, since we know about the problems now, let’s move on to a possible solution. I myself, like to use ReactiveX APIs. In short, ReactiveX is an API for asynchronous programming using observable streams that combines the best ideas from the observer and iterator as well as functional programming. ReactiveX is implemented on different platforms: there is RxSwift for Swift, RxJava for Java, RxJS for JavaScript, etc. and they all share similar API respecting the language’s design and idioms.

In order to understand how to use observable streams in our applications, we need to change the way we think about designing applications. The most straightforward example of how it works is to think of an Excel spreadsheet. Let’s imagine that we have two cells in the spreadsheet and we want to sum them. That’s easy! Let’s take a third cell, take the addresses of two previous ones, and write a formula that adds their values. Now, the cell will display the sum or an error if either of the previous ones contained an invalid value (like a string instead of a number). Observable streams work in a similar way from a very high-level point of view.

Now that we’ve got a basic understanding of how observable streams work, let’s look at how the class interface would look if we chose streams over delegate. For the purpose of this article, we’re using the RxSwift library.

final class LocationFetcher {
let location: Observable<CLLocation>
}

As we can see, problem #1 is gone. We have one immutable property location which emits location updates and no component can modify it. Our program not only more deterministic but since we don’t need a specific reference to the delegate, we got rid of the additional protocol as well! Let’s see how subscribing to updated would look like:

let locationFetcher: LocationFetcher //Assume exists

locationFetcher.location
.observeOn(MainScheduler.instance)
.subscribe(onNext: { print("new location: \($0)") })
.disposed(by: disposeBag)

This solves problems #2 and #3. As we can see, RxSwift allows us to specify on which thread we’re receiving the updates, as well as multiple objects, can subscribe to a single stream to get updates via simple DSL-like API.

The downsides

The problem with many ReactiveX articles out there is that I didn’t see many of them outlining the disadvantages of this approach. All tools and libraries have good sides and bad sides and it’s up to us, developers to make the call to use them or not.

As I mentioned earlier, the main downside of using the observable streams approach is that we have to rethink the way we write mobile apps. This means that we’ll make many mistakes along the way and because of this, I highly discourage using ReactiveX for an important project for the first time. The best way is to find either a personal project or one that allows us to experiment and see if we like it. The learning curve for RxSwift is very steep and there aren’t that many good tutorials out there, so keep that in mind before using it for the first time.

Another disadvantage I experienced, is that while some things are very easy to implement using observable streams and make our code look nice and elegant, it doesn’t apply to everything. For example, there is a way to implement a UITableView data source using RxCocoa bindings, however, it’s not straightforward and takes longer rather than using the Apple recommended approach. My advice here is to use observable streams selectively. Start with networking, for example, make it work well and move on to other components and see if you really gain something by implementing them. Don’t blindly rewrite your whole app using RxSwift just because someone on the internet told you to do so.

Conclusion

In this article, we introduced the concept of shared state and side effects and brought to attention on what issues can they create as well as my proposition on how to easily fix them using ReactiveX libraries. In the next articles, we’ll focus on other common issues in mobile apps and how to fix them.

Dear reader, I assume that you are interested in all the tech news. One of the most interesting in recent times is those that combine hardware and software — often classified as IoT (Internet of Things).

Observing the market, you could have noticed that the so-called Smart Home sector is gaining strength and serious players on the market are introducing more and more “smart” devices as well as offer more and more advanced systems integrating these devices to work in a homogeneous environment — some of them can work with integration platforms from Apple (Home Kit with assistant Siri), Google (Google Home with voice assistant), Amazon (Smart Home with Alex voice assistant) and Microsoft (along with Cortana voice assistant).
I suppose you, like me, like devices that make your everyday life easier and would gladly equip you with your home. However, it is not always possible due to the high price or they not always fully meet your expectations.

There is an alternative solution that can give you a lot of fun, new knowledge, and finally a practical solution to the problem you may face on a daily basis.
That’s how it was with me — I’m interested in IoT devices, I like programming and I wanted to learn more about the hardware-software combination and finally, I needed to improve some daily activities — there was no other option — “smart” system needed to be built 🙂

The solution that I will describe has been created to facilitate one everyday activity: opening the gate to a multi-family building to its residents (including myself).

Perhaps you are wondering what’s the point!? Maybe you think that it would be a good idea to improve this activity, but there are already many products out there and there is no reason for duplicating them.
If you are interested in how I decided to solve this problem, let me take you through a typical scenario where a person enters a multi-family building:

A person holds the key to the gate scenario:

1. Pulls out the key (e.g. from the pocket)
2. Unlocks the lock with the key
3. Person gets in

A person has an access code to the intercom scenario:

1. Types many numbers to unlock the lock (what if it’s unclear what’s the combination? :))
2. Intercom unlocks the electro lock
3. Person gets in

This is not an extremely complicated activity and it may not make sense to optimize it, but if you ever tried to enter the building with your hands holding shopping bags, or your key to the gate was tucked away and it took a long time to take it out, you would certainly be happy with the solution, which would allow you to have the door open to the building at the touch of a button! Without looking for a key, without pressing a long sequence on the numbers on intercom’s keypad — only the iPhone in your pocket and one button on the door and you are in!

So, let's do it!

In order to achieve the intended goal, we will need a solution that will automatically recognize our presence nearby the entrance gate and after pressing the button on the door, the system will verify our permissions, and then (if we are allowed to pass the door) open the electro lock and thus release the door. Sounds simple, right?

The architecture of our system will be as simple as possible — I want to share with you a solution that is easy to implement and at the same time with the potential for further development according to your extra needs.

Most of the door lock control systems for buildings work in the sequence:

System listens to the presence of a person → Person near by the door (with smartphone) → System detects presence → Person launches the application → Person unlocks the door via the app → System verifies permissions → System unlocks the door

Our solution:

System listens to the presence of a person → Person near by the door (with iPhone) → System detects presence → Person presses the gate opening button on the door → System verifies the permissions → System unlocks the door

Please, notice how comfortable it is. No waisting time for getting the phone, launching the app, and interacting with the app to open the door.
It’s as simple as one button click.

How safe is our solution?

Please, keep in mind that the level of security against unauthorized use does not have to be very high here — the purpose is to prevent people who should not cross the building’s gate, but it won’t be a barrier for a person who previously possesses an iPhone with granted access to the gate. That’s why our solution is suitable for managing access to a building, but it should not be used to control access to housing.
Here, we focus on the convenience of use with a reasonable level of security.

Prerequisites:

• The gate to the building with an electric lock (with access to a key and/or intercom)
• Internet access for the gateway controller (e.g. WiFi in range)
• A computer with macOS operating system

Parts of our system:

• Gate controller (Raspberry Pi)
• User’s smartphone (iPhone)
• Cloud service (backend application deployed on Heroku)

Used communication channels within the system:

• HTTPS
• Bluetooth Low Energy (BLE 4.0)

The diagram below shows the principle of the entire system. It will allow you to familiarise yourself in detail with the role of each piece of the system, as well as with the interactions between them.

What do we need to assemble our IoT solution?

Collect the following items:

• Raspberry Pi Zero W microcomputer (I’ll use also a short name: “RPi”)
  Thanks to this device, we will have, apart from an advanced controller with the Linux OS, also a WiFi and BLE 4 module, without the need to attach additional modules

• microSD card (at least 16GB) with an adapter for SD card reader

• iPhone 5 or newer with iOS 10.3 (or newer)

• Power supply with micro USB connector to drive the Raspberry Pi

• Breadboard

• 2 LED diodes (green and red)

• Relay module (e.g. SRD-05VDC-SL-C)

• Push-button

• Resistors: 2 × 300Ω and 1 × 10kΩ
• Wires

How to connect all elements with each other?

Here is the recipe:

Note: Please, take into account that the relay module you have chosen may differ from the one on the diagram above, so connect according to specification.

This is how my physical implementation of the above scheme looks like:

As we already know what and how to connect with each other, it is time to prepare individual components of the system.

Configuration time

As first we will prepare a gateway controller — Raspberry Pi together with subassemblies.

To “be alive”, Raspberry Pi needs an operating system, and in our case, it will be Raspbian Stretch Light.

Once we have Raspberry Pi prepared and connected to the WiFi network (yes, that's important ), we can take care of preparing the environment for our program, which will be responsible for several key things:

• communication with iPhone (via BLE 4.0)
• generating a token and sending it to the service in the cloud (via HTTPS)
• validation of the token transferred from the iPhone
• opening the electro lock of the main gate

To handle the above I’ve prepared a program written in JavaScript that will be run within the Node.js environment. Later on, I will explain the more important parts of the code, but now we will continue the configuration thus we still have a few things to be installed.

Node.js installation

Log in to RPi via SSH (as user pi) and execute the following commands:

$ sudo apt-get update

$ sudo apt-get dist-upgrade

$ curl -sL https://deb.nodesource.com/setup_9.x | sudo -E bash -

$ sudo apt-get install -y nodejs

The above sequence guarantees the latest versions of the packages, and then we install the latest version of Node.js.

To check whether the operation was successful and what Node.js version we have, run the command:

$ node --version

The next step is to install the Node.js libraries that are used in the application and these are:

• UUID generator — generates an authorization token

  $ npm install uuid

• Cache — stores generated tokens

  $ npm install node-cache

• Console Log Formatter — makes log messages more developer-friendly
  $ npm install console-stamp
• GPIO Pins Controller — lets us read and write signals from/to RPi board pins

  $ npm install rpi-gpio

• Bluetooth Low Energy — handles all BLE communication
  Due to the fact that the installation is a bit more complicated, please follow the instruction given here
• GPIO Button Event Emitter — handles buttons’ events

  $ npm install rpi-gpio-buttons

• Request — supports HTTPS operations

  $ npm install request

Now we can install our program on RPi.

To do this, log in to RPi via SSH and create a folder:

$ mkdir /home/pi/gateguard

Download the ZIP-ed source code from GitHub and unpack it, and then move *.js files to the newly created folder:

$ wget -O gateguard-rpi.zip https://github.com/inFullMobile/gateguard-rpi/archive/master.zip

$ unzip gateguard-rpi.zip

$ cp -r gateguard-rpi-master/* /home/pi/gateguard/

We still have one more thing to configure, but we can’t do it until the app in the cloud is setup — it is about a generated URL address of our application, which will be included in the code on PRi, so that RPi can connect to it in the cloud.

Raspberry Pi is almost ready… so it’s time to launch another element of our system — a service in the cloud, which will be responsible for coordinating communication between the iPhone and RPi.

Two more elements of the system require an Xcode environment (preferably the newest one, currently Xcode 9.3) and if you do not have it yet, please install it from the Apple AppStore store (https://itunes.apple.com/pl/app/xcode/id497799835?mt = 12), then launch and complete the installation.

The cloud app will be deployed on the Heroku platform, where we can host our application for free for development and education purposes.

As the first step, I suggest setting up an account on the Heroku platform, within which our application will be deployed and maintained.
Go to heroku.com and create an account (if you do not have one already).

Then we will need the Heroku Command Line Interface (aka Heroku CLI) installed on the computer. We’ll use it to deploy the application.
To install Heroku CLI, follow the instruction: Heroku CLI Installation.

As the application is written with the Vapor framework (Swift on board), please install Vapor Tool Box which will support the app: Vapor Tool Box Installation.

In the next step, download the application code from the repository. To do this efficiently, use the Git client:

$ git clone https://github.com/inFullMobile/gateguard-cloud.git

Let’s prepare our project for deployment with Heroku CLI commands:

$ cd gateguardcloud

$ rm -rf .git #it removes current git version control files

$ heroku login #once asked, provide your username (email) and password

#create new git local repository

$ git init

$ git add .

$ git commit -m “Initial commit”

We can now deploy our application to Heroku servers:

$ vapor heroku init

as a result, you will be asked some questions and you may answer as I did:

Would you like to provide a custom Heroku app name?

y/n> n

Would you like to deploy to a region other than the US?

y/n> y

Region code (us/eu):

> eu

https://pacific-lowlands-45092.herokuapp.com/ | https://git.heroku.com/pacific-lowlands-45092.git

Would you like to provide a custom Heroku buildpack?

y/n> n

Setting buildpack...

Are you using a custom Executable name?

y/n> n

Setting procfile...

Committing procfile...

Would you like to push to Heroku now?

y/n> y

This may take a while...

Building on Heroku ... ~5-10 minutes [ • ]

and finally

Building on Heroku ... ~5-10 minutes [Done]

Spinning up dynos [Done]

Visit https://dashboard.heroku.com/apps/

App is live on Heroku, visit

https://pacific-lowlands-45092.herokuapp.com/ | https://git.heroku.com/pacific-lowlands-45092.git

Remember generated domain for your cloud app for later use (in my case it is https://pacific-lowlands-45092.herokuapp.com)

It is a good moment to return to the code on RPi and configure the correct URL address of our service in the cloud. To do this, reconnect to RPi via SSH and open the file /home/pi/gateguard/cloud_module.js for editing then enter the correct address of the service on Heroku (code: line 35). In my case it looks like this:

uri: ‘https://pacific-lowlands-45092.herokuapp.com/register-token'

We need two more unique identifiers for Bluetooth communication, and you can get them by doing a 2× command:

$ uuidgen

In my case, it has been generated UUIDs:

• 93384AB6–9EB1–4AF2–90FB-F88ABB6F79AF

• 4E98BE1C-F8D9–46AD-9D08-C0AAA7DFEE7A

The first on them will be used on Raspberry Pi as BLE peripheral’s service identifier, the second will be assigned to the peripheral’s characteristic.

Assign your generated UUIDs to service and characteristics in source file /home/pi/gateguard/shared_module.js respectively:

this.bleServiceUUID = '93384AB6-9EB1-4AF2-90FB-F88ABB6F79AF'
this.bleCharacteristicUUID = '4E98BE1C-F8D9-46AD-9D08-C0AAA7DFEE7A'

Are you ready to launch the program on PRi? 10… 9… 8…

$ nohup sudo node /home/pi/gateguard/gateguard.js > /home/pi/gateguard/gateguard.log &

where the nohup command will guarantee the work of the program in the background as we disconnect from the RPi, while sudo is necessary for our program to work on permissions allowing it to access BLE and IO ports of our microcomputer. All logs thrown by our program will go to gateguard.log file.

Time for the second element of the system — an application for the iPhone.

In this case, you just need to download the project source files from the repository:

$ git clone https://github.com/inFullMobile/gateguard-ios.git

and open the project in Xcode.
Before running on the iPhone, set the correct URL address of the app in the cloud, what can be done in the project’s source file HttpClient.swift — change the address assigned to the constant:

// That's my URL address! Use yours ;)
static let gateGuardHost = URL(string: "https://pacific-lowlands-45092.herokuapp.com")!

Now configure the correct UUIDs for BLE service and characteristic in the BLEService.swift file (remember to assign appropriate UUIDs to service and characteristics — the same as in sources of PRi app):

static var serviceUUID: CBUUID {

return CBUUID(string: "93384AB6-9EB1-4AF2-90FB-F88ABB6F79AF")

}

static var newTokenNotificationCharacteristicUUID: CBUUID {

return CBUUID(string: "4E98BE1C-F8D9-46AD-9D08-C0AAA7DFEE7A")

}

Ensure that Bluetooth on iPhone is ON!

Now you can launch the application on your phone.

Congratulations! You did it! Our GateGuard should now work as expected — test it with alternately Bluetooth switched ON and OFF on the phone, and you will observe the result of the action in the form of flashing or glowing LEDs and the operation of the relay, which connected to the electro lock will unlock the gate to the building.

For your information, I’ll explain the LEDs behavior:

• The green LED blinks — the gate opening button has been pressed, the iPhone with the Gate Guard application is within RPi BLE range and the authorization is in progress
• The green LED is on — the door’s electro lock is open
• The red LED blinks — the gate opening button has been pressed but RPi has not identified the iPhone with the Gate Guard application running
• The red LED is on — the user hasn’t passed the authorization successfully (the token from the iPhone is invalid) and the gate will not be opened

Please note that there is no authentication step in the iPhone’s application. Due to the simplicity of the solution, I’ve skipped the authentication process, but there is nothing to prevent you from adding a login screen that will protect the application from unauthorized use.

A bit about code itself

If you are interested in how communication between RPi, iPhone, and application in the cloud has been resolved, stay with me, and I will explain the most important pieces of the code right now.

If you are new to the BLE subject, I recommend a very good introduction made by Mikołaj Chmielewski in the article Introduction to Bluetooth LE on iOS: Mi Band 2 Case Study.

What is happening on Raspberry Pi?

Our device is responsible for the following:

• acting as a BLE peripheral for iPhone connected to it
• generating a new token
• transferring token to the cloud app
• validation of a token transferred from the iPhone
• electro lock control

Let’s go through the source code to see what’s happening there.

Following the above bullet points, acting as a BLE peripheral for iPhone connected to it is handled by the code:

onSubscribe(maxValueSize, callback) {
console.log('BLE characteristic subscribed')

shared.subscribedToCharacteristic = true
this.valueDidChangeCallback = callback
}

Generation of authorization token is done by the code:

const tokenId = Math.floor(Math.random() * MAX_TOKEN_ID)
const token = uuid()

Transferring token to the cloud app is done this way:

    registerTokenInCloud(tokenId, token, completionCallback) {
        console.log('register token in cloud service')
        if (!this.requestInProgress) {
            console.log('http request')

            const _this = this

            this.requestInProgress = true

            request(this._requestOptions(tokenId, token), function(error, response, body) {
                console.log('http response')

                _this.requestInProgress = false

                if (!error && response.statusCode == 200) {
                    console.log('New token registered on cloud service with success')
                    completionCallback(true)
                } else {
                    console.error('Error while registering token in cloud service: ' + error)
                    completionCallback(false)
                }
            })
        }
    }

    _requestOptions(tokenId, token) {
        return {
            uri: 'https://gateguard.herokuapp.com/register-token',
            method: 'POST',
            json: {
                "id": tokenId,
                "token": token
            }
        }
    }

Another step is the validation of the token:

onWriteRequest(data, offset, withoutResponse, callback) {
        console.log('Authorization request from mobile phone')

        this.greenLedManager.off()

        var dataParts = data.toString().split('|')

        const tokenId = dataParts[0]
        const token = dataParts[1]

        var cachedToken = null

        try {
            cachedToken = shared.cache.get(tokenId, true)
            if (token.toUpperCase() == cachedToken.toUpperCase()) {
                console.log('Token is valid! Opening the gate...')

                this.greenLedManager.on(led.LEDModeEnum.solid, shared.ELECTROLOCK_ON_DURATION)
                this.relayManager.on(shared.ELECTROLOCK_ON_DURATION)
            } else {
                console.log('Token is invalid - access to the gate denied!')

                this.redLedManager.on(led.LEDModeEnum.solid, shared.ELECTROLOCK_ON_DURATION)
            }

            callback(0)
        } catch (err) {
            console.log('Error: ' + err)
            callback(1)
        }
    }

Electro lock controlling is implemented in relay_module.js.

Opening the gate is happening here:

this.relayManager.on(shared.ELECTROLOCK_ON_DURATION)

What about iPhone’s role?

The app mainly works in background and

• is looking instantly for particular UUID which represents RPi service/characteristic
• gets requested token (request comes from RPi) from cloud service
• sends token back to RPi for further authorization procedure

Instant looking around for familiar Raspberry Pi looks like this:

    private func scanForPeripheral() {
        guard self.isElectronicKeyActive else { return }
        
        self.centralManager.scanForPeripherals(withServices: [CBUUID.serviceUUID],
                                               options: [CBCentralManagerScanOptionAllowDuplicatesKey: NSNumber(booleanLiteral: true)])
    }

and successively

func peripheral(_ peripheral: CBPeripheral, didDiscoverServices error: Error?) {
        guard error == nil else { return }
        
        guard let service = peripheral.services?.filter({ $0.uuid == CBUUID.serviceUUID }).first else {
            return
        }
        
        peripheral.discoverCharacteristics([CBUUID.newTokenNotificationCharacteristicUUID], for: service)
    }
    
    func peripheral(_ peripheral: CBPeripheral, didDiscoverCharacteristicsFor service: CBService, error: Error?) {
        guard let characteristic = service.characteristics?.filter({ $0.uuid == CBUUID.newTokenNotificationCharacteristicUUID }).first else {
            return
        }
        self.storedCharacteristic = characteristic
        peripheral.setNotifyValue(true, for: characteristic)
}

Once the peripheral device is connected and the gate’s button pressed, it generates new authorization token (unknown for iPhone’s app) and requests for it. The token is sent to RPi app right after being taken from cloud service.

        self.bleService.tokenDidRequestCallback = { [weak tokenService, weak bleService] (_ tokenId: Int) in
            
            tokenService?.getToken(with: tokenId) { (_ result) in
                switch result {
                case .success(let token):
                    bleService?.respond(withToken: token)
                case .error(let error):
                    let errorMessage = String(describing: error)
                    print("Error: \(errorMessage)")
                }
            }
}

There is also a token exchange platform — service in the cloud.

The backend application is written in Swift with the use of the Vapor framework and hosted on Heroku servers. Simple service which is responsible for two things:

• storing newly generated authorization token (for a limited time only)
• answering with token while being asked for it with tokenID

The first responsibility is handled this way:

        post("register-token") { req in
            guard let id = req.json?["id"]?.int, let token = req.json?["token"]?.string else {
                return Response(status: .badRequest)
            }
            
            try self.cache.set("\(id)", token, expiration: Date(timeIntervalSinceNow: Constants.tokenDuration))
            
            return Response(status: .ok)
        }

The second is implemented this way:

        get("token") { req in
            guard let id = req.query?["id"]?.int else {
                return Response(status: .badRequest)
            }
            
            var json = JSON()
            
            guard let token = try self.cache.get("\(id)") else {
                return Response(status: .noContent)
            }
            
            try json.set("id", id)
            try json.set("token", token)
            
            return json
}

As you can see, all pieces of the system talk to each other via BLE and HTTPS. Details of implementation you can always find in provided repositories.

That was huge fun for me to build that system and I hope you may find it interesting too.

Probably most of you have heard or visited hackathons. I'd like to tell you about the unusual one. CanonHackathon is a first projector hackathon in Poland, organized by Google Developers Group Warsaw and Canon. The rules were easy: teams had 24 hours to make a video mapping project.

The goal of CanonHackathon was to prove that video projectors can be used not only for watching movies.

Teams came up with different ideas. Above you can see the team that created an interactive art installation made out of 3 projectors and Arduino and a plant. Another team created a project that helped people to connect a lot of projectors together in an easy way.

My favorite project used projectors for controlling smart home devices. Projector, Microsoft Kinect, and a team of smart people were the keys to success.

There was a team that created a music visualizer. Imagine yourself playing piano and your whole room changing colors and reacting visually to you performing. You could also play your favorite song and literally "see the beat".

Here we'll discuss the Instagram slideshow app we've created. It helps event organizers to make a slideshow with pictures that have a particular Instagram tag. Pictures are mapped on a cube, so it looks more interesting than just a flat wall, commonly used during events. A user doesn't need any PC. All you need is an Android phone and a Chromecast. In the next section, we'll overview the technical part of the application.

Let's make an app. Architecture setup

We'll use the InFullMVP library for implementing a Model View Presenter architecture in our app.

Setup Gradle:

repositories {
    maven { url 'https://maven.infullmobile.com/public' }
}

compile 'com.infullmobile.android:infullmvp-kotlin:1.1.14'
testCcompile 'com.infullmobile.android:infullmvp-kotlin-basetest:1.1.14'

Moving, scaling and rotating imageView

Alright, now we have an MVP app with an empty activity. Let's give it some content.

Imagine yourself a cube in front of you. Projectors are displaying an image from your phone on this cube. And to fit a picture in a cube we have to move our picture around, scale it to make it fit in a cube, or any other object in front of you. So after it'll have the same effect as in the picture above. For that, we can use an open-source library called TNImageView.

Add the TNImageView library to your project. Add jitpack.io to your root build.gradle at the end of repositories:

allprojects {
		repositories {
			...
			maven { url 'https://jitpack.io' }
		}
	}

Include the following dependency:

compile 'com.github.AmeerHamzaaa:TNImageView-Android:0.1.2'

Create an activity layout so it looks like this:

<RelativeLayout
   android:layout_width="match_parent"
   android:layout_height="match_parent">


   <ImageView
       android:id="@+id/slideShowImage"
       android:layout_width="100dp"
       android:layout_height="100dp"
       android:clickable="true"
       android:src="@drawable/ice_cream"/>
</RelativeLayout>

Now let's initialize a TNImageView:

class MainActivityView @Inject constructor() : PresentedActivityView<MainActivityPresenter>() {


    @LayoutRes override val layoutResId = R.layout.activity_main
    val slideShowImage: ImageView by bindView(R.id.slideShowImage)


    override fun onViewsBound() {
        TNImageView().makeRotatableScalable(slideShowImage)
    }
}

Our result:

Matrix transformation for imageView

Imagine a situation when a cube in front of you is rotated ~30°. Now we have to skew an image to fit. Here is how we do it.

private fun skewBitmap(src: Bitmap, xSkew: Float, ySkew: Float): Bitmap {
        val xCoordinates = 0
        val yCoordinates = 0
        val matrix = Matrix()
        matrix.postSkew(xSkew, ySkew)
        return Bitmap.createBitmap(src, xCoordinates, yCoordinates, src.width, src.height, matrix, true)
}

So now we can skew our ImageView

Fetching images from Instagram by tag name

Finally, we can fit our Instagram picture on a surface of a cube or a backpack for example. But our app is kind of boring because it has only 1 picture. Let's fetch images from Instagram by a tag and show it.

First, we have to get an Instagram Access Token. The fastest way is to use Elfsight token generation service: All instructions are here

1. Generate POJOs from JSON that Instagram returns you. Here is more info on how to do it. Your code should look like this, after removing all unused properties:

data class ResponseInstaByTag(
        @field:SerializedName("data")
        val data: List<DataItem>
)


data class DataItem(
        @field:SerializedName("images")
        val images: Images
)


data class Images(
        @field:SerializedName("standard_resolution")
        val standardResolution: StandardResolution
)


data class StandardResolution(
        @field:SerializedName("url")
        val url: String
)

2. Define API service interface:

interface InstagramApiService {
    @GET("tags/{tag}/media/recent?access_token=YOUR_ACCESS_TOKEN")
    fun getPicsByTag(@Path("tag") tag: String): Single<ResponseInstaByTag>
}

3. Initialize HTTP client Retrofit. The whole main module should look like this:

@Module
public abstract class MainActivityModule {


    private static String BASE_URL = "https://api.instagram.com/v1/";


    @MainActivityScope
    @Provides
    static Retrofit providesRetrofit() {
        return new Retrofit.Builder()
                .baseUrl(BASE_URL)
                .addConverterFactory(GsonConverterFactory.create())
                .addCallAdapterFactory(RxJava2CallAdapterFactory.create())
                .build();
    }


    @MainActivityScope
    @Provides
    static MainActivityView providesMvpView() {
        return new MainActivityView();
    }


    @MainActivityScope
    @Provides
    static InstagramApiService providesInstagramApiService(Retrofit retrofit) {
        return retrofit.create(InstagramApiService.class);
    }


    @MainActivityScope
    @Provides
    static Scheduler providesScheduler() {
        return Schedulers.io();
    }


    @MainActivityScope
    @Provides
    static GetPicturesByTagUseCase providesGetPicturesByTagUseCase(Scheduler scheduler,
                                                                   InstagramApiService instagramApiService) {
        return new GetPicturesByTagUseCase(scheduler, instagramApiService);
    }


    @MainActivityScope
    @Provides
    static MainActivityModel providesMvpModel(GetPicturesByTagUseCase getPicturesByTagUseCase) {
        return new MainActivityModel(getPicturesByTagUseCase);
    }


    @MainActivityScope
    @Provides
    static MainActivityPresenter providesMvpPresenter(
            MainActivityModel model,
            MainActivityView view
    ) {
        return new MainActivityPresenter(model, view);
    }


    @MainActivityScope
    @Binds
    abstract Context bindsContext(SampleMvpActivity activity);
}

4. Fetch images from Instagram:

class MainActivityPresenter @Inject constructor(
        private val model: MainActivityModel,
        view: MainActivityView
) : Presenter<MainActivityView>(view) {


    private var disposableApiService: Disposable? = null
    private val tagName = "sky"


    override fun bind(intentBundle: Bundle, savedInstanceState: Bundle, intentData: Uri?) {
        loadPictures(tagName)
    }


    private fun loadPictures(tag: String) {
        disposableApiService = model.getPicturesByTag(tag)
                .subscribe(
                        { imagesList ->
                            val links = imagesList.data.map { dataItem -> dataItem.images.standardResolution.url }
                            presentedView.startSlideShow(links)
                        },
                        { handleError(it) }
                )
    }
}

5. For starting slideshow we can use Interval operatorObservable.interval(delaySlideshow, TimeUnit.SECONDS. It will run loadImage() method every 3 seconds. Please pay attention to that we first load a picture and after we make a skew transformation on it. Why? Because if we'll not transform picture, we'll lose the previous state of a transformation. Add this code to MainActivityPresenter

fun startSlideShow(urls: List<String>) {
        val delaySlideshow = 3L
        disposableTimer = Observable.interval(delaySlideshow, TimeUnit.SECONDS)
                .observeOn(AndroidSchedulers.mainThread())
                .map { getNextPictureUrl(currentIndex, urls) }
                .flatMap { url -> loadBitmapByUrl(url) }
                .map { bitmap -> skewBitmap(bitmap, skewX, skewY) }
                .subscribe(
                        { bitmap -> presentedView.showPicture(bitmap) },
                        { handleError(it) }
                )
    }


private fun getNextPictureUrl(urls: List<String>): String {
        if (currentIndex >= urls.size) currentIndex = 0
        return urls[currentIndex++]
}


private fun loadBitmapByUrl(url: String): Observable<Bitmap> {
        return Observable.create<Bitmap> { emiter ->
            Picasso.with(context).load(url).into(object : Target {
                override fun onBitmapLoaded(bitmapParam: Bitmap, from: LoadedFrom?) {
                    emiter.onSuccess(bitmapWithTransformation)
                }
                override fun onPrepareLoad(placeHolderDrawable: Drawable?) {}
                override fun onBitmapFailed(errorDrawable: Drawable?) {
                    emiter.onError(IllegalStateException("Bitmap loading has failed"))
                }
            })
        }
}

6. Show loaded and transformed pictures on a screen. Add this code to MainActivityView:

fun showPicture(bitmap: Bitmap) = slideShowImage.setImageBitmap(bitmap)

7. Always remember to dispose of disposables in a Presenter class to avoid memory leaks:

override fun unbind() {
        super.unbind()
        disposableApiService?.dispose()
        disposableTimer?.dispose()
}

8. Connect Chromecast to the projector. In your phone go to Settings -> Connected devices -> Cast -> Select your Chromecast.

So now we have a slideshow on almost any 3d object in our room.

Organizers have told that that's not the last CanonHackathon in Poland. A lot of teams had few ideas but had time to implement only one.

Have you ever tried to do some video mapping projects? Would you like to try? Do you find Instagram API easy to use? What would you change or add in that prototype app? Feel free to share your experience.

Day by day our applications have to do more and more complicated tasks without compromising their responsiveness. That’s why we need to know how to make the best use of power that awaits our devices. We can do it by utilizing concurrency through the usage of Grand Central Dispatch or Operations. Today we will talk about Operations.

Operation

Simply put, Operation is a wrapper around some work that we would like to execute. Speaking more formally it is an abstract class that when subclassed will perform a given task for us. It’s built atop of the Grand Central Dispatch, which allows us to focus less on details of how concurrent execution will be done and more on the implementation of our business logic. Operations can help us with tasks that require more time to complete such as network calls or data processing.

Block operation

A very simple example of Operation is Block Operation. Sometimes we may think that a task that we would like to do is just too small to create Operation object for it — that’s when we can use the Block Operation.

import UIKit

let printerOperation = BlockOperation()

printerOperation.addExecutionBlock { print("I") }
printerOperation.addExecutionBlock { print("am") }
printerOperation.addExecutionBlock { print("printing") }
printerOperation.addExecutionBlock { print("block") }
printerOperation.addExecutionBlock { print("operation") }

printerOperation.completionBlock = {
    print("I'm done printing")
}

let operationQueue = OperationQueue()
operationQueue.addOperation(printerOperation)

In this playground example, we create a printerOperation as our BlockOperation object, then we add to it blocks of code that will be part of this operation. After adding all of the blocks we set the completion block that will be executed after operation finishes. Now the only thing missing is starting our operation and to do so we create an Operation Queue object. We will go into details of what exactly the Operation Queue is but for now think about it as a queue that waits for operations to get added to it and then executes them on a separate thread. If we were to run this example a few times in a row we would get a different order of printed words because the order isn’t guaranteed here. We will later see how to control the order of task execution inside an Operation Queue.

Creating custom Operation objects

Synchronous operation

Sometimes using the BlockOperation simply won’t be enough. For example when we want to keep our code decoupled in order to be able to swap operations depending on our needs or when we would like to make our operation more generic. That’s when we need to define a custom operation object. When we create our own subclass of the Operation the least we have to do is to override its main method by putting the implementation of our task inside of it and handle the possibility that it was canceled. We will talk more about cancelation later down the road.

To make our operations nicely organized we can add properties, initializers, and helper methods. Here we have an example of the Operation that adds a filter to an image.

import UIKit

class MonoImageOperation: Operation {

    var inputImage: UIImage?
    var outputImage: UIImage?

    init(inputImage: UIImage) {
        self.inputImage = inputImage
    }

    override public func main() {
        if self.isCancelled {
            return
        }
        outputImage = applyMonoEffectTo(image: inputImage)
    }

    private func applyMonoEffectTo(image: UIImage?) -> UIImage? {
        guard let image = image,
            let ciImage = CIImage(image: image),
            let mono = CIFilter(name: "CIPhotoEffectMono",
                                 withInputParameters: [kCIInputImageKey: ciImage])
        else { return nil }

        let ciContext = CIContext()
        guard let monoImage = mono.outputImage,
            let cgImage = ciContext.createCGImage(monoImage, from: monoImage.extent)
        else { return nil }

        return UIImage(cgImage: cgImage)
    }
}

Now let’s take a look at how we can use our brand new operation.

import UIKit

class ViewController: UIViewController {

    @IBOutlet weak var imageView: UIImageView!

    override func viewDidLoad() {
        super.viewDidLoad()

        let image = UIImage(named: "image-1.jpg")
        let monoImageOperation = MonoImageOperation(inputImage: image!)
        monoImageOperation.completionBlock = {
            DispatchQueue.main.async {
                self.imageView.image = monoImageOperation.outputImage
            }
        }
        let operationQueue = OperationQueue()
        operationQueue.addOperation(monoImageOperation)
    }
}

An important thing to note here is that inside of the completion handler we are setting the imageView’s image property to the output of our operation on the main queue because every UI related change has to happen there.

Now that we know how to create a custom Operation, it’s important to understand its lifecycle.

Operation states

Every operation has states that change throughout the course of its execution. When we instantiate an operation we set its state to isReady. Later when we decide to run our operation, its state switches to isExecuting. Next, it can go down two ways: we can decide to cancel our operation, or we can wait and let it finish — in both cases we end up with isFinished status. We’ll discuss canceling in more detail after the next example.

Using synchronous operations we don’t have to worry about states because they are being handled for us by the system. It’s not the case with an asynchronous operation, that’s why it’s important to know how and when the operation states change.

Asynchronous Operation

Some long-running tasks, such as network calls, require us to make our operation asynchronous. We need to do it because if we were just to call an asynchronous method from regular Operation’s main() method it would think that it’s completed right away, as asynchronous calls return immediately.

Because an operation queue that’s running our operations can’t tell when it’s done with an asynchronous call, we need to notify it about the operation’s state changes through KVO.

To make our operation asynchronous we need to override the following method and properties:

This property explicitly says that our operation is going to be asynchronous.

2. isExecuting

This property has to be overridden by us because in the case of asynchronous operations we must handle state changes on our own. It states whether an operation is currently executing.

3. isFinished

Similar to isExecuting, we have to override isFinished in order to take care of changing the operation state. This property demonstrates whether the operation is already finished.

4. start()

This method is the place where our operation begins. We’re responsible for checking if it wasn’t canceled, then changing its state to isExecuting and generating KVO notifications. After that, we have to call an asynchronous method right away or the main method with an asynchronous method inside it which gives us a nicer code organization.

import Foundation

class AsyncOperation: Operation {
    public enum State: String {
        case ready, executing, finished

        fileprivate var keyPath: String {
            return "is" + rawValue.capitalized
        }
    }

    public var state = State.ready {
        willSet {
            willChangeValue(forKey: state.keyPath)
            willChangeValue(forKey: newValue.keyPath)
        }
        didSet {
            didChangeValue(forKey: oldValue.keyPath)
            didChangeValue(forKey: state.keyPath)
        }
    }
}

Here we can see an Operation subclass called AsyncOperation which will be a base for an asynchronous operation that we will create in the next example. We added a computed property state that will generate proper KVO notifications before and after the state changes so we won’t have to worry about doing it manually. These notifications are being used by the OperationQueue for handling operations.

extension AsyncOperation {

    override var isAsynchronous: Bool {
        return true
    }

    override var isExecuting: Bool {
        return state == .executing
    }

    override var isFinished: Bool {
        return state == .finished
    }

    override func start() {
        if isCancelled {
            return
        }
        main()
        state = .executing
    }
}

Next, we have an extension inside which we override the necessary properties and start() method as described at the beginning of this section.

This operation subclass was taken from one of Ray Wenderlich’s tutorials.

Now let’s see how we can use this base class to create an actual asynchronous operation.

import UIKit

class AsyncImageDownloadOperation: AsyncOperation {

    var downloadedImage: UIImage?

    override func main() {
        let defaultSession = URLSession(configuration: .default)
        guard let imgUrl = URL(string: "https://unsplash.com/photos/M9O6GRrEEDY/download?force=true") else { return }
        let dataTask = defaultSession.dataTask(with: imgUrl) { (data, response, error) in
            if let error = error {
                print("Image download encountered an error: \(error.localizedDescription)")
            } else if let data = data, let response = response as? HTTPURLResponse,
                response.statusCode == 200 {
                if self.isCancelled {
                    self.state = .finished
                    return
                }
                let image = UIImage(data: data)
                self.downloadedImage = image
                self.state = .finished
            }
        }
        dataTask.resume()
    }
}

As discussed above inside main() method we have an asynchronous method, in this case, some image downloading code. Inside the dataTask call, we check if the operation wasn’t canceled in the meantime — if it was then we return without setting the downloadedImage. Each state change sends KVO notifications through the computed state property inside the AsyncOperation class.

To actually use an object of this class we should add it to an operation queue, and we already know how to do it, but we didn’t yet talk in detail about what an operation queue is.

Operation Queue

Operation Queue is a special queue to which we can add our operations to have them executed on a separate thread. It is a kind of FIFO queue but we don’t have any certainty about the exact order execution. If we would like to have one operation executed faster than the other, we can make use of a queue priority.

Queue priority has to be set on the operation before adding it to an operation queue.

We can pick from one of 5 priorities:

1. veryLow
2. low
3. normal
4. high
5. veryHigh

By default, an operation has normal queuePriority.

On the chart above we have an example of adding multiple processes with different priorities to an operation queue. As we can see tasks with higher priority are getting executed faster. We can limit the number of operations being executed concurrently inside a queue by setting its maxConcurrentOperationCount property. For example, making it equal one would make the queued serial. There is also an option to make queue wait for all of its operations to complete, but keep in mind that it will block the current thread.

If we would like to cancel all tasks that are currently inside an operation queue we can do so by calling its cancelAllOperations() method. This method is the reason why we check if the operation isn’t canceled before starting it because there may be a case when it was waiting for its turn inside a queue but got canceled before even starting. We also have an option to suspend a queue preventing it from starting any queued operations, but operations that are already executing will continue to do so. Even if our operation queue is suspended, we can keep adding new operations to it, however, it will not start any of them until we will set its isSuspended property to false.

Quality of Service

Through the usage of qualityOfService we determine which object will get faster access to resources such as network, CPU time, disk resources, and so on. We can set the quality of service to a certain operation object or to the whole operation queue. If the operation has its qualityOfService property set then it will be used instead of the queue’s qualityOfService.

We can pick one of five options:

Used for things that have to be provided to the user as fast as possible such as drawing to the screen or processing control events

2. userInitiated

Used for a user-requested work — for example loading a recipe after a user has selected it on the recipes list.

3. utility

Used for work that the user is willing to wait longer for such as exporting a bulk file.

4. background

Used for work that is not visible to the user — syncing with remote database or pre-fetching content.

5. default

This is the one that will be assigned to the object that got no qualityOfService assigned by us — but it’s something that won’t happen in our case because both Operation and Operation Queue have a default background qualityOfService.

It’s important to choose the right qualityOfService for the job that our operation or operation queue should do because it can have both a positive or negative impact. If we are doing some resource-heavy operation that is important for the user we need to pick the userInitiated, but doing so for something not important because we feel like it may help will only waste battery.

Summary

Concurrency programming isn’t easy but with the right tools, such as the Operations we can make good use of it without worrying too much about all the details happening under the hood. Now that we know the basics of Operations we will be able to tackle more complicated (and fun) cases in the next post!

In this article, I would like to describe a development process that helps speed up the delivery of an iOS application. Organization and proper project structure are especially important while working with a large group of developers divided into multiple teams.

The problem

An application’s root components are user interface, the business logic behind, and communication with services over a network. Multiple separate teams must work together, each with their own speed and workflow. As a result, a lot of time is being wasted on synchronization among them.
Have you ever been blocked by other team members because you were waiting for certain endpoints or designs? Yes, so have I.

I would like to focus on the cooperation between mobile and backend developers. An implementation plan, an API design, and documentation are the first things every team must create at the beginning. This will work in the initial phase, but at some point, something will go wrong — the only question is when. Especially in the later stages, some changes and adjustments are going to be made that will force to redesign and reimplement things from scratch.

I will address how to resolve these problems using frameworks and mocks. In this method, a developer can switch between a mocked and real backend at a time of his choosing. The main advantage is that neither backend nor mobile team doesn’t block each other while changing the current implementation.

Frameworks

Using frameworks has many advantages. The most important is code separation: you are one hundred percent sure that the target contains only the necessary code and no other dependencies.

It is especially useful while separating the application from the network layer. If your application implements other independent functionalities you can extract them into submodules as well.

Another thing is shorter compilation time — code changes in one framework won’t force another to be recompiled. You can read more about using frameworks here.

Frameworks are independent of the type of project pattern you are using (MVC, MVP, MVVM, etc.) — network layer separation will work with any of them.

The below figure shows the project structure of a sample application.

1. SampleApp project contains the main application code: a user interface, the business logic, the database, etc. It also contains unit and UI tests related to the application itself.
2. The networking framework contains all classes that wrap up communication with external web services, data parsing, and validation. Unit tests are separated as well so that they won’t get mixed with application tests.

Below I described each component in detail along with the most significant code snippets.

Models are the data structures exchanged between the application and the backend — usually represented by JSON or XML. You can use whichever parser you prefer. In this example, the model conforms to the Codable protocol.

A networking class is a public interface exposed to an application. It uses a Facade pattern where only some relevant methods are accessible while its internal logic is hidden. This enforces and guarantees better code separation in contrast to a single module.

Configuration structure

1. useMockedApiClient — determines which API client to use: the mocked or the backend one. You can switch between them by setting the property in only one place.
2. mockedRequestDelay — the time after a mocked request is returned. It simulates communication latency between the server and the application over a network. It can be set to 0 for development in order not to waste time on loading so that new features can be tested quickly. The most important thing is having this property set to a huge value e.g. 10 seconds, and then testing if the application works correctly with a poor network connection. You can test if the user interface components are blocked and spinners displayed at a proper time. This wouldn’t be easy using a real connection or other tools that simulate network latency.

Networking class

1. configuration — described above.
2. apiClient — the API client that communicates with the real backend.
3. mockedAPIClient — the client that uses mocked data.
4. client — the public property exposed to the application in order to communicate with either the real or mocked backend depending on the useMockedApiClient property.

The most important component is the API client, which is responsible for the communication with the backend. The goal is to have two different implementations of the API client: real and mocked.

APIClient contains the definition of a public interface exposed to the application target.

1. accessTokenProvider — the access token storage.
2. authentication, products — the group of endpoints divided into categories.

BackendAPIClient — the client that communicates with the backend.

Endpoints are grouped into categories, in this example, there are named Authentication and Products.

MockedAPIClient — the client that uses mocks.

Returns the data created by a mocked data factory. The main advantage is that you can control data you want to test the app with. For example, you can put very long texts, different variations of attributes representing your business logic, and check if everything is displayed inside the application properly.

Endpoints are grouped into categories. For simplicity, I’m showing only one group with a user authentication method.

Internal BackendAuthentication implementation communicates with the backend, parses the response, and handles errors.

Internal MockedAuthentication implementation creates and returns mocked data. Data can be loaded and parsed from local JSON files, but I encourage them to create data structures using factory class — MockedDatabase in this example. The main advantage of this is that it is easier to maintain model changes because they are validated during the compilation time. Mocked data can be modified and stored in memory as well: the developer can manipulate it during each launch session and all the changes made in one view will be reflected in others instantly.

There is a large number of available methods on how to mock network requests. Some of them are in the form of an external library and others require to be implemented by the developer. Below I’m presenting a few alternatives you can use to stub application with mocked data.

OHHTTPStubs

OHHTTPStubs is a library for stubbing network requests. One of the best features in this framework is a tool that allows simulating network speed — it is especially useful to test application behavior using a slow internet connection. Another great tool allows us to record network responses and create mocks from them! You can record entire communication with the server and turn its responses into mocks. It will be very easy to update or create new mocks in case of backend changes.
OHHTTPStubs is bound to NSURLSession, so you can use it with all popular networking frameworks like Alamofire and AFNetworking. OHHTTPStubs is available using CocoaPods and Carthage. More information is available on GitHub.

Kakapo

Kakapo allows mocking server behaviors and responses. Its usage is similar to OHHTTPStubs. It is bound with NSURLSession, as a result, it doesn’t require changing current application implementation. All you need to do is create a router which intercepts network request and returns mocked response. The router can be created and registered dynamically based on the current user input. It allows simulating real backend where mocked responses will be updated with changes users made during the application runtime! Kakapo is available using CocoaPods and Carthage. More information is available on GitHub.

WireMock

Mocking server with WireMock. Marco Santarossa in his great article describes a different approach on how to provide mocked data to an iOS application. The idea is to connect the application to a local server created using WireMock. The main benefit of this method is that neither test code nor data is embedded inside the application. Moreover, it doesn’t require to implement and maintain code responsible for delivering mocks.

Afterword

Frameworks separate the functionality into submodules, which makes code more readable. They shorten compilation time and are independent of a chosen project pattern. You can implement separated unit tests as well, which keeps coding much more cleaner.

Using a mocked backend is debatable: its relevance can be established for each project individually. Nevertheless, it saves a lot of time, especially while both the application and the backend are being developed at the same time. One team doesn’t have to stop working on features in case of either adjustments, deployment, or connection errors.

The market of wearable devices is growing fast and thus the knowledge of the Bluetooth Low Energy protocol, which is currently used for most of the short-ranged inter-device communication, is becoming essential for a mobile apps developer.

Recently, I got my hands on Xiaomi Mi Band 2 and, although the device has a dedicated app — Mi Fit, I couldn’t resist the urge to create my own one. In this article, I would like to walk you through the basics of creating it. Code snippets, which I’ll show you here, are simplified, but you can check out my full project here. Let’s get started!

Setup

When you want to do anything Bluetooth-related on iOS — CoreBluetooth framework is your best friend. Its central element is the CBCentralManager class, which is your entry point to discovering nearby peripherals — that is — Bluetooth devices that can be connected to an iOS device.

import CoreBluetooth

class MiService: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate {
    lazy var manager = CBCentralManager(delegate: self, queue: DispatchQueue.main, options: nil)
}

Note: MiService class will serve as a container for all Bluetooth-related logic and all methods and properties listed in snippets below should be added to it.

CBCentralManager is designed to communicate through delegate methods listed in the CBCentralManagerDelegate protocol. It has one non-optional method — centralManagerDidUpdateState(_:) — and that’s where we need to start. It’s called whenever the Bluetooth module in an iOS device changes its state — e.g. when you turn on or off Bluetooth in the Settings app. Additionally, it’s called just after the manager has been initialized. The state value that we want — in order to proceed — is .powerOn (so make sure to have your Bluetooth activated). When a manager is in that state, it can discover peripherals and connect to them.

Discovering nearby devices

Once in the correct state, we can scan for nearby peripherals with scanForPeripherals(withServices: options:) method. To receive its results we need to implement the next delegate method — centralManager(_: didDiscover: advertisementData: rssi:), which is called every time the manager discovers a new peripheral. Its second argument is an instance of CBPeripheral class, which corresponds to a certain peripheral. We can store all discovered peripherals in an array and e.g. display all of them in a table view to let the user choose the one he wants to connect to.

Note: If you’re having problems discovering your Mi Band, make sure it’s paired with your iOS device, then open Mi Fit app and navigate to Profile → Mi Band 2 (in My devices section) → Discoverable and make sure the Discoverable mode is on.

func centralManagerDidUpdateState(_ central: CBCentralManager) {
    if central.state == .poweredOn {
        manager.scanForPeripherals(withServices: nil, options: nil)
    }
}

var discoveredPeripherals: [CBPeripheral] = []

func centralManager(_ central: CBCentralManager, didDiscover peripheral: CBPeripheral, advertisementData: [String : Any], rssi RSSI: NSNumber) {
    print(peripheral)
    discoveredPeripherals.append(peripheral)
}

Connecting to a device

Assuming the user has chosen one of the discovered peripherals, we can use the manager’s connect(_: options:) method to connect to the chosen device bypassing the corresponding CBPeripheral instance as the first argument.

var miBand: CBPeripheral?

func connectToPeripheral(at index: Int) {
    manager.connect(discoveredPeripherals[index], options: nil)
}

func centralManager(_ central: CBCentralManager, didConnect peripheral: CBPeripheral) {
    manager.stopScan()
    miBand = peripheral
    peripheral.delegate = self
    peripheral.discoverServices(nil)
}

func centralManager(_ central: CBCentralManager, didFailToConnect peripheral: CBPeripheral, error: Error?) {
    print(error)
}

The result of the connect operation is returned through one of the two methods from CBCentralManagerDelegate protocol: centralManager(_: didConnect:), in case of success, or centralManager(_: didFailToConnect: error:), in case of failure. Assuming everything went well, we can stop scanning for nearby devices and save the connected peripheral in a variable for convenience.

Next, we should make our MiService implement CBPeripheralDelegate protocol, so it can become a delegate of the chosen peripheral and receive notifications about its state changes.

Bluetooth LE interface introduction

Bluetooth LE interfaces are arranged in services and characteristics. You can think about services as classes and characteristics as their properties/methods. Services encapsulate characteristics that have something in common. Both services and characteristics can be identified by their UUIDs. Bluetooth standard defines a specification called Generic Attributes (GATT), which contains definitions of some commonly used services, like Heart Rate service. Later you may notice, that for some of those standard services, Xcode will print their names in object descriptions, instead of UUIDs.

Unfortunately, Xiaomi didn’t document the BLE interface they’re using in the Mi Band 2. This means that, apart from GATT services, we have no reference to how provided services can be used. This means it all comes down to guessing and sniffing network communication of the official Mi Fit app. Fortunately, someone has already done that tedious work for us: people involved in the Gadgetbridge project. Thanks to their outstanding commitment, we have access to most features of Mi Band 2 (and also other wearable devices).

Discovering device interface

To be able to interact with a peripheral, you have to first discover its services with the peripheral’s discoverServices(_) method. All discovered services are available under the peripheral’s services property, once peripheral(_: didDiscoverServices: error:) method is called.

func peripheral(_ peripheral: CBPeripheral, didDiscoverServices error: Error?) {
    print(error ?? peripheral.services)
    peripheral.services?.forEach { service in
        peripheral.discoverCharacteristics(nil, for: service)
    }
}

Once we have a list of available services we can discover their characteristics. Discovered characteristics are available under services’ characteristics property, after receiving a call to peripheral(_: didDiscoverCharacteristicsFor: error:) method.

Reading device data

So far, we’ve just set things up, but this is where, finally, the fun begins. Once we have discovered a characteristic, we can read its value and/or register for notifications, which will be sent every time this value changes. But before you do either, it’s good to check what kinds of interactions (reading, notifying, writing, etc.) are available for a given characteristic — this information is stored in a characteristic’s properties property, which is an OptionSet of CBCharacteristicProperties.

func peripheral(_ peripheral: CBPeripheral, didDiscoverCharacteristicsFor service: CBService, error: Error?) {
    print(error ?? service.characteristics)
    service.characteristics?.forEach { characteristic in	
        if characteristic.properties.contains(.read) {
            peripheral.readValue(for: characteristic)
        }
        if characteristic.properties.contains(.notify) {
            peripheral.setNotifyValue(true, for: characteristic)
        }
    }
}

There is, however, one last setup step we need to perform. Reading a characteristic’s value is an asynchronous operation, so to receive the actual value we need to implement peripheral(_: didUpdateValueFor: error:) method from CBPeripheralDelegate protocol.

func peripheral(_ peripheral: CBPeripheral, didUpdateValueFor characteristic: CBCharacteristic, error: Error?) {
    let valueBytes: [UInt8] = value?.map { $0 }
    print("New value for: \(characteristic)")
}

When you run your application and connect to your band, you should see these kinds of logs:

New value for: <CBCharacteristic: 0x1c40bf620, UUID = 00000007-0000-3512-2118-0009AF100700, properties = 0x12,
value = <0c0b0000 00070000 00010000 00>, notifying = YES>

The bolded part is the new value of a given characteristic. This particular log entry describes the characteristic, which holds information about the number of steps and meters covered and kilocalories burned today. However, when analyzing these bytes, it’s important to keep in mind that the majority of today’s digital devices use little-endian byte ordering, which means that the least significant bytes of a number are on its left side. Each of the aforementioned values is stored on 4 bytes: steps count on bytes 1–4, meters on bytes 5–8, and kilocalories on bytes 9–12. So e.g. to read a number of steps we take bytes 0b, 00, 00, 00 as UInt8s.

<0c 0b000000 07000000 01000000>

Then we cast each to UInt32, shift numbers left bitwise by subsequent multiples of 8, starting from 0 and finally sum everything. I’ve created a simple extension, which does just that:

extension UInt32 {
    static func from(bytes: [UInt8]) -> UInt32? {
        guard bytes.count <= 4 else { return nil }
        return bytes
            .enumerated()
            .map { UInt32($0.element) << UInt32($0.offset * 8) }
            .reduce(0, +)
    }
}

So if you want to extract steps count inperipheral(_: didUpdateValueFor: error:) method you can do it like this:

let stepsCount = UInt32.from(bytes: Array(valueBytes[1...4]))

Controlling a device

As for controlling the behavior of the band, we can e.g. start a heart rate measurement. This can be done through the standard Heart Rate GATT service and its Heart Rate Control Point characteristic. First, we need to find that service and characteristic in our band’s peripheral object.

After that, it’s just a matter of calling writeValue(_ : for: type:) method peripheral object, with a sequence of 3 bytes, where the second byte indicates the single measurement and third acts as an “on” flag. The last parameter indicates the writing type — with or without a response. To pick the right type, you should check properties property of given characteristics, as sometimes only one of them is accepted.

func measureHeartRate() {
    guard let miBand = miBand, 
          let hrControlPoint = miBand.services?.first(where: { $0.uuid.uuidString == "180D" })?
                                     .characteristics?.first(where: { $0.uuid.uuidString == "2A39" }) else { return }
    miBand.writeValue(Data(bytes: [0x15, 0x2, 0x1]), for: hrControlPoint, type: .withResponse)
}

After that, your band should start blinking with a green light on its backside, which means, it’s actually measuring your heart rate. The measurement usually takes a few seconds and after that, you should receive its value in Heart Rate Measurement characteristic update notification (assuming that, you have registered for its notifications).

Wrap up

And that’s it! You now know how to create Bluetooth-enabled apps for iOS With just a bit of additional work, you can come up with something like this:

For more Mi Band 2 characteristics’ usage examples you can check out my full project or Gadgetbridge’s Mi Band 2 support class. If you have any questions, feel free to drop us an email.