search

merdok / homebridge-miot

Homebridge plugin for devices supporting the Xiaomi miot protocol
MIT License
364 stars 62 forks source link
homebridge homekit micloud miio miot miot-devices miot-spec xioami

readme

homebridge-miot

verified-by-homebridge homebridge-miot mit-license follow-me-on-twitter join-discord

homebridge-miot is a plugin for homebridge which allows you to control any device supporting the miot protocol from Xiaomi!
The goal is to add Homekit support to miot devices and make them fully controllable from the native Homekit iOS app and Siri.

Feedback and contribution is helpful and will improve the plugin!

If your device is not supported please create a request and specify the device model and type.

Features

Supported device types

More device types will be added!

For a full list of supported devices by model check here: all supported devices by model.

Even if your device is not on the supported devices list, worry not! The plugin will use the miot spec to categorize your device as best as possible.

Installation

If you are new to homebridge, please first read the homebridge documentation. If you are running on a Raspberry, you will find a tutorial in the homebridge wiki.

Install homebridge:

sudo npm install -g homebridge

Install homebridge-miot:

sudo npm install -g homebridge-miot

Configuration

Add the miot platform in config.json in your home directory inside .homebridge.

Add your devices in the devices array.

Example configuration:

{
  "platforms": [
    {
      "platform": "miot",
      "micloud": {
        "username": "miotuser@mio.com",
        "password": "mySecretPassword",
        "country": "cn"
      },
      "devices": [
        {
          "name": "Xiaomi Smartmi Fan 3",
          "ip": "192.168.0.83",
          "token": "63d4d8fba83f94aa5ad8f96536c84c12",
          "pollingInterval": 10,
          "horizontalMoveControl": true,
          "buzzerControl": true,
          "ledControl": true,
          "modeControl": true,
          "offDelayControl": true,
          "ioniserControl": true,
          "horizontalAngleButtons": [
            5,
            60,
            100
          ],
          "actionButtons": [
            {
              "action": "fan:toggle",
              "name": "Toggle power action",
              "params": [
                123
              ]
            },
            {
              "action": "2.3",
              "name": "Toggle mode action"
            }
          ],
          "methodButtons": [
            {
              "method": "get_room_mapping",
              "name": "Get room mapping"
            }
          ],
          "propertyControl": [
            {
              "property": "fan:anion",
              "name": "Control anion"
            },
            {
              "property": "2.7",
              "value": 0,
              "name": "Set natural wind mode"
            },
            {
              "property": "custom-service:speed-level",
              "config": {
                "type": "fan"
              }
            }
          ],
          "propertyMonitor": [
            {
              "property": "battery:battery-level",
              "name": "Show bat level only when mode 1",
              "linkedProperty": "vacuum:mode",
              "linkedPropertyValue": 1
            },
            {
              "property": "vacuum:mode",
              "value": 2,
              "name": "Notify when mode 2 set"
            },
            {
              "property": "battery:battery-level",
              "value": 15,
              "valueOperator": "lessOrEqual",
              "name": "Low Battery"
            }
          ]
        }
      ]
    }
  ]
}

Token

For the plugin to work the device token is required. The plugin offers you two ways to retrieve the token for your devices:

Other ways:

Configuration

Keep in mind that your device needs to support the feature which you enable, otherwise you will not see any effect.

Platform configuration fields

Some device types also have some specific configuration fields. Please have a look at the device type page to check whether there are any available under the docs.

Property and Action names (or ids)

There are 4 ways to get the property an action names (or ids) used in actionButtons, propertyControl and propertyMonitor:

Property control config

Some properties have a configuration which enables to change certain aspects of the resulting service.

Value range properties:

BLE and ZigBee devices

It is also possible to connect BLE and ZigBee devices to the plugin via a gateway or hub. To do that, first the device needs to be connected to the gateway or hub, afterwards you have to manually specify the token and ip of the gateway/hub, but the model and deviceId needs to be that of the BLE or ZigBee device. All the required information can be retrieved from the MiCloud either via the Ui or the CLI commands.

Example:

{
  "platforms": [
    {
      "platform": "miot",
      "devices": [
        {
          "name": "Zigbee Outlet",
          "ip": "<GATEWAY_IP>",
          "token": "<GATEWAY_TOKEN>",
          "model": "lumi.plug.mmeu01",
          "deviceId": "<OUTLET_DID>",
        }
      ]
    }
  ]
}

CLI

The plugin also offers a command line interface to control your devices directly from the command line.
Just type miot in the console to get a list of available options. Currently available are:

Examples:

miot send <IP> -t <TOKEN> get_properties '[{"siid":2,"piid":2}]'

miot send <IP> -t <TOKEN> set_properties '[{"siid":2,"piid":2,"value":1}]'

miot send <IP> -t <TOKEN> action '{"aiid":13,"in":[],"siid":10}'

miot cloud list-devices

miot cloud get-props '[{"siid":2,"piid":2,"did":"<DID>"}]'

miot cloud set-props '[{"siid":2,"piid":2,"value":1,"did":"<DID>"}]'

Troubleshooting

Debug

If you have any issues with the plugin or device services then you can run homebridge in debug mode, which will provide some additional information. This might be useful for debugging issues.

Homebridge debug mode:

homebridge -D

Deep debug log, add the following to your config.json:

"deepDebugLog": true

This will enable additional extra log which might be helpful to debug all kind of issues.

Connection test

You can test the connection to a device with the following cli command:

miot test <ip> -t <token>

If the connection test will succeed then your ip and token are correct!

Special thanks

HAP-NodeJS & homebridge - for making this possible.