NAME

OpenHAP::MDNS - mDNS service registration wrapper for mdnsctl(8)

SYNOPSIS

    use OpenHAP::MDNS;
    my $mdns = OpenHAP::MDNS->new(
        service_name => 'OpenHAP Bridge',
        port         => 51827,
        txt_records  => {
            'c#' => 1,
            'ff' => 0,
            'id' => 'AA:BB:CC:DD:EE:FF',
            'md' => 'OpenHAP',
            'pv' => '1',
            's#' => 1,
            'sf' => 1,
            'ci' => 2,
        },
    );
    $mdns->register_service();
    # Later, on shutdown
    $mdns->unregister_service();

DESCRIPTION

This module provides a wrapper around OpenBSD's mdnsctl(8) command to register HomeKit Accessory Protocol (HAP) services with mdnsd(8) for Bonjour/mDNS service discovery.

iOS devices use mDNS to discover HAP accessories on the local network. This module enables that discovery by registering the appropriate service with the required TXT records.

METHODS

new

    my $mdns = OpenHAP::MDNS->new(%args);

Create a new MDNS registration handler. Options:

"service_name" (string): The service name to advertise. This appears as the accessory name in the Home app. Default: "OpenHAP Bridge".
"port" (integer): TCP port number where the HAP server is listening. Default: 51827.
"txt_records" (hashref): TXT record key-value pairs for the service. Required HAP fields:

"c#" - Configuration number (incremented when accessories change)
"ff" - Feature flags (typically 0)
"id" - Device ID in XX:XX:XX:XX:XX:XX format
"md" - Model name
"pv" - Protocol version (1, not 1.1 due to mdnsd dot delimiter)
"s#" - State number (typically 1)
"sf" - Status flags (1 if unpaired, 0 if paired)
"ci" - Category identifier (2 for bridge)

Default: "{}".

"mdnsctl" (string): Path to the "mdnsctl" command. Default: "/usr/sbin/mdnsctl".

register_service

    $mdns->register_service();

    mdnsctl publish "Service Name" hap tcp port "key1=val1.key2=val2"

Note that TXT record entries are separated by dots ("."), not commas. This matches how mdnsd(8) serializes TXT records internally using length-prefixed character-strings per RFC 6763.

The "mdnsctl" process must remain running to maintain the service registration. The process ID is stored internally and can be killed via unregister_service().

Returns 1 on success, "undef" on failure. Failures are logged as warnings but do not die, allowing the daemon to continue running even if mdnsd is not available.

If the service is already registered, this method returns immediately without attempting re-registration.

unregister_service

    $mdns->unregister_service();

Unregister the HAP service by killing the mdnsctl process. Sends a TERM signal to the background mdnsctl process started by register_service().

Returns 1 always. This should be called during daemon shutdown to clean up the service registration.

If the service is not registered, this method returns immediately.

is_registered

    my $bool = $mdns->is_registered();

Returns true if the service is currently registered with mdnsd.

ERROR HANDLING

All methods that interact with mdnsctl handle errors gracefully:

Failures are logged as warnings via OpenHAP::Log
Methods return "undef" on failure rather than dying
The daemon can continue operating without mDNS registration

This design allows OpenHAP to function even when mdnsd(8) is not running or available.

EXAMPLES

Basic Usage

    use OpenHAP::MDNS;
    use OpenHAP::HAP;
    my $hap = OpenHAP::HAP->new(name => 'My Bridge');
    
    my $mdns = OpenHAP::MDNS->new(
        service_name => $hap->{name},
        port         => 51827,
        txt_records  => $hap->get_mdns_txt_records(),
    );
    $mdns->register_service();

Custom mdnsctl Path

    my $mdns = OpenHAP::MDNS->new(
        service_name => 'Test Bridge',
        mdnsctl      => '/usr/local/sbin/mdnsctl',
    );

OPENBSD CONVENTIONS

This module follows OpenBSD conventions:

Uses mdnsctl(8) rather than implementing mDNS protocol directly
Fails gracefully when system services are unavailable
Logs via syslog using OpenHAP::Log
Returns undef for recoverable errors, reserves die for programming errors