[homekit.binding] New HomeKit client binding

CODEOWNERS

@@ -165,6 +165,7 @@
 /bundles/org.openhab.binding.herzborg/ @Sonic-Amiga
 /bundles/org.openhab.binding.homeassistant/ @antroids @ccutrer
 /bundles/org.openhab.binding.homeconnect/ @bruestel
+/bundles/org.openhab.binding.homekit/ @andrewfg
 /bundles/org.openhab.binding.homematic/ @FStolte @gerrieg @mdicke2s
 /bundles/org.openhab.binding.homewizard/ @Daniel-42
 /bundles/org.openhab.binding.hpprinter/ @cossey

bom/openhab-addons/pom.xml

@@ -811,6 +811,11 @@
       <artifactId>org.openhab.binding.homeconnect</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.homekit</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.homematic</artifactId>

bundles/org.openhab.binding.homekit/NOTICE

@@ -0,0 +1,13 @@
+This content is produced and maintained by the openHAB project.
+
+* Project home: https://www.openhab.org
+
+== Declared Project Licenses
+
+This program and the accompanying materials are made available under the terms
+of the Eclipse Public License 2.0 which is available at
+https://www.eclipse.org/legal/epl-2.0/.
+
+== Source Code
+
+https://github.com/openhab/openhab-addons

bundles/org.openhab.binding.homekit/README.md

@@ -0,0 +1,143 @@
+# HomeKit Binding
+
+This binding allows pairing with HomeKit accessories and **imports** their services as channel groups and their respective service- characteristics as channels.
+Do not confuse this with the [HomeKit system integration](https://www.openhab.org/addons/integrations/homekit/) which **exports** openHAB Items to a HomeKit controller.
+
+## Supported Things
+
+There are three types of Things supported:
+
+- `accessory`: This integrates a single HomeKit accessory, which has its own LAN connection.
+  Its services appear as Channel Groups, and their respective characteristics appear as Channels.
+- `bridged-accessory`: This integrates a single HomeKit accessory, which does NOT have its own LAN connection.
+  It has the same functionality as an `accessory`, except that its communication is done via a `bridge` (see below).
+- `bridge`: This integrates a HomeKit bridge accessory, which has its own LAN connection.
+  It does not have any own Channels.
+  Instead it contains multiple `bridged-accessory` Things (see above).
+
+Things of type `bridge` and `accessory` both communicate directly with their HomeKit accessory device via the LAN.
+Whereas `bridged-accessory` Things communicate via their respective `bridge` Thing.
+
+## Discovery
+
+Both `accessory` and `bridge` Things will be auto-discovered via mDNS.
+And once a `bridge` Thing has been instantiated and paired, its `bridged-accessory` Things will also be auto-discovered.
+
+## Configuration for `bridge` and `accessory` Things
+
+The following table shows the Thing configuration parameters for `bridge` and `accessory` Things.
+
+| Name              | Type    | Description                                          | Default   | Required | Advanced |
+|-------------------|---------|------------------------------------------------------|-----------|----------|----------|
+| `ipAddress`       | text    | IP v4 address of the HomeKit accessory.              | see below | yes      | no       |
+| `httpHostHeader`  | text    | The fully qualified host name as discovered by mDNS. | see below | yes      | yes      |
+| `macAddress`      | text    | Unique accessory identifier as discovered by mDNS.   | see below | yes      | yes      |
+| `refreshInterval` | integer | Interval at which the accessory is polled in sec.    | 60        | no       | yes      |
+
+NOTE: as a general rule, if you create the Things via the Inbox from the mDNS discovery result, then all of the above configuration parameters will have their proper values already preset.
+
+`ipAddress` must match the format `123.123.123.123:4567` representing its IP v4 address and port.
+
+`httpHostHeader` is required for the 'Host:' header of HTTP requests sent to the `accessory` or `bridge`.
+It must be the fully qualified host name (e.g. `foobar._hap._tcp.local.` or, if the port is not 0 or 80, `foobar._hap._tcp.local.:1234`) as found manually via (say) an mDNS discovery app.
+
+`macAddress` must be the unique accessory identifier as found manually via (say) an mDNS discovery app.
+
+### Configuration for `bridged-accessory` Things
+
+The following table shows the Thing configuration parameters for `bridged-accessory` Things.
+
+| Name              | Type    | Description                                          | Default   | Required | Advanced |
+|-------------------|---------|------------------------------------------------------|-----------|----------|----------|
+| `accessoryID`     | integer | ID of the accessory.                                 | see below | yes      | yes      |
+
+As a general rule `accessoryID` is set by the auto-discovery process.
+However you can configure it manually if you wish.
+It must be the ID of the `bridged-accessory` within the `bridge`.
+
+## Thing Pairing
+
+The `bridge` and `accessory` Things need to be paired with their respective HomeKit accessories.
+This requires entering the HomeKit pairing code by means of a Thing Action.
+
+Note that HomeKit accessories can only be paired with one controller, so if it is already paired with something else, you will need to remove that pairing first.
+There are two forms of pairing:
+
+1. Simple pairing.
+  This works directly between two devices – a HomeKit client (this binding) and a HomeKit accessory.
+  In this case you need only to enter the pairing code into the Thing Action.
+1. Pairing with external authorization.
+  In addition to the HomeKit client (this binding) and the HomeKit accessory, it requires an additional third party to put the accessory into pairing mode.
+  Typically the additional third party can be either a) using the accessory's app to put it into pairing mode, or b) pressing a pairing button on the device.
+
+In either case above, the Pairing Code must be entered manually into the Thing Action dialog.
+The Pairing Code must match the format `XXX-XX-XXX` or `XXXX-XXXX` or `XXXXXXXX` where `X` is a single digit.
+
+For case 1. above, the `With External Authentication` switch must be `OFF`.
+Whereas for case 2. above, must be `ON`.
+
+## Channels
+
+For `accessory` and `bridged-accessory` Things, the Channels are auto-created depending on the services and characteristics published by the HomeKit accessory.
+Things of type `bridge` do not have own Channels.
+
+As a general rule openHAB has one Channel for each HomeKit characteristic.
+Some HomeKit accessories have separate characteristics for 'target' and 'current' states.
+The two characteristics may have different values (e.g. for a thermostat).
+In all such cases the Thing has a Channel for each characteristic so that both values can be accessed.
+
+Some HomeKit characteristics represent fixed information e.g. model number, firmware version, etc.
+Such values appear in openHAB as properties of the respective Thing.
+
+### Special Extra HSBType Channel
+
+In openHAB the norm is that lighting objects shall be represented by a single `HSBType` Channel which manages hue, saturation, brightness, and on-off states.
+By contrast a HomeKit accessory has four separate characteristics for hue, saturation, brightness, and on-off.
+So the Thing creates one additional `HSBType` Channel that amalgamates hue, saturation, brightness, and on-off characteristics, according to the openHAB norm.
+
+## Integration with Apple Home App / Ecosystem
+
+Many HomeKit accessories are able only to be paired with one client.
+This means that if you want to pair such an accessory with this binding, you must first unpair it from the Apple Home app.
+
+If you want to integrate such an accessory with both this binding and with the Apple Home ecosystem, then you can use this binding to import the Channels as openHAB Items, and then use the openHAB system integration addon to re-export those Items to the Apple HomeKit eco system.
+
+## File Based Configuration
+
+### Thing Configuration
+
+Things are automatically configured when they are discovered.
+So for this reason it is difficult to create Things via a '.things' file, and therefore not recommended.
+
+```java
+Bridge homekit:bridge:velux "VELUX Gateway" [ host="192.168.0.235:5001", macAddress="XX:XX:XX:XX:XX:XX", hostName="foobar._hap._tcp.local.", refreshInterval=60 ] {
+    Thing bridged-accessory sensor "VELUX Sensor" @ "Hallway" [ accessoryID=2 ]
+    Thing bridged-accessory skylight_hallway "VELUX Window" @ "Hallway" [ accessoryID=3 ]
+    Thing bridged-accessory skylight_bathroom "VELUX Window" @ "Bathroom" [ accessoryID=4 ]
+}
+```
+
+### Item Configuration
+
+```java
+Group VeluxSensorSwitch "Velux indoor climate sensor" (Hallway) ["Sensor"]
+
+Number:Dimensionless Velux_Hallway_CO2 "CO2 [%d ppm]" <carbondioxide> (VeluxSensorSwitch) ["Measurement", "CO2"] { channel="homekit:bridged-accessory:velux:sensor:sensor-carbon-dioxide#carbon-dioxide-level-17", unit="ppm" }
+Number:Dimensionless Velux_Hallway_Humidity "Humidity [%.0f %%]" <humidity> (VeluxSensorSwitch) ["Measurement", "Humidity"] { channel="homekit:bridged-accessory:velux:sensor:sensor-humidity#relative-humidity-current-13", unit="%" }
+Number:Temperature Velux_Hallway_Temperature "Temperature" <temperature> (VeluxSensorSwitch) ["Measurement", "Temperature"] { channel="homekit:bridged-accessory:velux:sensor:sensor-temperature#temperature-current-10", unit="°C" }
+
+Group SkylightHallway "Skylight window" (Hallway) ["Window"]
+
+Rollershutter SkylightHallway_Position "Position" (SkylightHallway) ["OpenState"] { channel="homekit:bridged-accessory:velux:skylight_hallway:window#position-target-11" }
+
+Group SkylightBathroom "Skylight window" (SmallBathroom) ["Window"]
+
+Rollershutter SkylightBathroom_Position "Position" (SkylightBathroom) ["OpenState"] { channel="homekit:bridged-accessory:velux:skylight_bathroom:window#position-target-11" }
+```
+
+### Sitemap Configuration
+
+```perl
+Slider item=SkylightHallway_Position
+Slider item=SkylightBathroom_Position
+```

bundles/org.openhab.binding.homekit/pom.xml

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>org.openhab.addons.bundles</groupId>
+    <artifactId>org.openhab.addons.reactor.bundles</artifactId>
+    <version>5.1.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>org.openhab.binding.homekit</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: HomeKit Client Binding</name>
+
+  <dependencies>
+    <dependency>
+      <groupId>org.bouncycastle</groupId>
+      <artifactId>bcprov-jdk18on</artifactId>
+      <version>1.81</version>
+    </dependency>
+  </dependencies>
+
+</project>

bundles/org.openhab.binding.homekit/src/main/feature/feature.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<features name="org.openhab.binding.homekit-${project.version}" xmlns="http://karaf.apache.org/xmlns/features/v1.4.0">
+	<repository>mvn:org.openhab.core.features.karaf/org.openhab.core.features.karaf.openhab-core/${ohc.version}/xml/features</repository>
+
+	<feature name="openhab-binding-homekit" description="HomeKit Binding" version="${project.version}">
+		<feature>openhab-runtime-base</feature>
+		<bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.homekit/${project.version}</bundle>
+	</feature>
+</features>

bundles/org.openhab.binding.homekit/src/main/java/org/openhab/binding/homekit/internal/HomekitBindingConstants.java

@@ -0,0 +1,116 @@
+/*
+ * Copyright (c) 2010-2025 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.homekit.internal;
+
+import java.util.regex.Pattern;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.core.thing.Thing;
+import org.openhab.core.thing.ThingTypeUID;
+import org.openhab.core.thing.type.ChannelDefinition;
+import org.openhab.core.thing.type.ChannelTypeUID;
+
+/**
+ * Defines common constants which are used across the whole HomeKit binding.
+ *
+ * @author Andrew Fiddian-Green - Initial contribution
+ */
+@NonNullByDefault
+public class HomekitBindingConstants {
+
+    public static final String BINDING_ID = "homekit";
+
+    // List of all Thing Type UIDs
+    public static final ThingTypeUID THING_TYPE_ACCESSORY = new ThingTypeUID(BINDING_ID, "accessory");
+    public static final ThingTypeUID THING_TYPE_BRIDGED_ACCESSORY = new ThingTypeUID(BINDING_ID, "bridged-accessory");
+    public static final ThingTypeUID THING_TYPE_BRIDGE = new ThingTypeUID(BINDING_ID, "bridge");
+
+    /**
+     * Some Characteristics have variable values and others remain static over time. The latter are produced with
+     * a {@link ChannelDefinition} with this channel-type uid. And when Things are created, rather than instantiating
+     * them as (dynamic data) Channels of the Thing, instead they are added as (static data) Properties of the Thing.
+     */
+    public static final ChannelTypeUID CHANNEL_TYPE_STATIC = new ChannelTypeUID(BINDING_ID, "static-data");
+
+    /**
+     * format string for channel-group-type UIDs which represent services
+     * format: 'channel-group-type'-[serviceIdentifier]-[serviceIid]-[thingId]-[accessoryId]
+     * example: channel-group-type-accessory-information-1-1234567890abcdef-1
+     */
+    public static final String CHANNEL_GROUP_TYPE_ID_FMT = "channel-group-type-%s-%d-%s-%s";
+
+    /**
+     * format string for channel-type UIDs which represent characteristics
+     * format: 'channel-type'-[characteristicIdentifier]-[characteristicIid]-[thingId]-[accessoryId]
+     * example: channel-type-occupancy-detected-2694-1234567890abcdef-1
+     */
+    public static final String CHANNEL_TYPE_ID_FMT = "channel-type-%s-%d-%s-%s";
+
+    /**
+     * format string for channel-definition IDs like '[characteristicIdentifier]-[characteristicIid]'
+     * used to instantiate channels and labels like '[thingName]-[accessoryAid]' used to discover
+     * things; examples:
+     * <ul>
+     * <li>occupancy-detected-2694</li>
+     * <li>11:22:33:44:55:66-1234</li>
+     * </ul>
+     */
+    public static final String STRING_AID_FMT = "%s-%d";
+
+    // labels for things e.g. 'Living Room Light (11:22:33:44:55:66-1234)'
+    public static final String THING_LABEL_FMT = "%s (%s)";
+
+    // configuration parameters
+    public static final String CONFIG_HTTP_HOST_HEADER = "httpHostHeader";
+    public static final String CONFIG_IP_ADDRESS = "ipAddress";
+    public static final String CONFIG_REFRESH_INTERVAL = "refreshInterval";
+    public static final String CONFIG_ACCESSORY_ID = "accessoryID";
+    public static final String CONFIG_MAC_ADDRESS = Thing.PROPERTY_MAC_ADDRESS;
+
+    // thing properties
+    public static final String PROPERTY_PROTOCOL_VERSION = "protocolVersion";
+    public static final String PROPERTY_ACCESSORY_CATEGORY = "accessoryCategory";
+    public static final String PROPERTY_REPRESENTATION = "representationProperty";
+
+    // channel properties
+    public static final String PROPERTY_IID = "iid";
+    public static final String PROPERTY_FORMAT = "format";
+    public static final String PROPERTY_DATA_TYPE = "dataType";
+
+    // HomeKit HTTP URI endpoints and content types
+    public static final String ENDPOINT_ACCESSORIES = "/accessories";
+    public static final String ENDPOINT_CHARACTERISTICS = "/characteristics";
+    public static final String ENDPOINT_PAIR_SETUP = "/pair-setup";
+    public static final String ENDPOINT_PAIR_VERIFY = "/pair-verify";
+
+    public static final String CONTENT_TYPE_PAIRING = "application/pairing+tlv8";
+    public static final String CONTENT_TYPE_HAP = "application/hap+json";
+
+    // pattern matcher for pairing code XXX-XX-XXX or XXXX-XXXX or XXXXXXXX
+    public static final Pattern PAIRING_CODE_PATTERN = Pattern.compile("\\d{3}-\\d{2}-\\d{3}|\\d{4}-\\d{4}|\\d{8}");
+
+    // pattern matcher for host ipv4 address 123.123.123.123:12345
+    public static final Pattern IPV4_PATTERN = Pattern.compile(
+            "^(((25[0-5]|2[0-4]\\d|1\\d{2}|[1-9]?\\d)\\.){3}(25[0-5]|2[0-4]\\d|1\\d{2}|[1-9]?\\d)):(6553[0-5]|655[0-2]\\d|65[0-4]\\d{2}|6[0-4]\\d{3}|[1-5]?\\d{1,4})$");
+
+    // pattern matcher for a fully qualified host name like foobar._hap._tcp.local. or foobar._hap._tcp.local.:12345
+    // NOTE: this specially allows space characters in the host name -- even if normally not allowed by the RFC
+    public static final Pattern HOST_PATTERN = Pattern.compile(
+            "^([a-zA-Z0-9\\-\\x20]+)\\._hap\\._tcp\\.local\\.(?::([1-9]\\d{0,3}|[1-5]\\d{4}|6[0-4]\\d{3}|65[0-4]\\d{2}|655[0-2]\\d|6553[0-5]))?$");
+
+    // result messages for ThingActions; !! DO NOT LOCALIZE !!
+    public static final String ACTION_RESULT_OK = "OK";
+    public static final String ACTION_RESULT_OK_FORMAT = ACTION_RESULT_OK + " (%s)";
+    public static final String ACTION_RESULT_ERROR = "ERROR";
+    public static final String ACTION_RESULT_ERROR_FORMAT = ACTION_RESULT_ERROR + " (%s)";
+}