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.1'
}

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.1'

    // 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.

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