Skip to content

1.2 Integrate NIMMSTA into your application

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

Requirements

  • You should already have added the maven package to your project. Otherwise, see the previous section.
  • Linux: Make sure the NIMMSTA BLE USB Dongle is plugged in.
  • Windows: Make sure your have native bluetooth capability or the NIMMSTA BLE USB Dongle is plugged in.

Note

The word "device" in this documentation refers to a NIMMSTA scanner, for example the HS 50.

Instantiate ConnectionManager

As a first step you instantiate a ConnectionManager, which controls the connection and communication with the device. You have to make sure to create the ConnectionManager only once. We recommend using a singleton in the main class.

val connectionManager = ConnectionManager()

ConnectionManager connectionManager = new ConnectionManager();

Implement an event handler

Next, you need to implement a NIMMSTAEventHandler. The handler will receive all events from the device. Each function has the NIMMSTADevice, which is responsible for the event, as a parameter. For other possible events than the ones depicted here, see Events.

class ExampleEventHandler: NIMMSTAEventHandler {

    /* ... */

    override fun didStartConnecting(device: NIMMSTADevice) {
        // Connection process has started
        // Device interaction not yet possible
    }

    override fun didConnectAndInit(device: NIMMSTADevice) {
        // Device interaction is now possible
    }

    /* ... */
}

class ExampleEventHandler implements NIMMSTAEventHandler {

    /* ... */

    @Override
    public void didStartConnecting(NIMMSTADevice nimmstaDevice) {
        // Connection process has started
        // Device interaction not yet possible
    }

    @Override
    public void didConnectAndInit(NIMMSTADevice nimmstaDevice) {
        // Device interaction is now possible
    }

    /* ... */
}

Add the event handler to the ConnectionManager

In order to receive events from the ConnectionManger, you need to tell the ConnectionManager to start receiving events.

Note

You can register multiple event handlers at the same time.

// Create new event handler
val eventHandler = ExampleEventHandler()

// To start receiving events
connectionManager.startReceivingEvents(eventHandler)

// To stop receiving events
connectionManager.stopReceivingEvents(eventHandler)

// Create new event handler
ExampleEventHandler eventHandler = new ExampleEventHandler();

// To start receiving events
connectionManager.startReceivingEvents(eventHandler);

// To stop receiving events
connectionManager.stopReceivingEvents(eventHandler);

Display the connection QR code window

Now that we have created an event handler and added it to the ConnectionManager, we can connect to the device. To display the connection QR code, run the following function:

connectionManager.displayConnectionActivity()

connectionManager.displayConnectionActivity(false);

Once the user scanned the QR code with his device, the connection will be established automatically.

Checking the result of your call

You can check if the call succeeded by registering an onSuccess or onError handler.

Note

This only checks if the connection screen was displayed correctly, not if the connection attempt was successful!

connectionManager.displayConnectionActivity().onSuccess { 
    // success  
}.onError { 
    // error
}

connectionManager.displayConnectionActivity(false).onSuccess(new NIMMSTADoneCallback<Unit>() {
    @Override
    public void onDone(Unit unit) {
        // success
    }
}).onError(new NIMMSTAFailCallback<Throwable>() {
    @Override
    public void onFail(Throwable throwable) {
        // error
    }
});

Shutting down the connection when you close the application

To make sure your device disconnects correctly you need to shut down the connection when you close the application.

Note

If you don't do this, the connection will still be established after the app is closed (via the USB dongle).

connectionManager.close()

connectionManager.close();

Basic example

Don't forget that because the ConnectionManager processes the events asynchronously, the program will exit if it is not prevented from doing so. That's why we have to add the blocking sequence in the end.

class ExampleEventHandler: NIMMSTAEventHandler {

        override fun didStartConnecting(device: NIMMSTADevice) {
            // Connection process has started
            // Device interaction not yet possible
        }

        override fun didConnectAndInit(device: NIMMSTADevice) {
            // Device interaction is now possible
        }

}

fun main() {
    val connectionManager = ConnectionManager()
    val eventHandler = ExampleEventHandler()
    connectionManager.startReceivingEvents(eventHandler)
    connectionManager.displayConnectionActivity()

    var isRunning = true
    // Prevent app from exiting
    while (isRunning) {
        Thread.sleep(10)
    }

    // Call this before teardown of application to close NIMMSTA Smart Watch connection
    connectionManager.close()
}

class ExampleEventHandler implements NIMMSTAEventHandler {

    /* ... */

    @Override
    public void didStartConnecting(NIMMSTADevice nimmstaDevice) {
        // Connection process has started
        // Device interaction not yet possible
    }

    @Override
    public void didConnectAndInit(NIMMSTADevice nimmstaDevice) {
        // Device interaction is now possible
    }

    /* ... */

}

class Main {
    public static void main(String[] args) throws InterruptedException {
        ConnectionManager connectionManager = new ConnectionManager();
        ExampleEventHandler eventHandler = new ExampleEventHandler();
        connectionManager.startReceivingEvents(eventHandler);
        connectionManager.displayConnectionActivity(false);

        bool isRunning = true;
        // Prevent app from exiting
        while (isRunning) {
            Thread.sleep(10);
        }

        // Call this before teardown of application to close NIMMSTA Smart Watch connection
        connectionManager.close();
    }
}

Next Steps

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

If you want to start interacting with the device, 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 Requests, you can access the vibrator, LED and other device information. Layouts are needed if you want to show information on the screen.