Other settings, such as using Fahrenheit temperatures and specifying the interface to advertise the HomeKit bridge are also illustrated in the following sample:
| networkInterface | IP address or domain name under which the HomeKit bridge can be reached. If no value is configured, the add-on uses the primary IP address configured for openHAB. If unsure, keep it empty | (none) |
| port | Port under which the HomeKit bridge can be reached. | 9123 |
| useOHmDNS | mDNS service is used to advertise openHAB as HomeKit bridge in the network so that HomeKit clients can find it. openHAB has already mDNS service running. This option defines whether the mDNS service of openHAB or a separate service should be used. | false |
| blockUserDeletion | Blocks HomeKit user deletion in openHAB and as result unpairing of devices. If you experience an issue with accessories becoming non-responsive after some time, try to enable this setting. You can also enable this setting if your HomeKit setup is done and you will not re-pair ios devices. | false |
| pin | Pin code used for pairing with iOS devices. Apparently, pin codes are provided by Apple and represent specific device types, so they cannot be chosen freely. The pin code 031-45-154 is used in sample applications and known to work. | 031-45-154 |
| useFahrenheitTemperature | Set to true to use Fahrenheit degrees, or false to use Celsius degrees. Note if an item has a QuantityType as its state, this configuration is ignored and it's always converted properly. | false |
| name | Name under which this HomeKit bridge is announced on the network. This is also the name displayed on the iOS device when searching for available bridges. | openHAB |
| instances | Defines how many bridges to expose. Necessary if you have more than 149 accessories. Accessories must be assigned to additional instances via metadata. Additional bridges will use incrementing port numbers. | 1 |
| useDummyAccessories | When an accessory is missing, substitute a dummy in its place instead of removing it. See [Dummy Accessories](#dummy-accessories). | false |
After setting the global configuration, you will need to tag your [openHAB items](https://www.openhab.org/docs/configuration/items.html) for HomeKit with accessory type.
For our purposes, you may consider HomeKit accessories to be of two types: simple and complex.
A simple accessory will be mapped to a single openHAB item, e.g. HomeKit lighting can represent an openHAB Switch, Dimmer, or Color item.
A complex accessory will be made up of multiple openHAB items, e.g. HomeKit Thermostat can be composed of mode, and current & target temperature.
Complex accessories require a tag on a Group Item indicating the accessory type, as well as tags on the items it composes.
A HomeKit accessory has mandatory and optional characteristics (listed below in the table).
The mapping between openHAB items and HomeKit accessory and characteristics is done by means of [metadata](https://www.openhab.org/docs/concepts/items.html#item-metadata)
- full qualified: i.e. with accessory type and characteristic, e.g. "LeakSensor.LeakDetectedState"
- shorthand version: with only either accessory type or characteristic, e.g. "LeakSensor", "LeakDetectedState".
if shorthand version has only accessory type, then HomeKit will automatically link *all* mandatory characteristics of this accessory type to the openHAB item.
Alternatively, you may want to have a choice of controlling the items individually, OR as a group, from HomeKit.
The following examples defines a single HomeKit accessory _with multiple services_ that the Home app will allow you to control together, or drill down and control individually.
Note that `AccessoryGroup` doesn't expose any services itself, but allows you to group other services together underneath it.
Also note that when nesting accessories, you cannot use the shorthand of naming only a characteristic, and not its accessory type, since it would be ambiguous if that item belongs to a secondary service, or to the primary service it's nested under.
You can also group additional accessories directly under another accessory.
In this example, HomeKit will show three separate light controls.
As this is somewhat confusing that Home will allow controlling all members as a group, and you also have the group as a distinct switch inside the HomeKit accessory, this is not a recommended configuration.
Another way to build complex accessories is to associate multiple accessory types with the root group, and then define all of the individual characteristics on group members.
When using this style, you cannot have multiple instance of the same accessory type.
```java
Group FanWithLight "Fan with Light" {homekit = "Fan,Lighting"}
Switch FanActiveStatus "Fan Active Status" (FanWithLight) {homekit = "Fan.ActiveStatus"}
Number FanRotationSpeed "Fan Rotation Speed" (FanWithLight) {homekit = "Fan.RotationSpeed"}
The Home app uses the first accessory in a group as the icon for the group as a whole.
E.g. an accessory defined as `homekit="Fan,Light"` will be shown as a fan and an accessory defined as `homekit="Light,Fan"` will be shown as a light in the Home app.
You can also override the primary service by using adding `primary=<type>` to the HomeKit metadata configuration:
```java
Group FanWithLight "Fan with Light" {homekit = "Light,Fan" [primary = "Fan"]}
Note that for sensors that aren't interactive, the Home app will show the constituent pieces in the room and home summaries, and you'll only be able to see the combined accessory when viewing the accessories associated with a particular bridge in the home settings:
OpenHAB is a highly dynamic system, and prone to occasional misconfigurations where items can't be loaded for various reasons, especially if you're using something besides the UI to manage your items.
This is a problem for HomeKit because if the bridge makes a connection, but accessories are missing, then the HomeKit database will simply remove that accessory.
When the accessory does come back (i.e. because you corrected a syntax error in an .items file, or openHAB completes booting), all customization of that accessory will be lost - the room assignment, customized name, custom icon, status/home screen/favorite preferences, etc.
In order to work around this, the HomeKit addon can create dummy accessories for any accessory it has previously published to HomeKit.
If the item backing the accessory is later re-created, everything will sync back up and nothing will be lost.
You can also run the console command `openhab:homekit listDummyAccessories` to see which items are missing.
Apple devices may or may not show "Not Responding" for some or all accessories when there are dummy accessories, since they will no longer be backed by actual items with state.
It's recommended that you resolve this state as soon as possible, since HomeKit may decide your entire bridge is being uncooperative, and remove everything itself.
If you actually meant to remove an item, you will need to purge the dummy items from the database so that they'll disappear from the Home app altogether.
In order to do so, run the console command `openhab:homekit pruneDummyAccessories`.
Alternatively, disabling, saving, and then re-enabling `useDummyAccessories` in the addon settings will have the same effect.
However, some dimmer devices for example do not expect brightness on "ON" event, some others do not expect "ON" upon brightness change.
In order to support different devices HomeKit integration can filter some events. Which events should be filtered is defined via dimmerMode configuration.
Note that seemingly most of these characteristics are not accessible from the Home app.
At the least, you should be able to edit names, control main power, switch inputs, alter input visibility, and be notified when the user wants to open the TV's menu.
HomeKit Windows Covering, Window and Door accessory types have following mandatory characteristics:
- CurrentPosition (0-100% of current window covering position)
- TargetPosition (0-100% of target position)
- PositionState (DECREASING,INCREASING or STOPPED as state). If no state provided, HomeKit will send STOPPED
These characteristics can be mapped to a single openHAB rollershutter item. In such case currentPosition will always equal target position, means if you request to close a blind/window/door, HomeKit will immediately report that the blind/window/door is closed.
As discussed above, one can use full or shorthand definition. Following two definitions are equal:
In contrast, HomeKit window covering/door/window have inverted mapping
- OPEN if position 100%
- CLOSED if position is 0%
Therefore, HomeKit integration inverts by default the values between openHAB and HomeKit, e.g. if openHAB current position is 30% then it will send 70% to HomeKit app.
If you add configuration parameter "stop=true", openHAB will emulate stop and send "STOP" command to rollershutter item if you click on the blind icon in the iOS home app while the blind is moving.
Some blinds devices do support "STOP" command but would stop if they receive UP/DOWN while moving om the same direction. In order to support such devices add "stopSameDirection" parameter.
When a thermostat is configured with all three of TargetTemperature, HeatingThresholdTemperature, and CoolingThresholdTemperature, Home will set the characteristics as follows:
If your thermostat simply has a heating set point and cooling set point, and uses those points regardless of HEAT, COOL, or AUTO mode, you may simply omit the TargetTemperature characteristic, and the add-on will dynamically route to those characteristics as appropriate:
```java
Group gThermostat "Thermostat" {homekit = "Thermostat"}
Number thermostat_current_temp "Thermostat Current Temp [%.1f °C]" (gThermostat) {homekit = "CurrentTemperature"}
String thermostat_current_mode "Thermostat Current Mode" (gThermostat) {homekit = "CurrentHeatingCoolingMode"}
The HomeKit valve accessory supports following 2 optional characteristics:
- duration: this describes how long the valve should set "InUse" once it is activated. The duration changes will apply to the next operation. If valve is already active then duration changes have no effect.
- remaining duration: this describes the remaining duration on the valve. Notifications on this characteristic must only be used if the remaining duration increases/decreases from the accessoryʼs usual countdown of remaining duration.
Upon valve activation in Home app, Home app starts to count down from the "duration" to "0" without contacting the server. Home app also does not trigger any action if it remaining duration get 0.
It is up to valve to have an own timer and stop valve once the timer is over.
Some valves have such timer, e.g. pretty common for sprinklers.
In case the valve has no timer capability, openHAB can take care on this - start an internal timer and send "Off" command to the valve once the timer is over.
configuration for these two cases looks as follow:
Sensors have typically one mandatory characteristic, e.g. temperature or lead trigger, and several optional characteristics which are typically used for battery powered sensors and/or wireless sensors.
Following table summarizes the optional characteristics supported by sensors.
| Name | String | Name of the sensor. This characteristic is interesting only for very specific cases in which the name of accessory is dynamic. if you not sure then you don't need it. |
| ActiveStatus | Switch, Contact | Accessory current working status. "ON"/"OPEN" indicates that the accessory is active and is functioning without any errors. |
| FaultStatus | Switch, Contact | Accessory fault status. "ON"/"OPEN" value indicates that the accessory has experienced a fault that may be interfering with its intended functionality. A value of "OFF"/"CLOSED" indicates that there is no fault. |
| TamperedStatus | Switch, Contact | Accessory tampered status. "ON"/"OPEN" indicates that the accessory has been tampered. Value should return to "OFF"/"CLOSED" when the accessory has been reset to a non-tampered state. |
| BatteryLowStatus | Switch, Contact, Number | Accessory battery status. "ON"/"OPEN" indicates that the battery level of the accessory is low. Value should return to "OFF"/"CLOSED" when the battery charges to a level that's above the low threshold. Alternatively, you can give a Number item that's the battery level, and if it's lower than the lowThreshold configuration, it will report low. |
Switch and Contact items support inversion of the state mapping, e.g. by default the openHAB switch state "ON" is mapped to HomeKit contact sensor state "Open", and "OFF" to "Closed".
The configuration "inverted=true" inverts this mapping, so that "ON" will be mapped to "Closed" and "OFF" to "Open".
To expose multiple Stateless Programmable Switches as a single accessory with multiple buttons (aka a scene controller), you need to configure ServiceLabel on the accessory group and ServiceIndex on each switch.
Note that in the Home app, the individual switch names will be ignored, and will simply be displayed as "Button 1", "Button 2", etc. (for ARABIC_NUMERALS style).
```java
Group gSceneController "Scene Controller" { homekit="AccessoryGroup"[ServiceLabel="ARABIC_NUMERALS"] }
For configuration options, the default values are in parentheses.
For enum values, the parentheses indicate the default values if the item is a Number or a Switch.
All enum values can be customized via item metadata. I.e. `HEAT="heating", COOL="cooling"`, or `HEAT=5, COOL=7` for a Number.
<aid="customizeable-enum">Some enums can have the list of valid values customized, meaning that if you customize the mapping, any value that is missing will not be presented to the user.</a>
They are appropriately marked.
Enums that are linked to Switches or Contacts have an `inverted` param that will reverse the sense of `ON`/`OFF` or `OPEN`/`CLOSED`.
Note that even though these characteristics can be linked to an item, they are not dynamic and cannot be updated once the Home app reads their initial values.
All accessories also support the following optional characteristic that can be linked to a Switch item:
| | | VOCDensity | Number | VOC Density in micrograms/m3, default max 1000 | minValue (0), maxValue (100), step (1) | |
| BasicFan | | | | Fan. A BasicFan is a subset of Fan, but the Home app allows you to customize the icon of the accessory to show a ceiling fan. | | |
| | OnState | | Dimmer, Switch | Accessory current working status. A value of "ON"/"OPEN" indicates that the accessory is active and is functioning without any errors. | inverted (false) | |
| | | RotationSpeed | Dimmer, Number | Fan rotation speed in % (1-100) | | |
| Battery | | | | Accessory with battery. Battery can be chargeable (configuration chargeable:true) and non-chargeable (configuration chargeable:false) | | |
| | BatteryLevel | | Number | Battery level 0% to 100% | | |
| | BatteryChargingState | | Contact, Dimmer, Switch | Mandatory only for chargeable battery. ON/OPEN = battery is charging | | |
| | BatteryLowStatus | | Contact, Number, Switch | Battery low indicator. ON/OPEN = battery level is low; for number if the value is below the lowThreshold, then it is low. Default is 20. | inverted (false), lowThreshold (20) | |
| ContactSensor | | | | Contact Sensor, An accessory with on/off state that can be viewed in HomeKit but not changed such as a contact sensor for a door or window | | |
| Door | | | | Motorized door. One Rollershutter item covers all mandatory characteristics. see examples below. | | |
| | CurrentPosition | | Dimmer, Number, Rollershutter | Current position of motorized door | | |
| | PositionState | | Number, Rollershutter, String | Position state. If no state is provided, "STOPPED" is used. | | DECREASING (0), INCREASING (1), STOPPED (2) |
| | TargetPosition | | Dimmer, Number, Rollershutter | Target position of motorized door | | |
| | | HoldPosition | Rollershutter, Switch | Motorized door should stop at its current position. ON is sent to Switch items. STOP is sent to Rollershutter items. Only supported by 3rd party Home apps (such as Elgato Eve) | | |
| | | ObstructionStatus | Contact, Dimmer, Switch | Current status of obstruction sensor. ON-obstruction detected, OFF - no obstruction | | |
| Doorbell | | | | Doorbell. This accessory must also have a Speaker, Microphone, and Camera RTP Stream Management service in the same group in order to be usable by the Home App. The latter is not yet implemented in openHAB. | | |
| | ProgrammableSwitchEvent | | Contact, Number, String, Switch | The button press event. Note that the event will be forwarded to Home for every _update_ of the item, not just on change. | inverted (false) | SINGLE_PRESS (0, ON, OPEN), DOUBLE_PRESS (1), LONG_PRESS (2) [*](#customizable-enum) |
| | ActiveStatus | | Dimmer, Switch | Accessory current working status. A value of "ON"/"OPEN" indicates that the accessory is active and is functioning without any errors. | | |
| | | CurrentFanState | Number, String | Current fan state. | | INACTIVE (0), IDLE (1), BLOWING_AIR (2) |
| | | LockControl | Number, Switch, String | Status of physical control lock | inverted (false) | CONTROL_LOCK_DISABLED (0, OFF), CONTROL_LOCK_ENABLED (1, ON) |
| | ActiveStatus | | Dimmer, Switch | Accessory current working status. A value of "ON"/"OPEN" indicates that the accessory is active and is functioning without any errors. | | |
| | | CoolingThresholdTemperature | Number | Maximum temperature that must be reached before cooling is turned on | minValue (10), maxValue (35), step (0.1) | |
| | | HeatingThresholdTemperature | Number | Minimum temperature that must be reached before heating is turned on | minValue (0), maxValue (25), step (0.1) | |
| | | LockControl | Number, Switch, String | Status of physical control lock | inverted (false) | CONTROL_LOCK_DISABLED (0, OFF), CONTROL_LOCK_ENABLED (1, ON) |
| | | RotationSpeed | Number | Fan rotation speed in % (1-100) | | |
| InputSource | | | | Input source linked service. Can only be used with Television. | | |
| | | ConfiguredName | String | Name of the input source configured in the iOS Home app. User can rename the source in iOS Home app and this characteristic can be used to reflect change in openHAB and sync name changes from openHAB to Home app. | | |
| | | Configured | Contact, Dimmer, Switch | If the source is configured on the device. Non-configured inputs will not show up in the Home app. - ON/OPEN = show, OFF/CLOSED = hide. Default is ON. Can also be configured via metadata, e.g. [Configured=true] | | |
| | | CurrentVisibility | Contact, Dimmer, Number, String, Switch | If the source has been hidden by the user. Can also be configured via metadata, e.g. [CurrentVisibility=false] | inverted (false) | SHOWN (0, ON), HIDDEN (1, OFF) |
| | | Identifier | Number | The identifier of the source, to be used with the ActiveIdentifier characteristic. Can also be configured via metadata, e.g. [Identifier=1] | | |
| | | InputDeviceType | String | Type of the input device. possible values (OTHER, TV, RECORDING, TUNER, PLAYBACK, AUDIO_SYSTEM). Custom mapping can be defined at item level. Can also be configured via metadata, e.g. [InputDeviceType="OTHER"]. | | |
| | | InputSourceType | String | Type of the input source. possible values (OTHER, HOME_SCREEN, TUNER, HDMI, COMPOSITE_VIDEO, S_VIDEO, COMPONENT_VIDEO, DVI, AIRPLAY, USB, APPLICATION). Custom mapping can be defined at item level. Can also be configured via metadata, e.g. [InputSourceType="OTHER"]. | | |
| | | TargetVisibilityState | Switch, Number, String | The desired visibility state of the input source. | inverted (false) | SHOWN (0, ON), HIDDEN (1, OFF) |
| IrrigationSystem | | | | An accessory that represents multiple water valves and accommodates a programmed scheduled. | | |
| | Active | | Contact, Dimmer, Number, String, Switch | If the irrigation system as a whole is enabled. This must be ON if any of the valves are also enabled. | inverted (false) | INACTIVE (0, OFF), ACTIVE (1, ON) |
| | InUseStatus | | Contact, Dimmer, Number, String, Switch | If the irrigation system as a whole is running. This must be ON if any of the valves are ON. | inverted (false) | NOT_IN_USE (0, OFF, CLOSED), IN_USE (1, ON, OPEN) |
| | ProgramMode | | String | The current program mode of the irrigation system. Possible values (NO_SCHEDULED - no programs scheduled, SCHEDULED - program scheduled, SCHEDULED_MANUAL - program scheduled, currently overriden to manual mode). | | |
| Lighting | | | | A lightbulb, can have further optional parameters for brightness, hue, etc | | |
| | OnState | | Switch | State of the light - ON/OFF | | |
| | | Brightness | Dimmer, Color | Brightness in % (1-100). See "Usage of dimmer modes" for configuration details. | | |
| | | ColorTemperature | Dimmer, Number | Color temperature. If the item is a Number with no units, it is represented in mireds. The default value range is from 50 to 400 (2500 K to 20,000 K). If the item is a Dimmer, it will be transformed linearly to mireds. Color temperature should not be used in combination with hue, saturation and brightness. | minValue (50), maxValue (400), inverted | |
| | | Hue | Dimmer, Color | Hue | | |
| | | Saturation | Dimmer, Color | Saturation in % (1-100) | | |
| Outlet | | | | An accessory that can be turned off and on. While similar to a lightbulb, this will be presented differently in the Siri grammar and iOS apps | | |
| | InUseStatus | | Contact, Dimmer, Switch | Indicates whether the outlet has an appliance e.g., a floor lamp, physically plugged in. This characteristic is set to True even if the plugged-in appliance is off. | inverted (false) | |
| | OnState | | Dimmer, Switch | State of the outlet - ON/OFF | | |
| SecuritySystem | | | | Security system. | | |
| | CurrentSecuritySystemState | | Number, String | Current state of the security system | | STAY_ARM (0), AWAY_ARM (1), NIGHT_ARM (2), DISARMED (3), TRIGGERED (4) |
| | TargetSecuritySystemState | | Number, String | Requested state of the security system. While the requested state is not DISARM, and the current state is DISARMED, HomeKit will display "Arming...", for example during an exit delay. | | STAY_ARM (0), AWAY_ARM (1), NIGHT_ARM (2), DISARM (3) [*](#customizable-enum) |
| | | CurrentTiltAngle | Dimmer, Number | Number Item = current angle of slats. values -90 to 90. A value of 0 indicates that the slats are rotated to a fully open position. Dimmer Item = the percentage of openness (0%-100%) | | |
| | | ConfiguredName | String | Name of the speaker accessory configured in iOS Home app. User can rename the speaker in iOS Home app and this characteristic can be used to reflect change in openHAB and sync name changes from openHAB to Home app. | | |
| | | Active | Contact, Dimmer, Number, String, Switch | Accessory current working status | inverted (false) | INACTIVE (0, OFF), ACTIVE (1, ON) |
| | | Volume | Number | Speaker volume from 0% to 100% | | |
| StatelessProgrammableSwitch | | | | A stateless programmable switch is a button or scene controller that simply sends an event to Home when it is pressed, allowing automations to occur. See [Stateless Programmable Switch Groups](#Stateless-Programmable-Switch-Groups) for configuring multiple in one accessory. | | |
| | ProgrammableSwitchEvent | | Contact, Number, String, Switch | The button press event. Note that the event will be forwarded to Home for every _update_ of the item, not just on change. | inverted (false) | SINGLE_PRESS (0, ON, OPEN), DOUBLE_PRESS (1), LONG_PRESS (2) [*](#customizable-enum) |
| | | Volume | Number | Speaker volume from 0% to 100% | | |
| Switchable | | | | An accessory that can be turned off and on. While similar to a lightbulb, this will be presented differently in the Siri grammar and iOS apps | | |
| | OnState | | Dimmer, Switch | State of the switch - ON/OFF | | |
| Television | | | | Television accessory with inputs | | |
| | Active | | Contact, Dimmer, Number, String, Switch | State of the television (on/off) | inverted (false) | INACTIVE (0, OFF), ACTIVE (1, ON) |
| | | ActiveIdentifier | Number | The input that is currently active (based on its identifier). Can also be configured via metadata, e.g. [ActiveIdentifier=1] | | |
| | | ClosedCaptions | Contact, Dimmer, Number, String, Switch | Indicates closed captions are enabled. Can also be configured via metadata, e.g. [ClosedCaptions=true] | inverted (false) | DISABLED (0, OFF), ENABLED (1, ON) |
| | | ConfiguredName | String | Name of the television accessory configured in the iOS Home app. User can rename the television in iOS Home app and this characteristic can be used to reflect change in openHAB and sync name changes from openHAB to Home app. | | |
| | | CurrentMediaState | Number, String | Current television state. | | PLAY (0), PAUSE (1), STOP (2), UNKNOWN (3) |
| | | PictureMode | Number, String | Selected picture mode. | | OTHER (0), STANDARD (1), CALIBRATED (2), CALIBRATED_DARK (3), VIVID (4), GAME (5), COMPUTER (6), CUSTOM (7) |
| | | PowerMode | Switch, Number, String | This oddly named characteristic will receive an ON command when the user requests to open the TV's menu. | inverted (false) | SHOW (0, ON), HIDE (1, OFF) |
| | | SleepDiscoveryMode | Contact, Dimmer, Number, String, Switch | Indicates if the television is discoverable while in standby mode. Can also be configured via metadata, e.g. [SleepDiscoveryMode=true] | inverted (false) | NOT_DISCOVERABLE (0, OFF), ALWAYS_DISCOVERABLE (1, ON) |
| | | TargetMediaState | Number, String | Target television state. | | PLAY (0), PAUSE (1), STOP (2) |
| TelevisionSpeaker | | | | An accessory that can be added to a Television in order to control the speaker associated with it. | | |
| | Mute | | Switch | If the television is muted. ON = muted, OFF = not muted. | | |
| | | Active | Contact, Dimmer, Number, String, Switch | Unknown. This characteristic is undocumented by Apple, but is still available. | inverted (false) | INACTIVE (0, OFF), ACTIVE (1, ON) |
| | | Volume | Dimmer, Number | Current volume. | | |
| | | VolumeControlType | String | The type of control available. This will default to infer based on what other items are linked. NONE = status only, no control; RELATIVE = INCREMENT/DECREMENT only, no status; RELATIVE_WITH_CURRENT = INCREMENT/DECREMENT only with status; ABSOLUTE = direct status and control. Can also be configured via metadata, e.g. [VolumeControlType="ABSOLUTE"]. | | |
| | | VolumeSelector | Dimmer, String | If linked to a dimmer item, will send INCREASE/DECREASE commands. If linked to a string item, will send INCREMENT and DECREMENT. | | |
| Thermostat | | | | A thermostat requires at least one of TargetTemperature, CoolingThresholdTemperature, or HeatingThresholdTemperature must be provided. | | |
| | CurrentTemperature | | Number | Current temperature. | minValue (0), maxValue (100), step (0.1) | |
| | | TargetTemperature | Number | Target temperature. If CoolingThresholdTemperature and HeatingThresholdTemperature are also provided, this characteristic is used when the thermostat is in HEAT or COOL mode. In AUTO mode, this characteristic receives the average of the two thresholds. | minValue (10), maxValue (38), step (0.1) | |
| | | CoolingThresholdTemperature | Number | Maximum temperature that must be reached before cooling is turned on. If TargetTemperature is not provided, this characteristic will also be used in COOL mode. | minValue (10), maxValue (35), step (0.1) | |
| | | HeatingThresholdTemperature | Number | Minimum temperature that must be reached before heating is turned on. If TargetTemperature is not provided, this characteristic will also be used in HEAT mode. | minValue (0), maxValue (25), step (0.1) | |
| | | RelativeHumidity | Number | Relative humidity in % between 0 and 100. | | |
| | | TargetRelativeHumidity | Number | Target relative humidity in % between 0 and 100. | | |
| | | TemperatureUnit | Number, String, Switch | The units the accessory itself uses to display the temperature. Can also be configured via metadata, e.g. [TemperatureUnit="CELSIUS"] | | CELSIUS (0, OFF), FAHRENHEIT (1, ON) |
| | ActiveStatus | | Dimmer, Switch | Accessory current working status. A value of "ON"/"OPEN" indicates that the accessory is active and is functioning without any errors. | | |
| | InUseStatus | | Contact, Dimmer, Switch | Indicates whether fluid flowing through the valve. A value of "ON"/"OPEN" indicates that fluid is flowing. | inverted (false) | |
| | | Duration | Number | Defines how long a valve should be set to ʼIn Useʼ in second. | homekitDefaultDuration = {default duration in seconds} | |
| | | RemainingDuration | Number | Describes the remaining duration on the accessory. the remaining duration increases/decreases from the accessoryʼs usual countdown. i.e. changes from 90 to 80 in a second. | | |
| Window | | | | Motorized window. One Rollershutter item covers all mandatory characteristics. see examples below. | | |
| | CurrentPosition | | Dimmer, Number, Rollershutter | Current position of motorized window | | |
| | PositionState | | Number, Rollershutter, String | Position state. If no state is provided, "STOPPED" is used. | | DECREASING (0), INCREASING (1), STOPPED (2) |
| | TargetPosition | | Dimmer, Number, Rollershutter | Target position of motorized window | | |
| | | HoldPosition | Rollershutter, Switch | Motorized door should stop at its current position. ON is sent to Switch items. STOP is sent to Rollershutter items. Only supported by 3rd party Home apps (such as Elgato Eve) | | |
| | | ObstructionStatus | Contact, Dimmer, Switch | Current status of obstruction sensor. ON-obstruction detected, OFF - no obstruction | | |
| WindowCovering | | | | Window covering / blinds. One Rollershutter item covers all mandatory characteristics. see examples below. | | |
| | CurrentPosition | | Dimmer, Number, Rollershutter | Current position of window covering | | |
| | PositionState | | Number, Rollershutter, String | Position state. If no state is provided, "STOPPED" is used. | | DECREASING (0), INCREASING (1), STOPPED (2) |
| | TargetPosition | | Dimmer, Number, Rollershutter | Target position of window covering | | |
| | | CurrentHorizontalTiltAngle | Dimmer, Number | Number Item = current angle of horizontal slats. values -90 to 90. A value of 0 indicates that the slats are rotated to a fully open position. A value of -90 indicates that the slats are rotated all the way in a direction where the user-facing edge is higher than the window-facing edge. Dimmer Item = the percentage of openness (0%-100%) | | |
| | | CurrentVerticalTiltAngle | Dimmer, Number | Number Item = current angle of vertical slats (-90 to +90) . Dimmer Item = the percentage of openness (0%-100%) | | |
| | | HoldPosition | Rollershutter, Switch | Motorized door should stop at its current position. ON is sent to Switch items. STOP is sent to Rollershutter items. Only supported by 3rd party Home apps (such as Elgato Eve) | | |
| | | ObstructionStatus | Contact, Dimmer, Switch | Current status of obstruction sensor. ON-obstruction detected, OFF - no obstruction | | |
| | | TargetHorizontalTiltAngle | Dimmer, Number | Number Item = target angle of horizontal slats (-90 to +90). Dimmer Item = the percentage of openness (0%-100%) | | |
| | | TargetVerticalTiltAngle | Dimmer, Number | Number Item = target angle of vertical slats. Dimmer Item = the percentage of openness (0%-100%) | | |
In order to overcome this limitation, you can instruct openHAB to expose multiple bridges to HomeKit, and then manually assign specific accessories to different instances.
You will need to manually add each additional bridge in the Home app, since the QR Code in settings will only be for the primary bridge; however the same PIN is still used.
In order to assign a particular accessory to a different bridge, set the `instance` metadata parameter:
To do this, you can issue the command `openhab:homekit clearPairings` from the [OSGi console](https://www.openhab.org/docs/administration/console.html).
After doing this, you may need to remove the file `$OPENHAB_USERDATA/jsondb/homekit.json` and restart openHAB.
HomeKit requires a unique identifier for each accessory advertised by the bridge.
This unique identifier is hashed from the Item's name.
For that reason, it is important that the name of your Items exposed to HomeKit remain consistent.
HomeKit listens by default on port 9124.
Java prefers the IPv6 network stack by default.
If you have connection or detection problems, you can configure Java to prefer the IPv4 network stack instead.
To prefer the IPv4 network stack, adapt the Java command line arguments to include: `-Djava.net.preferIPv4Stack=true`
Depending on the openHAB installation method, you should modify `start.sh`, `start_debug.sh`, `start.bat`, or `start_debug.bat` (standalone/manual installation) or `EXTRA_JAVA_OPTS` in `/etc/default/openhab2` (Debian installation).
If you encounter any issues with the add-on and need support, it may be important to get detailed logs of your device's communication with openHAB.
In order to get logs from the underlying library used to implement the HomeKit protocol, enable trace logging using the following commands at [the console](https://www.openhab.org/docs/administration/console.html):
if you don't see openHAB in the Home app, probably multicast DNS (mDNS) traffic is not routed correctly from openHAB to Home app device or openHAB is already in paired state.
You can verify this with [Discovery DNS iOS app](https://apps.apple.com/us/app/discovery-dns-sd-browser/id305441017) as follow:
- to confirm this, check whether you can find _openhab-server._tcp. if you don't see it as well, traffic is blocked. check your network router/firewall settings.
- if you found _hap._tcp, open it. you should see the name of your openHAB HomeKit bridge (default name is openHAB)
- if sf is equal 0 (as on screenshot), openHAB is already paired and does not accept any new pairing request. you can reset pairing using `openhab:homekit clearPairings` command in karaf console.
- if you see openHAB bridge and sf is equal to 1 but you dont see openHAB in the Home app, the Home app probably still thinks it is already paired with openHAB. remove your home from the Home app and restart the iOS device.
