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

const currentDevice = connectionManager.devices.length > 0 ? connectionManager.devices[0] : null;
// or
const deviceWithAddress = connectionManager.getDeviceWithAddress("AB:CD:EF:00:01:02");

Properties

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

  • Get/Set preferredTriggerMode = Disabled, Button, Touch, ButtonAndTouch
  • Get/Set preferredPickingMode = DISABLED, ENABLED
  • 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

Example

// Get TriggerMode
const triggerMode = device.preferredTriggerMode;
// Change TriggerMode
device.preferredTriggerMode = TriggerMode.ButtonAndTouch;
// Change DecoderBoardSettings to only allow QR Codes to be scanned
device.decoderBoardSettings = '{"decoderboardSettings":{"00":"00","01":"00","02":"00","04":"00","05":"00","06":"00","07":"00","08":"00","F163":"00","09":"00","F046":"00","E3":"00","0A":"00","0B":"00","0C":"00","0D":"00","0E":"00","F16A":"00","0F":"00","53":"00","54":"00","55":"00","59":"00","F150":"00","F073":"00","5A":"00","5B":"00","5F":"00","60":"00","F80538":"00","28":"00","29":"00","F140":"00","F142":"00","F022":"00","F80772":"00","F023":"00","F145":"00","F024":"00","F026":"00","2A":"00","F8048F":"00","F052":"00","F053":"00","F098":"00","F054":"00","F055":"00","F056":"00","7B":"00","F13D":"00","F13E":"00"},"appSettings":{}}';

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 promise to be resolved and extract it in the following way: 

device.getDeviceInfo().then((response) => {
    // Address of the device
    const address = response.address;
    // Current batteryLevel in percent
    const batteryLevel = response.batteryLevel;
    // Current version of the hardware of the connected HS 50
    const hardwareVersion = response.hardwareVersion;
    // Current version of the firmware of the connected HS 50
    const firmwareVersion = response.firmwareVersion;
    // Current version of the ble firmware of the connected HS 50
    const bleFirmwareVersion = response.bleFirmwareVersion;
    // Current version of the ble script of the connected HS 50
    const bleScriptVersion = response.bleScriptVersion;
    // Current version of the imager of the connected HS 50
    const imagerFirmwareVersion = response.imagerFirmwareVersion;
    // Current version of the touch controller of the connected HS 50
    const touchFirmwareVersion = response.touchFirmwareVersion;
    // Current version of the bootloader
    const bootloaderVersion = response.bootloaderVersion;
    // Serial number of the HS-50
    const serialNumber = response.serialNumber;
}).catch((error) => {
    console.log("Error getting device info", error);
});

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().then(() => {
    console.log("HS 50 is connected");
}).catch((error) => {
    console.log("HS 50 is not connected", error);
});

Disconnect

Disconnect from the device.

device.disconnect().then(() => {
    console.log("Disconnected");
}).catch((error) => {
    console.log("Error while disconnecting", error);
})

Stop Reconnecting

Stops a device from reconnecting.

device.stopReconnecting().then(() => {
    console.log("Reconnecting stopped");
}).catch((error) => {
    console.log("Error while stopping reconnecting", error);
})

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 two predefined layouts that can be used with this function:

  • SuccessLayout: Displays a tick icon and some text
  • ErrorLayout: Displays a cross icon and some text

To change the layout you need to do the following: 

device.setLayout(new SuccessLayout("Test successful")).then(() => {
    console.log("Layout successfully set");
}).catch((error) => {
    console.log("Error setting layout", error);
});
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 for.

device.setLayoutFor(3000, new SuccessLayout("Test successful")).then(() => {
    console.log("Layout with timeout successfully set");
}).catch((error) => {
    console.log("Error setting layout with timeout", error);
})

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. 

const 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>
                <!-- The elements are going to be placed here -->
                <cell x="10" y="10" name="text1">Text1</cell>
                <cell x="10" y="50" name="text2">Text2</cell>
            </staticElements>
        </screen>
    </device>
</NimmstaLayout>
`;
device.setXMLLayout(xml).then(() => {
    console.log("XML layout successfully set");
}).catch((error) => {
    console.log("Error setting XML layout", error);
});

Set XML Layout For

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

const 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>
                <!-- The elements are going to be placed here -->
                <cell x="10" y="10" name="text1">Text1</cell>
                <cell x="10" y="50" name="text2">Text2</cell>
            </staticElements>
        </screen>
    </device>
</NimmstaLayout>
`;
device.setXMLLayoutFor(5000, xml).then(() => {
    console.log("XML layout with timeout successfully set");
}).catch((error) => {
    console.log("Error setting XML layout with timeout", error);
});

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: 

device.updateLayout({"text1": "New Text 1", "text2": "New Text 2"}).then(() => {
    console.log("Layout successfully updated");
}).catch((error) => {
    console.log("Error updating layout", error);
});

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
const red = 255;
const green = 0;
const blue = 255;
device.setLEDColor(red, green, blue).then(() => {
    console.log("Led color successfully set");
}).catch((error) => {
    console.log("Error setting LED color", error);
});

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
const hex = "#FF00FF";
device.setLEDColorHex(hex).then(() => {
    console.log("Led color successfully set");
}).catch((error) => {
    console.log("Error setting LED color", error);
});

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. A Trigger Burst can be triggered in two different ways 

// Way 1 - Parameters
const repeat = 5; // How often to trigger the beeper. 0 means indefinitely. Must be greater or equal to 0 and smaller or equal to 255
const duration = 500; // Duration how long one cycle takes in milliseconds. Must be greater or equal to 10 and smaller or equal to 4095
const 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
const intensity = 100; // How loud the beeper is (0-100).
device.triggerBeeperBurstParameters(repeat, duration, pulseDuration, intensity).then(() => {
    console.log("Successfully triggered beeper burst");
}).catch((error) => {
    console.log("Error triggering beeper burst", error);
});
// Way 2 - Beeper Burst Class
const beeperBurst = new BeeperBurst(repeat, duration, pulseDuration, intensity);
device.triggerBeeperBurst(beeperBurst).then(() => {
    console.log("Successfully triggered beeper burst");
}).catch((error) => {
    console.log("Error triggering beeper burst", error);
});

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. You can trigger a LED burst on the HS 50 in two different ways. 

// Way 1 - Parameters
const red = 255;
const green = 0;
const blue = 255;
const repeat = 3; // Amount of repeats, 0 means indefinitely. Must be greater or equal to 0 and smaller or equal to 255
const duration = 500; // Duration how long one cycle takes in milliseconds. Must be greater or equal to 10 and smaller or equal to 4095
const 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.triggerLEDBurstParameters(repeat, duration, pulseDuration, red, green, blue).then(() => {
    console.log("Led burst successfully triggered");
}).catch((error) => {
    console.log("Error triggering LED Burst", error);
});
// Way 2 - LED Burst Class
const ledBurst = new LedBurst(repeat, duration, pulseDuration, red, green, blue);
device.triggerLEDBurst(ledBurst).then(() => {
    console.log("Led burst successfully triggered");
}).catch((error) => {
    console.log("Error triggering LED Burst", error);
});

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().then(() => {
    console.log("Successfully triggered SOS");
}).catch((error) => {
    console.log("Error triggering SOS", error);
});

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. A vibrator burst can be triggered in two ways. 

// Way 1 - Parameters
const repeat = 5; // How often to trigger the vibrator. 0 means indefinitely. Must be greater or equal to 0 and smaller or equal to 255
const duration = 500; // Duration how long one cycle takes in milliseconds. Must be greater or equal to 10 and smaller or equal to 4095
const 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
const intensity = 100; // How strong the vibration is (0-100).
device.triggerVibratorBurstParameters(repeat, duration, pulseDuration, intensity).then(() => {
    console.log("Successfully triggered vibrator burst");
}).catch((error) => {
    console.log("Error triggering vibrator burst", error);
});
// Way 2 - Vibrator Burst Class
const vibratorBurst = new VibratorBurst(repeat, duration, pulseDuration, intensity);
device.triggerVibratorBurst(vibratorBurst).then(() => {
    console.log("Successfully triggered vibrator burst");
}).catch((error) => {
    console.log("Error triggering vibrator burst", error);
});

Trigger Multi Bursts

You can trigger multiple bursts at the same time with the triggerBursts method. If you only want to trigger two different bursts at the same time you can use null for the remaining one. 

const repeat = 5;
const duration = 500;
const pulseDuration = 250;
const intensity = 100;
const red = 255;
const green = 0;
const blue = 255;

const ledBurst = new LedBurst(repeat, duration, pulseDuration, red, green, blue);
const vibratorBurst = new VibratorBurst(repeat, duration, pulseDuration, intensity);
const beeperBurst = new BeeperBurst(repeat, duration, pulseDuration, intensity);
device.triggerBursts(ledBurst, vibratorBurst, beeperBurst).then(() => {
    console.log("Successfully triggered bursts");
}).catch((error) => {
    console.log("Error triggering bursts", error);
});

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 

const duration = 1000;

device.triggerImager(duration).then(() => {
    console.log("Successfully triggered imager");
}).catch((error) => {
    console.log("Error triggering imager", error);
});

Events

The following events can be subscribed to be notified if the event occurred:

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: 

device.scanEvent.subscribe((event) => {
    console.log("Scanned barcode:", event.barcode);
    console.log("Barcode Bytes:", event.barcodeBytes);
    // original (scanned) barcode without rules applied
    console.log("Scanned barcode without rules:", event.originalBarcode);
});

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. 

device.touchEvent.subscribe((event) => {
    console.log(`TouchEvent: X: ${event.x} Y: ${event.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. 

device.buttonEvent.subscribe((event) => {
    console.log(`Button "${event.value}" was pressed.`);
});

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. 

device.triggerEvent.subscribe((event) => {
    console.log('Trigger Event');
});

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.

device.doubleTriggerEvent.subscribe((event) => {
    console.log('Double Trigger Event');
});

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.

device.tripleTriggerEvent.subscribe((event) => {
    console.log('Triple Trigger Event');
});

Start Charging Event

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

device.startChargingEvent.subscribe((event) => {
    console.log(`Started Charging, Battery Level: ${event.batteryLevel}`);
});

Stop Charging Event

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

device.stopChargingEvent.subscribe((event) => {
    console.log(`Stopped Charging, Battery Level: ${event.batteryLevel}`);
});

Error Event

An error event occurs if no action that was sent can be found for the error response that the Android app sent. This most likely means that a general error occurred which has nothing to do with the corresponding actions. 

device.errorEvent.subscribe((event) => {
    console.log("An error occurred", event.message+"<br>"+event.stacktrace);
});

Battery Level Changed Event

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

device.batteryLevelChangedEvent.subscribe((event) => {
    console.log(`Battery level changed to ${event.batteryLevel}`);
});

Disconnect Event

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

device.disconnectEvent.subscribe((event) => {
    console.log(`Device disconnected with reason ${event.reason}`);
});