{"analyzedAt":"2023-01-08T18:22:28.253Z","collected":{"metadata":{"name":"homebridge-miot","scope":"unscoped","version":"1.5.0","description":"Homebridge plugin for devices supporting the miot protocol","keywords":["homebridge-plugin","xiaomi","miot","micloud","smartmi","fan","smart","mi","zhimi","dmaker","homekit","heater","humidifier","air purifier","air","purifier","ceiling","outlet","curtain","window","gosund","dooya","vacuum","robot","cleaner","roborock","dreame","air quality","air monitor","over","air fryer","light","yeelink"],"date":"2023-01-08T18:22:06.178Z","author":{"name":"merdok"},"publisher":{"username":"merdok","email":"merdok87@o2.pl"},"maintainers":[{"username":"merdok","email":"merdok87@o2.pl"}],"repository":{"type":"git","url":"git+https://github.com/merdok/homebridge-miot.git"},"links":{"npm":"https://www.npmjs.com/package/homebridge-miot","homepage":"https://github.com/merdok/homebridge-miot#readme","repository":"https://github.com/merdok/homebridge-miot","bugs":"https://github.com/merdok/homebridge-miot/issues"},"license":"MIT","dependencies":{"@homebridge/plugin-ui-utils":"^0.0.19","node-fetch":"^2.6.7","randomstring":"^1.2.1","color-convert":"^2.0.1","yargs":"^17.3.1","chalk":"^4.1.2","env-paths":"^2.2.1"},"releases":[{"from":"2022-12-09T00:00:00.000Z","to":"2023-01-08T00:00:00.000Z","count":0},{"from":"2022-10-10T00:00:00.000Z","to":"2023-01-08T00:00:00.000Z","count":5},{"from":"2022-07-12T00:00:00.000Z","to":"2023-01-08T00:00:00.000Z","count":7},{"from":"2022-01-08T00:00:00.000Z","to":"2023-01-08T00:00:00.000Z","count":23},{"from":"2021-01-08T00:00:00.000Z","to":"2023-01-08T00:00:00.000Z","count":84}],"readme":"\n\n# homebridge-miot\n\n[](https://github.com/homebridge/homebridge/wiki/Verified-Plugins)\n[](https://www.npmjs.com/package/homebridge-miot)\n[](https://github.com/merdok/homebridge-miot/blob/master/LICENSE)\n[](https://twitter.com/merdok_dev)\n[](https://discord.gg/c9AWNESQMg)\n\n\n\n`homebridge-miot` is a plugin for homebridge which allows you to control any device supporting the miot protocol from Xiaomi! \nThe goal is to add Homekit support to miot devices and make them fully controllable from the native Homekit iOS app and Siri.\n\n#### Feedback and contribution is helpful and will improve the plugin!\n#### If your device is not supported please create a request and specify the device model and type.\n\n### Features\n* Integrates miot devices into Homekit\n* Detect device types automatically via miot spec or by local device implementations\n* Fully customizable Homekit accessories\n* Homekit automations for your miot devices\n\n### Supported device types\n* Fan\n* Ceiling Fan\n* Heater\n* Humidifier\n* Dehumidifier\n* Air Purifier\n* Air Conditioner\n* Outlet\n* Curtain\n* Fresh Air System\n* Robot Cleaner - [Room Cleaning guide](https://github.com/merdok/homebridge-miot/blob/main/docs/robotcleaner.md)\n* Light\n* Airer\n* Oven\n* Air Fryer\n* Coffee Machine\n* Camera\n* Bath Heater\n* Kettle\n* Thermostat\n* Switch\n* Air Monitor\n* Cooker\n* Speaker\n* Contact Sensor\n* Gateway\n\nMore device types will be added!\n\nFor a full list of supported devices by model check here: [all supported devices by model](https://github.com/merdok/homebridge-miot/blob/master/supported_devices.md).\n\n#### 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.\n\n## Installation\n\nIf you are new to homebridge, please first read the homebridge [documentation](https://github.com/homebridge/homebridge#readme).\nIf you are running on a Raspberry, you will find a tutorial in the [homebridge wiki](https://github.com/homebridge/homebridge/wiki/Install-Homebridge-on-Raspbian).\n\nInstall homebridge:\n```sh\nsudo npm install -g homebridge\n```\n\nInstall homebridge-miot:\n```sh\nsudo npm install -g homebridge-miot\n```\n\n## Configuration\n\nAdd the `miot` platform in `config.json` in your home directory inside `.homebridge`.\n\nAdd your devices in the `devices` array.\n\nExample configuration:\n\n```js\n{\n \"platforms\": [\n {\n \"platform\": \"miot\",\n \"micloud\": {\n \"username\": \"miotuser@mio.com\",\n \"password\": \"mySecretPassword\",\n \"country\": \"cn\"\n },\n \"devices\": [\n {\n \"name\": \"Xiaomi Smartmi Fan 3\",\n \"ip\": \"192.168.0.83\",\n \"token\": \"63d4d8fba83f94aa5ad8f96536c84c12\",\n \"pollingInterval\": 10,\n \"horizontalMoveControl\": true,\n \"buzzerControl\": true,\n \"ledControl\": true,\n \"modeControl\": true,\n \"offDelayControl\": true,\n \"ioniserControl\": true,\n \"horizontalAngleButtons\": [\n 5,\n 60,\n 100\n ],\n \"actionButtons\": [\n {\n \"action\": \"fan:toggle\",\n \"name\": \"Toggle power action\",\n \"params\": [\n 123\n ]\n },\n {\n \"action\": \"2.3\",\n \"name\": \"Toggle mode action\"\n }\n ],\n \"methodButtons\": [\n {\n \"method\": \"get_room_mapping\",\n \"name\": \"Get room mapping\"\n }\n ],\n \"propertyControl\": [\n {\n \"property\": \"fan:anion\",\n \"name\": \"Control anion\"\n },\n {\n \"property\": \"2.7\",\n \"value\": 0,\n \"name\": \"Set natural wind mode\"\n },\n {\n \"property\": \"custom-service:speed-level\",\n \"config\": {\n \"type\": \"fan\"\n }\n }\n ],\n \"propertyMonitor\": [\n {\n \"property\": \"battery:battery-level\",\n \"name\": \"Show bat level only when mode 1\",\n \"linkedProperty\": \"vacuum:mode\",\n \"linkedPropertyValue\": 1\n },\n {\n \"property\": \"vacuum:mode\",\n \"value\": 2,\n \"name\": \"Notify when mode 2 set\"\n }\n ]\n }\n ]\n }\n ]\n}\n```\n\n### Token\nFor the plugin to work the device token is required. The plugin offers you two ways to retrieve the token for your devices:\n- You can use the plugin's settings in homebridge-config-ui-x (Homebridge Ui), where you will find a **\"Discover All Devices via MiCloud\"** button, which can automatically get the tokens for all your devices!\n- Another way it to use the command line tools, simply type `miot cloud-devices -u -p ` in the command line to get the tokens for all your devices!\n\nOther ways: \n- guide to retrieve token manually: [obtaining mi device token](https://github.com/merdok/homebridge-miot/blob/master/obtain_token.md). \n- a great tool to easily retrieve the token: [Xiaomi Cloud Tokens Extractor](https://github.com/PiotrMachowski/Xiaomi-cloud-tokens-extractor).\n\n### Configuration\nKeep in mind that your device needs to support the feature which you enable, otherwise you will not see any effect.\n#### Platform configuration fields\n- `platform` [required]\nMust always be **\"miot\"**.\n- `devices` [required]\nA list of your devices.\n- `micloud` [optional]\nThis is a global configuration object for the MiCloud connection. When specified, this credentials will be used when a device requires a MiCloud connection. Some older devices require a MiCloud connection in order to be controlled! **Default: \"\" (not specified)**\n - Can also be specified even when no devices require the MiCloud, in that case additional information for the devices will be retrieved.\n - An object should have the following properties:\n - *username* - [required] the MiCloud username\n - *password* - [required] the MiCloud password\n - *country* - [optional] the country where the servers are located for your devices. **Default: \"cn\"**\n - *forceMiCloud* - [optional] forces to use MiCloud even when the device supports local commands. **Default: false**\n - *timeout* - [optional] set a custom request timeout in milliseconds. **Default: 5000**\n#### General device configuration fields\n- `name` [required]\nName of the accessory.\n- `ip` [required]\nip address of your device.\n- `token` [required]\nThe token of your device.\n- `deviceId` [optional]\nThe deviceId is required for a MiCloud connection to identify the device. If not specified an attempt will be made to retrieve it from a local connection to the device **Default: \"\" (not specified)**\n- `model` [optional]\nThe device model if known. Should only be specified when certain about the device model. If specified then the accessory will be created instantly without the need to first discover and identify the device. **Default: \"\" (not specified)**\n- `micloud` [optional]\nWhen specified overwrites the global setting for the device. Useful when you have devices on different servers or want to force certain devices to use MiCloud. **Default: \"\" (not specified)**\n- `prefsDir` [optional]\nThe directory where the device info will be stored. **Default: \"~/.homebridge/.xiaomiMiot\"**\n- `pollingInterval` [optional]\nThe device state polling interval in seconds. **Default: 15**\n- `propertyChunkSize` [optional]\n Size of a property chunk when syncing properties with the device. A lower value might reduce the load on the device. Range 1-14 **Default: device class default, if not defined -> 14**\n- `deepDebugLog` [optional]\nEnables additional more detailed debug log. Useful when trying to figure out issues with the plugin. **Default: false**\n- `customAccessory` [optional]\n Creates a custom empty accessory for the device which can be manually populated with services. Requires ***actionButtons***, ***propertyControl*** or ***propertyMonitor*** to be set. **Default: false**\n- `onlyMainService` [optional]\n Only the main accessory service will be created without any additional services. Useful when wanting to have a clean layout. ***actionButtons***, ***propertyControl*** or ***propertyMonitor*** can be used to manually add services. **Default: false**\n- `buzzerControl` [optional]\nWhether the buzzer service is enabled. This allows to turn on/off the device buzzer/alarm. **Default: true**\n- `ledControl` [optional]\nWhether the led service is enabled. This allows to turn on/off the device LED. **Default: true**\n- `childLockControl` [optional]\nWhether the child lock control service is enabled. This allows to turn on/off the device child lock. **Default: true**\n- `modeControl` [optional]\nShow mode switches which allow to change the device mode. **Default: true**\n- `actionButtons` [optional]\nShow additional action switches if the device supports any. **Default: false**\n - Set to *true* or *false* to show/hide all actions available on the device\n - Set an array of action names or action ids to only show the desired actions\n - You can also set an array of objects as the value which enables advanced configuration. An object can have the following properties:\n - *action* - [required] the action name or action id\n - *name* - [optional] the name of the switch\n - *params* - [optional] parameters to be used for the action, not all actions support parameters\n- `methodButtons` [optional]\nExecute a raw miio method on the device. Can be useful for advanced robot cleaner configuration **Default: \"\" (not specified)**\n - Creates statless switches which when pressed execute the method, the result of the method call is printed in the log\n - Set an array of method names to only show the desired method buttons\n - You can also set an array of objects as the value which enables advanced configuration. An object can have the following properties:\n - *method* - [required] the method name\n - *name* - [optional] the name of the switch\n - *params* - [optional] parameters to be used for the method call\n- `propertyControl` [optional]\nAllows to control any properties of your device. **Default: \"\" (not specified)**\n - Creates ui controls on your device based on the property type\n - Set an array of property names or property ids\n - You can also set an array of objects as the value which enables advanced configuration. An object can have the following properties:\n - *property* - [required] the property name or id\n - *name* - [optional] the name of the control\n - *value* - [optional] a fixed value which will be set to the property. When specified will create a stateless switch\n - *linkedProperty* - [optional] linked property used for status checking. Useful when control should only be possible when for example the device is on\n - *linkedPropertyValue* - [optional] the value of the linked property\n - *config* - [optional] a configuration object, for details see below\n- `propertyMonitor` [optional]\nAllows to monitor any properties of your device. **Default: \"\" (not specified)**\n - Creates a light sensor to display numeric values. String values are logged\n - Set an array of property names or property ids\n - You can also set an array of objects as the value which enables advanced configuration. An object can have the following properties:\n - *property* - [required] the property name or id\n - *name* - [optional] the name of the control\n - *value* - [optional] when a fixed value is specified instead of a light sensor a presence sensor will be created which triggers when the property has the specified value\n - *linkedProperty* - [optional] linked property used for status checking- Useful when monitor should only be possible when for example the device is on\n - *linkedPropertyValue* - [optional] the value of the linked property\n\n#### 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](https://github.com/merdok/homebridge-miot/tree/main/docs).\n\n#### Property and Action names (or ids)\nThere are 4 ways to get the property an action names (or ids) used in ***actionButtons***, ***propertyControl*** and ***propertyMonitor***:\n- Use the [Miot Spec Fetcher](https://merdok.github.io/miotspec/)\n- Use the plugin's settings in homebridge-config-ui-x (Homebridge Ui), where you will find a **\"Fetch Device Metadata\"** button\n- Check the homebridge log. Available device property and action names will be printed there during initialization\n- You can also use the official miot spec in order to determine the names or ids [Miot Spec - Released](https://miot-spec.org/miot-spec-v2/instances?status=released)\n\n#### Property control config\nSome properties have a configuration which enables to change certain aspects of the resulting service.\n\n###### Value range properties:\n- *type* - the type of the accessory which is created **Default: \"lightbulb\"**\n - lightbulb\n - fan\n\n## CLI\nThe plugin also offers a command line interface to control your devices directly from the command line. \nJust type `miot` in the console to get a list of available options. Currently available are:\n- `miot send` -> Send a RAW command over your local network to the device\n- `miot test` -> Test connection to a device\n- `miot tokens` -> Store and show tokens for specific devices\n- `miot cloud` -> Connect to the MiCloud, execute commands, list devices and get specific device info\n- `miot fetch-metadata` -> Fetch device metadata for the specified model\n\n## Troubleshooting\n\n##### Debug\nIf 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.\n\nHomebridge debug mode:\n```sh\nhomebridge -D\n```\n\nDeep debug log, add the following to your config.json:\n```json\n\"deepDebugLog\": true\n```\nThis will enable additional extra log which might be helpful to debug all kind of issues.\n\n##### Connection test\nYou can test the connection to a device with the following cli command:\n```sh\nmiot test -t \n```\n\nIf the connection test will succeed then your ip and token are correct!\n\n## Special thanks\n[HAP-NodeJS](https://github.com/KhaosT/HAP-NodeJS) & [homebridge](https://github.com/nfarina/homebridge) - for making this possible."},"npm":{"downloads":[{"from":"2023-01-07T00:00:00.000Z","to":"2023-01-08T00:00:00.000Z","count":41},{"from":"2023-01-01T00:00:00.000Z","to":"2023-01-08T00:00:00.000Z","count":298},{"from":"2022-12-09T00:00:00.000Z","to":"2023-01-08T00:00:00.000Z","count":1363},{"from":"2022-10-10T00:00:00.000Z","to":"2023-01-08T00:00:00.000Z","count":9044},{"from":"2022-07-12T00:00:00.000Z","to":"2023-01-08T00:00:00.000Z","count":16321},{"from":"2022-01-08T00:00:00.000Z","to":"2023-01-08T00:00:00.000Z","count":34151}],"starsCount":0},"github":{"starsCount":231,"forksCount":34,"subscribersCount":8,"issues":{"count":387,"openCount":16,"distribution":{"3600":29,"10800":25,"32400":27,"97200":46,"291600":43,"874800":59,"2624400":85,"7873200":60,"23619600":11,"70858800":2,"212576400":0},"isDisabled":false},"contributors":[{"username":"merdok","commitsCount":595},{"username":"0x5e","commitsCount":12},{"username":"mrking","commitsCount":8},{"username":"nVuln","commitsCount":4},{"username":"ahelpingchip","commitsCount":3},{"username":"seanzhang98","commitsCount":3},{"username":"blue2000hk","commitsCount":3},{"username":"achrovisual","commitsCount":3},{"username":"saurikCornel","commitsCount":2},{"username":"satrik","commitsCount":2},{"username":"johnhom1024","commitsCount":1},{"username":"rhusar","commitsCount":1},{"username":"LiuLiujie","commitsCount":1}],"commits":[{"from":"2023-01-01T00:00:00.000Z","to":"2023-01-08T00:00:00.000Z","count":13},{"from":"2022-12-09T00:00:00.000Z","to":"2023-01-08T00:00:00.000Z","count":18},{"from":"2022-10-10T00:00:00.000Z","to":"2023-01-08T00:00:00.000Z","count":60},{"from":"2022-07-12T00:00:00.000Z","to":"2023-01-08T00:00:00.000Z","count":103},{"from":"2022-01-08T00:00:00.000Z","to":"2023-01-08T00:00:00.000Z","count":212}]},"source":{"files":{"readmeSize":14806,"testsSize":1651,"hasChangelog":true},"outdatedDependencies":{"env-paths":{"required":"^2.2.1","stable":"3.0.0","latest":"3.0.0"},"chalk":{"required":"^4.1.2","stable":"5.2.0","latest":"5.2.0"},"node-fetch":{"required":"^2.6.7","stable":"3.3.0","latest":"4.0.0-beta.4"}}}},"evaluation":{"quality":{"carefulness":0.7899999999999999,"tests":0.3,"health":0.5,"branding":0},"popularity":{"communityInterest":286,"downloadsCount":3014.6666666666665,"downloadsAcceleration":-12.755802891933032,"dependentsCount":0},"maintenance":{"releasesFrequency":1,"commitsFrequency":1,"openIssues":1,"issuesDistribution":0.9672143297593879}},"score":{"final":0.5368299247671944,"detail":{"quality":0.46401097861987706,"popularity":0.13607678201649123,"maintenance":0.9999993070727409}}}