Homebridge Plugin for OpenHAB2 - Complete Edition (works also with OpenHAB3!)
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.
Preface
Since the native HomeKit integration of OpenHAB has significantly improved (still lacking some of the available Service of this plugin), I don't think there is much value in this plugin.
After testing openHAB3's HomeKit integration for a week, I decided to move back to homebridge, due to the instability of openHAB's implementation.
As part of my OpenHAB 3 migration I updated the code to support OH3, finally put some bug fixes that happened over the last year into the release and replaced the depricated request package.
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.
Configuration
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.
host: The IP or hostname of your openHAB instance. The Protocol specifier (http://) is optional, defaults to http:// (independent of the specified port)
port: (optional) If not specified the default port of the specified host protocol is used
username: (optional) Username for HTTP(S) basic auth
password: (optional) Password for HTTP(S) basic auth
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:
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. The combination of name and type needs to be unique and should not change in the hombridge configuration (you can safely rename the item within the Home.app after adding them). Changing name or type in the config will change the item's serial number, which would be registered as a new/different one.
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
Configuration for every accessory
Grouping
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:
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. All BatteryServices defined in the items 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!
Battery Levels and Warnings
Every accessory can be configured to show battery warnings and battery levels. The following configuration can be optionally added to every item:
batteryItem(optional): The openHAB item representing the battery level for this accessory.
Needs to be of type Switch, Contact or Number within openHAB
Note: If the type is Number, then the battery warning will be based on batteryItemThreshold and the battery level will be the value of the item
Note: If the type is Switch or Contact the BatteryLevel will always show 0% and for states ON or OPEN a battery warning will be triggered
batteryItemInverted(optional): If batteryItem's state needs to be interpreted inverted, set this value to "true" (Only for types Switch and Contact)
Default: "false"
Allowed values: "true" & "false"don't forget the quotes
batteryItemThreshold(optional): The threshold of batteryItem's numeric value, below a warning will be triggered
Default: "20"
Allowed values: All integers
batteryItemChargingState: The openHAB item representing if the device is currently charging
Needs to be of type Switch or Contact within openHAB
Default: Item will be reported as 'Not chargeable' to HomeKit if this item is not available
batteryItemChargingStateInverted(optional): If batteryItemChargingState's state needs to be interpreted inverted, set this value to "true"
Default: "false"
Allowed values: "true" & "false"don't forget the quotes
Available accessory types
Lightbulb
This service describes a lightbulb.
{
"name": "An items name, as shown in Homekit later",
"type": "light",
"item": "Itemname-within-OpenHAB",
"sendOnOnlyWhenOff": "false"
}
item: The openHAB item controlled by this accessory
Needs to be of type Switch, Dimmer or Color within openHAB (HomeKit will correctly display brightness -in case of Dimmer or Color- and color settings -in case of Color-)
sendOnOnlyWhenOff: This addresses the different behaviour of lights as discussed in issue #57 and when enabled uses @weakfl 's proposed fix
Default: "false"
Allowed values: "true" & "false"don't forget the quotes
Fan
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 or Dimmer within openHAB (HomeKit will correctly display fan speed control -in case of Number or Dimmer-)
Security System
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 as Home in the Home.app
AwayArm: The home is unoccupied, shown as Away in the Home.app
NightArm: The home is occupied and the residents are sleeping, shown as Night in the Home.app
Disarmed: The security system is disabled, shown as Off in the Home.app
AlarmTriggered: The security alarm is triggered
Thermostat
This service describes a thermostat.
Important notes on Thermostat Capabilities
A thermostat can have the capability to cool, heat or do both
The modeItem will precede heatingItem or coolingItem (when modeItem is defined, heatingItem and coolingItem will be ignored)
If modeItem is present while modeItemCharacteristic is present the allowed values for modeItem will be restricted based on modeItemCharacteristic (see below)
If modeItem is not present, one of the following is required: heatingItem or coolingItem
Based on those, the capability to heat or cool will be derived
If both are present, coolingItem will be ignored, therefore the item will only be able to either cool or heat
currentTempItem: The openHAB item representing the current temperature as measured by the thermostat
Needs to be of type Number, Rollershutter, or Dimmer within openHAB
(Note: When using Dimmer or Rollershutter type and OpenHAB receives a non numeric command like ON, OFF, INCREASE, DECREASE, UP or DOWN 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, or Dimmer within openHAB
(Note: When using Dimmer or Rollershutter type and OpenHAB receives a non numeric command like ON, OFF, INCREASE, DECREASE, UP or DOWN 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, or Dimmer within openHAB
(Note: When using Dimmer or Rollershutter type and OpenHAB receives a non numeric command like ON, OFF, INCREASE, DECREASE, UP or DOWN 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, or Dimmer within openHAB
(Note: When using Dimmer or Rollershutter type and OpenHAB receives a non numeric command like ON, OFF, INCREASE, DECREASE, UP or DOWN 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, see Important Notes above): The openHAB item showing, if the room is currently being heated
Needs to be of type Switch within openHAB
coolingItem(optional, see Important Notes above): The openHAB item showing, if the room is currently being cooled
Needs to be of type Switch within openHAB
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
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, or Dimmer within openHAB
(Note: When using Dimmer or Rollershutter type and OpenHAB receives a non numeric command like ON, OFF, INCREASE, DECREASE, UP or DOWN 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, or Dimmer within openHAB
(Note: When using Dimmer or Rollershutter type and OpenHAB receives a non numeric command like ON, OFF, INCREASE, DECREASE, UP or DOWN 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 from heatingItem and coolingItem.
Needs to be of type Number within openHAB
Only discrete values are recognized:
0 ≙ Off
1 ≙ Heating
2 ≙ Cooling
3 ≙ Auto
modeItemCapability(optional): If you are using modeItem the discrete values accepted and shown in the app can be restricted:
Allowed values: Heating (will restrict modeItem to 0, 1, 3), Cooling (will restrict modeItem to 0, 2, 3) or HeatingCooling (will not restrict modeItem)
Default HeatingCooling
minTemp(optional): If you need to change the minimum allowed temperature, the currentTempItem is reading
Needs to be an float
Default: -100
maxTemp(optional): If you need to change the maximum allowed temperature, the currentTempItem is reading
Needs to be a float
Default: 200
minTempStep(optional): If you need to change the granularity of the currentTempItem reading/writing (Note: Home.app seem to not allow a greater granularity than 0.5 in the UI, however the reported values might be more granular)
Needs to be a float
Default: 0.1
Humidifier/Dehumidifier
This service describes a humidifier and/or dehumidifier accessory.
currentHumidityItem: The openHAB item representing the current humidity
Needs to be of type Number, Rollershutter, or Dimmer within openHAB
(Note: When using Dimmer or Rollershutter type and OpenHAB receives a non numeric command like ON, OFF, INCREASE, DECREASE, UP or DOWN 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)
item: The openHAB item showing, if the (de-)humidfier is currently active
Needs to be of type Switch or Contact within openHAB
inverted(optional): If activeItem's state needs to be interpreted inverted, set this value to "true"
Default: "false"
Allowed values: "true" & "false"don't forget the quotes
humidifierItem(optional, if dehumidifierItem is present, otherwise required): The openHAB item showing, if the room is currently humidified
Needs to be of type Switch or Contact within openHAB
dehumidifierItem(optional, if humidifierItem is present, otherwise required): The openHAB item showing, if the room is currently dehumidified
Needs to be of type Switch or Contact within openHAB
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 from humidifierItem and dehumidifierItem 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
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, or Dimmer within openHAB
(Note: When using Dimmer or Rollershutter type and OpenHAB receives a non numeric command like ON, OFF, INCREASE, DECREASE, UP or DOWN 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, or Dimmer within openHAB
(Note: When using Dimmer or Rollershutter type and OpenHAB receives a non numeric command like ON, OFF, INCREASE, DECREASE, UP or DOWN 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, or Dimmer within openHAB
(Note: When using Dimmer or Rollershutter type and OpenHAB receives a non numeric command like ON, OFF, INCREASE, DECREASE, UP or DOWN 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 within openHAB
swingItemInverted(optional): If swingItem's state needs to be interpreted inverted, set this value to "true"
Default: "false"
Allowed values: "true" & "false"don't forget the quotes
rotationSpeedItem: (optional) The openHAB item representing the rotation speed
Needs to be of type Number, Rollershutter, or Dimmer within openHAB
(Note: When using Dimmer or Rollershutter type and OpenHAB receives a non numeric command like ON, OFF, INCREASE, DECREASE, UP or DOWN 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)
minFanSpeed(optional): If you need to change the minimum allowed fan speed, the rotationSpeedItem is reading in percent
Needs to be an float
Default: 0
maxFanSpeed(optional): If you need to change the maximum allowed fan speed, the rotationSpeedItem is reading in percent
Needs to be a float
Default: 100
minTempStep(optional): If you need to change the granularity of the rotationSpeedItem reading/writing (Note: Home.app seem to not allow a greater granularity than 0.5 in the UI, however the reported values might be more granular)
Needs to be a float
Default: 1
Heater/Cooler
This service describes a heater and/or cooler accessory.
Important notes on Heater/Cooler
The Heater/Cooler implementation within HomeKit clashes with OpenHAB. The Heater/Cooler is usable but there might be bugs around the mode. If the swing item and rotation speed item are not required, it is recommended to use the Thermostat Service!
客服电话
APP下载
官方微信
请发表评论