Skip to content

Connection Requests

This section describes all Requests that are concerned with establishing connection, cancelling a connection attempt or disconnecting from a device.

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.

Display Connect Activity

Displays the connection screen.

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

Search for NIMMSTA Devices

Starts searching for connectable devices. If a device is found a DeviceFoundEvent is sent.

Note

Please make sure to catch errors for this request. If location or bluetooth permissions are not granted, this will return an error. As a workaround, we recommend using the DisplayConnectActivity action.

{
    "type": "GENERAL_REQUEST",
    "id": 0,
    "action": {
        "name": "SearchForNimmstaDevices",
        "data": {
            "checkPermissions": true // optional, default: false. Will check permissions using an activity before scanning.
        }
    }
}

Cancels searching for devices.

{
    "type": "GENERAL_REQUEST",
    "id": 0,
    "action": {
        "name": "CancelSearch"
    }
}

Enable / Disable Multi Device

Enables or disables the ability to connect multiple devices.

{
    "type": "GENERAL_REQUEST",
    "id": 0,
    "action": {
        "name": "SetConnectionManagerSettings",
        "data": {
            "allowMultiDevice": true, // false for disable
            "interpretButtonAsMotionTrigger": true // if true, the button will be interpreted as a motion trigger
        }
    }
}

Get Connection Code

Gets a connection code that can be displayed, so the user can scan it and connect.

Returns

  • connectionCode (string) Connection code to display, including the prefix.
  • qrCodeImage (string) Base64-encoded barcode image (PNG), size 300px x 300px.
{
  "type": "GENERAL_REQUEST",
  "id": 0,
  "action": {
    "name": "GetConnectionCode"
  }
}

Connect to Connection Code

Connect to a device using a connection code. The connection code consists of a 5-digit code and the prefix XXConnectHSD50XX: or a 6-digit code and the prefix XXConnectHST50XX: for temporary connection codes, which the device forgets on shutdown.

Note

Please make sure to catch errors for this request. If location or bluetooth permissions are not granted, this will return an error. As a workaround, we recommend using the DisplayConnectActivity action.

Returns

  • 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": "GENERAL_REQUEST",
    "id": 0,
    "action": {
        "name": "ConnectToConnectionCode",
        "data": {
            "connectionCode": "XXConnectHSD50XX:5F9OV",
            "checkPermissions": true // optional, default: false. Will check permissions using an activity before scanning.
        }
    }
}

Connect to Address

Connect to a device using an address.

Note

Please make sure to catch errors for this request. If location or bluetooth permissions are not granted, this will return an error. As a workaround, we recommend using the DisplayConnectActivity action.

Returns

  • 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": "GENERAL_REQUEST",
    "id": 0,
    "action": {
        "name": "ConnectToAddress",
        "data": {
            "address": "E1:98:8B:41:2A:70",
            "checkPermissions": true // optional, default: false. Will check permissions using an activity before scanning.
        }
    }
}

Check permissions using an activity

In order to check if all permissions are set and bluetooth is enabled, App Version 7.0.5+ provides a way to do this.

Returns empty response if all was good, error otherwise.

{
    "type": "GENERAL_REQUEST",
    "id": 0,
    "action": {
        "name": "CheckForPermissionsUsingActivity"
    }
}

Get Devices

Returns a list of all devices by a given filter. Filter is one of - ALL - CONNECTED - CONNECTING - CHARGING - SEARCHING_TO_RECONNECT

Returns

  • devices (array of strings) List of devices found.
{
    "type": "GENERAL_REQUEST",
    "id": 0,
    "action": {
        "name": "GetDevices",
        "data": {
            "filter": "CONNECTED"
        }
    }
}

Device Requests

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

Device Is Connected

Checks if a given device is connected.

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

Cancel connect

Cancel connection attempt with a device. You can either supply an address or a ConnectionCode. If both are supplied, the ConnectionCode is ignored.

  • address (string) Address of the device.
  • connectionCode (string) ConnectionCode including connect prefix.
{
    "type": "DEVICE_REQUEST",
    "device": "E1:98:8B:41:2A:70",
    "id": 0,
    "action": {
        "name": "CancelConnect",
        "data": {
            "address": "E1:98:8B:41:2A:70",
            "connectionCode": "XXConnectHSD50XX:5F9OV"
        }
    }
}

Cancel all connect

Cancels all connection attempts.

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

Disconnect

Disconnects from a given device. You can set shutdown to true in order to also shutdown.

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