# Class SetupPayload

java.lang.Object
com.codename1.home.commissioning.SetupPayload

public final class SetupPayload extends Object

A Matter onboarding payload: the `MT:` string behind the QR code on an accessory, or the 11 or 21 digit code printed under it.

##### Why this is parsed here rather than handed straight to the platform

Commissioning opens an operating-system sheet, and if the payload is garbage that sheet fails with the OS's own wording -- which tells a user nothing about the fact that they scanned the barcode on the box instead of the one on the device. Parsing first means a wrong code is caught in your app, in your words, before anything is opened.

It also makes a scanner screen possible: `getVendorId()` and `getProductId()` identify the accessory before it has joined anything, so a UI can say what it is about to add.

##### What is deliberately not here

There is no way to generate a payload, and `getPasscode()` exists because the format contains it, not because anything in this API wants it. Treat the passcode the way you would any pairing secret: do not log it and do not persist it.

Only the standard compact encoding is understood. A vendor-extended TLV payload -- the long form some accessories use to carry extra data -- is rejected by `parse(java.lang.String)` rather than half-read; the platform commissioning UI understands those, so pass the raw string through with `CommissioningRequest.setRawSetupPayload(java.lang.String)` when this refuses one.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DISCOVERY_BLE`
  Bluetooth Low Energy discovery bit of `getDiscoveryCapabilities()`.
  `static final int`
  `DISCOVERY_ON_NETWORK`
  On-network discovery bit of `getDiscoveryCapabilities()` -- the accessory is already on the IP network and is discoverable over mDNS.
  `static final int`
  `DISCOVERY_SOFT_AP`
  Wi-Fi discovery bit of `getDiscoveryCapabilities()`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `getCustomFlow()`
  Whether the vendor requires their own app to finish setup.
  `int`
  `getDiscoveryCapabilities()`
  How the accessory can be found, as a mask of `DISCOVERY_SOFT_AP`, `DISCOVERY_BLE` and `DISCOVERY_ON_NETWORK`.
  `int`
  `getDiscriminator()`
  The discriminator that picks this accessory out of several in pairing mode at once.
  `int`
  `getPasscode()`
  The pairing passcode.
  `int`
  `getProductId()`
  The vendor's product id for the accessory.
  `String`
  `getRaw()`
  The code exactly as it was supplied, for passing through to a platform that would rather parse it itself.
  `int`
  `getVendorId()`
  The Matter vendor id of the accessory.
  `int`
  `getVersion()`
  The payload format version.
  `boolean`
  `isFromQrCode()`
  Whether this came from a scanned QR payload rather than a typed code.
  `boolean`
  `isShortDiscriminator()`
  Whether `getDiscriminator()` is the short four-bit form.
  `static boolean`
  `isValid(String text)`
  Whether a string looks like something `parse(java.lang.String)` would accept, without throwing when it is not.
  `static SetupPayload`
  `parse(String text)`
  Parses a scanned QR payload or a typed manual code.
  `String`
  `toString()`
  A description safe to log or display.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### DISCOVERY_SOFT_AP

    public static final int DISCOVERY_SOFT_AP
    Wi-Fi discovery bit of `getDiscoveryCapabilities()`.
    See Also:
      - Constant Field Values

  - ### DISCOVERY_BLE

    public static final int DISCOVERY_BLE
    Bluetooth Low Energy discovery bit of `getDiscoveryCapabilities()`.
    See Also:
      - Constant Field Values

  - ### DISCOVERY_ON_NETWORK

    public static final int DISCOVERY_ON_NETWORK
    On-network discovery bit of `getDiscoveryCapabilities()` -- the accessory is already on the IP network and is discoverable over mDNS.
    See Also:
      - Constant Field Values

- ## Method Details

  - ### parse

    public static SetupPayload parse(String text)

    Parses a scanned QR payload or a typed manual code.

    Accepts the `MT:` QR form and the 11 and 21 digit manual forms, and tolerates the separators people type into a manual code -- spaces and hyphens are stripped before the digits are read.

    ###### Parameters

    - `text`: the scanned or typed code

    ###### Returns

    the parsed payload

    ###### Throws

    - `IllegalArgumentException`: when the text is not a Matter setup payload, when its check digit does not match, or when it is a vendor-extended payload this parser does not read. The message says which, because it is written to be shown to whoever is holding the accessory.

  - ### isValid

    public static boolean isValid(String text)

    Whether a string looks like something `parse(java.lang.String)` would accept, without throwing when it is not.

    For a scanner that is looking at every barcode in view and needs to ignore the ones that are not setup codes.

    ###### Parameters

    - `text`: the candidate, or `null`

    ###### Returns

    `true` when parsing would succeed

  - ### getRaw

    public String getRaw()

    The code exactly as it was supplied, for passing through to a platform that would rather parse it itself.

    ###### Returns

    the original text, never `null`

  - ### getVersion

    public int getVersion()

    The payload format version. Zero for a manual code, which does not carry one.

    ###### Returns

    the version

  - ### getVendorId

    public int getVendorId()

    The Matter vendor id of the accessory.

    Zero when unknown -- an 11-digit manual code does not carry one.

    ###### Returns

    the vendor id, or zero

  - ### getProductId

    public int getProductId()

    The vendor's product id for the accessory. Zero when unknown; see `getVendorId()`.

    ###### Returns

    the product id, or zero

  - ### getCustomFlow

    public int getCustomFlow()

    Whether the vendor requires their own app to finish setup.

    A non-zero custom flow means the accessory's manufacturer has declared that standard commissioning alone will not fully configure it -- so it may join the home and still not work until the user opens the vendor's app. Worth telling the user before they start rather than after.

    ###### Returns

    the custom-flow code; zero for a standard accessory

  - ### getDiscoveryCapabilities

    public int getDiscoveryCapabilities()

    How the accessory can be found, as a mask of `DISCOVERY_SOFT_AP`, `DISCOVERY_BLE` and `DISCOVERY_ON_NETWORK`.

    A manual code does not carry this, so one is reported as BLE and on-network, which is what the platform will try anyway.

    ###### Returns

    the discovery mask

  - ### getDiscriminator

    public int getDiscriminator()

    The discriminator that picks this accessory out of several in pairing mode at once.

    ###### Returns

    the 12-bit discriminator

  - ### isShortDiscriminator

    public boolean isShortDiscriminator()

    Whether `getDiscriminator()` is the short four-bit form.

    A manual code carries only the top four bits, so it narrows the field rather than identifying one accessory. Two devices in pairing mode in the same room can both match a typed code, which is a real situation and the reason the platform's own UI may still ask the user to choose.

    ###### Returns

    `true` when only the top four bits are meaningful

  - ### getPasscode

    public int getPasscode()

    The pairing passcode.

    A secret. Do not log it, do not persist it, and do not display it beyond echoing back what the user just typed.

    ###### Returns

    the passcode

  - ### isFromQrCode

    public boolean isFromQrCode()

    Whether this came from a scanned QR payload rather than a typed code.

    ###### Returns

    `true` for a QR payload

  - ### toString

    public String toString()

    A description safe to log or display.

    Names the vendor and product and omits the passcode, which is why it exists at all -- the obvious `toString` would have put a pairing secret into a log the first time someone debugged a scanner.

    ###### Returns

    the description, never `null`

    Overrides:
      `toString` in class `Object`