Pairing a Camera

A camera fresh out of the box has no network. Pairing is how it gets one: your app hands it a Wi-Fi SSID and password together with a pairing session key, the camera joins the network, and it uses that key to register itself with InstaVision against the right space.

The SDK offers two ways to get those credentials across. They differ only in the hand-off — everything before and after it is the same.

  Bluetooth QR code
How the camera receives the credentials BLEManager writes them over BLE The camera reads them off your screen
Which camera the app talks to Chosen from a Bluetooth scan Identified by scanning the label on the camera
Where the Wi-Fi list comes from The camera reports what it can see The user types the network in
Needs Bluetooth permission Camera permission
Works when The model has a Bluetooth radio and the phone can reach it Always

Contents

  1. Choosing a transport
  2. What both flows share
  3. Before you start
  4. The pages

Choosing a transport

Bluetooth is the better experience where it works. The user picks their camera from a list instead of hunting for a printed label, and picks their network from the ones the camera can actually see rather than typing an SSID and hoping the camera can reach it.

It is also the one that can fail before it starts. Bluetooth may be switched off, the permission may be declined, the camera may never appear in the scan, the connection may drop mid-flow, or the model may have no Bluetooth radio at all. QR pairing needs none of that, which makes it the fallback for every one of those dead ends — and the primary flow for models that cannot do Bluetooth.

So build both, lead with Bluetooth, and put a “connect via QR code” action on every failure screen: no camera found, connection failed, permission denied, empty Wi-Fi list.

CameraModelProperties.bluetooth, from deviceModelInfo, tells you whether a given model supports the Bluetooth flow at all.

A cellular camera is a third case that cuts across both. Its SIM has to be activated with bootstrapSim before either transport runs, and its session key is created with sessionType: .fourG(deviceId:) rather than the default .other.

What both flows share

Whichever transport you use, three things are the same.

The same five values reach the camera — ssid, password, sessionKey, region and env. Bluetooth writes them as a WiFiDetailModel; the QR code carries them as newline-separated text. region and env are numeric codes rather than the ServerRegion and Environment values you configured the SDK with.

The same session key. Both flows call createPairingSessionKey first, and both should call it immediately before the hand-off — the key expires, and the clock starts when it is created, not when the camera finally receives it. The request carries the time zone the camera will run in, whose tzFormat is a POSIX TZ string read out of the table.

The same confirmation. Neither hand-off reports success. In both flows you poll getPairingSessionStatus with the session key until the camera reports in, then poll the device itself until its pairingStatus is ready to use. Until that poll succeeds you do not know the camera got anything at all.

Before you start

Add whichever usage descriptions the flows you ship need. The app is terminated the first time it touches a framework whose description is missing:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>Used to set up your camera over Bluetooth.</string>

<key>NSCameraUsageDescription</key>
<string>Used to scan the QR code on your camera.</string>

The camera must be powered on and in pairing mode for either flow, and the user must be signed in and have a space to pair into.

The pages

  • Pairing Session Keys — creating a session key, polling its status, and the time zone formats the request needs. Read this first; both transports depend on it.
  • Pairing over Bluetooth — the BLEManager flow end to end, its published properties, methods and types.
  • Pairing with a QR Code — the fallback flow, the QR payload format, and QRCodeGenerator.

Table of contents