Protocol::HAP::SetupCode(3p) Perl Library Manual Protocol::HAP::SetupCode(3p)

Protocol::HAP::SetupCode - the rules of the HomeKit setup code

    use Protocol::HAP::SetupCode qw(normalize_setup_code validate_setup_code);
    # Normalize a setup code (remove dashes and spaces)
    my $normalized = normalize_setup_code('9876-5432');  # Returns '98765432'
    my $normalized = normalize_setup_code('9876 5432');  # Returns '98765432'
    my $normalized = normalize_setup_code('98765432');   # Returns '98765432'
    # Validate a setup code
    if (validate_setup_code('9876-5432')) {
        print "Valid setup code\n";
    }
    if (!validate_setup_code('1234-5678')) {
        print "Invalid setup code (sequential pattern)\n";
    }

This module handles HAP setup codes: the 8-digit numeric codes that pairing uses. The specification calls them setup codes [HAP-Pairing §2], so no name here uses the word it replaced.

The HAP specification says that dashes and spaces are format characters only. The module removes them before use. Thus "9876-5432" and 98765432 are the same setup code.

This function removes the dashes and the spaces from a setup code. It returns the 8-digit numeric string.

    my $normalized = normalize_setup_code('9876-5432');
    # Returns: '98765432'

The function returns "undef" if the input format is not valid. A valid input has exactly 8 digits after normalization.

This function does a check of a setup code against these HAP requirements:

  • The code must have exactly 8 digits after the removal of the dashes and the spaces.
  • The code must not be a trivial or sequential pattern.

The function returns 1 if the setup code is valid. It returns "undef" if the setup code is not valid.

    if (validate_setup_code('9876-5432')) {
        # the setup code is valid
    }

The HAP specification rejects these setup codes:

    00000000  11111111  22222222  33333333  44444444
    55555555  66666666  77777777  88888888  99999999
    12345678  87654321

Protocol::HAP::SRP, Protocol::HAP::Pairing, openhapd.conf(5), spec/HAP-Pairing.md

HomeKit Accessory Protocol Specification (Non-Commercial Version) Release R2, Section 5.6: Setup Code

2026-08-18 OpenBSD