Configure and Connect

Overview

You will need certain API calls regardless of your use case. These are related to configuring, connecting to, and disconnecting from the Tango service.

Before calling any other functions of the Tango API, you must do the following:

  1. Bind to and start the service.
  2. Define the configuration.
  3. Begin tracking data.

There is a fourth step that is optional: you can check the version of the Tango Core. If you choose to implement this, make it the first operation in the list and call it from the onCreate() method:

  1. Check the version of the Tango core.
  2. Bind to and start the service.
  3. Define the configuration.
  4. Begin tracking data.

The other three steps are required, and their order is important. You must follow it in order for your app to work properly. Each step is detailed below, along with the additional task of disconnecting from the service. Because the function calls relate to how your application starts, runs, and exits, the "Key Points" suggest where to put each function in the Android Activity Lifecycle.

Working with JNI

Because this topic is about calling into the C API, it requires knowledge of the Java Native Interface (JNI). We assume that you're familiar enough with JNI to make the appropriate JNI calls, and for the most part we don't detail them here. If you're new to JNI or would like some extra guidance, review the next section ("Check the installed version"), and then at the end of the section, click the drop-down icon next to Learn more about calling this library function using JNI.

This opens a section that provides a detailed explanation of how to use JNI to call the function in the Tango Support Library that gets the installed version of the Tango Core.

Check the installed version

TangoSupport_GetTangoVersion()

Check the installed version of the Tango core. If it's too old, it will not support the most up-to-date features. The core is backwards-compatible, so the version to check is the version you developed with.

int version = 0;
TangoErrorType err =
  TangoSupport_GetTangoVersion(env, caller_activity, &version);
if (err != TANGO_SUCCESS || version < kTangoCoreMinimumVersion) {
  // Handle the error
}

Bind to and start the service

TangoService_setBinder()

return context.bindService(intent, connection, Context.BIND_AUTO_CREATE);

The connection parameter above represents a ServiceConnection object. The bindService() method starts the service and returns immediately without a value, but when the Android system creates the connection to the Tango Service, it calls onServiceConnected() on the ServiceConnection object and delivers the IBinder object that the client uses to communicate with the service.

if (TangoService_setBinder(env, iBinder) != TANGO_SUCCESS) {
  // Handle the error.
}

For more information about binding, see Bound services in the Android documentation.

Set the configuration

TangoService_getConfig()

Define the configuration that your application needs. Configuration is handled by first getting the default or current configuration, and then setting any additional parameters you need.

tango_config_ = TangoService_getConfig(TANGO_CONFIG_DEFAULT);
if (tango_config_ == nullptr) {
  // Handle the error.
}

Common configuration types and parameters are:

// Configuration type enums for TangoService_getConfig().
TANGO_CONFIG_DEFAULT
TANGO_CONFIG_CURRENT
TANGO_CONFIG_MOTION_TRACKING

// Parameter types and names for TangoConfig get/set functions.
boolean "config_enable_auto_reset"          // Default: true
boolean "config_enable_depth"               // Default: false
boolean "config_enable_learning_mode"       // Default: false
boolean "config_enable_motion_tracking"     // Default: true
string "config_load_area_description_UUID"  // Default: empty

The following code shows an example of how to set a configuration parameter.

if (TangoConfig_setBool(config, "config_enable_auto_reset", true) != TANGO_SUCCESS) {
  // Handle the error.
}

Begin tracking data

TangoService_connect()

Start tracking data specified through the TangoConfig handle you initialized in the "Set the Configuration" section above. Make the data available through polling and callbacks.

if (TangoService_connect(nullptr, tango_config_) != TANGO_SUCCESS) {
  // Handle the error.
}

Disconnect from the service

Call TangoService_disconnect(). This frees the Tango service for other applications to use. TangoService_connect() must be called before you use the service again, which should be the case if you call it during onResume().

Send feedback about...

Tango C API
Tango C API