Getting Started

The Websocket Library is a wrapper around the core library for Android and JVM (Windows). It accepts connections from other applications on a websocket port. The library automatically sends all received events from the scanner to the client. Additionally, there are certain events that can be triggered from the client side, such as setting the LED color or changing the screen.

Requirements

• NIMMSTA Websocket Application, Windows App, or NIMMSTA Android App
• Client Application supporting Websockets
• Operating Systems:
  • Windows 64 Bit x86 with Java 64Bit
  • Linux 64 Bit with Java 64Bit (Tested with x86 on Ubuntu 20 and 22)
  • Android 8.0+
• Native Bluetooth capability with BLE 4.2+ on Android or Windows (Only Windows 10 Fall Creators Update (1709) or later) or NIMMSTA Bluetooth Dongle

Note

If you are using Android, you need at least version 5.0. You can get the latest version from the NIMMSTA B2B Portal.

Note

If you are using Windows, you can get the Websocket Jar from here: Download Websocket Jar.

Starting Websocket application (Linux + Windows)

Note

Make sure for Linux and Windows to have Java installed. We recommend OpenJDK or Oracle in Version 8-17.

When using the websocket application, you should start it like this:

java -jar websocket-7.0-xxx.jar [options] RANDOM

Please replace RANDOM with a random security token, which is needed for critical operations. There exist additional options here.

Integrate Websocket Library

To get started with the NIMMSTA Websocket Library, you have to create an application that will act as the websocket client.

The current default port is 64693 and the endpoint is /.

ws://localhost:64693

Connect a Scanner

There are multiple ways to connect a scanner. The simplest way of connecting is to use the displayConnectActivity request. If you send the following request a new window with the connection QR Code will be displayed.

{
  "type": "GENERAL_REQUEST",
  "id": 1,
  "action": {
    "name": "DisplayConnectActivity"
  }
}

This is the response you will get for this request:

{
  "type": "ACTION",
  "id": 1,
  "action": {
    "name": "DisplayConnectActivity",
    "success": true,
    "data": {},
    "message": null,
    "throwable": null
  }
}

Success = true indicates that the action was executed successfully. If success was false, you would get an error message and the stacktrace of the error that occurred.

If you now scan the connection QR Code with a scanner and the connection is established successfully you will get a ConnectEvent message from the socket:

{
  "type": "EVENT",
  "device": "C5:52:6A:11:A8:81",
  "event": {
    "name": "ConnectEvent",
    "data": {
      "reconnect": false
    }
  }
}

Now we know what the address of the connected scanner is so we can address the correct scanner for the device specific requests.

Sending request to devices

Sending request to perform actions on a connected scanner is almost identical to sending general requests. The only difference is that we need to specify a device address. In this example request we are turning the LED of the scanner green.

{
  "type": "DEVICE_REQUEST",
  "id": 2,
  "device": "C5:52:6A:11:A8:81",
  "action": {
    "name": "SetLEDColor",
    "data": {
      "red": "0",
      "green": "255",
      "blue": "0"
    }
  }
}

This request results in the following response, which indicates that the action was performed successfully:

{
  "type": "ACTION",
  "id": 2,
  "device": "C5:52:6A:11:A8:81",
  "action": {
    "name": "SetLEDColor",
    "success": true,
    "data": {},
    "message": null,
    "throwable": null
  }
}

Disconnect a scanner

If you want to disconnect a scanner you can send the following request:

{
  "type": "DEVICE_REQUEST",
  "id": 3,
  "device": "C5:52:6A:11:A8:81",
  "action": {
    "name": "Disconnect",
    "data": {
      "shutdown": false
    }
  }
}

Which then results in the following response which indicates that the scanner was successfully disconnected:

{
  "type": "ACTION",
  "id": 3,
  "device": "C5:52:6A:11:A8:81",
  "action": {
    "name": "Disconnect",
    "success": true,
    "data": {},
    "message": null,
    "throwable": null
  }
}

Also there will be another message with a DisconnectEvent. This events will get sent if a scanner disconnects (not only user initiated, but for example if the scanner gets out of range):

{
  "type": "EVENT",
  "device": "C5:52:6A:11:A8:81",
  "event": {
    "name": "DisconnectEvent",
    "data": {
      "reason": "USER_INITIATED"
    }
  }
}