No description, website, or topics provided.
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src
test
.gitignore
README.md
package-lock.json
package.json

README.md

homebridge-http-entry

A homebridge accessory to make HTTP calls to garage doors and gates.

Open, close, and get the state of your entry.

Features

  • Configurable endpoints for getting/setting entry state
  • Support for any type of HTTP method (default: GET)
  • Support for HTTP basic auth
  • Configurable mapping of endpoint response body to HomeKit garage door states
  • Supports pulling data from device (polling) or pushing from devices (webhooks)

Install

  • Requires homebridge (npm install -g homebridge).
  • Requires Node >= 8.11
npm install -g homebridge-http-entry

Usage

Update your homebridge configuration file with a new block under accessories.

Property | Type | Default | Description ---------|------|------ accessory | string | | (Required) HttpEntry name | string | | (Required) The name of your accessory. enableDebugLog | bool | false | Enable extra debug logging. auth.username | string | | HTTP auth username auth.password | string | | HTTP auth password webhooks.accessoryId | string | | A unique id for notification server urls webhooks.password | string | | An optional password for notification server requests pollInterval | number | | Interval to poll in milliseconds. Ignored if used with webhooks.accessoryId endpoints | object | | Supports getState, open, close. See Endpoint Configuration for details mappers | object | | Supports static, regex, and xpath. See Mappers for usage.

Example config (minimal)

{
  "accessory": "HttpEntry",
  "name": "Garage Bay 1",
  "endpoints": {
    "getState": {
      "method": "GET",
      "url": "http://bay1.local/state",
    },
    "open": {
      "method": "PUT",
      "url": "http://bay1.local/state",
      "body": "OPEN"
    },
    "close": {
      "method": "PUT",
      "url": "http://bay1.local/state",
      "body": "CLOSED"
    }
  }
}

Endpoint Configuration

Endpoint configuration is passed directly to request. Minimally url makes this useful, but you may also craft requests with PUT or POST methods.

Example:

{
  "url": "http://bay1.local/state",
  "method": "PUT",
  "body": "OPEN",
}

You may define any of the following endpoints:

  • getState
  • open
  • close

Advanced

Mappers

Mappers may be applied to the endpoint response to transform it into the numeric states expected by HomeKit. The GarageDoorOpener service expects one of the following states:

Value State
0 open
1 closed
2 opening
3 closing
4 stopped

Mappers are applied in order, with the result of the previous passed to the next. Use the mappers property to configurare mappers for your accessory.

Static

Map one value to another

Example configuration:

{
  "type": "static",
  "parameters": {
    "mapping": {
      "OPENING": 2,
      "CLOSING": 3
    }
  }
}

Example response:

OPENING

Output:

2

Regex

Capture output a regular expression

Example configuration:

{
  "type": "regex",
  "parameters": {
    "regexp": "^The door is currently (OPEN|CLOSED), yo!$",
    "captureGroup": 1
  }
}

Example response

The door is currently OPEN, yo!

Output:

OPEN

XPath

Capture output XML using XPath expressions

{
  "type": "xpath",
  "parameters": {
    "xpath": "//dd/text()",
    "index": 0
  }
}

Example response:

<main>
  <h1>Door</h1>
  <dl>
    <dt>State</dt>
    <dd>OPENING</dd>
  </dl>
</main>

Output:

OPENING

Webhooks

This accessory supports receiving updates via webhooks using homebridge-http-notification-server as a more efficient alternative to polling. Use the webhooks configuration to receive state updates from your accessory.

  1. Install and configure homebridge-http-notification-server.
  2. Add webhooks configuration to this accessory.
  3. Configure your sender

Example webhooks config:

{
  "webhooks": {
    "accessoryId": "bay1"
  }
}

Example sender configuration:

{
  "characteristic": "TargetDoorState",
  "value": 1
}

value should reflect the current door state (0-4).

License

ISC