1.1.2 • Published 2 years ago

homebridge-http-entry v1.1.2

Weekly downloads
-
License
ISC
Repository
github
Last release
2 years ago

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.

PropertyTypeDefaultDescription
accessorystring(Required) HttpEntry
namestring(Required) The name of your accessory.
enableDebugLogboolfalseEnable extra debug logging.
auth.usernamestringHTTP auth username
auth.passwordstringHTTP auth password
webhooks.accessoryIdstringA unique id for notification server urls
webhooks.passwordstringAn optional password for notification server requests
pollIntervalnumberInterval to poll in milliseconds. Ignored if used with webhooks.accessoryId
endpointsobjectSupports getState, open, close. See Endpoint Configuration for details
mappersobjectSupports 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:

ValueState
0open
1closed
2opening
3closing
4stopped

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

1.1.1

2 years ago

1.1.0

2 years ago

1.1.2

2 years ago

1.0.2

6 years ago

1.0.1

6 years ago

1.0.0

6 years ago