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 got. 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
• cycle

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

Developing

Testing

See https://github.com/homebridge/homebridge#plugin-development

1. yarn test
2. yarn watch
3. Configure homebridge from ~/.homebridge
4. yarn http-server and edit response from TestGateAccessory
5. Use an http client to create requests to notification server

Example:

POST http://127.0.0.1:8081
{
    "characteristic": "CurrentDoorState",
    "value": "1",
    "accessory": "gate"
}

License

ISC