Skip to content

# Adding to Your Android Studio Project

The Nix Universal SDK is provided as a Maven repository. You may install the library from Maven Central, or the provided `nixrepo.zip` archive can be unzipped and used as a local folder-based repository.

Tip

The latest stable version of the Nix Universal SDK is hosted on Maven Central. It is recommended to install from this source.

## Review the End User License Agreement

Before proceeding, review and accept the End User License Agreement.

## Add dependency from Maven Central

- Ensure that the `mavenCentral()` repository is available to your project. This is typically set in the `dependencyResolutionManagement` section of your project's `settings.gradle` file; it is usually already included by default.

    dependencyResolutionManagement {
        repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
        repositories {
            google()

            // Ensure that Maven Central is included
            mavenCentral()
        }
    }

- Add the `com.nixsensor:universalsdk` dependency to your app level `build.gradle` file

    dependencies {
        // Your existing dependencies here
        // ...

        // Nix Universal SDK
        implementation 'com.nixsensor:universalsdk:4.2.0'
    }

## Optional: Add dependencies for USB support

The Nix Universal SDK can communicate with devices directly attached via USB. This feature relies on the `usb-serial-for-android` library; USB support is automatically enabled once this library is included in your project.

Tip

If you do not require connections to USB attached devices, you can skip this step.

Warning

Prior to Nix Universal SDK version 4.2.0, the `usb-serial-for-android` dependency was included automatically. For SDK version 4.2.0 and later, it is optional and must manually be added to your project if USB support is needed.

- Add the `jitpack.io` repository to your project, typically in the `dependencyResolutionManagement` section of your project's `settings.gradle` file.

    dependencyResolutionManagement {
        repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
        repositories {
            google()
            mavenCentral()

            // Optional: Jitpack repo needed for usb-serial-for-android
            maven { url 'https://jitpack.io' }
        }
    }

- Add the `usb-serial-for-android:v3.8.1` dependency to your app level `build.gradle` file.

    dependencies {
        // Your existing dependencies here
        // ...

        // Nix Universal SDK
        implementation 'com.nixsensor:universalsdk:4.2.0'

        // Optional: Enables USB support in Nix Universal SDK
        implementation 'com.github.mik3y:usb-serial-for-android:v3.8.1'
    }

## Requesting required permissions

As of Android SDK version 23 (Marshmallow), certain permissions must be requested from the user at run-time, including those necessary for discovering nearby Bluetooth devices.

- These permissions must be requested at runtime prior to using the `DeviceScanner` class.
- The specific permissions to request depend on the Android version. The `getRequiredBluetoothPermissions()` property getter provides this list of permissions at runtime (see Kotlin or Java APIs).
- A helper function `requestBluetoothPermissions` is provided to request the appropriate permissions depending on the currently running Android version (see Kotlin or Java APIs).
- The helper function `isBluetoothPermissionGranted` is provided to check if these permissions have already been granted by the user (see Kotlin or Java APIs).

Warning

Device discovery will be impossible if the required permissions are not granted by the user.

The following example code requests these permissions at the creation of an `Activity`. Note that requesting this permission does not need to occur immediately at the beginning of your `Activity`, but simply needs to be performed prior to using the `DeviceScanner` class.

Kotlin Java

    companion object {
        // Define a constant value of your choice here
        const val PERMISSION_REQUEST_BLUETOOTH = 1000
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // ...

        // Request Bluetooth permissions if necessary
        if (!IDeviceScanner.isBluetoothPermissionGranted(this)) {
            IDeviceScanner.requestBluetoothPermissions(
                activity = this,
                requestCode = PERMISSION_REQUEST_BLUETOOTH
            )
        }
    }

    override fun onRequestPermissionsResult(
        requestCode: Int,
        permissions: Array<out String>,
        grantResults: IntArray
    ) {
        super.onRequestPermissionsResult(requestCode, permissions, grantResults)

        // Check if all requested permissions have been granted
        var allGranted = true
        for (result in grantResults) allGranted =
            allGranted and (result == PackageManager.PERMISSION_GRANTED)

        when (requestCode) {
            PERMISSION_REQUEST_BLUETOOTH -> {
                if (allGranted) {
                    // All permissions granted, OK to use `DeviceScanner`
                    // ...
                } else {
                    // Handle permission denial
                    // ...
                }
            }
        }
    }

    // Define a constant value of your choice here
    private static final int PERMISSION_REQUEST_BLUETOOTH = 1000;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // ...

        // Request Bluetooth permissions if necessary
        if (!IDeviceScanner.Companion.isBluetoothPermissionGranted(this)) {
            IDeviceScanner.Companion.requestBluetoothPermissions(
                this,
                PERMISSION_REQUEST_BLUETOOTH);
        }
    }

    @Override
    public void onRequestPermissionsResult(
        int requestCode,
        @NonNull String[] permissions,
        @NonNull int[] grantResults
    ) {
        super.onRequestPermissionsResult(requestCode, permissions, grantResults);

        // Check if all requested permissions have been granted
        boolean allGranted = true;
        for (int result : grantResults) {
            allGranted &= (result == PackageManager.PERMISSION_GRANTED);
        }

        switch (requestCode) {
            case PERMISSION_REQUEST_BLUETOOTH: {
                if (allGranted) {
                    // All permissions granted, OK to use `DeviceScanner`
                    // ...
                } else {
                    // Handle permission denial
                    // ...
                }
            }   break;
        }
    }

## Next steps

- Activating the SDK License