1.2 Integrate the NIMMSTA Light Tag Library into your application

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

The difference here from the normal integration is that we are using the Light Tag Library instead of the Core Library and the way we access the Light Tags is different from Smart Watches. Consequently, it means you have to use the documented repository. Also, instead of using connectionManager, we are using LTDeviceManager to manage Light Tags.

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.

Light Tag Device Basics

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

1. Every Light Tag has a unique Mac Address and can Store a "Location". We call the process of defining the Location "Attach".
2. The Location is a simple string that can be up to 20 characters long.
3. The SDK provides functions to define which Light Tags should be illuminated and with which color and intensity.
4. As long as no new information is coming, the SDK will always search for those Light Tags and illuminate them. Also when losing the connection, it will retry doing this.

Two basic classes exist:

LTLEDMode

The LTLEDMode is the representation of the LED mode of the Light Tag device. It contains the color, the intensity, and the blinking pattern of the LED.

Location

The Location is the representation of the location of the Light Tag device. It contains the name of the location.

Note: the location length should be less than equal to 20 characters.

Integrate NIMMSTA Light Tag Library into your application

As a first step you bind the NIMMSTALightTagServiceConnection to your Activity, which is connected to the LTDeviceManager. The goal is to connect to the LTDeviceManager, which controls the connection and communication with the Light Tag Devices.

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

KotlinJava

class MainActivity: Activity() {
        /* ... */
        private lateinit var lightTagServiceConnection: NIMMSTALightTagServiceConnection
        /* ... */

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

            lightTagServiceConnection = NIMMSTALightTagServiceConnection.bindToService(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 lightTagServiceConnection;
        /* ... */

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

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

        lightTagServiceConnection = NIMMSTALightTagServiceConnection.bindToService(this)
                .onComplete(new NIMMSTADoneCallback<Task<NIMMSTALightTagServiceConnection>>() {
                @Override
                public void onComplete(Task<NIMMSTALightTagServiceConnection> 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();
        }
    }

Light Tag Device Manager

The LTDeviceManager is the main entry point for interacting with the Light Tag devices. It provides methods for locating devices, disconnecting devices, and finding nearby devices.

Note: please note that Current Light Tag SDK is only working as long as exactly one smart watch is connected and does not work with more or no smart watches.

find nearby devices

To find nearby devices, you can use the following method: this method will return a flow of Light Tag devices that are nearby.

KotlinJava

val findNearbyDevices = deviceManager.findNearbyDevices().collect {
    // do something with the device
}.launchIn(lifecycleScope)

import java.util.concurrent.Flow;

Flow<LTDevice> findNearbyDevices = deviceManager.findNearbyDevices().collect {
    // do something with the device
}.launchIn(lifecycleScope);

Illuminate Light Tags (setDesiredLightTags)

This method takes a list of device locations and initiates the process of finding, connecting, and illuminating the Light Tag devices with the desired illumination pattern. The connections are managed while respecting the limit on the number of devices that can be connected simultaneously. It will illuminate as long the desired device is nearby and no new desired location is provided. To turn illuminated off, call this method with an empty list.

Preconditions: - The total number of connected devices should be less than 5.

Behavior: - If the connection limit is reached and new devices are provided, an ConnectionLimitExceedException is thrown. - If the provided devices list is empty, it will disconnect all devices. - If the provided devices list is not empty, it will attempt to connect to the devices.

Kotlin

```Kotlin val devices = listOf( Location("location 1"), Location("location 2") ) deviceManager.setDesiredLightTags(devices, LTLEDMode( LTColor.RED, 100, LTBlinkingPattern.Blinking, ))

// ```

Java

List<Location> devices = List.of(
        new Location("location 1"),
        new Location("location 2")
    );
deviceManager.setDesiredLightTags(devices, new LTLEDMode(
    LTColor.RED,
    100,
    LTBlinkingPattern.Blinking
));

Stop Illuminating Light Tags

stop illuminating Light Tags is a special case of setDesiredLightTags where the devices list is empty.

KotlinJava

deviceManager.setDesiredLightTags(emptyList())

deviceManager.setDesiredLightTags(Collections.emptyList())

Attach a new Location to a Light Tag

The attach method will set new location information to the Light Tag device. For the successful case, the Light Tag device will blink green.

Preconditions: - The total number of connected devices should be less than 5. - The device should be found in the nearby devices list.

Behavior: - If the connection limit is reached, an ConnectionLimitExceedException is thrown. - If no smartwatch is connected, a NoOrMoreThanOneSmartWatchConnected is thrown. - If the process can't be completed within 15 seconds, a TimeoutCancellationException is thrown.

KotlinJava

val findNearbyDevices = deviceManager.findNearbyDevices().filter { !it.isEOL }
val device = findNearbyDevices.first()
deviceManager.attach(device.macAddress, Location("location 1"))

deviceManager.attach(device.getAddress(), new Location("new location"))

Detach Location Information from a Light Tag

The detach method will detach the location information from the Light Tag device. For the successful case, the Light Tag device will blink green.

Note: detach is a special case of attach where the location is empty.

KotlinJava

deviceManager.detach(device.address)

deviceManager.detach(device.getAddress())

End of Life Behavior

This method will trigger the end of life behavior for the Light Tag device. End of life is the case in that the device has less than 5% and user can not illuminate the device anymore.

Note 1: all of precondition and behavior are the same as attach method.

Note 2: for being able to use this method, device has to be EOL. you can check it by device.isEOL property.

KotlinJava

deviceManager.endOfLifeBehaviour(device.address)

deviceManager.endOfLifeBehaviour(device.getAddress())

LTDevice

The LTDevice is the representation of a Light Tag device. It contains all the necessary information about the device, such as the MAC address, the battery level, and the location.

KotlinJava

val device = deviceManager.findNearbyDevices().first()
android.util.Log.INFO("Device MAC Address: ${device.address}")
android.util.Log.INFO("Device Battery Level: ${device.batteryLevel}")
android.util.Log.INFO("Device Location: ${device.location}")
android.util.Log.INFO("Device rssi: ${device.rssi}")
android.util.Log.INFO("Device state: ${device.state}")
android.util.Log.INFO("Device is EOL: ${device.isEOL}")
android.util.Log.INFO("Device is connected: ${device.isConnected}")
android.util.Log.INFO("Device is disconnected: ${device.isDisconnected}")

LTDevice device = deviceManager.findNearbyDevices().first();
android.util.Log.INFO("Device MAC Address: " + device.getAddress());
android.util.Log.INFO("Device Battery Level: " + device.getBatteryLevel());
android.util.Log.INFO("Device Location: " + device.getLocation());
android.util.Log.INFO("Device rssi: " + device.getRssi());
android.util.Log.INFO("Device state: " + device.getState());
android.util.Log.INFO("Device is EOL: " + device.isEOL());
android.util.Log.INFO("Device is connected: " + device.isConnected());
android.util.Log.INFO("Device is disconnected: " + device.isDisconnected());