Android Client SDK

The Nabto Edge Android Client SDK is a Java abstraction on top of the underlying libnabto_client.so and nabto_client.h known from the Plain C Nabto Client SDK library.

This document describes installation and a quick intro. Also see the API Reference and full example apps, the thermostat app or the video streaming app.

Note: There is a “silent” breaking change when upgrading from Nabto Edge Android SDK 2.x to 3.0: The semantics of close() changes significantly and you must change your application accordingly. You will not discover the breaking change as a compile error - but as subtle errors in the field.

Installation

It is recommended to install through Gradle using the Maven Central repository.

Add the Edge Android Client SDK library to the individual projects where it is needed. That is, add a dependency in the project level build.gradle file:

...
dependencies {
    ...
    implementation 'com.nabto.edge.client:library:3.0.1'
}
...

We additionally offer a convenience library for Kotlin that is meant to be used with Kotlin coroutines. This library can also be added by using the Maven Central Repository and adding the following dependency to the project level gradle file.

implementation 'com.nabto.edge.client:library-ktx:3.0.1'

Hello, world!

This example client sets up a connection and connects to a device. It then makes a CoAP request to the device which has registered a CoAP endpoint called /hello-world (such as provided by the CoAP Hello, World device).

NabtoClient client = NabtoClient.create(...);
Connection connection = client.createConnection();
JSONObject options = new JSONObject();
options.put("ProductId", ...);
options.put("DeviceId", ...);
options.put("ServerConnectToken", ...);
options.put("PrivateKey", ...);
connection.updateOptions(options.toString());

connection.connect();
Coap coap = connection.createCoap("GET", "/hello-world");
coap.execute();

int statusCode = coap.getResponseStatusCode();
int contentFormat = coap.getResponseContentFormat();
byte[] payload = coap.getResponsePayload();

...

connection.close();

Note that the above example is overly simplified pseudo code: It does not handle errors - and it ignores the notion of access control (pairing): If connecting to any device with access control enabled (e.g., all but the examples named with a simple_ prefix), you must consider client/device pairing - please see the introduction to pairing and the “Connecting using Authentication” examples.

Hello, Kotlin!

If you are using Kotlin with library-ktx extensions then the above Hello World example can be written using coroutines:

NabtoClient client = NabtoClient.create(...);
Connection connection = client.createConnection();
JSONObject options = new JSONObject();
options.put("ProductId", ...);
options.put("DeviceId", ...);
options.put("ServerConnectToken", ...);
options.put("PrivateKey", ...);
connection.updateOptions(options.toString());

myCoroutineScope.launch {
  connection.connectAsync();
  Coap coap = connection.createCoap("GET", "/hello-world");
  coap.executeAsync();

  int statusCode = coap.getResponseStatusCode();
  int contentFormat = coap.getResponseContentFormat();
  byte[] payload = coap.getResponsePayload();
}

...

connection.close();

The async version of functions (such as the above coap.executeAsync()) are suspending functions that will suspend the execution of the enveloping coroutine until the function is finished. Using coroutines in Kotlin is the recommended way to avoid blocking the main thread on Android. See Kotlin coroutines on Android for further information.

The note above on error handling and access control / pairing in the Java example applies to this Kotlin example as well.

Error Handling

Errors from the underlying Nabto Edge Client SDK are passed to the application through exceptions that wrap the underlying error code.

Some functions accept an application callback, e.g. for the application to handle read stream data. The application must not throw exceptions in such callbacks. Any thrown exceptions are ignored as there is no meaningful way to propagate them to the underlying Nabto Edge Client SDK that invokes the callback function.