Exceeding features of homebridge-openhab2 and openHAB's Homekit Plugin since
v.0.3.0
This homebridge plugin for openHAB fully supports all services offered by Apple's HomeKit Accessory Protocol (HAP), as far as it is feasible based on the item types offered by OpenHAB (see below for the currently supported 32 accessories). In opposite to the existing openHAB homebridge plugin or the native openHAB Homekit Plugin, this plugin requires explicit declaration of accessories in the homebridge configuration and does not use openHAB's tagging system, which leads to a little more effort during configuration, but proves more reliable and functional in more complex installations. See Comparisson below.
Note: Please install homebridge first.
npm install -g homebridge-openhab2-complete
Some people are experiencing dependency issues between homebridge's node version and the required node version for this project. My local setup is based on oznu's homebridge docker container, where I never ran into any problems. In order to install the plugin in the docker, just add npm install homebridge-openhab2-complete
to the startup.sh
script inside the mapped docker volume.
This is a platform plugin, that will register all accessories within the Bridge provided by homebridge. The following shows the general homebridge configuration (config.json
), see the Supported HAP Services below, in order to get the detailed configuration for each service.
{
"bridge": {
...
},
"accessories": [
...
],
"platforms": [
{
"platform": "openHAB2-Complete",
"host": "http://192.168.0.100",
"port": "8080",
"accessories": [
{
"name": "An items name, as shown in Homekit later",
"type": "switch",
"item": "Itemname-within-OpenHAB"
},
...
]
},
...
]
}
platform
has to be"openHAB2-Complete"
host
: The IP or hostname of your openHAB instance. The Protocol specifier (http://
) is optional, defaults tohttp://
(independent of the specified port)port
: (optional) If not specified the default port of the specifiedhost
protocol is used.accessory
: An array of accessories exposed to HomeKit, see the next chapter for available services and their configurations.
Alternatively you can group accessories of the same type
in a sub-array:
...
"platforms": [
{
...
"accessories": [
{
"type": "switch",
"items": [
{
"name": "An items name, as shown in Homekit later",
"item": "Itemname-within-OpenHAB"
},
{
"name": "An items name, as shown in Homekit later",
"item": "Itemname-within-OpenHAB"
},
...
]
},
...
]
},
...
The following is a list of all services that are currently supported and which values are required within the accessory configuration. Every accessory needs a name
(as shown in HomeKit later) and a type
.
- Complex Accessories:
- Lightbulb
- Homebridge configuration type:
light
- Homebridge configuration type:
- Fan
- Homebridge configuration type:
fan
- Homebridge configuration type:
- Security System
- Homebridge configuration type:
security
- Homebridge configuration type:
- Lightbulb
- Climate Control Accessories:
- Thermostat
- Homebridge configuration type:
thermostat
- Homebridge configuration type:
- Humidifier/Dehumidifier
- Homebridge configuration type:
humidifier
- Homebridge configuration type:
- Heater/Cooler
- Homebridge configuration type:
heatercooler
- Homebridge configuration type:
- Air Purifier
- Homebridge configuration type:
airpurifier
- Homebridge configuration type:
- Thermostat
- Audio Accessories:
- Speaker
- Homebridge configuration type:
speaker
- Homebridge configuration type:
- Microphone
- Homebridge configuration type:
microphone
- Homebridge configuration type:
- Speaker
- Watering Accessories:
- Faucet
- Homebridge configuration type:
faucet
- Homebridge configuration type:
- Valve
- Homebridge configuration type:
valve
- Homebridge configuration type:
- Irrigation System
- Homebridge configuration type:
irrigation
- Homebridge configuration type:
- Faucet
- Position Based Actors:
- Window Covering
- Homebridge configuration type:
windowcovering
- Homebridge configuration type:
- Door
- Homebridge configuration type:
door
- Homebridge configuration type:
- Window
- Homebridge configuration type:
window
- Homebridge configuration type:
- Lock Mechanism
- Homebridge configuration type:
lock
- Homebridge configuration type:
- Garage Door Opener
- Homebridge configuration type:
garage
- Homebridge configuration type:
- Slat
- Homebridge configuration type:
slat
- Homebridge configuration type:
- Window Covering
- Numeric Sensors:
- Temperature Sensor
- Homebridge configuration type:
temp
- Homebridge configuration type:
- Humidity Sensor
- Homebridge configuration type:
humidity
- Homebridge configuration type:
- Light Sensor
- Homebridge configuration type:
lux
- Homebridge configuration type:
- Air Quality Sensor
- Homebridge configuration type:
air
- Homebridge configuration type:
- Temperature Sensor
- Binary Actors:
- Binary Sensors:
- Motion Sensor
- Homebridge configuration type:
motion
- Homebridge configuration type:
- Occupancy Sensor
- Homebridge configuration type:
occupancy
- Homebridge configuration type:
- Leak Sensor
- Homebridge configuration type:
leak
- Homebridge configuration type:
- Carbon Monoxide Sensor
- Homebridge configuration type:
co
- Homebridge configuration type:
- Carbon Dioxide Sensor
- Homebridge configuration type:
co2
- Homebridge configuration type:
- Contact Sensor
- Homebridge configuration type:
contact
- Homebridge configuration type:
- Smoke Sensor
- Homebridge configuration type:
smoke
- Homebridge configuration type:
- Filter Maintenance Sensor
- Homebridge configuration type:
filter
- Homebridge configuration type:
- Motion Sensor
The following services are also defined by the HomeKit protocol, but since I don't know a good way to map them to openHAB items, I currently don't plan to implement them. Let me know if you have any ideas, by opening an issue!
- Camera RTP Stream Management
- Doorbell
- Stateless Programmable Switch
Since iOS 13 multiple accessories can be grouped within a single accessory. This can be -as far as I have tested- done in an arbitrary way. The syntax to define a grouped item is as follows:
{
{
"type": "group",
"name": "Group Name",
"model": "Group Type Model",
"batteryItem": "Itemname-within-OpenHAB",
"batteryItemThreshold": "20",
"items": [
{
"type": "homebridge-openhab2-complete item type",
"name": "An items name, as shown in Homekit later",
"item": "Itemname-within-OpenHAB"
}, {
"type": "homebridge-openhab2-complete item type",
"items": [
{
"name": "An items name, as shown in Homekit later",
"item": "Itemname-within-OpenHAB",
}, {
...
}
]
}
]
}
type
: Needs to be"group"
name
: The name as shown in HomeKit later (in some instances I have experienced that this name is dropped in favor of the first item's name)model
(optional): A model description, defining the grouping. This is only shown in the expanded settings of the group.batteryItem
,batteryItemThreshold
, ... (optional): A battery service can only be defined on the most upper level for the whole group. See Battery Levels and Warnings for more information on the syntax. AllBatteryServices
defined in theitems
array will be ignored!items
: An array of item definitions. As shown in the example, the different items will be defined here, as if they were outside of the group, either through single item definition or multiple definitions of the same type in a sub-array. Those configuration styles can be combined!
Every accessory can be configured to show battery warnings and battery levels. The following configuration can be optionally added to every item:
{
"batteryItem": "Itemname-within-OpenHAB",
"batteryItemThreshold": "10",
"batteryItemInverted": "false",
"batteryItemChargingState": "Itemname-within-OpenHAB",
"batteryItemChargingStateInverted": "false"
}
batteryItem
(optional): The openHAB item representing the battery level for this accessory.- Needs to be of type
Switch
,Contact
orNumber
within openHAB - Note: If the type is
Number
, then the battery warning will be based onbatteryItemThreshold
and the battery level will be the value of the item - Note: If the type is
Switch
orContact
theBatteryLevel
will always show 0% and for statesON
orOPEN
a battery warning will be triggered
- Needs to be of type
batteryItemInverted
(optional): IfbatteryItem
's state needs to be interpreted inverted, set this value to"true"
(Only for typesSwitch
andContact
)- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
batteryItemThreshold
(optional): The threshold ofbatteryItem
's numeric value, below a warning will be triggered- Default:
"20"
- Allowed values: All integers
- Default:
batteryItemChargingState
: The openHAB item representing if the device is currently charging- Needs to be of type
Switch
orContact
within openHAB - Default: Item will be reported as 'Not chargeable' to HomeKit if this item is not available
- Needs to be of type
batteryItemChargingStateInverted
(optional): IfbatteryItemChargingState
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
This service describes a lightbulb.
{
"name": "An items name, as shown in Homekit later",
"type": "light",
"item": "Itemname-within-OpenHAB"
}
item
: The openHAB item controlled by this accessory- Needs to be of type
Switch
,Dimmer
orColor
within openHAB (HomeKit will correctly display brightness -in case ofDimmer
orColor
- and color settings -in case ofColor
-)
- Needs to be of type
This service describes a fan.
{
"name": "An items name, as shown in Homekit later",
"type": "fan",
"item": "Itemname-within-OpenHAB"
}
item
: The openHAB item controlled by this accessory- Needs to be of type
Switch
,Number
orDimmer
within openHAB (HomeKit will correctly display fan speed control -in case ofNumber
orDimmer
-)
- Needs to be of type
This service describes a security system.
{
"name": "An items name, as shown in Homekit later",
"type": "security",
"item": "Itemname-within-OpenHAB"
}
item
: The openHAB item representing the state of the security system- Needs to be of type
String
within openHAB - Allowed values (Every other value will be ignored and shown as an error)
StayArm
: The home is occupied and the residents are active, shown asHome
in the Home.appAwayArm
: The home is unoccupied, shown asAway
in the Home.appNightArm
: The home is occupied and the residents are sleeping, shown asNight
in the Home.appDisarmed
: The security system is disabled, shown asOff
in the Home.appAlarmTriggered
: The security alarm is triggered
- Needs to be of type
This service describes a thermostat.
{
"name": "An items name, as shown in Homekit later",
"type": "thermostat",
"currentTempItem": "Itemname-within-OpenHAB",
"targetTempItem": "Itemname-within-OpenHAB",
"currentHumidityItem": "Itemname-within-OpenHAB",
"targetHumidityItem": "Itemname-within-OpenHAB",
"heatingItem": "Itemname-within-OpenHAB",
"coolingItem": "Itemname-within-OpenHAB",
"tempUnit": "Celsius",
"heatingThresholdTempItem": "Itemname-within-OpenHAB",
"coolingThresholdTempItem": "Itemname-within-OpenHAB",
"modeItem": "Itemname-within-OpenHAB",
"minTemp": "-100",
"maxTemp": "200",
"minStep": "0.1"
}
currentTempItem
: The openHAB item representing the current temperature as measured by the thermostat-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
targetTempItem
: The openHAB item representing the target temperature inside the room-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
currentHumidityItem
(optional): The openHAB item representing the current humidity as measured by the thermostat-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
targetHumidityItem
(optional): The openHAB item representing the target humidity inside the room-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
heatingItem
(optional, ifcoolingItem
is present, otherwise required): The openHAB item showing, if the room is currently being heated- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
coolingItem
(optional, ifheatingItem
is present, otherwise required): The openHAB item showing, if the room is currently being cooled- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
tempUnit
(optional): Gives the measurement unit of the thermostat. HomeKit always expects the input to be in degrees celsius, therefore specifying Fahrenheit as a unit, the plugin will convert the values to be shown correctly on the fly.- Default:
Celsius
- Allowed values:
Celsius
&Fahrenheit
- Default:
heatingThresholdTempItem
(optional): The openHAB item describing the heating threshold in Celsius for devices that support simultaneous heating and cooling. The value of this characteristic represents the 'minimum temperature' that mus be reached before heating is turned on.-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
coolingThresholdTempItem
(optional): The openHAB item describing the cooling threshold in Celsius for devices that support simultaneous heating and cooling. The value of this characteristic represents the 'maximum temperature' that mus be reached before cooling is turned on.-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
modeItem
(optional): If your thermostat can be set to heating, cooling or auto mode through an item, and/or reports back its current configuration use this item, otherwise the heating/cooling capabilities are deferred fromheatingItem
andcoolingItem
and will not be changeable.- Needs to be of type
Number
within openHAB - Only discrete values are recognized:
- 0 ≙
Off
- 1 ≙
Heating
- 2 ≙
Cooling
- 3 ≙
Auto
- 0 ≙
- Needs to be of type
minTemp
(optional): If you need to change the minimum allowed temperature, the thermostat is reading- Needs to be an float
- Default:
-100
maxTemp
(optional): If you need to change the maximum allowed temperature, the thermostat is reading- Needs to be a float
- Default:
200
minStep
(optional): If you need to change the granularity of the temperature reading- Needs to be a float
- Default:
0.1
This service describes a humidifier and/or dehumidifier accessory.
{
"name": "An items name, as shown in Homekit later",
"type": "humidifier",
"currentHumidityItem": "Itemname-within-OpenHAB",
"activeItem": "Itemname-within-OpenHAB",
"activeItemInverted": "false",
"humidifierItem": "Itemname-within-OpenHAB",
"dehumidifierItem": "Itemname-within-OpenHAB",
"modeItem": "Itemname-within-OpenHAB",
"humidifierThresholdItem": "Itemname-within-OpenHAB",
"dehumidifierThresholdItem": "Itemname-within-OpenHAB",
"waterLevelItem": "Itemname-within-OpenHAB",
"swingItem": "Itemname-within-OpenHAB",
"swingItemInverted": "false",
"rotationSpeedItem": "Itemname-within-OpenHAB"
}
currentHumidityItem
: The openHAB item representing the current humidity-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
activeItem
: The openHAB item showing, if the (de-)humidfier is currently active- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
activeItemInverted
(optional): IfactiveItem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
humidifierItem
(optional, ifdehumidifierItem
is present, otherwise required): The openHAB item showing, if the room is currently humidified- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
dehumidifierItem
(optional, ifhumidifierItem
is present, otherwise required): The openHAB item showing, if the room is currently dehumidified- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
modeItem
: (optional) If your (de-)humidifier can be set to humidifying, dehumidifying or auto mode through an item, and/or reports back its current configuration use this item, otherwise the humidifying/dehumidifying capabilities are deferred fromhumidifierItem
anddehumidifierItem
and will not be changeable.- Needs to be of type
Number
within openHAB - Only discrete values are recognized:
- 0 ≙
Humidifier or Dehumidifier
- 1 ≙
Humidifier
- 2 ≙
Dehumidifier
- 0 ≙
- Needs to be of type
humidifierThresholdItem
: (optional) The openHAB item describing the humidifying threshold. The value of this characteristic represents the 'minimum relative humidity' that mus be reached before humidifying is turned on.-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
dehumidifierThresholdItem
: (optional) The openHAB item describing the dehumidifying threshold. The value of this characteristic represents the 'maximum relative humidity' that mus be reached before dehumidifying is turned on.-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
waterLevelItem
: (optional) The openHAB item representing the current water level-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
swingItem
: (optional) The openHAB item showing, if swing is active- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
swingItemInverted
(optional): IfswingItem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
rotationSpeedItem
: (optional) The openHAB item representing the rotation speed-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
This service describes a heater and/or cooler accessory.
{
"name": "An items name, as shown in Homekit later",
"type": "heatercooler",
"currentTempItem": "Itemname-within-OpenHAB",
"activeItem": "Itemname-within-OpenHAB",
"activeItemInverted": "false",
"heatingItem": "Itemname-within-OpenHAB",
"coolingItem": "Itemname-within-OpenHAB",
"modeItem": "Itemname-within-OpenHAB",
"heatingThresholdTempItem": "Itemname-within-OpenHAB",
"coolingThresholdTempItem": "Itemname-within-OpenHAB",
"swingItem": "Itemname-within-OpenHAB",
"swingItemInverted": "false",
"rotationSpeedItem": "Itemname-within-OpenHAB",
"tempUnit": "Celsius"
}
currentTempItem
: The openHAB item representing the current temperature-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
activeItem
: The openHAB item showing, if the heater/cooler is currently active- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
activeItemInverted
(optional): IfactiveItem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
heatingItem
(optional, ifcoolingItem
is present, otherwise required): The openHAB item showing, if the room is currently being heated- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
coolingItem
(optional, ifheatingItem
is present, otherwise required): The openHAB item showing, if the room is currently being cooled- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
modeItem
: (optional) If your heater/cooler can be set to heating, cooling or auto mode through an item, and/or reports back its current configuration use this item, otherwise the heating/cooling capabilities are deferred fromheatingItem
andcoolingItem
and will not be changeable.- Needs to be of type
Number
within openHAB - Only discrete values are recognized:
- 0 ≙
Auto
- 1 ≙
Heat
- 2 ≙
Cool
- 0 ≙
- Needs to be of type
heatingThresholdTempItem
: (optional) The openHAB item describing the heating threshold in Celsius for devices that support simultaneous heating and cooling. The value of this characteristic represents the 'minimum temperature' that mus be reached before heating is turned on.-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
coolingThresholdTempItem
: (optional) The openHAB item describing the cooling threshold in Celsius for devices that support simultaneous heating and cooling. The value of this characteristic represents the 'maximum temperature' that mus be reached before cooling is turned on.-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
swingItem
: (optional) The openHAB item showing, if swing is active- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
swingItemInverted
(optional): IfswingItem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
rotationSpeedItem
: (optional) The openHAB item representing the rotation speed-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
tempUnit
(optional): Gives the measurement unit of the thermostat, currently does not change anything inside HomeKit- Default:
Celsius
- Allowed values:
Celsius
&Fahrenheit
- Default:
This service describes an air purifier accessory.
{
"name": "An items name, as shown in Homekit later",
"type": "airpurifier",
"purifyingItem": "Itemname-within-OpenHAB",
"modeItem": "Itemname-within-OpenHAB",
"activeItem": "Itemname-within-OpenHAB",
"activeItemInverted": "false",
"swingItem": "Itemname-within-OpenHAB",
"swingItemInverted": "false",
"rotationSpeedItem": "Itemname-within-OpenHAB"
}
purifyingItem
: The openHAB item showing, if the air purifier is currently purifying the air- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
modeItem
: The openHAB item showing, if the air purifier is currently in Manual (OFF
orCLOSED
) or Automatic Mode (ON
orOPEN
)- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
activeItem
: The openHAB item showing, if the air purifier is currently active- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
activeItemInverted
(optional): IfactiveItem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
swingItem
: (optional) The openHAB item showing, if swing is active- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
swingItemInverted
(optional): IfswingItem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
rotationSpeedItem
: (optional) The openHAB item representing the rotation speed-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
This service is used to control the audio output settings on a speaker device.
Note: Even though Speaker
is part of Apple's HAP specification, this accessory is shown as "not supported" in the Home.app.
{
"name": "An items name, as shown in Homekit later",
"type": "speaker",
"muteItem": "Itemname-within-OpenHAB",
"muteItemInverted": "true",
"volumeItem": "Itemname-within-OpenHAB"
}
muteItem
: The openHAB item showing, if the speaker is muted- Needs to be of type
Switch
within openHAB
- Needs to be of type
muteItemInverted
(optional): IfmuteItem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
volumeItem
(optional): The openHAB item controlling the speaker's volume-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
This service is used to control the audio input settings on an audio device (primarily used for microphones).
Note: Even though Microphone
is part of Apple's HAP specification, this accessory is shown as "not supported" in the Home.app.
{
"name": "An items name, as shown in Homekit later",
"type": "microphone",
"muteItem": "Itemname-within-OpenHAB",
"muteItemInverted": "true",
"volumeItem": "Itemname-within-OpenHAB"
}
muteItem
: The openHAB item showing, if the microphone is muted- Needs to be of type
Switch
within openHAB
- Needs to be of type
muteItemInverted
(optional): IfmuteItem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
volumeItem
(optional): The openHAB item controlling the microphone's volume-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
This service describes a faucet.
{
"name": "An items name, as shown in Homekit later",
"type": "faucet",
"item": "Itemname-within-OpenHAB",
"inverted": "true"
}
item
: The openHAB item showing, if the faucet is currently active- Needs to be of type
Switch
within openHAB
- Needs to be of type
inverted
(optional): Ifitem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
This service describes a valve.
{
"name": "An items name, as shown in Homekit later",
"type": "valve",
"item": "Itemname-within-OpenHAB",
"inverted": "true",
"inUseItem": "Itemname-within-OpenHAB",
"inUseItemInverted": "true",
"durationItem": "Itemname-within-OpenHAB",
"valveType": "generic"
}
item
: The openHAB item showing, if the valve is currently active- Needs to be of type
Switch
within openHAB
- Needs to be of type
inverted
(optional): Ifitem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
inUseItem
Representing, if the valve is currently in use (ifSwitch
isON
,Contact
isOPEN
orNumber
is greater than 0)- Needs to be of type
Switch
,Contact
orNumber
within openHAB
- Needs to be of type
inUseItemInverted
(optional): IfinUseItem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
durationItem
(optional): This item will be set by HomeKit to show the duration for the watering. This item should also be decreased, to show the remaining watering time- Needs to be of type
Number
within openHAB
- Needs to be of type
valveType
(optional): The type of valve described by this service.- Default:
generic
- Allowed values:
generic
,irrigation
,showerhead
,faucet
- Default:
This service describes an irrigation system.
{
"name": "An items name, as shown in Homekit later",
"type": "irrigation",
"activeItem": "Itemname-within-OpenHAB",
"acitveItemInverted": "true",
"inUseItem": "Itemname-within-OpenHAB",
"inUseItemInverted": "true",
"durationItem": "Itemname-within-OpenHAB",
"programMode": "manual",
"programModeItem": "Itemname-within-OpenHAB"
}
activeItem
: The openHAB item showing, if the valve is currently active- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
activeItemInverted
(optional): IfactiveItem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
inUseItem
Representing, if the valve is currently in use (ifSwitch
isON
,Contact
isOPEN
orNumber
is greater than 0)- Needs to be of type
Switch
,Contact
orNumber
within openHAB
- Needs to be of type
inUseItemInverted
(optional): IfinUseItem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
durationItem
(optional): This item will be set by HomeKit to show the duration for the watering. This item should also be decreased, to show the remaining watering time- Needs to be of type
Number
within openHAB
- Needs to be of type
programMode
(optional): The current program mode of this accessory.- Default:
noprogram
- Allowed values:
noprogram
,scheduled
,manual
- Default:
programModeItem
(optional): If your accessory can dynamically report its program mode, use this item as an alternative toprogramMode
.- Needs to be of type
Number
within openHAB - Only discrete values are recognized:
- 0 ≙
No Program scheduled
- 1 ≙
Program scheduled
- 2 ≙
Manual Mode
- 0 ≙
- Needs to be of type
This service describes motorized window coverings or shades - examples include shutters, blinds, awnings etc.
{
"name": "An items name, as shown in Homekit later",
"type": "windowcovering",
"item": "Itemname-within-OpenHAB",
"inverted": "false",
"multiplier": "1",
"stateItem": "Itemname-within-OpenHAB",
"stateItemInverted": "false",
"stateItemMultiplier": "1",
"manuMode": "false",
"horizontalTiltItem": "Itemname-within-OpenHAB",
"horizontalTiltItemRangeStart": "-90",
"horizontalTiltItemRangeEnd": "90",
"verticalTiltItem": "Itemname-within-openHAB",
"verticalTiltItemRangeStart": "-90",
"verticalTiltItemRangeEnd": "90"
}
item
: The openHAB item representing the window covering, receiving commands about the target position and determining the current position (ifstateItem
is not set)- Needs to be of type
Rollershutter
,Number
orSwitch
within openHAB
- Needs to be of type
inverted
(optional): Ifitem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
multiplier
(optional): Ifitem
's state need to be multiplied by a fixed amount to make sense to HomeKit, set this to a number (e.g. if your device stores its state in a float range from 0 to 1, where HomeKit expects integer numbers from 0 to 100 use a multiplier of 100)- Default:
"1"
- Needs to be a number don't forget the quotes
- Default:
stateItem
(optional): The openHAB item, used to determine the state of the window covering instead ofitem
's state- Needs to be of type
Rollershutter
,Number
,Switch
orContact
within openHAB
- Needs to be of type
stateItemInverted
(optional): IfstateItem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
stateItemMultiplier
(optional): IfstateItem
's state need to be multiplied by a fixed amount to make sense to HomeKit, set this to a number (e.g. if your device stores its state in a float range from 0 to 1, where HomeKit expects integer numbers from 0 to 100 use a multiplier of 100)- Default:
"1"
- Needs to be a number don't forget the quotes
- Default:
manuMode
(optional): If your item can be operated manually, you should enable this mode to not seeOpening...
orClosing...
on the item when manipulating the state manually (This is due to the fact that HomeKit stores aTargetState
value and compares it to theActualState
to show this metadata. ThemanuMode
automatically changes theTargetState
of the item, when theActualState
is changed)- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
horizontalTiltItem
(optional): An item representing the angle of horizontal slats.-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state) -
Allowed value range:
-90
to90
(for different ranges, seehorizontalTiltItemRangeStart
andhorizontalTiltItemRangeEnd
):- 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
- A value of 90 indicates that the slats are rotated all the way in a direction where the window-facing edge is higher than the user-facing edge
-
horizontalTiltItemRangeStart
(optional): If the range of the openHAB item does not start at-90
(e.g. if the angle is represented in percent from 0 to 100) set this value. The range will be mapped linearly.- Default:
"-90"
- Allowed values: All integers
- Default:
horizontalTiltItemRangeEnd
(optional): If the range of the openHAB item does not end at90
(e.g. if the angle is represented in percent from 0 to 100) set this value. The range will be mapped linearly.- Default:
"90"
- Allowed values: All integers
- Default:
verticalTiltItem
(optional): An item representing the angle of vertical slats.-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state) -
Allowed value range:
-90
to90
(for different ranges, seeverticalTiltItemRangeStart
andverticalTiltItemRangeEnd
):- 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 to the left of the window-facing edge
- A value of 90 indicates that the slats are rotated all the way in a direction where the user-facing edge is to the right of the window-facing edge
-
verticalTiltItemRangeStart
(optional): If the range of the openHAB item does not start at-90
(e.g. if the angle is represented in percent from 0 to 100) set this value. The range will be mapped linearly.- Default:
"-90"
- Allowed values: All integers
- Default:
verticalTiltItemRangeEnd
(optional): If the range of the openHAB item does not end at90
(e.g. if the angle is represented in percent from 0 to 100) set this value. The range will be mapped linearly.- Default:
"90"
- Allowed values: All integers
- Default:
This service describes a motorized door
{
"name": "An items name, as shown in Homekit later",
"type": "door",
"item": "Itemname-within-OpenHAB",
"inverted": "false",
"multiplier": "1",
"stateItem": "Itemname-within-OpenHAB",
"stateItemInverted": "false",
"stateItemMultiplier": "1",
"manuMode": "false"
}
item
: The openHAB item representing the door, receiving commands about the target position and determining the current position (ifstateItem
is not set)- Needs to be of type
Rollershutter
,Number
orSwitch
within openHAB
- Needs to be of type
inverted
(optional): Ifitem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
multiplier
(optional): Ifitem
's state need to be multiplied by a fixed amount to make sense to HomeKit, set this to a number (e.g. if your device stores its state in a float range from 0 to 1, where HomeKit expects integer numbers from 0 to 100 use a multiplier of 100)- Default:
"1"
- Needs to be a number don't forget the quotes
- Default:
stateItem
(optional): The openHAB item, used to determine the state of the door instead ofitem
's state- Needs to be of type
Rollershutter
,Number
,Switch
orContact
within openHAB
- Needs to be of type
stateItemInverted
(optional): IfstateItem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
stateItemMultiplier
(optional): IfstateItem
's state need to be multiplied by a fixed amount to make sense to HomeKit, set this to a number (e.g. if your device stores its state in a float range from 0 to 1, where HomeKit expects integer numbers from 0 to 100 use a multiplier of 100)- Default:
"1"
- Needs to be a number don't forget the quotes
- Default:
manuMode
(optional): If your item can be operated manually, you should enable this mode to not seeOpening...
orClosing...
on the item when manipulating the state manually (This is due to the fact that HomeKit stores aTargetState
value and compares it to theActualState
to show this metadata. ThemanuMode
automatically changes theTargetState
of the item, when theActualState
is changed)- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
This service describes a motorized window
{
"name": "An items name, as shown in Homekit later",
"type": "window",
"item": "Itemname-within-OpenHAB",
"inverted": "false",
"multiplier": "1",
"stateItem": "Itemname-within-OpenHAB",
"stateItemInverted": "false",
"stateItemMultiplier": "1",
"manuMode": "false"
}
item
: The openHAB item representing the window, receiving commands about the target position and determining the current position (ifstateItem
is not set)- Needs to be of type
Rollershutter
,Number
orSwitch
within openHAB
- Needs to be of type
inverted
(optional): Ifitem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
multiplier
(optional): Ifitem
's state need to be multiplied by a fixed amount to make sense to HomeKit, set this to a number (e.g. if your device stores its state in a float range from 0 to 1, where HomeKit expects integer numbers from 0 to 100 use a multiplier of 100)- Default:
"1"
- Needs to be a number don't forget the quotes
- Default:
stateItem
(optional): The openHAB item, used to determine the state of the window instead ofitem
's state- Needs to be of type
Rollershutter
,Number
,Switch
orContact
within openHAB
- Needs to be of type
stateItemInverted
(optional): IfstateItem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
stateItemMultiplier
(optional): IfstateItem
's state need to be multiplied by a fixed amount to make sense to HomeKit, set this to a number (e.g. if your device stores its state in a float range from 0 to 1, where HomeKit expects integer numbers from 0 to 100 use a multiplier of 100)- Default:
"1"
- Needs to be a number don't forget the quotes
- Default:
manuMode
(optional): If your item can be operated manually, you should enable this mode to not seeOpening...
orClosing...
on the item when manipulating the state manually (This is due to the fact that HomeKit stores aTargetState
value and compares it to theActualState
to show this metadata. ThemanuMode
automatically changes theTargetState
of the item, when theActualState
is changed)- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
The HomeKit Lock Mechanism service is designed to expose and control the physical lock mechanism on a device.
{
"name": "An items name, as shown in Homekit later",
"type": "lock",
"item": "Itemname-within-OpenHAB",
"inverted": "false",
"stateItem": "Itemname-within-OpenHAB",
"stateItemInverted": "false"
}
item
: The openHAB item representing the lock, receiving commands about the target position and determining the current position (ifstateItem
is not set)- Needs to be of type
Switch
within openHAB
- Needs to be of type
inverted
(optional): Ifitem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
stateItem
(optional): The openHAB item, used to determine the state of the lock instead ofitem
's state- Needs to be of type
Rollershutter
,Number
,Switch
orContact
within openHAB
- Needs to be of type
stateItemInverted
(optional): IfstateItem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
This service describes a garage door opener tat controls a single door. If a garage has more than one door, then each door should have its own Garage Door Opener Service.
{
"name": "An items name, as shown in Homekit later",
"type": "garage",
"item": "Itemname-within-OpenHAB",
"inverted": "false",
"multiplier": "1",
"stateItem": "Itemname-within-OpenHAB",
"stateItemInverted": "false",
"stateItemMultiplier": "1",
"obstructionItem": "Itemname-within-OpenHAB",
"obstructionItemInverted": "false"
}
item
: The openHAB item representing the garage door, receiving commands about the target position and determining the current position (ifstateItem
is not set)- Needs to be of type
Rollershutter
,Number
orSwitch
within openHAB - In case of a
Number
item:- 100 ≙ OPEN
- 0 ≙ CLOSED
- In case of a
Rollershutter
item:- For the current state, the accessory behaves like a
Number
item - For the target state, the item will receive
UP
andDOWN
commands - If you have an inverted
Rollershutter
item, use the same item asstateItem
withstateItemInverted
set to"true"
andinverted
set to false
- For the current state, the accessory behaves like a
- Needs to be of type
inverted
(optional): Ifitem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
multiplier
(optional): Ifitem
's state need to be multiplied by a fixed amount to make sense to HomeKit, set this to a number (e.g. if your device stores its state in a float range from 0 to 1, where HomeKit expects integer numbers from 0 to 100 use a multiplier of 100)- Default:
"1"
- Needs to be a number don't forget the quotes
- Default:
stateItem
(optional): The openHAB item, used to determine the state of the garage door instead ofitem
's state- Needs to be of type
Rollershutter
,Number
,Switch
orContact
within openHAB
- Needs to be of type
stateItemInverted
(optional): IfstateItem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
stateItemMultiplier
(optional): IfstateItem
's state need to be multiplied by a fixed amount to make sense to HomeKit, set this to a number (e.g. if your device stores its state in a float range from 0 to 1, where HomeKit expects integer numbers from 0 to 100 use a multiplier of 100)- Default:
"1"
- Needs to be a number don't forget the quotes
- Default:
obstructionItem
: The openHAB item showing, if an obstruction is detected- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
obstructionItemInverted
(optional): IfobstructionItem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
This service describes a slat which tilts on a vertical or a horizontal axis.
Note: Even though Slat
is part of Apple's HAP specification, this accessory is shown as "not supported" in the Home.app.
{
"name": "An items name, as shown in Homekit later",
"type": "slat",
"stateItem": "Itemname-within-OpenHAB",
"stateItemInverted": "false",
"item": "Itemname-within-OpenHAB",
"itemRangeStart: "itemRangeStart",
"itemRangeEnd: "itemRangeEnd",
"slatType": "horizontal"
}
stateItem
: The openHAB item describing the current state. The state can beFixed
orSwinging
.- Needs to be of type
Switch
orContact
within openHAB - By default,
OPEN
orON
represents a swinging state, andCLOSED
orOFF
a fixed state.
- Needs to be of type
stateItemInverted
(optional): IfstateItem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
item
(optional): The openHAB item representing the tilt angle of the slat, if the user can set the slats to a particular tilt angle.-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state) -
Allowed value range:
-90
to90
(for different ranges, seeitemRangeStart
anditemRangeEnd
):- A value of 0 indicates that the slats are rotated to a fully open position
- If
slatType
isvertical
:- 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
- A value of 90 indicates that the slats are rotated all the way in a direction where the window-facing edge is higher than the user-facing edge
- If
slatType
ishorizontal
:- A value of -90 indicates that the slats are rotated all the way in a direction where the user-facing edge is to the left of the window-facing edge
- A value of 90 indicates that the slats are rotated all the way in a direction where the user-facing edge is to the right of the window-facing edge
-
itemRangeStart
(optional): If the range of the openHAB item does not start at-90
(e.g. if the angle is represented in percent from 0 to 100) set this value. The range will be mapped linearly.- Default:
"-90"
- Allowed values: All integers
- Default:
itemRangeEnd
(optional): If the range of the openHAB item does not end at90
(e.g. if the angle is represented in percent from 0 to 100) set this value. The range will be mapped linearly.- Default:
"90"
- Allowed values: All integers
- Default:
slatType
(optional): Describes the type of slats- Default:
horizontal
- Allowed values:
horizontal
&vertical
- Default:
This service describes a temperature sensor.
{
"name": "An items name, as shown in Homekit later",
"type": "temp",
"currentTempItem": "Itemname-within-OpenHAB",
"tempUnit": "Celsius",
"minTemp": "-100",
"maxTemp": "200",
"minStep": "0.1"
}
currentTempItem
: The openHAB item representing the current temperature-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
tempUnit
(optional): Gives the measurement unit of the thermostat. HomeKit always expects the input to be in degrees celsius, therefore specifying Fahrenheit as a unit, the plugin will convert the values to be shown correctly on the fly.- Default:
Celsius
- Allowed values:
Celsius
&Fahrenheit
- Default:
minTemp
(optional): If you need to change the minimum allowed temperature, the thermostat is reading- Needs to be an float
- Default:
-100
maxTemp
(optional): If you need to change the maximum allowed temperature, the thermostat is reading- Needs to be a float
- Default:
200
minStep
(optional): If you need to change the granularity of the temperature reading- Needs to be a float
- Default:
0.1
This service describes a humidity sensor.
{
"name": "An items name, as shown in Homekit later",
"type": "humidity",
"item": "Itemname-within-OpenHAB"
}
item
: The openHAB item representing the current humidity-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
This service describes a light sensor.
{
"name": "An items name, as shown in Homekit later",
"type": "lux",
"item": "Itemname-within-OpenHAB"
}
item
: The openHAB item representing the current light in lux-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
This service describes an air quality sensor.
{
"name": "An items name, as shown in Homekit later",
"type": "air",
"item": "Itemname-within-OpenHAB"
}
item
: The openHAB item representing the current air quality, referring to the cumulative air quality recorded by the accessory, which may be based on multiple sensors present.- Needs to be of type
Number
within openHAB - Only discrete values are recognized:
- 0 ≙
UNKNOWN
- 1 ≙
EXCELLENT
- 2 ≙
GOOD
- 3 ≙
FAIR
- 4 ≙
INFERIOR
- 5 ≙
POOR
- 0 ≙
- Needs to be of type
This service describes a binary switch.
{
"name": "An items name, as shown in Homekit later",
"type": "switch",
"item": "Itemname-within-OpenHAB",
"inverted": "false"
}
item
: The openHAB item controlled by this accessory- Needs to be of type
Switch
within openHAB
- Needs to be of type
inverted
(optional): Ifitem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
This service describes an outlet.
{
"name": "An items name, as shown in Homekit later",
"type": "outlet",
"item": "Itemname-within-OpenHAB",
"inverted": "true",
"inUseItem": "Itemname-within-OpenHAB",
"inUseItemInverted": "false"
}
item
: The openHAB item controlled by this accessory- Needs to be of type
Switch
within openHAB
- Needs to be of type
inverted
(optional): Ifitem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
inUseItem
(optional): Representing, if the outlet is currently in use (ifSwitch
isON
,Contact
isOPEN
orNumber
is greater than 0)- Default: The state of
item
is used to show if the outlet is in use - Needs to be of type
Switch
,Contact
orNumber
within openHAB
- Default: The state of
inUseItemInverted
(optional): IfinUseItem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
This service describes a motion sensor.
{
"name": "An items name, as shown in Homekit later",
"type": "motion",
"item": "Itemname-within-OpenHAB",
"inverted": "true"
}
item
: The openHAB item showing, if motion is detected- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
inverted
(optional): Ifitem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
This service describes an occupancy sensor.
{
"name": "An items name, as shown in Homekit later",
"type": "occupancy",
"item": "Itemname-within-OpenHAB",
"inverted": "true"
}
item
: The openHAB item showing, if occupancy is detected- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
inverted
(optional): Ifitem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
This service describes a leak sensor.
{
"name": "An items name, as shown in Homekit later",
"type": "leak",
"item": "Itemname-within-OpenHAB",
"inverted": "true"
}
item
: The openHAB item showing, if a leak is detected- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
inverted
(optional): Ifitem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
This service describes a carbon monoxide sensor.
{
"name": "An items name, as shown in Homekit later",
"type": "co",
"item": "Itemname-within-OpenHAB",
"inverted": "true",
"levelItem": "Itemname-within-OpenHAB"
}
item
: The openHAB item showing, if carbon monoxide is detected- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
inverted
(optional): Ifitem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
levelItem
(optional): The openHAB item representing the current carbon monoxide level, measured by the sensor-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
This service describes a carbon dioxide sensor.
{
"name": "An items name, as shown in Homekit later",
"type": "co2",
"item": "Itemname-within-OpenHAB",
"inverted": "true",
"levelItem": "Itemname-within-OpenHAB"
}
item
: The openHAB item showing, if carbon dioxide is detected- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
inverted
(optional): Ifitem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
levelItem
(optional): The openHAB item representing the current carbon dioxide level, measured by the sensor-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
This service describes a contact sensor.
{
"name": "An items name, as shown in Homekit later",
"type": "contact",
"item": "Itemname-within-OpenHAB",
"inverted": "true"
}
item
: The openHAB item showing, if contact is detected- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
inverted
(optional): Ifitem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
This service describes a smoke sensor.
{
"name": "An items name, as shown in Homekit later",
"type": "smoke",
"item": "Itemname-within-OpenHAB",
"inverted": "true"
}
item
: The openHAB item showing, if smoke is detected- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
inverted
(optional): Ifitem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
This service describes a filter maintenance sensor.
{
"name": "An items name, as shown in Homekit later",
"type": "filter",
"item": "Itemname-within-OpenHAB",
"inverted": "true",
"levelItem": "Itemname-within-OpenHAB"
}
item
: The openHAB item showing, if filter maintenance is required- Needs to be of type
Switch
orContact
within openHAB
- Needs to be of type
inverted
(optional): Ifitem
's state needs to be interpreted inverted, set this value to"true"
- Default:
"false"
- Allowed values:
"true"
&"false"
don't forget the quotes
- Default:
levelItem
(optional): The openHAB item representing the current filter level-
Needs to be of type
Number
,Rollershutter
, orDimmer
within openHAB(Note: When using
Dimmer
orRollershutter
type and OpenHAB receives a non numeric command likeON
,OFF
,INCREASE
,DECREASE
,UP
orDOWN
this might lead to unexpected behaviour and/or non-responsive HomeKit items. This exception is not covered by this plugin and the user needs to ensure a consistent state)
-
Obviously the aim of this project is a full coverage of the HAP specification. Due to the limitations of smart devices in my home I can only test a subset and would love to have your feedback and input for this project.
Due to the very limited documentation on homebridge plugin development I have not implemented a dynamic platform (there is only this partly complete wiki entry). If anyone of you knows how to do it, please contact me directly!
If you have feedback or suggestions how to better represent the services as openHAB Items, feel free to open an issue.
If you would like to contribute just send me a pull request. In order to add a new service you have to modify/add the following parts:
- Create your own accessory class within
./accessory
- The only required functions are
getServices()
(returning an array ofHAP.Service
with attachedHAP.Characteristic
) andidentify()
(which does not need to do anything). Those are implemented in theAccessory
super class and don't need to be overridden. Make sure thatthis._services
is populated and reflects your service - Define
const type = "YourTypeName"
(this will be used insideconfig.json
to identify an accessory of your type) andfunction createAccessory(platform, config)
returning an instance of your Accessory. - Finally expose
type
andcreateAccessory
throughmodule.exports = {type, createAccessory}
My accessories are using centrally defined characteristics inside ./accessory/characteristic
. See NumericSensor.js
for a simple characteristic implementation and TemperatureSensor.js
for a simple accessory using this characteristic. This is not a requirement, but highly recommended.
homebridge-openhab2 plugin | openHAB2 - Complete Edition |
---|---|
Verly little configuration within homebridge/openHAB, only tags within *.items files and inclusion within sitemap, obviously requiring both to be created manually |
Explicit declaration within config.json not requiring instable openHAB Metadata Provider (removes items if state is NULL ) and de-couples homebridge configuration from openHAB |
Support only 1:1 mappings between Items and HomeKit services | Supports composite items (e.g. Thermostat, Security System, Battery States, etc.) |
Uses SSE to receive push notifications from openHAB about state change and requires sitemap definitions |
Pulling of states through REST interface & push notifications from openHAB through SSE without the requirement of a sitemap |
Thermostats never really worked | Thermostats working as expected |
4 accessory types supported | 29 different accessory types supported |
Light item in openHAB gets triggered multiple times from single user interaction | Light item in openHAB receives only one command per user interaction |
No support for items with notification capabilities | Many HomeKit services can notify the user about a state change. Those accessories are only supported in this plugin |
Concluding, I personally might only consider using the OpenHAB homebridge plugin in smaller, less diverse installations. However my own installation has a a lot of different device types, that I want to fully include in HomeKit, therefore this plugin is the only feasible way for me and everyone alike.
First of all, a massive thank you to all the users of this plugin, seeing so many positive responses to my work keeps me going and improving!
A couple of people helped me test this piece of software and by opening issues, pointing me into new and interesting directions and showing me ways to improve this plugin. A couple of them are very persistent and I want to thank you guys:
- Pieter Janssens (@piejanssens) for his kind words on the openHAB community forum
- Grzegorz (@grzegorz914) for providing quick feedback and opening a couple of helpful PR's
- @EjvindHald for at least the same amount of feedback
- Honorable mentions for finding my bugs and opening great, helpful and responsive issues:
- @hartmood
- @maisun
- @apfelflo89
- @CHTHSCH