[kgoderis]

Description

Bugfix / improvement for HomeKit bridge advertising on hosts where a system mDNS daemon already owns UDP 5353.

When useOHmDNS does not yield a matching shared JmDNS client (or when creating a dedicated advertiser), the add-on previously fell back to HAP-Java's JmDNS path, which binds UDP 5353. On macOS, mDNSResponder owns that port exclusively; the bind fails (Address already in use / "no suitable mDNS") and Apple Home never discovers _hap._tcp even though the HAP TCP listener is up. The same class of conflict appears with Avahi and other system responders.

This change prefers HAP-Java's native DNS-SD / Bonjour advertiser (HomekitAdvertisers.nativeDnssd() via DNSServiceRegister / JNA) when that path is supported, so _hap._tcp is published without binding 5353. Existing useOHmDNS=true sharing of openHAB's JmDNS is unchanged when a suitable client is found.

Depends on the upstream HAP-Java PR (not yet merged/released):

• Add native DNS-SD advertiser for macOS (no UDP 5353 bind) hap-java/HAP-Java#213
• macOS: JmDNS advertiser cannot bind UDP 5353 (mDNSResponder); need native DNS-SD path hap-java/HAP-Java#212

Until that lands on Maven Central as a release (currently hap 2.0.10-SNAPSHOT + embedded JNA 5.14.0), this PR is a draft. After the HAP-Java release, the pom will be bumped to the released version and the draft can leave WIP.

Resolves #22012

Related reports (mDNSResponder / UDP 5353 / _hap._tcp advertising)

GitHub

• macOS: JmDNS advertiser cannot bind UDP 5353 (mDNSResponder); need native DNS-SD path hap-java/HAP-Java#212 — macOS JmDNS cannot bind 5353; native DNS-SD needed
• [io.homekit] No recovery from SocketException #21970 — HomeKit advertising loss / canceled JmDNS instances (announced=false)
• [homekit.io] Doesn’t start if OH start before network is available  #13399 — HomeKit on macOS (Mac Mini) start / reachability around network availability
• [HomeKit] mDNS (_hap._tcp) announcement missing for first HomeKit bridge #17998 — _hap._tcp announcement missing for HomeKit bridge

Community

• https://community.openhab.org/t/docker-openhab-3-2-homekit-does-not-start-address-already-in-use/132861
• https://community.openhab.org/t/openhab2-homekit-question-about-smarthome-homekit-allowunauthenticated-true/18482 (Avahi vs HomeKit on 5353)
• https://community.openhab.org/t/disable-mdns-responder/147383
• https://community.openhab.org/t/homekit-integration-pairing-problems/82618 (5353 / mDNS discovery)
• https://community.openhab.org/t/docker-oh-3-homekit/134389 (_hap._tcp / 5353 discovery)

User impact

• No configuration change required for the common macOS case (useOHmDNS=false): native DNS-SD is selected automatically when supported.
• useOHmDNS=true continues to prefer openHAB's shared JmDNS when a matching interface client exists.
• Adds a runtime dependency on JNA (embedded in the HomeKit bundle) for the native path.

Compliance

• EPL-2.0 headers preserved
• Signed-off-by: Karel Goderis <karel.goderis@me.com> on all commits (DCO)
• Spotless check passed on org.openhab.io.homekit
• NOTICE updated for JNA
• README: useOHmDNS documents the native DNS-SD fallback

Testing

Verified on openHAB 5.3.0.M3 (native macOS Apple Silicon):

• With this jar and useOHmDNS=false, logs show native DNS-SD registration (no UDP 5353 bind by the JVM)
• dns-sd -B _hap._tcp lists the openHAB bridge instance(s)
• Pair-setup / Home discovery proceeds past Bonjour advertisement

CI of this draft will not resolve hap 2.0.10-SNAPSHOT until HAP-Java #213 is released; please treat merge readiness as blocked on that upstream release.

[lsiepel]

JFTR #13399 and #21970 are not related, they have a different cause, for #21970 there is a PR pending.