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 Details

  • 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