DEPZ Stereo Vision Logo

Sensors SDK Documentation

Documentation for the DEPZ USB sensor SDKs in Python, JavaScript (TypeScript), C#, Java, C, C++ and Rust: installation, hands-on guides with examples, full API references — dedicated pages for each sensor, the Android SDK and the ROS 2 package.

View on GitHub

depz-sensor-sdk-android brings the DEPZ USB sensor boards to Android 12 and newer (API 31+), over the phone's or the board computer's USB host port. It is a Kotlin library on top of the Java SDK: the protocol, the drivers and the decoding are the Java SDK's — and so are the measurement types — and this package adds what Android needs: the USB transport (CDC-ACM over UsbManager), discovery, the USB permission, and an API for Kotlin (suspend functions, Flow) and for Java (callbacks, listeners). No JNI, no native code, no root.

Install

Maven Central, io.github.depz-ai:depz-sensor-sdk-android (Install has the requirements). In a standard Android Studio / Gradle project (Android Gradle Plugin 8.1 or newer, mavenCentral() among the repositories):

// build.gradle.kts of the app module
android {
    defaultConfig { minSdk = 31 }   // Android 12, or newer
}

dependencies {
    implementation("io.github.depz-ai:depz-sensor-sdk-android:1.0.0")
}

The Java SDK (io.github.depz-ai:depz-sensor-sdk, package ai.depz.sensor.*) and kotlinx-coroutines-core come with it as its dependencies; the desktop serial library of the Java SDK (jSerialComm) does not. No other setup: no core-library desugaring, no R8 rules, no native code. Install has the requirements, what the artifact brings into an app, and the build from the sources until it is published.

Quick start

Kotlin — the first attached board, opened and streaming:

suspend fun showDistance(context: Context) {
    val board = DepzAndroid.discover(context).firstOrNull() ?: return   // no DEPZ board attached
    try {
        DepzAndroid.open(context, board).use { sensor ->   // asks for the USB permission when needed
            if (sensor is Sr04Sensor) {
                sensor.start()
                sensor.measurements.collect { m -> Log.i("DEPZ", "${m.distanceMm()} mm") }
            }
        }   // collect returns when the sensor is closed
    } catch (e: UsbPermissionDeniedException) {
        Log.w("DEPZ", "the user refused the USB permission", e)
    } catch (e: DepzException) {
        Log.w("DEPZ", "the board failed or was unplugged", e)   // unplugged: DeviceLostException
    }
}

Java — no coroutines: a callback for the opened sensor, a listener for its stream, both called on the main thread:

ExecutorService background = Executors.newSingleThreadExecutor();

DepzUsbDevice board = DepzAndroid.discover(context).get(0);
DepzAndroid.open(context, board, new DepzCallback<DepzSensor>() {   // asks for the USB permission when needed
    @Override public void onResult(DepzSensor sensor) {             // main thread
        if (sensor instanceof Sr04Sensor sr04) {
            Cancellable subscription = sr04.measurements(new StreamListener<Sr04Measurement>() {
                @Override public void onItem(Sr04Measurement m) { show(m.distanceMm()); }    // main thread
                @Override public void onError(DeviceLostException e) { showUnplugged(); }   // the board is lost
                @Override public void onEnd() { }                                           // the sensor was closed
            });
            background.execute(() -> sr04.getDevice().start());     // a Java SDK call: it blocks
            // later: subscription.cancel(); sensor.close();
        }
    }

    @Override public void onError(Exception error) {                // UsbPermissionDeniedException, DepzException…
        showError(error);
    }
});

Permissions

No <uses-permission> and no manifest entry of the app's: USB host access is granted per device, by the user, in a system dialog. DepzAndroid.open shows it when the app does not hold the permission yet; requestPermission asks ahead of time:

val board = DepzAndroid.discover(context).first()
if (!DepzAndroid.hasPermission(context, board)) {
    val granted = DepzAndroid.requestPermission(context, board)   // the system's dialog
    if (!granted) return                                         // the user refused
}
val serial = DepzAndroid.device(context, board.usbDevice).serial   // readable from now on

A refusal is false here and a UsbPermissionDeniedException from open. A board unplugged while its dialog is open ends the wait: false here, a DeviceLostException ("…: device detached") from open. The permission is for the attached device: a board plugged in again is asked for again. Android hides the board's USB serial number until it is granted. The SDK's manifest declares <uses-feature android:name="android.hardware.usb.host" android:required="true">, merged into the app's: Google Play offers the app only to devices with a USB host port.

Supported boards

Every board of the DEPZ USB sensor line the Java SDK has a device class for — DepzAndroid.open returns the class of the board's family:

Board Class Stream
HC-SR04 (ultrasonic) Sr04Sensor measurements: Sr04Measurement
VL53L4CD (single-zone ToF) Vl53l4cdSensor measurements: Vl53l4Measurement
VL53L0X, VL53L1CX, VL53L1CB, VL53L3CX, VL53L4CX (1D ToF family) Vl53lxSensor measurements: Vl53lxMeasurement
VL53L5CX, VL53L7CX, VL53L7CH, VL53L8CX, VL53L8CH (8×8 ToF) Vl53l8Sensor frames: Vl53l8Frame
TMF8829 (multizone dToF) Tmf8829Sensor measurements: MeasurementBuilder.Measurement
BNO055 (9-axis IMU) Bno055Sensor samples: Bno055Sample
BNO085, BNO086 (9-axis IMU) Bno086Sensor reports: Reports.Report

Any other DEPZ board opens as a GenericSensor (its device is the Java SDK's DepzDevice). The measurement types, the configuration and the sensors' behaviour are the Java SDK's: its per-sensor pages apply as they are.

Where to next

  • Install — requirements, the dependency, what comes with it, building it from the sources.
  • Examples — the sample app: build it, run it from adb, where in its sources each thing an app does with a board is; the short snippets by task.
  • Guide — discovery, opening, each family's setup, threads and cancellation, an unplugged board and hot-plug, the Java API, recording, R8; and in the field: an OTG adapter and a powered hub, Google Play Protect, the permission dialog as the user meets it, a board that is not listed.
  • API reference — the KDoc of DepzAndroid, DepzSensor and the classes around them, in the IDE and as the artifact's -javadoc.jar (Dokka HTML).
  • Java SDK — the device classes under every DepzSensor (sensor.device) and each sensor's own pages.
  • Source & license — the SDKs are open source (MIT): github.com/depz-ai/depz-sensor-sdk, the Android package in its folder packages/depz-sensor-sdk-android.

We value your privacy

We use cookies to enhance your browsing experience, serve personalized content, and analyze our traffic. By clicking "Accept All", you consent to our use of cookies. View cookie policy details