4.1 Requests

The requests are accessible by calling device.api on any NIMMSTADevice. We always provide a reference to the device in every callback method.

You can also save the currently connected device in a variable. This way you always have access to the device, even when you are not using on of the provided callback methods.

Note

This documentation only shows the most important requests. Please have a look at the TextProtocolAPI class in the apidocs for additional requests.

KotlinJava

class MainActivity: Activity(), NIMMSTAEventHandler {

    // variable that saves the currently connected device
    // you can use this reference to access the api when
    // you are not using a callback method
    var currentDevice: NIMMSTADevice? = null

    override fun didConnectAndInit(device: NIMMSTADevice) {
        currentDevice = device
    }

    override fun didStartCharging(device: NIMMSTADevice) {
        // example request
        device.api.getDeviceInfo().onSuccess {
            // handle device info
        }.onError { error ->
            // handle error
        }
    }
}

class MainActivity extends Activity implements NIMMSTAEventHandler {

    // variable that saves the currently connected device
    // you can use this reference to access the api when
    // you are not using a callback method
    NIMMSTADevice currentDevice;

    @Override
    public void didConnectAndInit(@NotNull NIMMSTADevice nimmstaDevice) {
        currentDevice = nimmstaDevice;
    }

    @Override
    public void didStartCharging(@NotNull NIMMSTADevice nimmstaDevice) {
        // example request
        nimmstaDevice.getApi().getDeviceInfo().onSuccess(new NIMMSTADoneCallback<DeviceInfo>() {
            @Override
            public void onDone(DeviceInfo deviceInfo) {
                // handle device info
            }

        }).onError(new NIMMSTAFailCallback<Throwable>() {
            @Override
            public void onFail(Throwable throwable) {
                // handle error
            }
        });
    }
}

Instead of using the onSuccess and onError callbacks (onDone and onFail if you are using Java), you can also use await to block execution until the result is available.

Note

Since we are using Kotlin Coroutines, the await function is only available on suspending functions! This feature is also not available if you are using Java.

Kotlin

GlobalScope.launch {
    device.api.getDeviceInfo().await()
}

Get Device Versions

Get versions of the connected device.

KotlinJava

device.api.getDeviceVersions()

nimmstaDevice.getApi().getDeviceVersions();

Set LED Color

Set the LED Color of the device.

KotlinJava

// using rgb
device.api.setLEDColor(0, 255, 0)

// using hex
device.api.setLEDColor("00ff00")

// using Color class
device.api.setLEDColor(Color.GREEN)

// using rgb
nimmstaDevice.getApi().setLEDColor(255, 255, 255);

// using hex
nimmstaDevice.getApi().setLEDColor("00ff00");

// using Color class
nimmstaDevice.getApi().setLEDColor(Color.GREEN);

Trigger SOS

An SOS signal is 3x red LED flash with 3x vibration and 3x beeping.

KotlinJava

device.api.triggerSOS()

nimmstaDevice.getApi().triggerSOS();

Trigger Bursts

Triggers every burst request at once (LED, Vibrator, Beeper) using a given pattern.

You should use this if you want to trigger multiple types of bursts at the same time. If this is not your goal, use one of the other requests, like Trigger LED Burst or Trigger Beeper Burst.

Note

You do not need to supply an object for every type of request.

KotlinJava

val ledBurst = LEDBurst.Builder()
    .color(Color.RED)
    .burst()
    .repeats(5)
    .duration(500)
    .pulseDuration(100)
    .build()

val vibratorBurst = VibratorBurst.Builder()
    .intensity(100)
    .burst()
    .repeats(3)
    .duration(500)
    .pulseDuration(250)
    .build()

val beeperBurst = BeeperBurst.Builder()
    .intensity(100)
    .burst()
    .repeats(3)
    .duration(500)
    .pulseDuration(100)
    .build()

device.api.triggerBursts(ledBurst, vibratorBurst, beeperBurst)

LEDBurst ledBurst = LEDBurst.Companion.Builder()
    .color(Color.RED)
    .burst()
    .repeats(5)
    .duration(500)
    .pulseDuration(100)
    .build();

VibratorBurst vibratorBurst = VibratorBurst.Companion.Builder()
    .intensity(100)
    .burst()
    .repeats(3)
    .duration(500)
    .pulseDuration(250)
    .build();

BeeperBurst beeperBurst = BeeperBurst.Companion.Builder()
    .intensity(100)
    .burst()
    .repeats(3)
    .duration(500)
    .pulseDuration(100)
    .build();

nimmstaDevice.getApi().triggerBursts(ledBurst, vibratorBurst, beeperBurst);

Trigger LED Burst

Triggers the LED multiple times in the given Color.

• repeat Amount of repeats, 0 means indefinitely (0-10).
• duration Duration how long one cycle takes in milliseconds (10-4095).
• pulseDuration How long the LED is on within one cycle in milliseconds (10-4095).

You can provide the color as rgb, hex or as a Color class.

KotlinJava

device.api.triggerLEDBurst(2, 250, 400, 0, 255, 0)
device.api.triggerLEDBurst(5, 1000, 250, "00ff00")
device.api.triggerLEDBurst(3, 500, 350, Color.GREEN)

nimmstaDevice.getApi().triggerLEDBurst(2, 250, 400, 0, 255, 0);
nimmstaDevice.getApi().triggerLEDBurst(5, 1000, 250, "00ff00");
nimmstaDevice.getApi().triggerLEDBurst(3, 500, 350, Color.GREEN);

Trigger Vibrator Burst

A vibrator burst is a succession of vibrations of the Smart Watch with a given pattern, which is repeated for a given amount of times or indefinitely. If you want to cancel an indefinitely long vibrator burst, you need to send a short vibration with only one repeat.

• repeat How often to trigger the vibrator. 0 means indefinitely (0-10).
• duration Duration how long one cycle takes in milliseconds (10-4095).
• pulseDuration How long the vibrator is on within one cycle in milliseconds (10-4095).
• intensity Intensity of the vibrator (0-100).

KotlinJava

device.api.triggerVibratorBurst(3, 500, 250, 100)

nimmstaDevice.getApi().triggerVibratorBurst(3, 500, 250, 100);

Trigger Beeper Burst

A beeper burst is a succession of beeps of the Smart Watch with a given pattern, which is repeated for a given amount of times or indefinitely. If you want to cancel an indefinitely long beeper burst, you need to send a short beep with only one repeat.

• repeat How often to trigger the beeper. 0 means indefinitely (0-10).
• duration Duration how long one cycle takes in milliseconds (10-4095).
• pulseDuration How long the beeper is on within one cycle in milliseconds (10-4095).
• intensity Volume of the beeper (0-100).

KotlinJava

device.api.triggerBeeperBurst(5, 500, 250, 100)

nimmstaDevice.getApi().triggerBeeperBurst(5, 500, 250, 100);

Software Update

Conducting a software update happens in two steps. First you need to check the software update file using checkSoftwareUpdate. If this file is correct, you will be able to install it on the device using installer.sendToDeviceAsync.

Note

Please be aware that only .nimmstaupdate files are supported!

As the name suggests, sending a software update to the device happens asynchronously. This means you can still use the scanner as usual while the software update is being transmitted to the device. It will only be installed if the update is transmitted successfully and the device is restarted by the user afterwards.

KotlinJava

device.api.checkSoftwareUpdate(localVfs("Myfile.nimmstaupdate")) { isInstalled, installer, versions ->
    if (isInstalled) {
        // if the version is already installed
    } else {
        installer.sendToDeviceAsync().onSuccess {
            // disconnect and tell user to restart device to install update
        }.onError {
            // error occurred while trying to send software update to device
            // tell user to restart device and try again
        }
    }
}.onError {
    // If there is an error with the file
}

nimmstaDevice.getApi().checkSoftwareUpdate(LocalVfsJvmKt.localVfs("Myfile.nimmstaupdate"), new Function3<Boolean, SoftwareFileContext, ReleaseFileInfo, Unit>() {
    @Override
    public Unit invoke(Boolean isAlreadyInstalled, SoftwareFileContext softwareFileContext, ReleaseFileInfo versions) {
        if (isAlreadyInstalled) {
            // if the version is already installed
        } else {
            softwareFileContext.sendToDeviceAsync().onSuccess(new NIMMSTADoneCallback<Unit>() {
                @Override
                public void onDone(Unit unit) {
                    // disconnect and tell user to restart device to install update
                }
                }).onError(new NIMMSTAFailCallback<Throwable>() {
                    @Override
                    public void onFail(Throwable throwable) {
                        // error occurred while trying to send software update to device
                        // tell user to restart device and try again
                    }
                });
            }
        return null;
    }
})
.onError(new NIMMSTAFailCallback<Throwable>() {
    @Override
    public void onFail(Throwable throwable) {
        // If there is an error with the file
    }
});

Trigger Imager

Warning

This is an experimental feature! Be aware that there can be complications if the imager should be triggered using the trigger or the touchscreen.

Triggers a scan on the device.

• pulseDuration How long the imager should stay on (0 - 4095).

KotlinJava

device.api.triggerImager(1000)

nimmstaDevice.getApi().triggerImager(1000);