{"id":23817866,"url":"https://github.com/lsongdev/node-mijia","last_synced_at":"2025-08-18T16:09:13.021Z","repository":{"id":57297093,"uuid":"95292486","full_name":"lsongdev/node-mijia","owner":"lsongdev","description":":house: Control Mi Home devices, such as Mi Robot Vacuums, Mi Air Purifiers, Mi Smart Home Gateway (Aqara) and more","archived":false,"fork":false,"pushed_at":"2019-06-11T02:22:13.000Z","size":353,"stargazers_count":14,"open_issues_count":0,"forks_count":3,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-08-09T10:52:53.473Z","etag":null,"topics":["home-automation","mi-home","xiaomi","xiaomi-smart"],"latest_commit_sha":null,"homepage":"https://npmjs.org/mijia","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lsongdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-06-24T11:04:27.000Z","updated_at":"2025-05-18T13:46:12.000Z","dependencies_parsed_at":"2022-09-02T05:41:57.577Z","dependency_job_id":null,"html_url":"https://github.com/lsongdev/node-mijia","commit_stats":null,"previous_names":["lsongdev/node-mijia","song940/node-mijia"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lsongdev/node-mijia","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lsongdev%2Fnode-mijia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lsongdev%2Fnode-mijia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lsongdev%2Fnode-mijia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lsongdev%2Fnode-mijia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lsongdev","download_url":"https://codeload.github.com/lsongdev/node-mijia/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lsongdev%2Fnode-mijia/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271020023,"owners_count":24685793,"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","status":"online","status_checked_at":"2025-08-18T02:00:08.743Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["home-automation","mi-home","xiaomi","xiaomi-smart"],"created_at":"2025-01-02T05:48:56.377Z","updated_at":"2025-08-18T16:09:12.993Z","avatar_url":"https://github.com/lsongdev.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# miIO Device Library\n\n[![npm version](https://badge.fury.io/js/miio.svg)](https://badge.fury.io/js/miio)\n[![Dependencies](https://david-dm.org/aholstenson/miio.svg)](https://david-dm.org/aholstenson/miio)\n\nControl Mi Home devices that implement the miIO protocol, such as the\nMi Air Purifier, Mi Robot Vacuum and Mi Smart Socket. These devices are commonly\npart of what Xiaomi calls the Mi Ecosystem which is branded as MiJia.\n\n`miio` is [MIT-licensed](LICENSE.md) and requires at least Node 6.6.0. As\nthe API is promise-based Node 8 is recommended which provides support `async`\nand `await` that greatly simplifies asynchronous handling.\n\n**Note:** Since 0.15.0 this library has been rewritten to use [abstract-things](https://github.com/tinkerhub/abstract-things)\nas its base. The API of devices will have changed, and some bugs are to be\nexpected. Testing and feedback on the new API is welcome, please open issues\nas needed.\n\n## Devices types\n\nThe intent of this library is to support all miIO-compatible devices and to\nprovide an easy to use API for them. The library maps specific device models to\ngeneric device types with well defined capabilities to simplify interacting with\nthem.\n\nCurrently supported devices are:\n\n* Air Purifiers (1, 2 and Pro)\n* Mi Humidifier\n* Mi Smart Socket Plug and Power Strips\n* Mi Robot Vacuum (V1 and V2)\n* Mi Smart Home Gateway (Aqara) and accessories - switches, sensors, etc\n* Philips Light Bulb and Eyecare Lamp\n* Yeelights (White Bulb, Color Bulb, Desk Lamp and Strip)\n\nSee [documentation for devices](docs/devices/README.md) for information about\nthe types, their API and supported device models. You can also check\n[Missing devices](docs/missing-devices.md) if you want to know what you can do\nto help this library with support for your device.\n\n## Installation\n\nTo install into your project:\n\n```\nnpm install miio\n```\n\nTo install globally for access to the command line tool:\n\n```\nnpm install -g miio\n```\n\n## Usage\n\n```javascript\nconst miio = require('miio');\n```\n\nResolve a handle to the device:\n\n```javascript\n// Resolve a device, resolving the token automatically or from storage\nmiio.device({ address: '192.168.100.8' })\n  .then(device =\u003e console.log('Connected to', device))\n  .catch(err =\u003e handleErrorHere);\n\n// Resolve a device, specifying the token (see below for how to get the token)\nmiio.device({ address: '192.168.100.8', token: 'token-as-hex' })\n  .then(device =\u003e console.log('Connected to', device))\n  .catch(err =\u003e handleErrorHere);\n```\n\nCall methods to interact with the device:\n\n```javascript\n// Switch the power of the device\ndevice.togglePower()\n  .then(on =\u003e console.log('Power is now', on))\n  .catch(err =\u003e handleErrorHere);\n\n// Using async/await\nawait device.togglePower();\n```\n\nListen to events such as property changes and actions:\n\n```javascript\n// Listen for power changes\ndevice.on('power', power =\u003e console.log('Power changed to', power));\n\n// The device is available for event handlers\nconst handler = ({ action }, device) =\u003e console.log('Action', action, 'performed on', device);\ndevice1.on('action', handler);\ndevice2.on('action', handler);\n```\n\nCapabilities and types are used to hint about what a device can do:\n\n```javascript\nif(device.matches('cap:temperature')) {\n  console.log(await device.temperature());\n}\n\nif(device.matches('cap:switchable-power')) {\n  device.setPower(false)\n    .then(console.log)\n    .catch(console.error);\n}\n```\n\nIf you are done with the device call `destroy` to stop all network traffic:\n\n```javascript\ndevice.destroy();\n```\n\n## Tokens and device management\n\nA few miIO devices send back their token during a handshake and can be used\nwithout figuring out the token. Most devices hide their token, such as\nYeelights and the Mi Robot Vacuum.\n\nThere is a command line tool named `miio` that helps with finding and storing\ntokens. See [Device management](docs/management.md) for details\nand common use cases.\n\n## Discovering devices\n\nUse `miio.devices()` to look for and connect to devices on the local network.\nThis method of discovery will tell you directly if a device reveals its token\nand can be auto-connected to. If you do not want to automatically connect to\ndevices you can use `miio.browse()` instead.\n\nExample using `miio.devices()`:\n\n```javascript\nconst devices = miio.devices({\n  cacheTime: 300 // 5 minutes. Default is 1800 seconds (30 minutes)\n});\n\ndevices.on('available', device =\u003e {\n  if(device.matches('placeholder')) {\n    // This device is either missing a token or could not be connected to\n  } else {\n    // Do something useful with device\n  }\n});\n\ndevices.on('unavailable', device =\u003e {\n  // Device is no longer available and is destroyed\n});\n```\n\n`miio.devices()` supports these options:\n\n* `cacheTime`, the maximum amount of seconds a device can be unreachable before it becomes unavailable. Default: `1800`\n* `filter`, function used to filter what devices are connected to. Default: `reg =\u003e true`\n* `skipSubDevices`, if sub devices on Aqara gateways should be skipped. Default: `false`\n* `useTokenStorage`, if tokens should be fetched from storage (see device management). Default: `true`\n* `tokens`, object with manual mapping between ids and tokens (advanced, use [Device management](docs/management.md) if possible)\n\nSee [Advanced API](docs/advanced-api.md) for details about `miio.browse()`.\n\n## Device API\n\nCheck [documentation for devices](docs/devices/README.md) for details about\nthe API for supported devices. Detailed documentation of the core API is\navailable in the section [Using things in the abstract-things documentation](http://abstract-things.readthedocs.io/en/latest/using-things.html).\n\n## Library versioning and API stability\n\nThis library uses [semantic versioning](http://semver.org/) with an exception\nbeing that the API for devices is based on their type and capabilities and not\ntheir model.\n\nThis means that a device can have methods removed if its type or capabilities\nchange, which can happen if a better implementation is made available for the\nmodel. When working with the library implement checks against type and\ncapabilities for future compatibility within the same major version of `miio`.\n\nCapabilities can be considered stable across major versions, if a device\nsupports `power` no minor or patch version will introduce `power-mega` and\nreplace `power`. If new functionality is needed the new capability will be\nadded along side the older one.\n\n## Reporting issues\n\n[Reporting issues](docs/reporting-issues.md) contains information that is\nuseful for making any issue you want to report easier to fix.\n\n## Debugging\n\nThe library uses [debug](https://github.com/visionmedia/debug) with two\nnamespaces, `miio` is used for packet details and network discovery and devices\nuse the `thing:miio` namespace. These are controlled via the `DEBUG`\nenvironment flag. The flag can be set while running the miio command or any\nNodeJS script:\n\nShow debug info about devices during discovery:\n\n```\n$ DEBUG=thing\\* miio discover\n```\n\nTo activate both namespaces set `DEBUG` to both:\n\n```\n$ DEBUG=miio\\*,thing\\* miio discover\n```\n\n## Protocol documentation\n\nThis library is based on the documentation provided by OpenMiHome. See https://github.com/OpenMiHome/mihome-binary-protocol for details. For details\nabout how to figure out the commands for new devices look at the\n[documentation for protocol and commands](docs/protocol.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flsongdev%2Fnode-mijia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flsongdev%2Fnode-mijia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flsongdev%2Fnode-mijia/lists"}