Chirp Connect Android SDK

The Chirp SDK for Android allows you to send and receive data from within your Android application. It communicates directly with the audio hardware to generate and receive data, played from the device’s speaker.

Getting Started

To get started with the Chirp SDK, you’ll first need to register for Chirp Application credentials. Sign up to the developer console at the Chirp Admin Center. Once signed in, you will have access to your app key and secret.

Step 1 - Copy the chirp-connect-3.3.2.aar file to your app/libs directory. Add the following to the dependencies block of your Module build.gradle Gradle script.

compile 'io.chirp.connect:chirp-connect-3.3.2@aar'
compile 'com.squareup.okhttp3:okhttp:3.9.0'

To instruct Gradle where to find the local .aar file, add flatDir section to the repositories block. (You’ll need to add a repositories block if one does not already exist.)

repositories {
  flatDir {
    dirs 'libs'
  }
}

Step 2 - To declare that your app requires audio permissions, add the following to your AndroidManifest.xml, inside the bottom of the <manifest> element. Please note that INTERNET and ACCESS_NETWORK_STATE permissions are not required if you already downloaded the licence from the Admin Centre.

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

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

Chirp SDK requires at minimum of Android 4.1.x which is Android API level 15.

Step 3 - Import the SDK.

import io.chirp.connect.ChirpConnect;
import io.chirp.connect.interfaces.ConnectEventListener;
import io.chirp.connect.interfaces.ConnectLicenceListener;
import io.chirp.connect.models.ChirpError;
import io.chirp.connect.models.ConnectState;

Step 4 - And instantiate the SDK with your own application key and secret.

String KEY = "YOUR_APP_KEY_HERE";
String SECRET = "YOUR_APP_SECRET_HERE";
String LICENCE = "YOUR_LICENCE_HERE";   //If you have one

ChirpConnect chirpConnect = new ChirpConnect(this, KEY, SECRET);

Step 5 - The licence must be set right after the SDK is instantiated. If you dont have the licence you can get it using getLicence method.

chirpConnect.getLicence(new ConnectLicenceListener() {

  @Override
  public void onSuccess(String networkLicence) {
    Log.d("getLicence", "onSuccess");
    ChirpError setLicenceError = chirpConnect.setLicence(networkLicence);
    if (setLicenceError.getCode() > 0) {
      Log.e("ChirpError:", setLicenceError.getMessage());
    }
  }

  @Override
  public void onError(ChirpError chirpError) {
    Log.e("getLicence", chirpError.getMessage());
  }
});

Otherwise, if you have the licence string you can set it directly.

ChirpError setLicenceError = chirpConnect.setLicence(LICENCE);
if (setLicenceError.getCode() > 0) {
  Log.e("ChirpError:", setLicenceError.getMessage());
}

Step 6 - To be able to send and receive data we need to implement the ConnectEventListener interface.

chirpConnect.setListener(new ConnectEventListener() {

  @Override
  public void onSent(byte[] payload) {
    Log.v("chirpConnectDemoApp", "This is called when a payload has been sent " + payload);
  }

  @Override
  public void onSending(byte[] payload) {
    Log.v("chirpConnectDemoApp", "This is called when a payload is being sent " + payload);
  }

  @Override
  public void onReceived(byte[] payload) {
    Log.v("chirpConnectDemoApp", "This is called when a payload has been received " + payload);
  }

  @Override
  public void onReceiving() {
    Log.v("chirpConnectDemoApp", "This is called when the SDK is expecting a payload to be received");
  }

  @Override
  public void onStateChanged(byte oldState, byte newState) {
    Log.v("chirpConnectDemoApp", "This is called when the SDK state has changed " + oldState + " -> " + newState);
  }

  @Override
  public void onSystemVolumeChanged(int old, int current) {
    Log.d("chirpConnectDemoApp", "This is called when the Android system volume has changed " + old + " -> " + current);
  }

});

Step 7 - We can now start the audio processing loop of the SDK in order to send or receive data. Please make sure that the licence is set before starting the SDK.

chirpConnect.start();

First we will generate some random data to send using the SDK. When the .send() method is called, Connect will encode the data and send it out through the device’s loudspeaker. The length of the data can be dynamic but should not exceed the size of the maximum payload length set by your licence configuration. The maximum payload length is returned by the .getMaxPayloadLength() method.

long maxLength = chirpConnect.getMaxPayloadLength();
byte[] payload = chirpConnect.randomPayload(maxLength);
chirpConnect.send(payload);

Step 8 - Requesting Permissions at Run Time Beginning in version 6.0 (API level 23), Android allows users to toggle apps permissions at run time. Also by default, some permissions will be disabled when the app starts up for the first time.

The RECORD_AUDIO permission, which is fundamental in the use of ChirpConnect, is an example of this. Therefore, it is important to check your app has RECORD_AUDIO permissions every time it is brought to the foreground.

We recommend using the android lifecycle methods, onResume() and onPause() to detect permissions and to trigger start and stopping listening. See the following.

@Override
protected void onResume() {
  super.onResume();

  if (ContextCompat.checkSelfPermission(this, Manifest.permission.RECORD_AUDIO) != PackageManager.PERMISSION_GRANTED) {
    ActivityCompat.requestPermissions(this, new String[] {Manifest.permission.RECORD_AUDIO}, RESULT_REQUEST_RECORD_AUDIO);
  }
  else {
    chirpConnect.start();
  }
}

@Override
public void onRequestPermissionsResult(int requestCode, String permissions[], int[] grantResults) {
  switch (requestCode) {
    case RESULT_REQUEST_RECORD_AUDIO: {
      if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
        chirpConnect.start();
      }
      return;
    }
  }
}

@Override
protected void onPause() {
  super.onPause();
  chirpConnect.stop();
}

Step 9 - Stop and close the SDK when activity is destroyed

In order to make sure the SDK will be closed, we need to call the close method to empty the memory and to delete the instance when the activity is destroyed.

@Override
public void onDestroy() {
  super.onDestroy();
  chirpConnect.stop();
  try {
    chirpConnect.close();
  } catch (IOException e) {
    e.printStackTrace();
  }
}

You are now ready to start using ChirpConnect in your own application.