Pairing a Camera

Pairing hands a camera the credentials it needs to reach the network and a pairing session key that ties it to the space. The key is created here first; how it reaches the camera is the only difference between the two pairing methods, and both end with the same key being consumed.

Pre-requisite: The user has to be signed in to perform the following operations.

Create a pairing session key

To create a pairing session key, The following method can be used:

spaceId (required): The space ID of the device.
request (required): PairingSessionRequest — timezoneSettings is required; sessionType defaults to SessionType.OTHER.value and deviceId to null.

The camera is provisioned with the time zone given here, so it is normally taken from the phone. TZ.getTzFormat builds the POSIX format string that accompanies the id — see Time Zones for the format and for changing it later.

val timezoneId = TimeZone.getDefault().id                 // "Asia/Kolkata"
val tzFormat = TZ.getTzFormat(assetManager, timezoneId)   // "IST-5:30"

val request = PairingSessionRequest(
  timezoneSettings = TimezoneSettings(timezoneId, tzFormat), // The timezone settings
  sessionType = SessionType.FOUR_G.value, // Optional; defaults to SessionType.OTHER.value ("")
  deviceId = "deviceId" // Optional; the backend expects it for a 4G camera
)
InstaVision.deviceServices.createPairingSession(
  spaceId = "spaceId",
  request = request,
  onSuccess = { pairingSession ->
    // The object contains the pairing session key
  },
  onError = { error ->
    // The error object contains the error code and message
  },
)

Get the pairing session status

To poll the status of a pairing session created earlier, The following method can be used. onSuccess receives a PairingStatusResponse (deviceId, expired, status, login, pairing):

spaceId (required): The space ID of the device.
sessionKey (required): The pairing session key.

InstaVision.deviceServices.getPairingSessionStatus(
  spaceId = "spaceId",
  sessionKey = "sessionKey",
  onSuccess = { status ->
    // The object contains the pairing session status
  },
  onError = { error ->
    // The error object contains the error code and message
  },
)

Both pairing methods confirm the result the same way, because the camera reports to the backend rather than to the app. Poll every 3 seconds until status equals PairingStatus.PROCESSED.type; the response then carries the deviceId of the paired camera.

val paired = status.status == PairingStatus.PROCESSED.type
val failed = status.expired || status.isLoginFailed() || status.isPairingFailed()

A failed attempt cannot be retried with the same key — create a fresh session and start again.

Choosing a pairing method

Page	Covers
Pairing via BLE	Connecting over Bluetooth and writing the Wi-Fi credentials to the camera
Pairing via QR Code	Rendering the credentials as a QR code for the camera to read with its lens

Only one of the two can be in progress at a time — the QR path requires that no BLE session is open, so call InstaVision.bleService.release() before switching to it.

Pairing a Camera

Create a pairing session key

Get the pairing session status

Choosing a pairing method

Table of contents