module

Matter::SetupPayload

SetupPayload handles encoding and decoding of Matter onboarding payloads

Matter devices use two types of setup codes:

  1. Manual Pairing Code: 11-digit decimal code (formatted as xxxx-xxx-xxxx)
  2. QR Code: Longer base38-encoded string with additional device information

Manual Pairing Code Format (Matter Core Spec § 5.1.4.1):

  • Bits 0-26: Setup PIN Code (27 bits)
  • Bits 27-38: Discriminator (12 bits)
  • Bit 39: Check digit (4 bits, Verhoeff algorithm)

The 11-digit code is computed as: (discriminator << 27) | PIN Then the Verhoeff check digit is appended.

Class methods

default_pin

Generate a default PIN for testing/examples Returns a valid PIN that's easy to remember

Source
format_manual_code(code : String) : String

Format an 11-digit code as xxxx-xxx-xxxx

Source
generate_manual_code(discriminator : UInt16, pin : UInt32, validate : Bool = true) : String

Generate a manual pairing code from discriminator and PIN

@param discriminator Device discriminator (12-bit value, 0-4095) @param pin Setup PIN code (27-bit value, 1-99999998, excluding invalid PINs) @param validate Whether to validate PIN security requirements (default: true) @return 11-digit manual pairing code string (formatted as xxxx-xxx-xxxx)

Algorithm from matter.js PairingCodeSchema.ts (Matter Core Spec § 5.1.4.1)

Source
generate_random_discriminator

Generate a random discriminator (12-bit value, 0-4095) Each device instance should have a unique discriminator

Source
generate_random_pin

Generate a random valid PIN that meets Matter requirements

  • Must be 1-99999998
  • Cannot be all same digit (11111111, etc.)
  • Cannot be 12345678 or 87654321
Source
generate_serial_number

Generate a serial number

Source
generate_unique_id

Generate a unique ID (UUID-like format)

Source
parse_manual_code(formatted_code : String) : Tuple(UInt16, UInt32)

Parse a formatted manual code back to discriminator and PIN

@param formatted_code Manual code in xxxx-xxx-xxxx format (or with spaces/dashes stripped) @return Tuple of {discriminator, pin}

Note: Manual pairing codes only encode the SHORT discriminator (top 4 bits of the full 12-bit discriminator). This function reconstructs the full discriminator from those 4 bits by assuming the lower 8 bits are zero. Algorithm from matter.js PairingCodeSchema.ts

Source
short_discriminator(discriminator : UInt16) : UInt16

Compute the short discriminator (4 bits: bits 8-11 of the full 12-bit discriminator) This is what gets encoded in manual pairing codes

Source
test_vendor_id

generate a test vendor id

Source

Nested types