Protocol Overview

This section gives a quick overview over how Requests and Responses are constructed.

Requests

A Request contains the following parts:

• type (string) Type of the Request.
  • GENERAL_REQUEST Used for getting general information about the API or connection.
  • DEVICE_REQUEST Interaction with the device like setting the LED color or triggering a vibrator burst.
  • LOG Log specific events in the Android or JVM Applications for debugging purposes.
• id (number) Id to identify the request. This needs to be set to make sure your client library is able to match the Response with the correct Request. Note that you need to implement this logic yourself since Websockets are asynchronous.
• device (string) Device address. Can be undefined, in which case the first connected device will be selected.
• action (object) Action to execute.
  • name (string) Name of the action. Case-insensitive.
  • data (object) Additional data specific to the request. Can be undefined or null.

Example:

{
    "type": "DEVICE_REQUEST",
    "id": 1,
    "device": "E1:98:8B:41:2A:70",
    "action": {
        "name": "SetLEDColor",
        "data": {
            "red": 255,
            "green": 255,
            "blue": 255
        }
    }
}

Responses

There are two types of Responses:

ACTION

Actions are sent as a response to a request.

• type (string) Type of the response.
  • ACTION Response to an action triggered by the client developer.
• id (number) Id of the action. This is the same id that sent with the request.
• device (string) Device address of the device on which the action was executed.
• action (object) Information about the action.
  • name (string) Name of the executed action.
  • success (boolean) True if the action was successfully executed, false otherwise.
  • data (object) Data associated with the response.
  • message (string) Error message. Null if the Request was successful.
  • throwable (string) Stack trace of the error. Null if the Request was successful.

Example:

{
  "type": "ACTION",
  "id": 0,
  "device": "E1:98:8B:41:2A:70",
  "action": {
      "name": "DisplayConnectActivity",
      "success": true,
      "data": {},
      "message": null,
      "throwable": null
  }
}

EVENT

Events are sent by the device, for example a scanner.

• type (string) Type of the response.
  • EVENT Event received from the device, see section about events.
• event (object) Event info.
  • name (string) Name of the event.
  • device (string) Device address where the event originated.
  • data (object) Event-specific data.

Example:

{
  "type": "EVENT",
  "event": {
      "name": "BatteryLevelChanged",
      "device": "E1:98:8B:41:2A:70",
      "data": {
          "batteryLevel": 99
      }
  }
}