开源软件名称：

开源软件地址：

开源编程语言：

开源软件介绍：

homebridge-mi-aqara

homebridge plugin for XiaoMi Aqara plugin.
小米/绿米网关的HomeBridge插件。

Thanks for nfarina(the author of homebridge), snOOrz(the author of homebridge-aqara), licuhui, 攀旺智能, magaHH, isundaylee, ileler, myriky, Runc2333, yangliu, wonderfullay, BrianHenryIE, all other developer and testers.
感谢 nfarina(homebridge的作者), snOOrz(homebridge-aqara的作者), licuhui, 攀旺智能, magaHH, isundaylee, ileler, myriky, Runc2333, yangliu, wonderfullay, BrianHenryIE, 以及每一位开发者和测试者.

Note: I have only a part of these devices, so some devices don't have tested. If you find bugs, please submit them to issues or QQ Group: 107927710.
注意: 我只有一部分设备, 所以一些设备没有得到充分的测试。 如果你发现Bug，请提交到 issues 或 QQ群: 107927710。

Note: According to aqara local network protocol use UDP port 9898, please notice the relevant configuration of firewall.
注意: 绿米的局域网协议使用的是UDP的9898端口，请配置好防火墙的相关配置。

Note: 0.5.x update to 0.6.x must be clear register accessories and update configuration file content.
注意: 0.5.x版本升级到0.6.x版本必须清空注册设备信息并且更新配置文件内容.

Note: About AcPartner, This project only provides gateway functionality. If you want the use air conditioning function, please refer to the project for homebridge-mi-acPartner.
注意: 有关空调伴侣，这个项目只提供网关的功能，如果你需要使用空调的功能，请参考项目homebridge-mi-acPartner。

Supported Devices(支持的设备)

Pre-Requirements(前置要求)

1. Make sure your IOS version is IOS11 or later.
   确保你的IOS设备版本高于IOS11。
2. Make sure you have gateway v2 or acpartner v3. gateway v1 has limited space so can't support this feature.
   确保你的小米网关是二代版本/空调伴侣是三代。小米网关一代不支持此插件。
3. Update gateway firmware to 1.4.1_155.0143(gateway v2), 1.4.1_148.019(acpartner v3) or later.
   确保你的网关的固件版本高于1.4.1_155.0143(小米网关二代), 1.4.1_148.019(空调伴侣三代)。

Installation(安装)

1. Install HomeBridge, please follow it's README.
   安装HomeBridge，请参考如下：README。
   If you are using Raspberry Pi, please read Running-HomeBridge-on-a-Raspberry-Pi.
   如果你使用树莓派安装，可以参考文章：在树莓派运行HomeBridge.
2. Make sure you can see HomeBridge in your iOS devices, if not, please go back to step 1.
   确保在你的IOS设备的家挺app中添加设备里能看到HomeBridge的桥，如果看不到请重复第一步。
3. Download homebridge-mi-aqara to your HomeBridge path or installation through NPM:
   下载homebridge-mi-aqara插件到你的HomeBridge上，使用如下NPM命令安装：

npm install -g homebridge-mi-aqara

Configuration(配置说明)

For more information about config, Please refer to file sampleConfig.json.
有关配置，可以参考配置文件 sampleConfig.json。

gateways configuration(网关配置)

Open aqara gateway's settings, enable local network protocol.
在网关的设置页面，打开 局域网控制协议。
Please follow the steps in this thread: http://wiki.yinhh.com/Wiki.jsp?page=Homebridge-mi-aqara or http://bbs.xiaomi.cn/t-13198850. It's in Chinese so you might need a translator to read it.
可以参考如下教程：http://wiki.yinhh.com/Wiki.jsp?page=Homebridge-mi-aqara 或 http://bbs.xiaomi.cn/t-13198850

On iPhone:
步骤可参考：

• Open the app
  打开米家app
• Select the gateway
  选择网关设备
• Press the top right (…) Settings button
  点击右上角的(…)按钮
• Select About
  选择关于
• Tap five times in the blank area to reveal the hidden menu items
  在空白区域中点击五次以显示隐藏菜单项
• Below the version numbers, choose the first: LAN Communication Protocol
  在版本号下面，选择第一个：局域网通信协议
• Toggle the LAN Communication Protocol switch to on
  将“LAN通信协议”开关切换到开
• Take note of the alphanumeric code beside Password
  记下密码旁边的字母数字代码
• Press OK
  点击OK
• Go back to the previous menu (About) and select the next option: Gateway Information
  返回上一个菜单（关于）并选择下一个选项：网关信息
• Take note of the MAC address at mac=
  记下mac=上的MAC地址

To control the devices, put gateway's MAC address (lower case without colon) and password (keep original and case sensitive) to ~/.homebridge/config.json.
将网关的mac地址(小写字母 去掉冒号)和密码(保持原始 区分大小写)写入到配置文件 ~/.homebridge/config.json。

Warning: gateway's MAC address (lower case without colon) and password (keep original and case sensitive).
警告: 网关的MAC地址 (全部小写 去掉冒号) 密码 (保持原始 区分大小写) 。
Warning: gateway's MAC address (lower case without colon) and password (keep original and case sensitive).
警告: 网关的MAC地址 (全部小写 去掉冒号) 密码 (保持原始 区分大小写) 。
Warning: gateway's MAC address (lower case without colon) and password (keep original and case sensitive).
警告: 网关的MAC地址 (全部小写 去掉冒号) 密码 (保持原始 区分大小写) 。
Important things are to be repeated for 3 times.
重要的事情说三遍。

{
    "platforms": [{
        "platform": "MiAqaraPlatform",
        "gateways": {
            "6409802da3b3": "02i44k56zrgg578b"
        }
    }]
}

If you have more than one gateways, fill them in right order, like below:
如果你有多个网关，可以这样填写：

{
    "platforms": [{
        "platform": "MiAqaraPlatform",
        "gateways": {
            "6409802da3b3": "02i44k56zrgg578b",
            "f0b4299a5b2b": "2F92E7DA90C66B86",
            "f0b4299a77dd": "syu3oasva3uqd5qd"
        }
    }]
}

Here is a way to search for gateways instead of multicast, because of some friends do not respond to information from gateway in their network environment.
有一些朋友的网络环境有一些问题，无法正常使用组播，这里提供一种配置方式来替代通过组播的方式寻找网关。
That is to say, we can config the IP address of the gateway to replace search gateway by multicast.
也就是说，可以通过配置网关的IP来替换通过组播的方式寻找网关。

{
    "platforms": [{
        "platform": "MiAqaraPlatform",
        "gateways": {
            "6409802da3b3": {
                "password": "02i44k56zrgg578b",
                "ip": "10.3.3.1"
            },
            "f0b4299a5b2b": {
                "password": "2F92E7DA90C66B86",
                "ip": "10.3.3.2"
            },
            "f0b4299a77dd": {
                "password": "syu3oasva3uqd5qd",
                "ip": "10.3.3.3"
            }
        }
    }]
}

It can also be mixed config, but without full configuration of ip, multicast packets will still be sent to search for other gateways which do not config ip.
也可以混合配置，不过只要有一个网关没有配置IP，程序就会发送组播信息来寻找未配置IP的网关。若所有网关全部配置了IP，则程序不发送组播包寻找网关。

{
    "platforms": [{
        "platform": "MiAqaraPlatform",
        "gateways": {
            "6409802da3b3": "02i44k56zrgg578b",
            "f0b4299a5b2b": {
                "password": "2F92E7DA90C66B86",
                "ip": "10.3.3.2"
            },
            "f0b4299a77dd": {
                "password": "syu3oasva3uqd5qd",
                "ip": "10.3.3.3"
            }
        }
    }]
}

bindAddress configuration(监听地址配置)

If your device(which running homebridge) has multiple network, please add the bindAddress configuration item to decide to listen which network, like below:
如果你运行HomeBridge的设备有多块网卡并且在多个网络中，可以通过这个配置来指定使用哪一个网络，配置如下：

{
    "platforms": [{
        "platform": "MiAqaraPlatform",
        "bindAddress": "10.0.1.1",
        "gateways": {
            "6409802da3b3": "02i44k56zrgg578b",
            "f0b4299a5b2b": "2F92E7DA90C66B86",
            "f0b4299a77dd": "syu3oasva3uqd5qd"
        }
    }]
}

sendWhoisCmdInterval configuration(自动发送whois命令间隔时间配置)

If this configuration item is not to configure, it will be send whois command every hour by default.
如果该配置项不填写，默认情况下，每小时发送一次。
If your network has some problems and you can't receive the heartbeat packet, you can use send whois command to replace the heartbeat function. If you use it in this way, you can set the value of the configuration item to 5 seconds, that is 5000. example:
如果你的网络有一些问题，无法收到心跳包，那么你可以使用发送a来替代心跳功能，如果这样使用，可以将配置项的值设为5秒，即5000，例子如下：

{
    "platforms": [{
        "platform": "MiAqaraPlatform",
        "bindAddress": "10.0.1.1",
        "sendWhoisCmdInterval": 5000,
        "gateways": {
            "6409802da3b3": "02i44k56zrgg578b",
            "f0b4299a5b2b": "2F92E7DA90C66B86",
            "f0b4299a77dd": "syu3oasva3uqd5qd"
        }
    }]
}

autoRemoveAccessoryInterval configuration(自动删除配件检测间隔时间配置)

If you want the plugin to help you automatically delete devices that have not received heartbeat for a long time, you can configure this item. The value is how often to detect. If you don't need to automatically delete accessories, you can not configure this configuration.
如果你希望插件帮你自动删除长时间收不到心跳的设备，则可以配置此项目，该值为多久检测一次。如果不需要自动删除配件功能，可以不配置此配置。
note: long time is defined as: no heartbeat received in more than 7 days.
注：长时间的定义为：超过7天未收到心跳。

{
    "platforms": [{
        "platform": "MiAqaraPlatform",
        "bindAddress": "10.0.1.1",
        "autoRemoveAccessoryInterval": 3600000,
        "gateways": {
            "6409802da3b3": "02i44k56zrgg578b",
            "f0b4299a5b2b": "2F92E7DA90C66B86",
            "f0b4299a77dd": "syu3oasva3uqd5qd"
        }
    }]
}

defaultValue configuration(默认值配置)

If you want to specify the default value, such as specify the name of the accessory, hide the accessory, any other configs. You can add a defaultValue mapping table to your config.json.
如果你想要指定默认值，比如配件的名字，是否隐藏配件以及其他一些配置，你可以在你的配置文件config.json中增加defaultValue配置项。 The config supported are as follows:
这个配置支持如下功能：

The rules are as follows:
配置规则如下：

{
    "platforms": [{
        "platform": "MiAqaraPlatform",
        "gateways": {
            "6409802da3b3": "02i44k56zrgg578b",
            "f0b4299a5b2b": "2F92E7DA90C66B86",
            "f0b4299a77dd": "syu3oasva3uqd5qd"
        },
        "defaultValue": {
            "device1 sid": {
                "DeviceAccessoryType1": {
                    "config1": "config1 value"
                }
            },
            "device2 sid": {
                "DeviceAccessoryType1": {
                    "config1": "config1 value"
                    "config2": "config2 value"
                },
                "DeviceAccessoryType2": {
                    "config1": "config1 value"
                }
            }
        }
    }]
}

examples:
例子:

{
    "platforms": [{
        "platform": "MiAqaraPlatform",
        "gateways": {
            "6409802da3b3": "02i44k56zrgg578b",
            "f0b4299a5b2b": "2F92E7DA90C66B86",
            "f0b4299a77dd": "syu3oasva3uqd5qd"
        },
        "defaultValue": {
            "158d0001000001": {
                "ContactSensor_ContactSensor": {
                    "name": "entrance door"
                }
            },
            "158d0001000002": {
                "MotionSensor2_MotionSensor": {
                    "name": "study room motion sensor"
                },
                "MotionSensor2_LightSensor": {
                    "name": "study room light sensor"
                }
            }
        }
    }]
}

The rules of A DeviceAccessoryType:
设备配件类型的规则如下：

DeviceName_HomeBridgeAccessoryType(_ExtraMessage)   
设备名称_HomeBridge的配件类型(_附加信息)

detail:
具体如下：

About Global:
有关全局配置方式：
Some similar configurations and repeated multiple copies are boring things. So I provided a global writing method.
一些类似的配置和重复的多次拷贝是件比较烦的事情，所以我提供了一个全局的功能：
The following two methods of writing are equivalent:
下面两段配置的效果是等同的：

....
"158d0001000008": {
    "DuplexSwitch_Switch_Left": {
        "name": "master bedroom room light",
        "serviceType": "Lightbulb"
    },
    "DuplexSwitch_Switch_Right": {
        "name": "study room light",
        "serviceType": "Lightbulb"
    }
}
....

....
"158d0001000008": {
    "Global": {
        "serviceType": "Lightbulb"
    },
    "DuplexSwitch_Switch_Left": {
        "name": "master bedroom room light"
    },
    "DuplexSwitch_Switch_Right": {
        "name": "study room light"
    }
}
....

In the same way, the following two kinds of writing are alse equivalent:
同样的方式，下面两段配置的效果也是等同的：

....
"158d0001000003": {
    "Button_StatelessProgrammableSwitch": {
        "name": "living room button"
    },
    "Button_Switch_VirtualSinglePress": {
        "name": "living room button virtual single press",
        "disable": true
    },
    "Button_Switch_VirtualDoublePress": {
        "name": "living room button virtual double press",
        "disable": true
    }
}
....

....
"158d0001000003": {
    "Global": {
        "disable": true 
    },
    "Button_StatelessProgrammableSwitch": {
        "name": "living room button",
        "disable": false
    },
    "Button_Switch_VirtualSinglePress": {
        "name": "living room button virtual single press"
    },
    "Button_Switch_VirtualDoublePress": {
        "name": "living room button virtual double press"
    }
}
....

It also provides a higher level of way, the following three kinds of writing are alse equivalent:
更高层级的配置也可适用，如下三段配置的效果均是等同的：

{
    "platforms": [{
        "platform": "MiAqaraPlatform",
        "gateways": {
            "6409802da3b3": "02i44k56zrgg578b",
            "f0b4299a5b2b": "2F92E7DA90C66B86",
            "f0b4299a77dd": "syu3oasva3uqd5qd"
        },
        "defaultValue": {
            "158d0001000007": {
                "SingleSwitch_Switch": {