NIMMSTAManager

The NIMMSTAManager handles the communication with the app. You can also connect to new Devices and check what devices are already connected to the app. It has an list of all currently connected devices.

KotlinJava

val device = manager.devices.firstOrNull();
val devicesWithKnownAddress = manager.getDeviceWithAddress(address);

NIMMSTADevice device = manager.getDevices().get(0);
NIMMSTADevice devicesWithKnownAddress = manager.getDeviceWithAddress(address);

Properties

The following properties can be read and set to change the behavior of the host application.

• allowMultiDevice = false, true
• interpretButtonAsMotionTrigger = false, true (if true, the preferredTriggerMode button will be interpreted as a motion trigger)

Example

KotlinJava

// Get AllowMultiDevice
val allowMultiDevice = manager.allowMultiDevice;
// Change AllowMultiDevice
manager.allowMultiDevice = true;

// Get AllowMultiDevice
boolean allowMultiDevice = manager.getAllowMultiDevice();
// Change AllowMultiDevice
manager.setAllowMultiDevice(true);

Actions

To communicate with the app to manage connections you can call several functions, that will be explained in this section.

The following actions are currently supported:

Display Connect Activity

This is the easiest way to connect a new HS-50. This action opens a new activity that displays the scannable connection QR-Code. After the connection is established successfully the activity disappears again.

KotlinJava

manager.displayConnectActivity()

manager.displayConnectActivity();

Search For NIMMSTA Devices

You can also start a search for NIMMSTA Devices, to detect all HS-50s that are in reach of your device. To get information about discovered/lost devices you have to implement the deviceFoundEvent and the deviceRemovedEvent that are covered in the event section.

Note

Please make sure to catch errors via onError. If location or bluetooth permissions are not granted, this will throw there. As a workaround, we recommend calling displayConnectActivity.

KotlinJava

manager.searchForNimmstaDevices().onSuccess { 
  Log.d(TAG, "Searching for devices")
}?.onError { error ->
  Log.e(TAG, "Error starting search", error)
}

manager.searchForNimmstaDevices().onSuccess((task) -> {
  Log.d(TAG, "Searching for devices");
  return task;
}).onError((error) -> {
  Log.e(TAG, "Error starting search", error);
  return null;
});

Cancel Search

The search you started above runs infinitely until you cancel it with this action again.

KotlinJava

manager.cancelSearch().onSuccess { 
  Log.d(TAG, "Cancelled successfully")
}?.onError { error ->
  Log.e(TAG, "Error canceling search", error)
}

manager.cancelSearch().onSuccess((task) -> {
  Log.d(TAG, "Cancelled successfully");
  return task;
}).onError((error) -> {
  Log.e(TAG, "Error canceling search", error);
  return null;
});

Connect to Address

If the search for devices found a device you know the address of it. With this address you can connect to the device.

Note

Please make sure to catch errors via onError. If location or bluetooth permissions are not granted, this will throw there. As a workaround, we recommend calling displayConnectActivity.

KotlinJava

manager.connectToAddress(address).onSuccess { device ->
  Log.d(TAG, "Connected to device: $device")
}?.onError { error ->
  Log.e(TAG, "Error connecting device", error)
}

manager.connectToAddress(address).onSuccess((device) -> {
  Log.d(TAG, "Connected to device: " + device);
  return null;
}).onError((error) -> {
  Log.e(TAG, "Error connecting device", error);
  return null;
});

Get Connection Code

If you want to implement the connection progress with the QR-Code scanning yourself you can do so with the getConnectionCode Action. This Action returns a connectionCode and a base64 encoded png image of a QR-Code that you can display on your webpage.

KotlinJava

manager.getConnectionCode().onSuccess { response ->
  Log.d(TAG, "Connected device: $device")
  val connectionCode = response.connectionCode
  val qrBase64 = response.qrCodeImage
  val decodedString: ByteArray = Base64.decode(qrBase64, Base64.DEFAULT)
  val decodedByte = BitmapFactory.decodeByteArray(decodedString, 0, decodedString.size)
  qrView.setImageBitmap(decodedByte)
  manager.connectToConnectionCode(connectionCode)
}?.onError { error ->
  Log.e(TAG, "Error", error)
}

manager.getConnectionCode().onSuccess((response) -> {
  String connectionCode = response.getConnectionCode();
  String qrBase64 = response.getQrCodeImage();
  byte[] decodedString = Base64.decode(qrBase64, Base64.DEFAULT);
  Bitmap decodedByte = BitmapFactory.decodeByteArray(decodedString, 0, decodedString.length);
  qrView.setImageBitmap(decodedByte);
  manager.connectToConnectionCode(connectionCode, null);
  return null;
}).onError((error) -> {
  Log.e(TAG, "Error", error);
  return null;
});

Connect to Connection Code

To connect to a device that has scanned the QR-Code you have to start a connection attempt.

Note

Please make sure to catch errors via onError. If location or bluetooth permissions are not granted, this will throw there. As a workaround, we recommend calling displayConnectActivity.

KotlinJava

manager.connectToConnectionCode(connectionCode).onSuccess { device ->
  Log.d(TAG, "Connected to device: $device")
}?.onError { error ->
  Log.e(TAG, "Error connecting device", error)
}

manager.connectToConnectionCode(connectionCode, null).onSuccess((device) -> {
  Log.d(TAG, "Connected to device: " + device);
  return null;
}).onError((error) -> {
  Log.e(TAG, "Error connecting device", error);
  return null;
});

Cancel Connect

To cancel an ongoing connect attempt you can call the cancelConnectAction, which accepts an address or an connectionCode.

KotlinJava

manager.cancelConnect(addressOrConnectionCode).onSuccess {
  Log.d(TAG, "Cancelled successfully")
}?.onError { error ->
  Log.e(TAG, "Error", error)
}

manager.cancelConnect("addressOrConnectionCode").onSuccess((task) -> {
  Log.d("TAG", "Cancelled successfully");
  return task;
}).onError((error) -> {
  Log.e("TAG", "Error", error);
  return null;
});

Cancel All Connect

You can also cancel all ongoing connection attempts at once.

KotlinJava

manager.cancelAllConnect().onSuccess {
  Log.d(TAG, "All Cancelled successfully")
}?.onError { error ->
  Log.e(TAG, "Error", error)
}

manager.cancelAllConnect().onSuccess((task) -> {
  Log.d(TAG, "All Cancelled successfully");
  return task;
}).onError((error) -> {
  Log.e(TAG, "Error", error);
  return null;
});

Events

To handle manager events you need to implement the NIMMSTAManagerEventHandler interface

KotlinJava

class MyActivity : AppCompatActivity(), NIMMSTAManagerEventHandler {
  ...
}

public class MyActivity extends AppCompatActivity implements NIMMSTAManagerEventHandler {
  ...
}

Device Found Event

The deviceFoundEvent occurs if a device is discovered by the NimmstaDevices search.

KotlinJava

override fun deviceFound(event: DeviceSearchEvent) {
  Log.d(TAG, "Device found: $event")
  super.deviceFound(event)
}

@Override
public void deviceFound(DeviceSearchEvent event) {
  Log.d(TAG, "Device found: " + event);
}

Device Removed Event

The deviceRemovedEvent occurs if a previously discovered device was lost again, e.g. out of range or shutdown.

KotlinJava

override fun deviceRemoved(event: DeviceSearchEvent) {
  Log.d(TAG, "Device removed: $event")
  super.deviceRemoved(event)
}

@Override 
public void deviceRemoved(DeviceSearchEvent event) {
  Log.d(TAG, "Device removed: " + event);
}