Skip to content

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 LTlightTagManager 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:

LightTagIlluminationConfig

The LightTagIlluminationConfig 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

You need to obtain the LightTagManager which is bound to the NIMMSTA connectionManager from Core Library, see Section 1.2. To obtain it, you need to bind to the NIMMSTAServiceConnection first to obtain [ConnectionManager] and call LightTagManagerFactory.lightTaglightTagManager(it.result.connectionManager!!, context).

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

        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

                    lightTagManager = LightTagManagerFactory.lightTaglightTagManager(it.result.connectionManager!!, applicationContext)
                } catch (throwable: Throwable) {
                    throwable.printStackTrace()

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

        override fun onDestroy() {
            super.onDestroy()

            serviceConnection.close()
            lightTagManager.close()
        }
    }

public class MainActivity extends Activity {
    /* ... */
    NIMMSTAServiceConnection serviceConnection;
    LightTagManager lightTagManager;
    /* ... */

    @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();

                    lightTagManager = LightTagManagerFactory.INSTANCE.lightTagDeviceManager(result.getResult().getConnectionManager(), getApplicationContext());
                } catch (Throwable throwable) {
                    throwable.printStackTrace();

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

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

        serviceConnection.close();
        lightTagManager.close();
    }
}

Light Tag Device Manager

The LightTagManager 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 Light Tags

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

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

import java.util.concurrent.Flow;

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

Illuminate Light Tags (setDesiredLightTags)

To illuminate a light tag, you need to provide the locations of Light Tags being illuminated and also the desired LED Mode. The SDK in the background will make sure to illuminate the Light Tag as long it is in range and also reilluminate it if it goes out of range and comes back in range. There can be a maximum of 5 Light Tags illuminated at the same time. The Light Tags will be illuminated until a new request is received. To turn it off, send a request with an empty deviceList.

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.
  • You can also provide a map of devices and their desired LED mode or color to have different colors.
  • You can also provide color off to connect Light Tags and be faster later, when you need them. Be aware it will disconnect once you provide a new intention which does not contain the location.
val devices = listOf(
        Location("location 1"),
        Location("location 2")
)
lightTagManager.setDesiredLightTags(devices, LightTagIlluminationConfig(
     LTColor.RED,
     100,
     LTBlinkingPattern.Blinking,
))
lightTagManager.setDesiredLightTags(devices, LTColor.RED)
setDesiredLightTags(mapOf(
    "Location1" to LTColor.RED,
    "Location2" to LTColor.OFF // already connects the light tag, so later if you want to change the color, it will be faster.
))
setDesiredLightTags(mapOf(
    "Location1" to LightTagIlluminationConfig(LTColor.RED, 100, LTBlinkingPattern.BLINK),
    "Location2" to LightTagIlluminationConfig(LTColor.OFF),
))

List<Location> devices = List.of(
    new Location("location 1"),
    new Location("location 2")
);
lightTagManager.setDesiredLightTags(devices, new LightTagIlluminationConfig(
    LTColor.RED,
    100,
    LTBlinkingPattern.Blinking
));
lightTagManager.setDesiredLightTags(Map.of(
    "location1", LTColor.Companion.getBLUE(),
    "location2", LTColor.Companion.getOFF()
));

LTColor

We have 13 predefined colors, of those the first 6 are very good distinguishable. In addition, we we have an automatic color which is recommended for most cases. The automatic color will choose a color that is not used by other Light Tags currently used by other users connected to the Cloud. If all colors are used or no cloud connection is available, it will pick a random color.

To get your desired color you can use the following predefined colors enum:

// Very good distinguishable colors
LTColor.RED
LTColor.GREEN
LTColor.BLUE
LTColor.YELLOW
LTColor.PURPLE
LTColor.TURQUOISE

// less distinguishable
LTColor.WHITE
LTColor.ORANGE
LTColor.VIOLET
LTColor.FORESTGREEN
LTColor.MAGENTA
LTColor.LIME
LTColor.PINK
LTColor.EMERGENCY

// Color Modes
LTColor.AUTOMATIC // Recommended for most cases
LTColor.RANDOM
LTColor.OFF

Stop Illuminating Light Tags

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

lightTagManager.setDesiredLightTags(emptyList())

lightTagManager.setDesiredLightTags(Collections.emptyList())

Attach a new Location to a Light Tag

The attach method will store new location information on 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.

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

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

lightTagManager.detach(device.address)

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

lightTagManager.endOfLifeBehaviour(device.address)

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

val device = lightTagManager.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 = lightTagManager.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());