HomeKit to MQTT bridge 🏡📱
Depends on HAP-NodeJS by KhaosT, all credits belong to him.
This project follows the mqtt-smarthome architecture. I'm using this to control a multitude of MQTT-connected "Things" in my home automation through Siri and with HomeKit apps.
Prerequisites:
- Debian, Ubuntu, Raspbian or macOS
- Node.js 6 or higher
- If you're running on Linux, you'll need to make sure you have the libavahi-compat-libdnssd-dev package installed:
sudo apt-get install libavahi-compat-libdnssd-dev
sudo npm install -g homekit2mqtt --unsafe-perm
Usage: homekit2mqtt [options] Options: -v, --verbosity possible values: "error", "warn", "info", "debug" [default: "info"] -m, --mapfile JSON file containing HomeKit Services to MQTT mapping definitions. See Readme. [default: "/Users/basti/WebstormProjects/homekit2mqtt/example-homekit2mqtt.json"] -n, --name instance name. used as mqtt client id and as prefix for connected topic [default: "homekit"] -u, --url mqtt broker url. See https://github.com/mqttjs/MQTT.js/wiki/mqtt [default: "mqtt://127.0.0.1"] -s, --storagedir directory to store homekit data -p, --port port homekit2mqtt is listening on [default: 51826] -w, --web-port port webserver is listening on [default: 51888] -x, --disable-web disable webserver -h, --help Show help [boolean] --version Show version number [boolean] -c, --pincode [default: "031-45-154"] -a, --username [default: "CC:22:3D:E3:CE:F6"] -b, --bridgename [default: "MQTT Bridge"]
homekit2mqtt needs a JSON file that defines devices and mappings from MQTT-topics and payloads to
HomeKit-characteristics. You can either create this manually or use the Web UI to configure homekit2mqtt. The Webserver
listens on Port 51888 by default, authentication username is homekit
and the password is the pincode (031-45-154
by
default).
See example-homekit2mqtt.json for an example configuration. Every Accessory is represented like this in the JSON file:
"TemperatureSensor": { // Unique Name - used to generate the accessory UUID
"service": "TemperatureSensor", // HomeKit Service Type (see below)
"name": "TemperatureSensor", // Display Name
"topic": {
// ... MQTT Topic Configuration ...
},
"payload": {
// ... MQTT Payload Configuration ...
},
"manufacturer": "Generic", // Additional Accessory Infos (optional)
"model": "TemperatureSensor" // Additional Accessory Infos (optional)
}
topic
- statusCarbonDioxideDetected
- statusLowBattery (optional)
- identify (optional)
payload
- onCarbonDioxideDetected
- onLowBattery (optional)
- identify (optional)
topic
- statusCarbonMonoxideDetected
- statusLowBattery (optional)
- identify (optional)
payload
- onCarbonMonoxideDetected
- onLowBattery (optional)
- identify (optional)
topic
- statusContactSensorState
- statusLowBattery (optional)
- identify (optional)
payload
- onContactDetected
- onLowBattery (optional)
- identify (optional)
topic
- setTargetPosition
- statusTargetPosition (optional)
- statusCurrentPosition (optional)
- statusPositionState (optional)
- statusObstruction (optional)
- identify (optional)
payload
- targetPositionFactor (optional)
- currentPositionFactor (optional)
- positionStatusDecreasing (optional)
- positionStatusIncreasing (optional)
- onObstructionDetected (optional)
- identify (optional)
topic
- statusEvent
- identify (optional)
payload
- identify (optional)
topic
- setOn
- statusOn (optional)
- setRotationDirection (optional)
- statusRotationDirection (optional)
- setRotationSpeed (optional)
- statusRotationSpeed (optional)
- identify (optional)
payload
- onTrue (optional, default:
true
) - onFalse (optional)
- rotationDirectionCounterClockwise (optional, default:
1
) - rotationDirectionClockwise (optional)
- rotationSpeedFactor (optional, default:
1
) - identify (optional)
topic
- setDoor
- statusDoor (optional)
- statusObstruction (optional)
- setLock (optional)
- statusLock (optional)
- identify (optional)
payload
- doorOpen
- doorClosed
- doorOpening (optional)
- doorClosing (optional)
- doorStopped (optional)
- onObstructionDetected (optional)
- lockUnsecured (optional)
- lockSecured (optional)
- identify (optional)
topic
- statusHumidity
- statusLowBattery (optional)
- identify (optional)
payload
- onLowBattery (optional)
- identify (optional)
topic
- statusLeakDetected
- statusLowBattery (optional)
- identify (optional)
payload
- onLeakDetected
- onLowBattery (optional)
- identify (optional)
topic
- setOn
- statusOn (optional)
- setBrightness (optional)
- statusBrightness (optional)
- setHue (optional)
- statusHue (optional)
- setSaturation (optional)
- statusSaturation (optional)
- setColorTemperature (optional)
- statusColorTemperature (optional)
- identify (optional)
payload
- onTrue
- onFalse
- brightnessFactor (optional, default:
1
) - hueFactor (optional, default:
1
) - saturationFactor (optional, default:
1
) - identify (optional)
topic
- statusAmbientLightLevel
- statusLowBattery (optional)
- identify (optional)
payload
- ambientLightLevelFactor (optional, default:
1
) - onLowBattery (optional)
- identify (optional)
topic
- setLock
- statusLock (optional)
- identify (optional)
payload
- lockSecured
- identify (optional)
topic
- setMute
- statusMute (optional)
- setVolume (optional)
- statusVolume (optional)
- identify (optional)
payload
- muteTrue
- muteFalse
- volumeFactor (optional, default:
1
) - identify (optional)
topic
- statusMotionDetected
- statusLowBattery (optional)
- identify (optional)
payload
- onMotionDetected
- onLowBattery (optional)
- identify (optional)
topic
- statusOccupancyDetected
- statusLowBattery (optional)
- identify (optional)
payload
- onOccupancyDetected
- onLowBattery (optional)
- identify (optional)
topic
- setOn
- statusOn (optional)
- statusOutletInUse
- identify (optional)
payload
- onFalse
- onTrue
- onOutletInUse
- identify (optional)
topic
- setSecuritySystemTargetState
- statusSecuritySystemCurrentState (optional)
- identify (optional)
payload
- identify (optional)
topic
- statusSmokeDetected
- statusLowBattery (optional)
- identify (optional)
payload
- onSmokeDetected
- onLowBattery (optional)
- identify (optional)
topic
- setMute
- statusMute (optional)
- setVolume (optional)
- statusVolume (optional)
- identify (optional)
payload
- muteTrue
- muteFalse
- volumeFactor, default:
1
) - identify (optional)
topic
- statusEvent
- identify (optional)
payload
- identify (optional)
topic
- setOn
- statusOn (optional)
- identify (optional)
payload
- onFalse
- onTrue
- identify (optional)
topic
- statusTemperature
- statusLowBattery (optional)
- identify (optional)
payload
- fahrenheit
Set to true if your sensor publishes values in degree fahrenheit - onLowBattery (optional)
- identify (optional)
topic
- setTargetTemperature
- statusTargetTemperature (optional)
- statusCurrentTemperature
- setTargetHeatingCoolingState (optional)
0 = off, 1 = heat, 2 = cool - statusTargetHeatingCoolingState (optional)
0 = off, 1 = heat, 2 = cool - statusCurrentHeatingCoolingState (optional)
0 = off, 1 = heat, 2 = cool - setTargetRelativeHumidity (optional)
- statusTargetRelativeHumidity (optional)
- statusCurrentRelativeHumidity (optional)
- setCoolingThresholdTemperature (optional)
- statusCoolingThresholdTemperature (optional)
- setHeatingThresholdTemperature (optional)
- statusHeatingThresholdTemperature (optional)
- identify (optional)
payload
- identify (optional)
topic
- setTargetPosition
- statusTargetPosition (optional)
- statusCurrentPosition (optional)
- statusPositionState (optional)
- statusObstruction (optional)
- identify (optional)
payload
- targetPositionFactor (optional, default:
1
) - currentPositionFactor (optional, default:
1
) - positionStatusDecreasing (optional)
- positionStatusIncreasing (optional)
- onObstructionDetected (optional)
- identify (optional)
topic
- setTargetPosition
- statusTargetPosition (optional)
- statusCurrentPosition (optional)
- statusPositionState (optional)
- identify (optional)
payload
- targetPositionFactor (optional, default:
1
) - currentPositionFactor (optional, default:
1
) - positionStatusDecreasing (optional)
- positionStatusIncreasing (optional)
- identify (optional)
MIT © Sebastian Raff and homekit2mqtt contributors