homebridge-http-switch 正在参加 2021 年度 OSC 中国开源项目评选,请投票支持!
homebridge-http-switch 在 2021 年度 OSC 中国开源项目评选 中已获得 {{ projectVoteCount }} 票,请投票支持!
2021 年度 OSC 中国开源项目评选 正在火热进行中,快来投票支持你喜欢的开源项目!
2021 年度 OSC 中国开源项目评选 >>> 中场回顾
homebridge-http-switch 获得 2021 年度 OSC 中国开源项目评选「最佳人气项目」 !
授权协议 ISC License
开发语言 JavaScript
操作系统 跨平台
软件类型 开源软件
开源组织
地区 不详
投 递 者 首席测试
适用人群 未知
收录时间 2021-11-10

软件简介

homebridge-http-switch Plugin

npm npm GitHub Workflow Status GitHub issues GitHub pull requests

homebridge-http-switch is a Homebridge plugin with which you can configure HomeKit switches which forward any requests to a defined http server. This comes in handy when you already have home automated equipment which can be controlled via http requests. Or you have built your own equipment, for example some sort of lightning controlled with an wifi enabled Arduino board which than can be integrated via this plugin into Homebridge.

homebridge-http-switch supports three different type of switches. A normal stateful switch and two variants of stateless switches (stateless and stateless-reverse) which differ in their original position. For stateless switches you can specify multiple urls to be targeted when the switch is turned On/Off.
More about on how to configure such switches can be read further down.

Installation

First of all you need to have Homebridge installed. Refer to the repo for instructions.
Then run the following command to install homebridge-http-switch

sudo npm install -g homebridge-http-switch

Updating the switch state in HomeKit

The 'On' characteristic from the 'switch' service has the permission to notify the HomeKit controller of state changes. homebridge-http-switch supports two ways to send state changes to HomeKit.

The 'pull' way:

The 'pull' way is probably the easiest to set up and supported in every scenario. homebridge-http-switch requests the state of the switch in an specified interval (pulling) and sends the value to HomeKit.
Look for pullInterval in the list of configuration options if you want to configure it.

The 'push' way:

When using the 'push' concept, the http device itself sends the updated value to homebridge-http-switch whenever the value changes. This is more efficient as the new value is updated instantly and homebridge-http-switch does not need to make needless requests when the value didn't actually change.
However because the http device needs to actively notify the homebridge-http-switch there is more work needed to implement this method into your http device.

Using MQTT:

MQTT (Message Queuing Telemetry Transport) is a protocol widely used by IoT devices. IoT devices can publish messages on a certain topic to the MQTT broker which then sends this message to all clients subscribed to the specified topic. In order to use MQTT you need to setup a broker server (mosquitto is a solid open source MQTT broker running perfectly on a device like the Raspberry Pi) and then instruct all clients to publish/subscribe to it.
For shelly.cloud devices mqtt is the best and only option to implement push-updates.

Using 'homebridge-http-notification-server':

For those of you who are developing the http device by themselves I developed a pretty simple 'protocol' based on http to send push-updates.
How to implement the protocol into your http device can be read in the chapter Notification Server

Configuration:

The configuration can contain the following properties:

Basic configuration options:

  • name <string> required: Defines the name which is later displayed in HomeKit
  • switchType <string> optional (Default: "stateful"): Defines the type of the switch:
    • "stateful": A normal switch and thus the default value.
    • "stateless": A stateless switch remains in only one state. If you switch it to on, it immediately goes back to off. Configuration example is further down.
    • "stateless-reverse": Default position is ON. If you switch it to off, it immediately goes back to on. Configuration example is further down.
    • "toggle": The toggle switch is a stateful switch however does not use the statusUrl to determine the current state. It uses the last set state as the current state. Default position is OFF.
    • "toggle-reverse"": Same as "toggle" but switch default position is ON.
  • onUrl <string | [string] | urlObject | [urlObject]> required: Defines the url (and other properties when using an urlObject) which is called when you turn on the switch.
  • offUrl <string | [string] | urlObject | [urlObject]> required: Defines the url (and other properties when using an urlObject) which is called when you turn off the switch.
  • statusUrl <string | urlObject> required: Defines the url (and other properties when using an urlObject) to query the current state from the switch. By default it expects the http server to return '1' for ON and '0' for OFF leaving out any html markup.
    You can change this using statusPattern option.

Advanced configuration options:

  • serialNumber <string> optional (Default: "SW01"): Defines a custom serial number shown in the home app.
  • statusPattern <string> optional (Default: "1"): Defines a regex pattern which is compared to the body of the statusUrl. When matching the status of the switch is set to ON otherwise OFF. Some examples.
  • statusCache <number> optional (Default: 0): Defines the amount of time in milliseconds a queried state of the switch is cached before a new request is made to the http device.
    Default is 0 which indicates no caching. A value of -1 will indicate infinite caching.
  • auth <object> optional: If your http server requires authentication you can specify your credential in this object. It uses those credentials for all http requests and thus overrides all possibly specified credentials inside an urlObject for onUrl, offUrl and statusUrl.
    The object can contain the following properties:
    • username <string> required
    • password <string> required
    • sendImmediately <boolean> optional (Default: true): When set to true the plugin will send the credentials immediately to the http server. This is best practice for basic authentication.
      When set to false the plugin will send the proper authentication header after receiving an 401 error code (unauthenticated). The response must include a proper WWW-Authenticate header.
      Digest authentication requires this property to be set to false!
  • httpMethod deprecated <string> optional: If defined it sets the http method for onUrl and offUrl. This property is deprecated and only present for backwards compatibility. It is recommended to use an [urlObject] to set the http method per url.
  • timeout <integer> optional (Default: 1000): When using a stateless switch this timeout in milliseconds specifies the time after which the switch is reset back to its original state.
  • pullInterval <integer> optional: The property expects an interval in milliseconds in which the plugin pulls updates from your http device. For more information read pulling updates.
    (This option is only supported when switchType is "stateful")
  • multipleUrlExecutionStrategy <string> optional (Default: "parallel"): Defines the strategy used when executing multiple urls. The following are available:
    • "parallel": All urls are executed in parallel. No particular order is guaranteed. Execution as fast as possible.
    • "series": All urls are executed in the given order. Each url must complete first before the next one is executed.
      When using series execution you can also have a look at the delay url.
  • debug <boolean> optional: If set to true debug mode is enabled and the plugin prints more detailed information.

Below are two example configurations. One is using simple string urls and the other is using simple urlObjects.
Both configs can be used for a basic plugin configuration.

{
    "accessories": [
        {
          "accessory": "HTTP-SWITCH",
          "name": "Switch",
          
          "switchType": "stateful",
          
          "onUrl": "http://localhost/api/switchOn",
          "offUrl": "http://localhost/api/switchOff",
          
          "statusUrl": "http://localhost/api/switchStatus"
        }   
    ]
}
{
    "accessories": [
        {
          "accessory": "HTTP-SWITCH",
          "name": "Switch",
          
          "switchType": "stateful",
          
          "onUrl": {
            "url": "http://localhost/api/switchOn",
            "method": "GET"
          },
          "offUrl": {
            "url": "http://localhost/api/switchOff",
            "method": "GET"
          },
          
          "statusUrl": {
            "url": "http://localhost/api/switchStatus",
            "method": "GET"
          }
        }   
    ]
}

UrlObject

A urlObject can have the following properties:

  • url <string> required: Defines the url pointing to your http server
  • method <string> optional (Default: "GET"): Defines the http method used to make the http request
  • body <any> optional: Defines the body sent with the http request. If value is not a string it will be converted to a JSON string automatically.
  • strictSSL <boolean> optional (Default: false): If enabled the SSL certificate used must be valid and the whole certificate chain must be trusted. The default is false because most people will work with self signed certificates in their homes and their devices are already authorized since being in their networks.
  • auth <object> optional: If your http server requires authentication you can specify your credential in this object. When defined the object can contain the following properties:
    • username <string> required
    • password <string> required
    • sendImmediately <boolean> optional (Default: true): When set to true the plugin will send the credentials immediately to the http server. This is best practice for basic authentication.
      When set to false the plugin will send the proper authentication header after receiving an 401 error code (unauthenticated). The response must include a proper WWW-Authenticate header.
      Digest authentication requires this property to be set to false!
  • headers <object> optional: Using this object you can define any http headers which are sent with the http request. The object must contain only string key value pairs.
  • requestTimeout <number> optional (Default: 20000): Time in milliseconds specifying timeout (Time to wait for http response and also setting socket timeout).
  • repeat <number> optional (Default: 1): Defines how often the execution of this urlObject should be repeated.
    Notice that this property only has an effect on ulrObject specified in onUrl or offUrl. Also have a look at the multipleUrlExecutionStrategy property. Using "parallel" execution could result in unpredictable behaviour.
  • delayBeforeExecution <number> optional (Default: 0): Defines the time in milliseconds to wait before executing the urlObject.
    Notice that this property only has an effect on ulrObject specified in onUrl or offUrl. Also have a look at the multipleUrlExecutionStrategy property.

Below is an example of an urlObject containing the basic properties:

{
  "url": "http://example.com:8080",
  "method": "GET",
  "body": "exampleBody",
  
  "strictSSL": false,
  
  "auth": {
    "username": "yourUsername",
    "password": "yourPassword"
  },
  
  "headers": {
    "Content-Type": "text/html"
  }
}

MQTTObject

A mqttObject can have the following properties:

Basic configuration options:
  • host <string> required: Defines the host of the mqtt broker.
  • port <number> optional (Default: 1883): Defines the port of the mqtt broker.
  • credentials <object> optional: Defines the credentials used to authenticate with the mqtt broker.
    • username <string> required
    • password <string> optional
  • subscriptions <object | array> required: Defines an array (or one single object) of subscriptions.
    • topic <string> required: Defines the topic to subscribe to.
    • characteristic <string> required: Defines the characteristic this subscription updates.
    • messagePattern <string> optional: Defines a regex pattern. If messagePattern is not specified the message received will be used as value. If the characteristic expects a boolean value it is tested if the specified regex is contained in the received message. Otherwise the pattern is matched against the message and the data from regex group can be extracted using the given patternGroupToExtract.
    • patternGroupToExtract <number> optional (Default: 1): Defines the regex group of which data is extracted.
Advanced configuration options:
  • protocol <string> optional (Default: "mqtt"): Defines protocol used to connect to the mqtt broker
  • qos <number> optional (Default: 1): Defines the Quality of Service (Notice, the QoS of the publisher must also be configured accordingly).
    In contrast to most implementations the default value is 1.
    • 0: 'At most once' - the message is sent only once and the client and broker take no additional steps to acknowledge delivery (fire and forget).
    • 1: 'At least once' - the message is re-tried by the sender multiple times until acknowledgement is received (acknowledged delivery).
    • 2: 'Exactly once' - the sender and receiver engage in a two-level handshake to ensure only one copy of the message is received (assured delivery).
  • clientId <string> optional (Default: 'mqttjs_' + Math.random().toString(16).substr(2, 8)): Defines clientId
  • keepalive <number> optional (Default: 60): Time in seconds to send a keepalive. Set to 0 to disable.
  • clean <boolean> optional (Default: true): Set to false to receive QoS 1 and 2 messages while offline.
  • reconnectPeriod <number> optional (Default: 1000): Time in milliseconds after which a reconnect is tried.
  • connectTimeout <number> optional (Default: 30000): Time in milliseconds the client waits until the CONNECT needs to be acknowledged (CONNACK).

Below is an example of an mqttObject containing the basic properties for a switch service:

{
  "host": "127.0.0.1",
  "port": 1883,
  
  "credentials": {
    "username": "yourUsername",
    "password": "yourPassword"
  },
  
  "subscriptions": [
    {
      "topic": "your/topic/here",
      "characteristic": "On",
      "messagePattern": "on"
    }
  ]
}

Stateless Switch

Since OFF is the only possible state you do not need to declare offUrl and statusUrl

{
    "accessories": [
        {
          "accessory": "HTTP-SWITCH",
          "name": "Switch",
          
          "switchType": "stateless",
          
          "timeout": 1000,
          
          "onUrl": "http://localhost/api/switchOn"
        }   
    ]
}  

Reverse Stateless Switch

Since ON is the only possible state you do not need to declare onUrl and statusUrl

{
    "accessories": [
        {
          "accessory": "HTTP-SWITCH",
          "name": "Switch",
          
          "switchType": "stateless-reverse",
          
          "timeout": 1000,
          
          "offUrl": "http://localhost/api/switchOff"
        }   
    ]
}

Multiple On or Off Urls

If you wish to do so you can specify an array of urls or urlObjects (onUrl or offUrl) when your switch is a stateless switch or a reverse-stateless switch.
This is not possible with a normal stateful switch.

Below are two example configurations of an stateless switch with three urls. One is using simple string array and the other is using simple urlObject arrays.

{
    "accessories": [
        {
          "accessory": "HTTP-SWITCH",
          "name": "Switch",
          
          "switchType": "stateless",
          "onUrl": [
            "http://localhost/api/switch1On",
            "http://localhost/api/switch2On",
            "http://localhost/api/switch3On"
          ]
        }   
    ]
}
{
    "accessories": [
        {
          "accessory": "HTTP-SWITCH",
          "name": "Switch",
          
          "switchType": "stateless",
          "onUrl": [
            {
              "url": "http://localhost/api/switch1On"
            },
            {
              "url": "http://localhost/api/switch2On"
            },
            {
              "url": "http://localhost/api/switch3On"
            }
          ]
        }   
    ]
}

The 'delay(...)' url

When using multiple urls and "series" as multipleUrlExecutionStrategy you can also specify so called delay urls in the onUrl or offUrl arrays. This could be used to guarantee a certain delay between two urls.
The delay url has the following pattern: "delay(INTEGER)" where 'INTEGER' is replaced with the delay in milliseconds.

Here is an example:

{
    "accessories": [
        {
          "accessory": "HTTP-SWITCH",
          "name": "Delayed Switch",
          
          "switchType": "stateless",
          "multipleUrlExecutionStrategy": "series",
          
          "onUrl": [
            "http://localhost/api/switch1On",
            "delay(1000)",
            "http://localhost/api/switch2On"
          ]
        }   
    ]
}

Examples for custom statusPatterns

The statusPattern property can be used to change the phrase which is used to identify if the switch should be turned on or off. So when you want the switch to be turned on when your server sends "true" in the body of the http response you could specify the following pattern:

{
    "statusPattern": "true"
}

However using Regular Expressions much more complex patterns are possible. Let's assume your http enabled device responds with the following json string as body, where one property has an random value an the other indicates the status of the switch:

{
    "perRequestRandomValue": 89723789,
    "switchState": true
}

Then you could use the following pattern:

{
    "statusPattern": "{\n    \"perRequestRandomValue\": [0-9]+,\n    \"switchState\": true\n}"
}

More on how to build regex patterns: https://www.w3schools.com/jsref/jsref_obj_regexp.asp

Notification Server

homebridge-http-switch can be used together with homebridge-http-notification-server in order to receive updates when the state changes at your external program. For details on how to implement those updates and how to install and configure homebridge-http-notification-server, please refer to the README of the repository first.

Down here is an example on how to configure homebridge-http-switch to work with your implementation of the homebridge-http-notification-server.

{
    "accessories": [
        {
          "accessory": "HTTP-SWITCH",
          "name": "Switch",
          
          "notificationID": "my-switch",
          "notificationPassword": "superSecretPassword",
          
          "onUrl": "http://localhost/api/switchOn",
          "offUrl": "http://localhost/api/switchOff",
          
          "statusUrl": "http://localhost/api/switchStatus"
        }   
    ]
}
  • notificationID is an per Homebridge instance unique id which must be included in any http request.
  • notificationPassword is optional. It can be used to secure any incoming requests.

To get more details about the configuration have a look at the README.

Available characteristics (for the POST body)

Down here are all characteristics listed which can be updated with an request to the homebridge-http-notification-server

  • characteristic "On": expects a boolean value
展开阅读全文

代码

评论 (0)

加载中
更多评论
暂无内容
发表于大前端专区
2018/01/13 16:56

homeassistant+homebridge

[使用iOS Homekit控制树莓派](http://caoyudong.com/2017/01/10/%E4%BD%BF%E7%94%A8iOS-Homekit%E6%8E%A7%E5%88%B6%E6%A0%91%E8%8E%93%E6%B4%BE/) [树莓派raspberrypi3打造homeassistant+homebridge智能家居中心(homekit)](https://zhuanlan.zhihu.com/p/31004760) [(少数派)从零开始,教你用树莓派 + IFTTT 实现 HomeKit 智能家居自动化](https://zhuanlan.zhihu.com/p/29130146) [[原创] 首发威锋!我们一起来玩HomeKit智能...

0
1
2018/05/11 10:12

homebridge安装问题解决

报错 dns_sd.DNSServiceRegister(self.serviceRef, flags, ifaceIdx, name, ^ Error: dns service error: unknown at Error (native) at new Advertisement (/usr/local/lib/node_modules/homebridge/node_modules/ha p-nodejs/node_modules/mdns/lib/advertisement.js:56:10) at Object.create [as createAdvertisement](/usr/local/lib/node_modules/homeb ridge/node_modules/hap-nodejs/node_modules/mdns/lib/advertisemen...

0
0
发表了博客
2018/02/23 09:15

if else和switch的效率

switch和if-else相比,由于使用了Binary Tree算法,绝大部分情况下switch会快一点,除非是if-else的第一个条件就为true. 说实话 我也没有深入研究过这个问题的根源 只是在实际开发中 没有人会去用很多很多else if的 都是用 switch case 的 后者比较清晰 给人感觉就是一个脑子很清楚的人写出来的东西 至于效率的本质 就让大企鹅去操心吧 编译器编译switch与编译if...else...不同。不管有多少case,都直接跳转,不需逐个比较查询。...

0
0
发表了博客
2019/09/26 17:10

switch语句

条件分支语句也叫switch语句 语法: switch(条件表达式){ case 表达式 : 语句… break; case 表达式 : 语句… break; default : 语句… break; } 执行流程: switch…case…语句 执行时会将case后表达式的值与switch条件表达式的值进行全等比较, 如果比较结果为true,则从当前case处开始执行代码。当前case后...

0
0
发表了博客
2018/09/18 22:37

switch用法

首先我们要了解: switch中文的意思就是转换,break也就是打断的意思 switch怎么用,其实和if差不多 switch(变量){ case 常量 : 语句块 break; //也可以有多个case default : 语句块 break; } 括号内只可以使用byte,short ,int,char类型的变量(然而这是JDK1.7之前的事) JDK1.7之后还可以支持一种叫String 类型的变量 现如今已是2018年最新版的就是JDK1.10了 那么为什么1.7之前只能支持上面的四种呢? 首先我们要知道一个常识:相同...

0
0
没有更多内容
加载失败,请刷新页面
点击加载更多
加载中
下一页
暂无内容
0 评论
0 收藏
分享
OSCHINA
登录后可查看更多优质内容
返回顶部
顶部