Home

Awesome

homekit2mqtt

mqtt-smarthome NPM version dependencies Status Build Status Coverage Status XO code style License

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.

Warning: Version 0.9.4 possibly introduces a breaking change. Due to the issue #89 service subtypes where added, please give your Home app a few minutes to get updates, if the accessories don't work at all anymore after an update from <=0.9.3 to >=0.9.4 you have to delete the persistence files and delete and re-add the bridge in iOS...:-(

Installation

Requirements

sudo npm install -g homekit2mqtt --unsafe-perm

I suggest to use pm2 to manage the homekit2mqtt process (start on system boot, manage log files, ...)

Command Line Options

<pre> 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: "./example-homekit2mqtt.json"] -n, --name instance name. used as prefix for connected topic [default: "homekit"] -u, --url mqtt broker url. [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 --disable-json-parse disable json parsing of received mqtt payloads [boolean] --insecure allow tls connections with invalid certificates[boolean] --retain if set, ALL MQTT messages sent will have the retain flag set [boolean] -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"] </pre>

Persisted Data

I strongly advice you to set the --storagedir and --mapfile option to a directory outside of the homekit2mqtt folder, otherwise an update of homekit2mqtt could overwrite your config.

MQTT Authentication and TLS

You can put credentials for authentication in the url supplied to the --url option: mqtt://user:password@broker. If you want to use TLS for the connection to the broker use mqtts:// as URL scheme, e.g. mqtts://broker:8883.

MQTT Payload parsing

By default homekit2mqtt parses incoming JSON payloads and tries to use the attribute val (following mqtt-smarthome payload convention). For a future release it is planned that this attribute will be configurable (see https://github.com/hobbyquaker/homekit2mqtt/issues/67).

If you set the --disable-json-parse option there will be no JSON parsing at all and homekit2mqtt just hands the incoming JSON through as string.

Plain (non-JSON) payloads containing the strings true or false are casted to boolean. Strings containing numbers are casted to numbers with parseFloat().

Configuration

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).

Web UI Web UI

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
    "name": "TemperatureSensor LivingRoom",                 // Accessory name
    "services": [
        {
            "service": "TemperatureSensor",                 // HomeKit service type (see available service types below)
            "name": "Temperature LivingRoom",               // Service name
            "topic": {                                              
                // ... MQTT topic configuration ...
            },
            "payload": {
                // ... MQTT payload configuration ...
            },
            "props": {
                // ... Optional Characteristic properties
            },
            "config": {
                // ... Optional Service configuration
            }       
        },
        // ... more services
    ],
    "manufacturer": "DIY Home Brew",                        // Additional accessory infos (optional)
    "model": "TemperatureSensor"                            // Additional accessory infos (optional)
  }

Available Service Types

AirPurifier

topic

payload

AirQualitySensor

topic

payload

BatteryService

topic

payload

CameraRTSPStreamManagement

topic

payload

config

CarbonDioxideSensor

topic

payload

CarbonMonoxideSensor

topic

payload

ContactSensor

topic

payload

Door

topic

payload

Doorbell

topic

payload

Fan

topic

payload

Fanv2

topic

payload

Faucet

topic

payload

FilterMaintenance

topic

payload

GarageDoorOpener

topic

payload

HeaterCooler

topic

payload

config

HumidifierDehumidifier

topic

payload

HumiditySensor

topic

payload

IrrigationSystem

topic

payload

LeakSensor

topic

payload

Lightbulb

topic

payload

LightSensor

topic

payload

LockManagement

topic

payload

LockMechanism

topic

payload

Microphone

topic

payload

MotionSensor

topic

payload

OccupancySensor

topic

payload

Outlet

topic

payload

SecuritySystem

topic

payload

Slat

topic

payload

config

SmokeSensor

topic

payload

Speaker

topic

payload

StatelessProgrammableSwitch

topic

payload

Switch

topic

payload

TemperatureSensor

topic

payload

Thermostat

topic

payload

config

Valve

topic

payload

config

Window

topic

payload

WindowCovering

topic

payload

License

MIT © Sebastian Raff and homekit2mqtt contributors