search

washcroft / homebridge-http-garagedoorcontroller

An HTTP based Garage Door/Light plugin for HomeBridge
MIT License
15 stars 7 forks source link

readme

homebridge-http-garagedoorcontroller (v2)

An HTTP based Garage Door/Light plugin for HomeBridge

Demo

About

This HomeBridge (Apple HomeKit) plugin exposes a garage door accessory and optional garage light, allowing control of your garage door and/or garage light via standard HTTP requests, from within the Apple ecosystem. Since security is important here, both API Key header and OAuth 1.0a signing/authentication is supported.

I added an Arduino based WiFi-enabled controller onto my existing garage door operator, the Arduino ran an HTTP server on the network listening for these HTTP requests from HomeBridge.

The Arduino controller toggles GPIO outputs to operate the garage door (using either two separate open/close relays, or more commonly cycling the same one) and also a third output to control the garage light (another relay).

The Arduino controller also uses GPIO inputs to report the state of the garage door (two inputs from separate open/closed reed switches) and also a third input to allow the garage light to be controlled via another source (i.e. the garage door operator itself).

Arduino Project

My Arduino project which accompanies this HomeBridge plugin can be found at HttpGarageDoorController, however this plugin can work for other implementations too.

Configuration

HomeBridge configuration sample:

  "accessories": [
    {
      "accessory": "HttpGarageDoorController",
      "name": "Garage Door",
      "lightName": "Garage Light",

      "doorOperationSeconds": 0,

      "httpHost": "garagedoorcontroller.local",
      "httpPort": 80,
      "httpSsl": false,
      "httpStatusPollMilliseconds": 4000,
      "httpRequestTimeoutMilliseconds": 10000,

      "httpHeaderName": "X-API-Key",
      "httpHeaderValue": "MyAPIKey",

      "oauthAuthentication": true,
      "oauthSignatureMethod": "HMAC-SHA256",
      "oauthConsumerKey": "MyOAuthConsumerKey",
      "oauthConsumerSecret": "MyOAuthConsumerSecret",
      "oauthToken": "MyOAuthToken",
      "oauthTokenSecret": "MyOAuthTokenSecret",

      "apiConfig":
      {
        "apiType": "HttpGarageDoorController"
      }
    }
  ],

For other implementations, the apiConfig block should be completed as follows:

Json API

      "apiConfig":
      {
        "apiType": "Json",
        "doorSuccessField": "success",

        "doorOpenMethod": "PUT",
        "doorOpenUrl": "/controller/door/open",

        "doorCloseMethod": "PUT",
        "doorCloseUrl": "/controller/door/close",

        "doorStateMethod": "GET",
        "doorStateUrl": "/controller/door/status",
        "doorStateField": "door-state",

        "lightSuccessField": "success",

        "lightOnMethod": "PUT",
        "lightOnUrl": "/controller/light/on",

        "lightOffMethod": "PUT",
        "lightOffUrl": "/controller/light/off",

        "lightStateMethod": "GET",
        "lightStateUrl": "/controller/light/status",
        "lightStateField": "light-state"
      }

Generic / Plain API

      "apiConfig":
      {
        "apiType": "Generic",

        "doorOpenMethod": "GET",
        "doorOpenUrl": "/controller/door/open",
        "doorOpenSuccessContent": "OK",

        "doorCloseMethod": "GET",
        "doorCloseUrl": "/controller/door/close",
        "doorCloseSuccessContent": "OK",

        "doorStateMethod": "GET",
        "doorStateUrl":"/controller/door/status",

        "lightOnMethod": "GET",
        "lightOnUrl":"/controller/light/on",
        "lightOnSuccessContent": "OK",

        "lightOffMethod": "GET",
        "lightOffUrl":"/controller/light/off",
        "lightOffSuccessContent": "OK",

        "lightStateMethod": "GET",
        "lightStateUrl":"/controller/light/status"
      }

Fields:

HTTP Fields

OAuth Fields

API Config Fields

Door State Values: When a door state API is configured, the API should return one of the following state values only (either in the specified Json field for a Json API, or as the complete response body for a Generic / Plain API).

Light State Values: When a light state API is configured, the API should return one of the following state values only to indicate the light is on, all other values indicate the light is off (either in the specified Json field for a Json API, or as the complete response body for a Generic / Plain API).

License

MIT License

Copyright (c) 2017 Warren Ashcroft

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.