Skip to content

NimmstaDevice

An instance of a NimmstaDevice is used to communicate with one HS 50. To get an instance of NIMMSTADevice, you need to iterate through all connected devices on the NIMMSTAManager.

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

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

Properties

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

  • Get/Set preferredTriggerMode = Disabled, Button, Touch, ButtonAndTouch, Motion, MotionAndButton, MotionAndTouch, MotionAndButtonAndTouch, DefaultEnabled
  • Get/Set preferredAimMode = Default, PickingMode, RepeatedAiming, PickingModeRepeatedAiming, ContinuousScanning, PickingModeContinuousScanning, RepeatedAimingContinuousScanning, PickingModeRepeatedAimingContinuousScanning
  • Get/Set reconnectTimeout = 1800 (Timeout in seconds; 30 minutes is default)
  • Get/Set barcodeRules
  • Get/Set prefersReconnect = true, false
  • Get/Set prefersShutdownOnCharge = true, false
  • Get/Set decoderBoardSettings
  • Get isCharging = true, false
  • Get isSearchingToReconnect = true, false
  • Get wasReconnected = true, false
  • Get batteryLevel = 0 - 100

Example

// Get TriggerMode
const triggerMode = device.preferredTriggerMode
// Change TriggerMode
device.preferredTriggerMode = TriggerMode.ButtonAndTouch

// Get TriggerMode
TriggerMode triggerMode = device.getPreferredTriggerMode();
// Change TriggerMode
device.setPreferredTriggerMode(TriggerMode.ButtonAndTouch);

Actions

To communicate with the corresponding HS 50 you can call several functions, each executing a specific action on the HS 50.

The following actions are currently supported:

Get Device Info

To get information about the given NimmstaDevice, you can call getDeviceInfo on the NimmstaDevice. To access the data of the response, you need to wait for the Task to be completed and access the information in the following way:

device.getDeviceInfo().onSuccess { response ->
  // Current battery status in percent
  val battery = response.battery
  // Current version of the hardware of the connected HS 50
  val hardwareVersion = response.hardwareVersion
  // Current version of the firmware of the connected HS 50
  val firmwareVersion = response.firmwareVersion
  // Current version of the ble firmware of the connected HS 50
  val bleFirmwareVersion = response.bleFirmwareVersion
  // Current version of the ble script of the connected HS 50
  val bleScriptVersion = response.bleScriptVersion
  // Current version of the bootloader of the connected HS 50
  val bootloaderVersion = response.bootloaderVersion
  // Current version of the imager of the connected HS 50
  val imagerFirmwareVersion = response.imagerFirmwareVersion
}.onError { error ->
  Log.e(TAG, "Error getting device info", error)
}

device.getDeviceInfo().onSuccess((response) -> {
  // Current battery status in percent
  int battery = response.getBattery();
  // Current version of the hardware of the connected HS 50
  String hardwareVersion = response.getHardwareVersion();
  // Current version of the firmware of the connected HS 50
  String firmwareVersion = response.getFirmwareVersion();
  // Current version of the ble firmware of the connected HS 50
  String bleFirmwareVersion = response.getBleFirmwareVersion();
  // Current version of the ble script of the connected HS 50
  String bleScriptVersion = response.getBleScriptVersion();
  // Current version of the bootloader of the connected HS 50
  String bootloaderVersion = response.getBootloaderVersion();
  // Current version of the imager of the connected HS 50
  String imagerFirmwareVersion = response.getImagerFirmwareVersion();
  return null;
}).onError((error) -> {
  Log.e(TAG, "Error getting device info", error);
  return null;
});

Is Device Connected

To check whether the HS 50 that corresponds to this NimmstaDevice is connected to the phone, you can call isConnected() on the NimmstaDevice.

device.isConnected().onSuccess {
  Log.d(TAG, "HS 50 is connected")
}.onError { error ->
  Log.e(TAG, "HS 50 is not connected", error)
}

device.isConnected().onSuccess((task) -> {
  Log.d(TAG, "HS 50 is connected");
  return task;
}).onError((error) -> {
  Log.e(TAG, "HS 50 is not connected", error);
  return null;
});

Disconnect

Disconnect from the device.

device.disconnect().onSuccess {
  Log.d(TAG, "Disconnected")
}.onError { error ->
  Log.e(TAG, "Error while disconnecting", error)
}

device.disconnect().onSuccess((task) -> {
  Log.d(TAG, "Disconnected");
  return task;
}).onError((error) -> {
  Log.e(TAG, "Error while disconnecting", error);
  return null;
});

Stop Reconnecting

Stops a device from reconnecting.

device.stopReconnecting().onSuccess {
  Log.d(TAG, "Reconnecting stopped")
}.onError { error ->
  Log.e(TAG, "Error while stopping reconnecting", error)
}

device.stopReconnecting().onSuccess((task) -> {
  Log.d(TAG, "Reconnecting stopped");
  return task;
}).onError((error) -> {
  Log.e(TAG, "Error while stopping reconnecting", error);
  return null;
});

Set Layout

To change the contents of the HS 50 screen, you can call setLayout with an instance of NimmstaLayout. For this action, the response does not contain any data. There are currently multiple predefined layouts that can be used with this function. Check out the Layout Documentation.

To change the layout you need to do the following:

device.setLayout(SuccessLayout("Test successful")).onSuccess {
  Log.d(TAG, "Layout successfully set")
}.onError { error ->
  Log.e(TAG, "Error setting layout", error)
}

device.setLayout(new SuccessLayout("Test successful")).onSuccess((task) -> {
  Log.d(TAG, "Layout successfully set");
  return task;
}).onError((error) -> {
  Log.e(TAG, "Error setting layout", error);
  return null;
});

To create your own predefined layout see Predefined Layouts.

Set Layout For

Same as Set Layout, but with a time in ms how long the layout should be shown on the scanner.

device.setLayoutFor(SuccessLayout("Test successful"), 3000).onSuccess {
  Log.d(TAG, "Layout with timeout successfully set")
}.onError { error ->
  Log.e(TAG, "Error setting layout with timeout", error)
}

device.setLayoutFor(new SuccessLayout("Test successful"), 3000).onSuccess((task) -> {
  Log.d(TAG, "Layout with timeout successfully set");
  return task;
}).onError((error) -> {
  Log.e(TAG, "Error setting layout with timeout", error);
  return null;
});

Set XML Layout

To change the contents of the HS 50 screen, you can call setXMLLayout with your own custom XML that represents a layout the HS 50 can understand. To learn more about XML layouts head over to Layout Basics of the NIMMSTA Android Core.

val xml = "<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
          "<NimmstaLayout name=\"empty\">" +
          "  <device width=\"1.54\" height=\"1.54\" pxx=\"200\" pxy=\"200\">" +
          "    <screen default=\"true\" name=\"default\">" +
          "      <staticElements>" +
          "        <cell x=\"10\" y=\"10\" name=\"text1\">Text1</cell>" +
          "        <cell x=\"10\" y=\"50\" name=\"text2\">Text2</cell>" +
          "      </staticElements>" +
          "    </screen>" +
          "  </device>" +
          "</NimmstaLayout>"

device.setLayout(xml).onSuccess {
  Log.d(TAG, "XML layout successfully set")
}.onError { error ->
  Log.e(TAG, "Error setting XML layout", error)
}

String xml = "<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
              "<NimmstaLayout name=\"empty\">" +
              "  <device width=\"1.54\" height=\"1.54\" pxx=\"200\" pxy=\"200\">" +
              "    <screen default=\"true\" name=\"default\">" +
              "      <staticElements>" +
              "        <cell x=\"10\" y=\"10\" name=\"text1\">Text1</cell>" +
              "        <cell x=\"10\" y=\"50\" name=\"text2\">Text2</cell>" +
              "      </staticElements>" +
              "    </screen>" +
              "  </device>" +
              "</NimmstaLayout>";

device.setLayout(xml).onSuccess((task) -> {
  Log.d(TAG, "XML layout successfully set");
  return task;
}).onError((error) -> {
  Log.e(TAG, "Error setting XML layout", error);
  return null;
});

Set XML Layout For

Same as Set XML Layout, but with a time in ms how long the layout should be shown for.

val xml = "<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
          "<NimmstaLayout name=\"empty\">" +
          "    <device width=\"1.54\" height=\"1.54\" pxx=\"200\" pxy=\"200\">" +
          "        <screen default=\"true\" name=\"default\">" +
          "            <staticElements>" +
          "                <cell x=\"10\" y=\"10\" name=\"text1\">Text1</cell>" +
          "                <cell x=\"10\" y=\"50\" name=\"text2\">Text2</cell>" +
          "            </staticElements>" +
          "        </screen>" +
          "    </device>" +
          "</NimmstaLayout>"

device.setLayoutFor(xml, 5000).onSuccess {
  Log.d(TAG, "XML layout with timeout successfully set")
}.onError { error ->
  Log.e(TAG, "Error setting XML layout with timeout", error)
}

String xml = "<?xml version=\"1.0\" encoding=\"utf-8\"?>" +
              "<NimmstaLayout name=\"empty\">" +
              "  <device width=\"1.54\" height=\"1.54\" pxx=\"200\" pxy=\"200\">" +
              "    <screen default=\"true\" name=\"default\">" +
              "      <staticElements>" +
              "        <cell x=\"10\" y=\"10\" name=\"text1\">Text1</cell>" +
              "        <cell x=\"10\" y=\"50\" name=\"text2\">Text2</cell>" +
              "      </staticElements>" +
              "    </screen>" +
              "  </device>" +
              "</NimmstaLayout>";

device.setLayoutFor(xml, 5000).onSuccess((task) -> {
  Log.d(TAG, "XML layout with timeout successfully set");
  return task;
}).onError((error) -> {
  Log.e(TAG, "Error setting XML layout with timeout", error);
  return null;
});

Update Layout

To update an already displayed Layout without sending the whole layout again, you can call updateLayout. Update layout requires an object with key value pairs. The key should be the same as the name of the element you want to update and the value represents the new value that should be displayed. To update a layout the following code is needed:

val params = mapOf("text1" to "New Text 1", "text2" to "New Text 2")
device.updateLayout(params).onSuccess {
  Log.d(TAG, "Layout successfully updated");
}.onError { error ->
  Log.e(TAG, "Error updating layout", error);
}

Map<String, String> params = new HashMap<>();
params.put("text1", "New Text 1");
params.put("text2", "New Text 2");

device.updateLayout(params).onSuccess((task) -> {
  Log.d(TAG, "Layout successfully updated");
  return task;
}).onError((error) -> {
  Log.e(TAG, "Error updating layout", error);
  return null;
});

Set LED Color

To set the color of the HS 50 LED, you can call setLEDColor with values for red, green and blue between 0 and 255, where 0 is no brightness at all and 255 represents the full brightness for the given color. The following code changes the LED color:

// In this example the LED is changed to purple
val red = 255
val green = 0
val blue = 255
device.setLEDColor(red, green, blue).onSuccess {
  Log.d(TAG, "Led color successfully set")
}.onError { error ->
  Log.e(TAG, "Error setting LED color", error)
}

// In this example the LED is changed to purple
int red = 255;
int green = 0;
int blue = 255;
device.setLEDColor(red, green, blue).onSuccess((task) -> {
  Log.d(TAG, "Led color successfully set");
  return task;
}).onError((error) -> {
  Log.e(TAG, "Error setting LED color", error);
  return null;
});

Set LED Color Hex

To set the color of the HS 50 LED with a hex string that represents the desired color, you can call setLEDColorHex with values like "#FF00FF" or "FF00FF". The following code changes the LED color:

// In this example the LED is changed to purple
val hex = "#FF00FF"
device.setLEDColorHex(hex).onSuccess {
  Log.d(TAG, "Led color successfully set")
}.onError { error ->
  Log.e(TAG, "Error setting LED color", error)
}

String hex = "#FF00FF";
device.setLEDColorHex(hex).onSuccess((task) -> {
  Log.d(TAG, "Led color successfully set");
  return task;
}).onError((error) -> {
  Log.e(TAG, "Error setting LED color", error);
  return null;
});

Trigger Beeper Burst

A beeper burst is a succession of beeps of the HS 50 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.

val repeat = 5 // How often to trigger the beeper. 0 means indefinitely. Must be greater or equal to 0 and smaller or equal to 255
val duration = 500 // Duration how long one cycle takes in milliseconds. Must be greater or equal to 10 and smaller or equal to 4095
val pulseDuration = 250 // How long the beeper is on within one cycle in milliseconds. Must be greater or equal to 10 and smaller or equal to 4095
val intensity = 100 // How loud the beeper is (0-100).
device.triggerBeeperBurst(repeat, duration, pulseDuration, intensity).onSuccess {
  Log.d(TAG, "Successfully triggered beeper burst")
}.onError { error ->
  Log.e(TAG, "Error triggering beeper burst", error)
}

int repeat = 5; // How often to trigger the beeper. 0 means indefinitely. Must be greater or equal to 0 and smaller or equal to 255
int duration = 500; // Duration how long one cycle takes in milliseconds. Must be greater or equal to 10 and smaller or equal to 4095
int pulseDuration = 250; // How long the beeper is on within one cycle in milliseconds. Must be greater or equal to 10 and smaller or equal to 4095
int intensity = 100; // How loud the beeper is (0-100).
device.triggerBeeperBurst(repeat, duration, pulseDuration, intensity).onSuccess((task) -> {
  Log.d(TAG, "Successfully triggered beeper burst");
  return task;
}).onError((error) -> {
  Log.e(TAG, "Error triggering beeper burst", error);
  return null;
});

Trigger LED Burst

A LED burst is a succession of flashes of the LED with a given pattern and color, which is repeated for a given amount of times or indefinitely.

val red = 255
val green = 0
val blue = 255
val repeat = 3 // Amount of repeats, 0 means indefinitely. Must be greater or equal to 0 and smaller or equal to 255
val duration = 500 // Duration how long one cycle takes in milliseconds. Must be greater or equal to 10 and smaller or equal to 4095
val pulseDuration = 250 // How long the LED is on within one cycle in milliseconds. Must be greater or equal to 10 and smaller or equal to 4095
device.triggerLEDBurst(repeat, duration, pulseDuration, red, green, blue).onSuccess {
  Log.d(TAG, "Led burst successfully triggered")
}.onError { error ->
  Log.e(TAG, "Error triggering LED Burst", error)
}

int red = 255;
int green = 0;
int blue = 255;
int repeat = 3; // Amount of repeats, 0 means indefinitely. Must be greater or equal to 0 and smaller or equal to 255
int duration = 500; // Duration how long one cycle takes in milliseconds. Must be greater or equal to 10 and smaller or equal to 4095
int pulseDuration = 250; // How long the LED is on within one cycle in milliseconds. Must be greater or equal to 10 and smaller or equal to 4095
device.triggerLEDBurst(repeat, duration, pulseDuration, red, green, blue).onSuccess((task) -> {
  Log.d(TAG, "Led burst successfully triggered");
  return task;
}).onError((error) -> {
  Log.e(TAG, "Error triggering LED Burst", error);
  return null;
});

Trigger SOS

An SOS signal is a red LED with 4x vibration and 4x beeping. To trigger a SOS signal you can use the following code:

device.triggerSOS().onSuccess {
  Log.d(TAG, "Successfully triggered SOS")
}.onError { error ->
  Log.e(TAG, "Error triggering SOS", error)
}

device.triggerSOS().onSuccess((task) -> {
  Log.d(TAG, "Successfully triggered SOS");
  return task;
}).onError((error) -> {
  Log.e(TAG, "Error triggering SOS", error);
  return null;
});

Trigger Vibrator Burst

A vibrator burst is a succession of vibrations of the HS 50 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.

val repeat = 5 // How often to trigger the vibrator. 0 means indefinitely. Must be greater or equal to 0 and smaller or equal to 255
val duration = 500 // Duration how long one cycle takes in milliseconds. Must be greater or equal to 10 and smaller or equal to 4095
val pulseDuration = 250 // How long the vibrator is on within one cycle in milliseconds. Must be greater or equal to 10 and smaller or equal to 4095
val intensity = 100 // How strong the vibration is (0-100).
device.triggerVibratorBurst(repeat, duration, pulseDuration, intensity).onSuccess {
  Log.d(TAG, "Successfully triggered vibrator burst")
}.onError { error ->
  Log.e(TAG, "Error triggering vibrator burst", error)
}

int repeat = 5; // How often to trigger the vibrator. 0 means indefinitely. Must be greater or equal to 0 and smaller or equal to 255
int duration = 500; // Duration how long one cycle takes in milliseconds. Must be greater or equal to 10 and smaller or equal to 4095
int pulseDuration = 250; // How long the vibrator is on within one cycle in milliseconds. Must be greater or equal to 10 and smaller or equal to 4095
int intensity = 100; // How strong the vibration is (0-100).
device.triggerVibratorBurst(repeat, duration, pulseDuration, intensity).onSuccess((task) -> {
  Log.d(TAG, "Successfully triggered vibrator burst");
  return task;
}).onError((error) -> {
  Log.e(TAG, "Error triggering vibrator burst", error);
  return null;
});

Trigger Imager

You can trigger the imager (the part of the scanner that takes pictures and recognizes codes) to scan without pressing the trigger button or the display The duration is passed as a number in milliseconds

val duration = 1000

device.triggerImager(duration).onSuccess {
  Log.d(TAG, "Successfully triggered imager")
}.onError { error ->
  Log.e(TAG, "Error triggering imager", error)
}

device.triggerImager(duration).onSuccess((task) -> {
  Log.d(TAG, "Successfully triggered imager");
  return task;
}).onError((error) -> {
  Log.e(TAG, "Error triggering imager", error);
  return null;
});

Events

To handle device events you need to implement the NIMMSTADeviceEventHandler interface

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

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

Connect Event

Connect events occur when a new HS 50 is connected to the device.

override fun didConnectAndInit(device: NIMMSTADevice) {
  Log.d(TAG, "New device connected")
}

@Override
public void didConnectAndInit(NIMMSTADevice device) {
  Log.d(TAG, "New device connected");
}

Disconnect Event

Disconnect events occur when a HS 50 gets disconnected for whatever reason. The returned event contains the reason of the disconnect.

override fun didDisconnect(device: NIMMSTADevice, reason: String) {
  Log.d(TAG, "Device disconnected; Reason: $reason")
}

@Override
public void didDisconnect(NIMMSTADevice device, String reason) {
  Log.d(TAG, "Device disconnected; Reason: " + reason);
}

Scan Event

Scan events happen when a user scans a barcode with the HS 50. The event contains the scanned barcode string after rules are applied, if there are any. To subscribe to a scan event the following code is used:

override fun didScanBarcode(device: NIMMSTADevice, event: Barcode) {
  Log.d(TAG, "Scanned barcode: ${event.barcode}")
}

@Override
public void didScanBarcode(NIMMSTADevice device, Barcode barcode) {
  Log.d(TAG, "Scanned barcode: " + barcode.getBarcode());
}

Touch Event

Touch events occur if a user touches the display of the HS 50. The event contains the x and the y coordinate of the touch location. This event is not affected by the setting of the trigger mode of the android app.

override fun didTouch(device: NIMMSTADevice, x: Double, y: Double) {
  Log.d(TAG, "Touched Display at: $x $y")
}

@Override
public void didTouch(NIMMSTADevice device, double x, double y) {
  Log.d(TAG, "Touched Display at: " + x + " " + y);
}

Button Event

Button events occur if a user touches a button on the display of the HS 50. The event contains the title of the button.

override fun didClickButton(device: NIMMSTADevice, button: String) {
  Log.d(TAG, "Button $button was clicked")
}

@Override
public void didClickButton(NIMMSTADevice device, String button) {
  Log.d(TAG, "Button " + button + " was clicked");
}

Trigger Event

A Trigger Event is fired if the trigger is pressed on the device. The trigger is the button which is usually used to trigger a scan.

override fun didTrigger(device: NIMMSTADevice) {
  Log.d(TAG, "Scanner was triggered")
}

@Override
public void didTrigger(NIMMSTADevice device) {
  Log.d(TAG, "Scanner was triggered");
}

Double Trigger Event

A Double Trigger Event is fired if the trigger is pressed twice on the device in quick succession. The trigger is the button which is usually used to trigger a scan.

Note

Before receiving a Double Trigger Event, you will always receive a Trigger Event.

override fun didDoubleTrigger(device: NIMMSTADevice) {
  Log.d(TAG, "Scanner was double triggered")
}

@Override
public void didDoubleTrigger(NIMMSTADevice device) {
  Log.d(TAG, "Scanner was double triggered");
}

Triple Trigger Event

A Triple Trigger Event is fired if the trigger is pressed three times on the device in quick succession. The trigger is the button which is usually used to trigger a scan.

Note

Before receiving a Triple Trigger Event, you will always receive first a Trigger Event and then a Double Trigger Event.

override fun didTripleTrigger(device: NIMMSTADevice) {
  Log.d(TAG, "Scanner was triple triggered")
}

@Override
public void didTripleTrigger(NIMMSTADevice device) {
  Log.d(TAG, "Scanner was triple triggered");
}

Start Charging Event

A Start Charging Event is fired if the device is placed on the charging pad and starts charging.

override fun didStartCharging(device: NIMMSTADevice) {
  Log.d(TAG, "Device started charging")
}

@Override
public void didStartCharging(NIMMSTADevice device) {
  Log.d(TAG, "Device started charging");
}

Stop Charging Event

A Stop Charging Event is fired if the device is removed from the charging pad and stops charging.

override fun didStopCharging(device: NIMMSTADevice) {
  Log.d(TAG, "Device stopped charging")
}

@Override
public void didStopCharging(NIMMSTADevice device) {
  Log.d(TAG, "Device stopped charging");
}

Battery Level Changed Event

Battery Level Changed events occur if the percentage of the battery of the HS 50 changed.

override fun batteryLevelChanged(device: NIMMSTADevice, newBatteryLevel: Int) {
  Log.d(TAG, "Battery level changed to $newBatteryLevel")
}

@Override
public void batteryLevelChanged(NIMMSTADevice device, int newBatteryLevel) {
  Log.d(TAG, "Battery level changed to " + newBatteryLevel);
}

Software Update Progress Event

Software Update Progress events occur when a SoftwareUpdate is sent to the device and progress was made.

override fun softwareUpdateProgress(device: NIMMSTADevice, progressPercent: Int) {
  Log.d(TAG, "Software update progress is: $progressPercent")
}

@Override
public void softwareUpdateProgress(NIMMSTADevice device, int progressPercent) {
  Log.d(TAG, "Software update progress is: " + progressPercent);
}