Android Developer SDK

At last, PandwaRF has an Android SDK. The library is called gollum. You can include this library module to your Android project and develop your own application to drive your PandwaRF.

Complete PandwaRF API documentation can be found here.

Getting started

Gradle setup

In your project build.gradle, add the Repo Read URL for PandwaRF Gollum Android Lib:

allprojects {
    repositories {
        ...
        maven {
            // Repo Read URL for PandwaRF Gollum Android Lib
            url "https://mymavenrepo.com/repo/l8uzsKQuWwYGByPmlbZ4/"
        }
    }
}

In your application Module build.gradle, provide the gradle dependency: nrftoolbox

gollum

dependencies {
    ...
    // Gollum Lib components
    implementation 'de.greenrobot:eventbus:2.4.1'
    implementation 'com.comthings.pandwarf:nrftoolbox:{x.y.z}'
    implementation 'com.comthings.pandwarf:gollum:{x.y.z}'
    ...
}

Using the library

Permissions

Your application must be authorized to connect via bluetooth and to scan bluetooth devices, here is the list of permissions to grant before using the library

 - android.permission.BLUETOOTH_CONNECT
 - android.permission.BLUETOOTH_SCAN

Connection

All PandwaRF methods are accessible using a singleton instance of GollumDongle class.

BLE connection

Register for BLE callbacks (Connection/Disconnection/... events)

GollumDongle.getInstance(context).setBleManagerAppCallbacks(bleManagerCallbacks)

BLE scan for PandwaRF devices

        GollumDongle.getInstance(context).searchDevice(object : ScannerListener {
            override fun onSignalNewDevice(bluetoothDevice: ExtendedBluetoothDevice?) {
                // Here you can check if the detected device is your PandwaRF by checking the address and/or the name.
            }

            override fun onSignalUpdateDevice(p0: ExtendedBluetoothDevice?) {
            }

            override fun onSignalConnectedDevice(p0: ExtendedBluetoothDevice?) {
            }

            override fun onSignalEndScan(p0: Boolean, p1: Exception?) {
            }
        }, false)

Stop BLE scanning for PandwaRF devices

GollumDongle.getInstance(context).stopSearchDevice()

Open PandwaRF connection

        val bleAddress = "XX:XX:XX:XX:XX:XX"
        val autoconnect = false
        val reconnectIfError = true
        val refreshDeviceCacheBeforeConnect = false
        val useTxFifoQueue = false
        val hideBleAddress = false
        GollumDongle.getInstance(context)
            .openGollumBleDevice(bleAddress, autoconnect, reconnectIfError, refreshDeviceCacheBeforeConnect, useTxFifoQueue, hideBleAddress)

Close PandwaRF BLE connection

GollumDongle.getInstance(context).closeGollumBleDevice()

Pause PandwaRF connection

in your activity onPause() method

override fun onPause() {
...
        // If you want to keep BLE background connection
	if (!isKeepConnectionInBackgroundEnabled()) {
		Log.d(TAG, "BLE connection pause, going to background");
                // Warning: Do not call this if connected in USB
		GollumDongle.getInstance(context).pause()
	}	
...

Resume PandwaRF connection

in your activity onResume() method

override fun onResume() {
...
        // If you want to resume BLE background connection
	if (!isKeepConnectionInBackgroundEnabled()) {
		Log.d(TAG, "Auto reconnect - onResume() - to last BLE mac address")
		GollumDongle.getInstance(context).reconnect("")
	}	
...

USB connection

Register for USB callbacks

GollumDongle.getInstance(getActivity()).setUsbManagerAppCallbacks(usbManagerCallbacks)

React to USB events

When USB is connected/disconnected, the following methods are called

public void onUsbDeviceConnected(String deviceName);
public void onUsbDeviceDisconnected(String deviceName);

Warning about USB Pause

Do not call the pause() method if you are connected in USB.

@Override
override fun onPause() {
...
  // Warning: Do not call pause() if connected in USB
  //GollumDongle.getInstance(context).pause()
...

App closing

in your activity onDestroy() method

@Override
override fun onDestroy() {
...
   GollumDongle.getInstance(context).destroy()
...

Communication with PandwaRF

Send data

// You must execute it from a separated thread. /!\ Not from the UI Thread /!\

GollumDongle.getInstance(context).txSetup(freq, mod, datarate, deviation)
GollumDongle.getInstance(context).setTxInfiniteMode(0,GollumDongle.getInstance(context).isPandwaRfRogue(), 0)
// txSend() takes an ASCII buffer as input
// 1 byte = 2 hex digits ==> Eg. "0xAB0F" is stored in data[] as [0x41, 0x42, 0x30, 0x46, ...]
byte[] data = { 0x41, 0x42, 0x30, 0x46, ... };
GollumDongle.getInstance(context).txSend(bytesArray, bytesArray.size, true)

Receive data

Receive from a separated thread:

GollumDongle.getInstance(context).rxSetup(freq, mod, drate, frameLength)
GollumDongle.getInstance(context).setRxInfiniteMode(0, GollumDongle.getInstance(context).isPandwaRfRogue())
while(true) {
    byte[] bufferHex = ByteArray(frameLength)    // Hex buffer : range [0x00 to 0xFF]
    val rx_size = GollumDongle.getInstance(context).rxListen(bufferHex , frameLength)

    // Convert buffer to ASCII. Since 1 byte is coded in 2 ASCII digits, bufferAsciiStr size = bufferHex size * 2
    val bufferAsciiStr = Utils.byteArrayToHexString(bufferHex, rx_size)

}

Receive from UI thread:

// For capture sync
        // set async mode to off (capture sync).
        GollumDongle.getInstance(applicationContext).writeAsyncMode(Hex.hexStringToByteArray("0"))
        // set the freq finder rssi threshold + rx rssi threshold, here the matter is the rx rssi
        // possible values for rx rssi are: [-93, -90, -86, -80, -74, -70, -64]
        GollumDongle.getInstance(applicationContext).writeRxRssiThreshold(-86, -86)
        GollumDongle.getInstance(applicationContext).rxSetup(frequencyHz, modulation, datarate, frameLength, bandwidthHz, deviation, false) { res, exception ->
            GlobalScope.launch {
                withContext(Dispatchers.IO) {
                    GollumDongle.getInstance(applicationContext).setRxInfiniteMode(0, GollumDongle.getInstance(context).isPandwaRfRogue)
                    var rx_size = 0 // Hex buffer : range [0x00 to 0xFF]
                    var bufferHex = ByteArray(frameLength)
                    while (true) {
                        rx_size = GollumDongle.getInstance(applicationContext).rxListen(bufferHex, frameLength)
                        if (rx_size > 0) {
                            // data received, do something
                        }
                    }
                }
            }
        }

Spectrum Analyzer

// Set the delay between each RSSI packet
GollumDongle.getInstance(context).rfSpecanSetPktDelay(0, pktDelayMs) { res, exception ->
    if (exception == null) {
        // Success
    }
}

...

// Kick the SpecAn
GollumDongle.getInstance(context).rfSpecanStart(0, startFrequencyHz, incHz, specchans, measInterval)

...

// Store data (do this from background thread)
while (true) {
  // Array to store RSSI values
  val rssi_buffer = ByteArray(specchans)
  val numRssiMeas = GollumDongle.getInstance(context).rfSpecanGetRssi(rssi_buffer, specchans)
  // Now display the data...
  ...
}

...

// Stop the SpecAn
 GollumDongle.getInstance(context).rfSpecanStop(0) { res, exception ->
    Log.d("SpecAn successfully stopped")
}

Brute Force

GollumDongle.getInstance(context).rfBruteForceAttackStart(0, rfSetupParams, bfStartParams) { res, exception ->
    Log.d("Brute Force successfully started")
}
...

// Get Brute Force status: do this from background thread
GollumDongle.getInstance(activity).rfBruteForceAttackStatusUpdate(0) { status, exception ->
     Log.d("New Brute force Status update: $status")
}   

...

GollumDongle.getInstance(activity).rfBruteForceAttackStop(0) { res, exception ->
    Log.d(Brute Force finished: $res")
}

Check the API documentation

PandwaRF API documentation can be found here.

Check our Sample Android Applications (Under maintenance /!)

Sample Android Application

• Spectrum Analyzer sample application
• RX/TX sample application
• JavaScript sample application