Skip to content

Regular Requests

This section documents all requests that can be sent once a connection has been established successfully.

Info

The following examples are all showing the Request. A general overview of how the responses look can be found in the overview section of the documentation. If the response contains additional data, we also document them here.

General Requests

General Requests do not need a connected device in order to be executed.

Update Keyboard Settings

Updates global keyboard settings. Need to be set again if the application is restarted.

Warning

This setting is only available on Windows!

  • keyInsertDelay (number) Time between keys in ms. Default is 0.
  • barcodeInsertDelay (number) Time between barcodes in ms. Please keep in mind that the delay happens after the barcode was inserted. Default is 0.
  • keyUpDelay (number) Time between key down and key up events in ms. Default is 0.
{
    "type": "GENERAL_REQUEST",
    "id": 0,
    "action": {
        "name": "UpdateKeyboardSettings",
        "data": {
            "keyInsertDelay": 10,
            "barcodeInsertDelay": 100,
            "keyUpDelay": 0
        }
    }
}

Adapt multi device setting

Enable or disable multi device after starting application without it.

{
    "type": "GENERAL_REQUEST",
    "id": 0,
    "action": {
        "name": "SetConnectionManagerSettings",
        "data": {
            "allowMultiDevice": true
        }
    }
}

Press Keys

Warning

This request is only available on Windows!

Press keys on the keyboard.

  • string (string) String with keys to be pressed.
  • virtualKeyCodes (boolean) True if virtual key codes should be used, false if unicode mode should be used.
{
    "type": "GENERAL_REQUEST",
    "id": 0,
    "action": {
        "name": "PressKeys",
        "data": {
            "string": "test123",
            "virtualKeyCodes": false
        }
    }
}

Device Requests

Device Requests need a connected device in order to be executed. If no device is provided, the first connected device is used.

Check Compatibility

Checks compatibility of the current version with the Websocket API. This Request should be used before establishing a connection to check if the API Version of the Websocket API changed, for example because of a software update.

You should throw an exception if the versions are incompatible and update your client application to comply with the new API version.

  • version (number) Current API Version.

Returns

  • clientVersion (string) Version string of the client.
  • apiVersion (string) Version string of the API.
  • compatible (boolean) True if they are compatible, false otherwise.
{
    "type": "GENERAL_REQUEST",
    "device": "E1:98:8B:41:2A:70",
    "id": 0,
    "action": {
        "name": "CheckCompatibility",
        "data": {
            "version": 2.0
        }
    }
}

Get Device Info

Get infos about the connected device.

Returns

  • address (string) Device address.
  • bleFirmwareVersion (string) BLE firmware version.
  • bleScriptVersion (string) BLE script version.
  • imagerFirmwareVersion (string) Imager firmware version.
  • hardwareVersion (string) Hardware version.
  • batteryLevel (number) Battery level (0-100).
  • firmwareVersion (string) Firmware version.
{
    "type": "DEVICE_REQUEST",
    "device": "E1:98:8B:41:2A:70",
    "id": 0,
    "action": {
        "name": "GetDeviceInfo"
    }
}

Set Device Settings

Change the settings of your device.

  • prefersShutdownOnCharge (boolean) If set to true the scanner should shut down when placed on the charging pad (default: false)
  • prefersReconnect (boolean) If set to true the device should automatically try to reconnect if the connection is lost (default: true).
  • preferredTriggerMode (string) Defines when scanning should be triggered (default: ButtonAndTouch).
    • By Button press and by pressing on the touchscreen (ButtonAndTouch)
    • Only by button press (Button)
    • Only by pressing on the touchscreen (Touch)
    • Disabled (Disabled)
    • Use the default trigger mode when enabled (DefaultEnabled)
    • By Motion Trigger (Beta), Button Press, and by pressing on the touchscreen (MotionAndButtonAndTouch)
    • By Motion Trigger (Beta) and by pressing on the touchscreen (MotionAndTouch)
    • By Motion Trigger (Beta) and by button press (MotionAndButton)
    • By Motion Trigger (Beta) only (Motion)
  • preferredPickingMode (string) Defines if PickingMode is enabled or disabled. In PickingMode if the button is pressed red crosshairs are shown while no barcodes will be scanned yet. Only the second time scanning is triggered a barcode will be scanned. The crosshairs are disabled after a timeout. If PickingMode is disabled scanning must be triggered until a barcode is scanned (default: DISABLED)
{
    "type": "DEVICE_REQUEST",
    "device": "E1:98:8B:41:2A:70",
    "id": 0,
    "action": {
        "name": "SetDeviceSettings",
        "data": {
            "prefersShutdownOnCharge": true,
            "prefersReconnect": false,
            "preferredTriggerMode": "Button",
            "preferredPickingMode": "ENABLED"
        }
    }
}

Set LED Color

To set the color of the NIMMSTA Smart Watch 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.

  • red (number) Value for red (0-255).
  • green (number) Value for green (0-255).
  • blue (number) Value for blue (0-255).
{
    "type": "DEVICE_REQUEST",
    "device": "E1:98:8B:41:2A:70",
    "id": 0,
    "action": {
        "name": "SetLEDColor",
        "data": {
            "red": 255,
            "green": 255,
            "blue": 255
        }
    }
}

Trigger Beeper Burst

A beeper burst is a succession of beeps of the NIMMSTA 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 (number) How often to trigger the beeper. 0 means indefinitely (0-10).
  • duration (number) Duration how long one cycle takes in milliseconds (10-4095).
  • pulseDuration (number) How long the beeper is on within one cycle in milliseconds (10-4095).
  • intensity (number) Volume of the beeper (0-100).
{
    "type": "DEVICE_REQUEST",
    "device": "E1:98:8B:41:2A:70",
    "id": 0,
    "action": {
        "name": "TriggerBeeperBurst",
        "data": {
          "repeat": 5,
          "duration": 500,
          "pulseDuration": 250,
          "intensity": 100
        }
    }
}

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.

  • red (number) Value for red (0-255).
  • green (number) Value for green (0-255).
  • blue (number) Value for blue (0-255).
  • repeat (number) Amount of repeats, 0 means indefinitely (0-10).
  • duration (number) Duration how long one cycle takes in milliseconds (10-4095).
  • pulseDuration (number) How long the LED is on within one cycle in milliseconds (10-4095).
{
  "type": "DEVICE_REQUEST",
  "device": "E1:98:8B:41:2A:70",
  "id": 0,
  "action": {
    "name": "TriggerLEDBurst",
    "data": {
      "red": 255,
      "green": 255,
      "blue": 255,
      "repeat": 3,
      "duration": 500,
      "pulseDuration": 250
    }
  }
}

Trigger SOS

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

{
    "type": "DEVICE_REQUEST",
    "device": "E1:98:8B:41:2A:70",
    "id": 0,
    "action": {
      "name": "TriggerSOS"
    }
}

Trigger Vibrator Burst

A vibrator burst is a succession of vibrations of the NIMMSTA 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 (number) How often to trigger the vibrator. 0 means indefinitely (0-10).
  • duration (number) Duration how long one cycle takes in milliseconds (10-4095).
  • pulseDuration (number) How long the vibrator is on within one cycle in milliseconds (10-4095).
  • intensity (number) Intensity of the vibrator (0-100).
{
  "type": "DEVICE_REQUEST",
  "device": "E1:98:8B:41:2A:70",
  "id": 0,
  "action": {
    "name": "TriggerVibratorBurst",
    "data": {
      "repeat": 3,
      "duration": 500,
      "pulseDuration": 250,
      "intensity": 100
    }
  }
}

Trigger Bursts

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

  • ledBurst (object)
    • repeat (number) Amount of repeats, 0 means indefinitely (0-10).
    • duration (number) Duration how long one cycle takes in milliseconds (10-4095).
    • pulseDuration (number) How long the LED is on within one cycle in milliseconds (10-4095).
    • red (number) Value for red (0-255).
    • green (number) Value for green (0-255).
    • blue (number) Value for blue (0-255).
  • vibratorBurst (object)
    • repeat (number) Amount of repeats, 0 means indefinitely (0-10).
    • duration (number) Duration how long one cycle takes in milliseconds (10-4095).
    • pulseDuration (number) How long the vibrator is on within one cycle in milliseconds (10-4095).
    • intensity (number) Intensity of the vibrator (0-100).
  • beeperBurst (object)
    • repeat (number) Amount of repeats, 0 means indefinitely (0-10).
    • duration (number) Duration how long one cycle takes in milliseconds (10-4095).
    • pulseDuration (number) How long the beeper is on within one cycle in milliseconds (10-4095).
    • intensity (number) Intensity of the beeper (0-100).
{
  "type": "DEVICE_REQUEST",
  "device": "E1:98:8B:41:2A:70",
  "id": 0,
  "action": {
    "name": "TriggerBursts",
    "data": {
      "ledBurst": {
        "repeat": 3,
        "duration": 500,
        "pulseDuration": 250,
        "red": 255,
        "green": 255,
        "blue": 255
      },
      "vibratorBurst": {
        "repeat": 3,
        "duration": 500,
        "pulseDuration": 250,
        "intensity": 100
      },
      "beeperBurst": {
        "repeat": 3,
        "duration": 500,
        "pulseDuration": 250,
        "intensity": 100
      }
    }
  }
}

Trigger Imager

Warning

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

Triggers a scan on the device.

  • pulseDuration (number) How long the imager should stay on (0 - 4095).
{
  "type": "DEVICE_REQUEST",
  "device": "E1:98:8B:41:2A:70",
  "id": 0,
  "action": {
    "name": "TriggerImager",
    "data": {
      "pulseDuration": 2000
    }
  }
}

Set Layout

To change the contents of the NIMMSTA Smart Watch screen, you can send a setLayout Request with your own custom XML that represents a layout the NIMMSTA Smart Watch can understand. To learn more about XML layouts have a look at the Layout Documentation.

  • layout (string) XML Layout as string.
  • layoutData (object)
    • text1 (string) Text to replace the contents of text1 with.
    • text2 (string) Text to replace the contents of text2 with.

It will return once the screen has been refreshed. If another setLayout call is done before, a CancellationException is thrown.

Note

The key values for this Request are not limited to text1 and text2. You can have any number of arguments, but they need to correspond to a value in the layout.

{
  "type": "DEVICE_REQUEST",
  "device": "E1:98:8B:41:2A:70",
  "id": 0,
  "action": {
    "name": "SetLayout",
    "data": {
      "layout": "<?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>",
      "layoutData": {
        "text1": "test",
        "text2": "test2"
      }
    }
  }
}

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 learn more about XML layouts have a look at the Layout Documentation.

  • layoutData (object)
    • text1 (string) Text to replace the contents of text1 with.
    • text2 (string) Text to replace the contents of text2 with.

Note

The key values for this Request are not limited to text1 and text2. You can have any number of arguments, but they need to correspond to a value in the layout.

{
  "type": "DEVICE_REQUEST",
  "device": "E1:98:8B:41:2A:70",
  "id": 0,
  "action": {
    "name": "UpdateLayout",
    "data": {
      "layoutData": {
        "text1": "test",
        "text2": "test2"
      }
    }
  }
}

Set Layout For

Sets the layout for a given time (timeout).

  • timeout (long) Timeout in ms (how long should the layout be displayed before switching back)
  • layout (string) XML Layout as string.
  • layoutData (object | null | undefined) Can be null or undefined.
    • text1 (string) Text to replace the contents of text1 with.
    • text2 (string) Text to replace the contents of text2 with.

Note

The key values for this Request are not limited to text1 and text2. You can have any number of arguments, but they need to correspond to a value in the layout.

{
  "type": "DEVICE_REQUEST",
  "device": "E1:98:8B:41:2A:70",
  "id": 0,
  "action": {
    "name": "SetLayoutFor",
    "data": {
      "timeout": 10000,
      "layout": "<?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>",
      "layoutData": {
        "text1": "test",
        "text2": "test2"
      }
    }
  }
}

Validate Software Update

Validates that the software update file is correct.

Note

You need to check the software update file using this command before performing the software update using the Perform Software Update request.

Note

This request needs a valid security token (password) in order to be executed. This is a precautionary measure to prevent illegal access to the software update functionality. The security token is provided as a command line argument when the web server starts.

  • file (string) Filepath to the .nimmstaupdate file on the host machine.
  • securityToken (string) Security token as explained above.

Returns

  • name (string) The name of the software package. i.e. "Firmware Update".
  • version (string) Version of the software.
  • type (string) Type of the software update.
  • isNewerVersion (boolean) Defines whether it is considered an update for the software.
  • isDowngrade (boolean) Defines if the update is considered a downgrade or not.
  • isSupported (boolean) Defines if the update is supported.
  • errorReason (string | null) Set if file is not supported, check isSupported for that as well.
{
  "type": "DEVICE_REQUEST",
  "device": "E1:98:8B:41:2A:70",
  "id": 0,
  "action": {
    "name": "ValidateSoftwareUpdate",
    "data": {
      "file": "C:\\Users\\User1\\Downloads\\test1.nimmstaupdate",
      "securityToken": "7549a4db2350e2e6e12536420d4a9794"
    }
  }
}

Perform Software Update

Performs the software update by transmitting the update file to the device. Once the update is started, you will receive constant progress updates with the Software Update Progress Event.

Note

You first need to validate the update using Validate Software Update before you can send it to the device!

Note

This request needs a valid security token (password) in order to be executed. This is a precautionary measure to prevent illegal access to the software update functionality. The security token is provided as a command line argument when the web server starts.

  • file (string) Filepath to the .nimmstaupdate file on the host machine.
  • selectedComponents (array of strings) Array of names of selected components to install. Can be left empty, in which case the default component is used.
  • securityToken (string) Security token as explained above.

Returns

  • status (string) Returns "ok" if the software update is starting.
{
  "type": "DEVICE_REQUEST",
  "device": "E1:98:8B:41:2A:70",
  "id": 0,
  "action": {
    "name": "PerformSoftwareUpdate",
    "data": {
      "file": "C:\\Users\\User1\\Downloads\\test1.nimmstaupdate",
      "selectedComponents": ["HS 50 Firmware", "HS 50 BootLoader"],
      "securityToken": "7549a4db2350e2e6e12536420d4a9794"
    }
  }
}

Log Requests

Log Requests can be sent for debugging purposes. The will appear in the log of the Android or JVM Application.

  • level (string) DEBUG, INFO, WARN, ERROR.
  • message (string) Log message.
{
    "type": "LOG",
    "level": "DEBUG",
    "message": "test"
}