{"id":29271208,"url":"https://github.com/homebridge-plugins/homebridge-http-curtain","last_synced_at":"2025-07-04T23:08:06.503Z","repository":{"id":38174876,"uuid":"259300160","full_name":"homebridge-plugins/homebridge-http-curtain","owner":"homebridge-plugins","description":"Homebridge plugin to operate web based/http curtains with push position updates.","archived":false,"fork":false,"pushed_at":"2022-12-11T05:59:16.000Z","size":598,"stargazers_count":2,"open_issues_count":9,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-02T08:12:29.572Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/homebridge-plugins.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-04-27T11:57:05.000Z","updated_at":"2025-06-12T19:03:50.000Z","dependencies_parsed_at":"2023-01-26T16:46:15.224Z","dependency_job_id":null,"html_url":"https://github.com/homebridge-plugins/homebridge-http-curtain","commit_stats":null,"previous_names":["homebridge-plugins/homebridge-http-curtain","quicksander/homebridge-http-curtain"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/homebridge-plugins/homebridge-http-curtain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homebridge-plugins%2Fhomebridge-http-curtain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homebridge-plugins%2Fhomebridge-http-curtain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homebridge-plugins%2Fhomebridge-http-curtain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homebridge-plugins%2Fhomebridge-http-curtain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/homebridge-plugins","download_url":"https://codeload.github.com/homebridge-plugins/homebridge-http-curtain/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/homebridge-plugins%2Fhomebridge-http-curtain/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263632058,"owners_count":23491530,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-04T23:08:04.393Z","updated_at":"2025-07-04T23:08:06.492Z","avatar_url":"https://github.com/homebridge-plugins.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.com/QuickSander/homebridge-http-curtain.svg?branch=master)](https://travis-ci.com/QuickSander/homebridge-http-curtain)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)\n[![npm version](https://badge.fury.io/js/homebridge-http-curtain.svg)](https://badge.fury.io/js/homebridge-http-curtain)\n[![verified-by-homebridge](https://badgen.net/badge/homebridge/verified/purple)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins)\n\n# homebridge-http-curtain\n\nThis [Homebridge](https://github.com/nfarina/homebridge) plugin can be used to integrate your curtain which has an HTTP api into HomeKit. This controller supports push notification _without_ the need for HomeBridge to periodically pull the curtain position value. There are a few other HTTP based curtain / window blinds\nplugins available, but I have not found any yet that does not poll the curtain controller continuously for position or state updates.\n\n_This is a fork of Supereg's [homebridge-http-temperature-sensor](https://github.com/Supereg/homebridge-http-temperature-sensor) modified to function as an curtain controller._\n\nFeatures:\n* Set target position (0-100).\n* Position change updates: push (efficient / less network and Homebridge load) or pull (easy to configure).\n* Retrieve current position.\n* Send identify request (via Eve Home app) to locate your curtain.\n\n## Installation\n\nFirst of all you need to have [Homebridge](https://github.com/nfarina/homebridge) installed. Refer to the repo for\ninstructions.  \nThen run the following command to install `homebridge-http-curtain`\n\n```\nsudo npm install -g homebridge-http-curtain\n```\n\n## Updating the curtain position in HomeKit\n\nThe _'CurrentPosition'_ characteristic from the _'WindowCovering'_ service has the permission to `notify` the\nHomeKit controller of state changes.\n`homebridge-http-curtain` supports two ways to send window blinds/curtain position changes to HomeKit.\n\n#### The 'pull' way:\n\nThe 'pull' way is probably the easiest to set up and supported in every scenario. `homebridge-http-curtain`\nrequests the value of the curtain/window blind in an specified interval (pulling) and sends the value to HomeKit.  \nLook for `pullInterval` in the list of configuration options if you want to configure it.\n\n#### The 'push' way:\n\nWhen using the 'push' concept the HTTP device itself sends the updated value itself to `homebridge-http-curtain`\nwhenever the value changes. This is more efficient as the new value is updated instantly and\n`homebridge-http-curtain` does not need to make needless requests when the value didn't actually change.\nHowever because the http device needs to actively notify the `homebridge-http-curtain` plugin there is more\nwork needed to implement this method into your http device.  \nHow to implement the protocol into your http device can be read in the chapter [**Notification Server**](#notification-server)\n\n## Configuration\n\nThe configuration can contain the following properties:\n* `name` \\\u003cstring\\\u003e **required**: Defines the name which is later displayed in HomeKit\n* `getCurrentPosUrl` \\\u003cstring | [urlObject](#urlobject)\\\u003e **required**: Defines the url\n(and other properties when using an urlObject) to query the current position from the curtain.\nIt expects the http server to return a integer ranging from 0-100 (step 1) leaving out any html markup when no `getCurrentPosRegEx`\nis provided.\n* `getCurrentPosRegEx` \\\u003cstring\\\u003e **optional**: A regular expression from which the first matched group determines the current position.\n* `getPositionStateUrl` \\\u003cstring | [urlObject](#urlobject)\\\u003e **optional**: Defines the url\n(and other properties when using an urlObject) to query the current state from the curtain.\nIt expects the http server to return a integer '0' (Closing), '1' (Opening) or '2' (Idle) leaving out any html markup.\nNote that Homekit ignores this state as it rather compares _CurrentPosition_ with _TargetPosition_.\n* `setTargetPosUrl` \\\u003cstring | [urlObject](#urlobject)\\\u003e **required**: Defines the url\n(and other properties when using an urlObject) to set the target position at the curtain.\nAny `%d` format specifier will be replaced by the requested target position.\n* `getTargetPosUrl` \\\u003cstring | [urlObject](#urlobject)\\\u003e **optional**: Defines the url\n(and other properties when using an urlObject) to retrieve the target position at the curtain.\n* `getTargetPosRegEx` \\\u003cstring\\\u003e **optional**: A regular expression from which the first matched group determines the target position.\n* `identifyUrl` \\\u003cstring | [urlObject](#urlobject)\\\u003e **optional**: URL to call when the HomeKit identify action is requested.\n* `pullInterval` \\\u003cinteger\\\u003e **optional**: The property expects an interval in **milliseconds** in which the plugin\npulls updates from your http device. For more information read [pulling updates](#the-pull-way). \n* `invertPosition` \\\u003cboolean\\\u003e **optional**: True: interpret 0% as fully open and 100% as fully closed.\n\nBelow is an example configuration. One URL is using a simple string URL and the other is using an urlObject.  \nBoth configs can be used for a basic plugin configuration.\n```json\n{\n    \"accessories\": [\n        {\n          \"accessory\": \"HttpCurtain\",\n          \"name\": \"Living Room Left Curtain\",\n\n          \"getCurrentPosUrl\": \"http://livingroom-curtain-left/api/v1/pos\",\n          \"setTargetPosUrl\": {\n            \"url\": \"http://livingroom-curtain-left/api/v1/pos/%d\",\n            \"method\": \"PUT\"\n          }\n        }   \n    ]\n}\n```\n\n\n\n\n#### UrlObject\n\nA urlObject can have the following properties:\n* `url` \\\u003cstring\\\u003e **required**: Defines the url pointing to your http server\n* `method` \\\u003cstring\\\u003e **optional** \\(Default: **\"GET\"**\\): Defines the http method used to make the http request\n* `body` \\\u003cstring\\\u003e **optional**: Defines the body sent with the http request\n* `auth` \\\u003cobject\\\u003e **optional**: If your http server uses basic authentication you can specify your credential in this\nobject. When defined the object must contain the following properties:\n    * `username` \\\u003cstring\\\u003e\n    * `password` \\\u003cstring\\\u003e\n* `headers` \\\u003cobject\\\u003e **optional**: Using this object you can define any http headers which are sent with the http\nrequest. The object must contain only string key value pairs.  \n\nBelow is an example of an urlObject containing all properties:\n```json\n{\n  \"url\": \"http://example.com:8080\",\n  \"method\": \"GET\",\n  \"body\": \"exampleBody\",\n\n  \"auth\": {\n    \"username\": \"yourUsername\",\n    \"password\": \"yourPassword\"\n  },\n\n  \"headers\": {\n    \"Content-Type\": \"text/html\"\n  }\n}\n```\n\n## Notification Server\n\n`homebridge-http-curtain` can be used together with\n[homebridge-http-notification-server](https://github.com/Supereg/homebridge-http-notification-server) in order to receive\nupdates when the state changes at your home automation device. For details on how to implement those updates and how to\ninstall and configure `homebridge-http-notification-server`, please refer to the\n[README](https://github.com/Supereg/homebridge-http-notification-server) of that repository.\n\nDown here is an example on how to configure `homebridge-http-curtain` to work with your implementation of the\n`homebridge-http-notification-server`.\n\n```json\n{\n    \"accessories\": [\n        {\n          \"accessory\": \"HttpCurtain\",\n          \"name\": \"Living Room Curtain\",\n\n          \"notificationID\": \"my-curtain\",\n          \"notificationPassword\": \"SuperSecretPassword\",\n\n          \"getUrl\": \"http://localhost/api/pos\"\n        }   \n    ]\n}\n```\n\n* `notificationID` is an per Homebridge instance unique id which must be included in any http request.  \n* `notificationPassword` is **optional**. It can be used to secure any incoming requests.\n\nTo get more details about the configuration have a look at the\n[README](https://github.com/Supereg/homebridge-http-notification-server).\n\n**Available characteristics (for the POST body)**\n\nDown here are all characteristics listed which can be updated with an request to the `homebridge-http-notification-server`\n\n* `characteristic` \"CurrentPosition\": expects an integer `value` in a range of 0 up to and including 100.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhomebridge-plugins%2Fhomebridge-http-curtain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhomebridge-plugins%2Fhomebridge-http-curtain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhomebridge-plugins%2Fhomebridge-http-curtain/lists"}