Skip to content

1.2 Integrate the NIMMSTA Core Library into your application

In this section, we will guide you through the process of integrating the basic library parts into the Android application.

Requirements

  • This integration works with native Kotlin / Java Android Projects. For Xamarin or .NET MAUI, please consider using a websocket integration.
  • You should already have added the maven package to your project. Otherwise, see the previous section.
  • You have to use either Java or Kotlin for the integration, but we recommend using Kotlin as we are providing easy-to-use features there.

Integrate NIMMSTA Library into your activity

As a first step you bind the NIMMSTAServiceConnection to your Activity, which is connected to the NIMMSTAConnectionManager. The goal is to connect to the NIMMSTAConnectionManager, which controls the connection and communication with the Smart Watch.

You need to integrate the NIMMSTAServiceConnection in each Android Activity and each Android Service separately:

class MainActivity: Activity() {
    /* ... */
    private lateinit var serviceConnection: NIMMSTAServiceConnection
    /* ... */

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

        serviceConnection = NIMMSTAServiceConnection.bindServiceToActivity(this).onComplete {
            try {
                // this is the point in time when the (background) task completes and the result throws if an error occurred.
                it.result
            } catch (throwable: Throwable) {
                throwable.printStackTrace()

                Toast.makeText(
                    this@MainActivity,
                    throwable.message,
                    Toast.LENGTH_LONG
                ).show()
            }
        }
    }

    override fun onDestroy() {
        super.onDestroy()

        serviceConnection.close()
    }
}

class MainActivity: Activity() {
    /* ... */
    NIMMSTAServiceConnection serviceConnection;
    /* ... */

    @Override
    protected void onCreate() {
        super.onCreate();

        /* ... your onCreate code ... */

        serviceConnection = NIMMSTAServiceConnection.bindServiceToActivity(this)
            .onComplete(new NIMMSTADoneCallback<Task<NIMMSTAServiceConnection>>() {
            @Override
            public void onDone(Task<NIMMSTAServiceConnection> result) {
                try {
                    // this is the point in time when the (background) task completes and the result throws if an error occurred.

                    result.getResult();
                } catch (Throwable throwable) {
                    throwable.printStackTrace();

                    Toast.makeText(
                        MainActivity.this,
                        throwable.getMessage(),
                        Toast.LENGTH_LONG
                    ).show();
                }
            }
        });
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();

        serviceConnection.close();
    }
}

Integrate the connection activity

Now that the connection to the service is set up, you can start the connection setup with the NIMMSTA Smart Watch. The NIMMSTAServiceConnection is the main entry point to connect to the NIMMSTA Smart Watch. To initiate the connection process, you need to check for an active connection. If no connection exists, show the connection setup Activity.

serviceConnection = NIMMSTAServiceConnection.bindServiceToActivity(this).onComplete {
    try {
        it.result // Already added previously

        // Check if connected, if not show connection Activity
        if (!serviceConnection.isConnected) {
            serviceConnection.displayConnectionActivity()
        }
    } catch (throwable: Throwable) {
        // ... Already added previously
    }
}

serviceConnection = NIMMSTAServiceConnection.bindServiceToActivity(this)
    .onComplete(new NIMMSTADoneCallback<Task<NIMMSTAServiceConnection>>() {
    @Override
    public void onDone(Task<NIMMSTAServiceConnection> result) {
        try {
            result.getResult(); // Already added previously

            if (!serviceConnection.isConnected()) {
                serviceConnection.displayConnectionActivity();
            }
        } catch (Throwable throwable) {
            // ... Already added previously
        }
    }
});

Enable Background Notifications

If you want your app to keep the Bluetooth connection alive when the app is in the background, you need to add this line in the onComplete callback of bindServiceToActivity.

Note

To also show the notification, you have to request the permission to show notifications (android.permission.POST_NOTIFICATIONS) before and declare it in AndroidManifest.xml.

it.result.enableBackgroundAndNotifications()

result.getResult().enableBackgroundNotifications();

Integrate the event handler

To get informed by the library about any events regarding the NIMMSTA Smart Watch, you need to add the NIMMSTAEventHandler to your activity. This is a preparation for all upcoming chapters.

Note

There can be multiple classes that register event handlers at the same time, so make sure you are currently the controlling Activity.

class MainActivity: Activity(), NIMMSTAEventHandler {
    /* ... */

    override fun didConnectAndInit(device: NIMMSTADevice) {
        // this is the point in time when you can start interacting with your device.
    }

    /* ... */
}

class MainActivity extends Activity implements NIMMSTAEventHandler {
    /* ... */

    @Override
    public void didConnectAndInit(NIMMSTADevice device) {
        // this is the point in time when you can start interacting with your device.
    }

    /* ... */
}

NIMMSTA Device Basics

Before you start adding your application-specific code, you should know a few basic concepts around the devices:

  1. Every NIMMSTA Device is treated as a new, fresh device. We do not store settings on the device.
  2. Devices usually reconnect automatically as long as the app keeps running. Devices that reconnect preserve layout and preferred settings. They behave exactly the same as before they were disconnected.
  3. When connecting a device by scanning the QR Code it is always treated as a new device. Layout and preferred settings are lost and must be set again.

This means that NIMMSTA Smart Watches can be exchanged between employees every day. There is no need for a mapping of employee and the NIMMSTA Smart Watch.

Next Steps

Now that you integrated the basic setup of a connection, you can start using the NIMMSTA Smart Watch. The following chapters go through different capabilities the NIMMSTA Smart Watch has:

If you want to start interacting with the NIMMSTA Smart Watch, you can start at any of those categories (you don't need to read them in order). With events, you can access scanned barcodes. With APIs, you can access the vibrator, LED and other device information. Layouts are needed if you want to show information on the screen.