{"id":13821046,"url":"https://github.com/syssi/xiaomi_fan","last_synced_at":"2025-10-04T19:44:09.365Z","repository":{"id":37450942,"uuid":"129049262","full_name":"syssi/xiaomi_fan","owner":"syssi","description":"Xiaomi Mi Smart Fan integration for Home Assistant","archived":false,"fork":false,"pushed_at":"2024-08-31T15:27:02.000Z","size":133,"stargazers_count":434,"open_issues_count":56,"forks_count":117,"subscribers_count":18,"default_branch":"develop","last_synced_at":"2025-03-28T08:08:25.633Z","etag":null,"topics":["custom-component","fan","hacktoberfest","home-assistant","miio","miio-protocol","miot","xiaomi"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/syssi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-11T07:00:21.000Z","updated_at":"2025-03-13T11:35:28.000Z","dependencies_parsed_at":"2024-10-03T10:12:06.038Z","dependency_job_id":null,"html_url":"https://github.com/syssi/xiaomi_fan","commit_stats":null,"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syssi%2Fxiaomi_fan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syssi%2Fxiaomi_fan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syssi%2Fxiaomi_fan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syssi%2Fxiaomi_fan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/syssi","download_url":"https://codeload.github.com/syssi/xiaomi_fan/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247149502,"owners_count":20891954,"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","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":["custom-component","fan","hacktoberfest","home-assistant","miio","miio-protocol","miot","xiaomi"],"created_at":"2024-08-04T08:01:14.314Z","updated_at":"2025-10-04T19:44:04.299Z","avatar_url":"https://github.com/syssi.png","language":"Python","funding_links":["https://www.buymeacoffee.com/syssi"],"categories":["Python"],"sub_categories":[],"readme":"# Xiaomi Mi Smart Pedestal Fan\n\n![GitHub actions](https://github.com/syssi/xiaomi_fan/actions/workflows/ci.yaml/badge.svg)\n![GitHub stars](https://img.shields.io/github/stars/syssi/xiaomi_fan)\n![GitHub forks](https://img.shields.io/github/forks/syssi/xiaomi_fan)\n![GitHub watchers](https://img.shields.io/github/watchers/syssi/xiaomi_fan)\n[![\"Buy Me A Coffee\"](https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg)](https://www.buymeacoffee.com/syssi)\n\nThis is a custom component for home assistant to integrate the Xiaomi Mi Smart Fan.\n\nPlease follow the instructions on [Retrieving the Access Token](https://www.home-assistant.io/integrations/xiaomi_miio/#xiaomi-cloud-tokens-extractor) to get the API token to use in the configuration.yaml file.\n\nCredits: Thanks to [Rytilahti](https://github.com/rytilahti/python-miio) for all the work.\n\n## Supported devices\n\n| Name                        | Model                  | Model no. | Specs |\n| ----------------------------| ---------------------- | --------- | ----- |\n| Pedestal Fan Fan V2         | zhimi.fan.v2           | | |\n| Pedestal Fan Fan V3         | zhimi.fan.v3           | | |\n| Pedestal Fan Fan SA1        | zhimi.fan.sa1          | | |\n| Pedestal Fan Fan ZA1        | zhimi.fan.za1          | | |\n| Pedestal Fan Fan ZA3        | zhimi.fan.za3          | | |\n| Pedestal Fan Fan ZA4        | zhimi.fan.za4          | ZLBPLDS04ZM | |\n| Smartmi Standing Fan 3      | zhimi.fan.za5          | | |\n| Pedestal Fan Fan 1C         | dmaker.fan.1c          | | |\n| Pedestal Fan Fan P5         | dmaker.fan.p5          | | |\n| Pedestal Fan Fan P8         | dmaker.fan.p8          | | |\n| Pedestal Fan Fan P9         | dmaker.fan.p9          | | |\n| Pedestal Fan Fan P10        | dmaker.fan.p10         | | |\n| Mijia Pedestal Fan          | dmaker.fan.p11         | BPLDS03DM  | 2800mAh, 24W, \u003c=58dB  |\n| Smart Standing Fan 2 Pro    | dmaker.fan.p33         | BPLDS03DM  | 2800mAh, 24W, \u003c=58dB  |\n| Pedestal Fan Fan P15        | dmaker.fan.p15         | | |\n| Mi Smart Standing Fan 2 P18 | dmaker.fan.p18         | BPLDS02DM  | AC, 15W, 30.2-55.8bB  |\n| Mi Smart Standing Fan 2 P30 | dmaker.fan.p30         | BPLDS02DM  | AC, 15W, 30.2-55.8bB  |\n| Rosou SS4 Ventilator        | leshow.fan.ss4         | | |\n| Xiaomi Smart Tower Fan      | dmaker.fan.p39         | BPTS01DM | 22W, \u003c=63dB |\n\n\n## Features\n\n### Pedestal Fan\n\n* Power (on, off)\n* Preset modes (Level 1, Level 2, Level 3, Level 4)\n* Speed percentage (0...100)\n* Oscillate (on, off)\n* Oscillation angle (30, 60, 90, 120, 140, 150)\n* Natural mode (on, off)\n* Rotate by 5 degrees (left, right)\n* Child lock (on, off)\n* LED brightness (bright, dim, off)\n* Attributes\n  - model\n  - temperature (zhimi.fan.v2 and v3 only)\n  - humidity (zhimi.fan.v2 and v3 only)\n  - led_brightness\n  - buzzer\n  - child_lock\n  - natural_level\n  - oscillate\n  - delay_off_countdown\n  - speed\n  - direct_speed\n  - natural_speed\n  - angle\n  - use_time\n  - ac_power\n  - battery (zhimi.fan.v2 and v3 only)\n  - battery_charge (zhimi.fan.v2 \u0026 v3 only)\n  - button_pressed (zhimi.fan.v2 \u0026 v3 only)\n  - led (zhimi.fan.v2 only)\n  - battery_state (zhimi.fan.v2 only)\n  - anion (zhimi.fan.za5 only)\n\n\n### Rosou SS4 Ventilator (leshow.fan.ss4)\n\n* Power (on, off)\n* Operation modes (manual, sleep, strong, natural)\n* Preset modes (Level 1, Level 2, Level 3, Level 4)\n* Speed percentage (0...100)\n* Oscillate (on, off)\n* Buzzer (on, off)\n* Delayed turn off (minutes)\n\n* Attributes\n  - `model`\n  - `mode`\n  - `speed`\n  - `buzzer`\n  - `oscillate`\n  - `delay_off_countdown`\n  - `error_detected`\n\n\n## Install\n\nYou can install this custom component via [HACS](https://hacs.xyz/). Search for for 'Xiaomi Mi Smart Pedestal Fan Integration' at the integration page of HACS. Alternatively, you can install it manually by copying the custom_component folder to your Home Assistant configuration folder.\n\nAs next step you have to setup the custom component at your `configuration.yaml`. This custom component doesn't provide a `config-flow` right now. A restart of Home Assistant is required afterwards.\n\n## Setup\n\n```yaml\n# configuration.yaml\n\nfan:\n  - platform: xiaomi_miio_fan\n    name: Xiaomi Smart Fan\n    host: 192.168.130.71\n    token: b7c4a758c251955d2c24b1d9e41ce47d\n```\n\nConfiguration variables:\n- **host** (*Required*): The IP of your fan.\n- **token** (*Required*): The API token of your fan.\n- **name** (*Optional*): The name of your fan.\n- **model** (*Optional*): The model of your device. This setting can be used to bypass the device model detection and is recommended if your device isn't always available.\n- **preset_modes_override** (*Optional*): Overrides the list of preset modes. Can be used to suppress the preset mode switches at homekit by passing an empty list (`preset_modes_override: []`).\n\n## Platform services\n\n#### Service `fan.set_percentage`\n\nSet the fan speed percentage.\n\n| Service data attribute    | Optional | Description                                                                |\n|---------------------------|----------|----------------------------------------------------------------------------|\n| `entity_id`               |      yes | Only act on a specific fan entity. Else targets all.                       |\n| `percentage`              |       no | Percentage speed setting. Valid values are between 0 and 100.              |\n\n#### Service `fan.set_preset_mode`\n\nSet a preset mode.\n\n| Service data attribute    | Optional | Description                                                                  |\n|---------------------------|----------|------------------------------------------------------------------------------|\n| `entity_id`               |      yes | Only act on a specific fan entity. Else targets all.                         |\n| `preset_mode`             |       no | Preset mode. Valid values are `Level 1`, `Level 2`, `Level 3` and `Level 4`. |\n\n#### Service `fan.oscillate`\n\nOscillates the fan.\n\n| Service data attribute    | Optional | Description                                                           |\n|---------------------------|----------|-----------------------------------------------------------------------|\n| `entity_id`               |      yes | Only act on a specific fan entity. Else targets all.                  |\n| `oscillating`             |       no | Flag to turn on/off oscillation. Valid values are `True` and `False`. |\n\n#### Service `fan.set_direction`\n\nRotates the fan 5 degrees to the left/right.\n\n| Service data attribute    | Optional | Description                                                          |\n|---------------------------|----------|----------------------------------------------------------------------|\n| `entity_id`               |      yes | Only act on a specific fan entity. Else targets all.                 |\n| `direction`               |       no | Rotate the fan 5 degrees. Valid values are `left`/`reverse` and `right`/`forward`.       |\n\n#### Service `xiaomi_miio_fan.fan_set_oscillation_angle`\n\nSet the oscillation angle. Supported values are 30, 60, 90 and 120 degrees.\n\n| Service data attribute    | Optional | Description                                                            |\n|---------------------------|----------|------------------------------------------------------------------------|\n| `entity_id`               |      yes | Only act on a specific xiaomi miio entity. Else targets all.           |\n| `angle`                   |       no | Angle in degrees. Valid values are `30`, `60`, `90`, `120`, and `140`. |\n\n#### Service `xiaomi_miio_fan.fan_set_delay_off`\n\nSet the scheduled turn off time. Supported values are 0, 60, 120, 180, 240, 300, 360, 420, 480 minutes. When 0 is passed, delay_off is disabled.\n\n\n| Service data attribute    | Optional | Description                                                          |\n|---------------------------|----------|----------------------------------------------------------------------|\n| `entity_id`               |      yes | Only act on a specific xiaomi miio entity. Else targets all.         |\n| `delay_off_countdown`     |       no | Time in minutes. Valid values are `0`, `60`, `120`, `180`, `240`, `300`, `240`, `300`, `360`, `420`, `480` minutes. |\n\n#### Service `xiaomi_miio_fan.fan_set_natural_mode_on`\n\nTurn the natural mode on.\n\n| Service data attribute    | Optional | Description                                                          |\n|---------------------------|----------|----------------------------------------------------------------------|\n| `entity_id`               |      yes | Only act on a specific xiaomi miio entity. Else targets all.         |\n\n#### Service `xiaomi_miio_fan.fan_set_natural_mode_off`\n\nTurn the natural mode off.\n\n| Service data attribute    | Optional | Description                                                          |\n|---------------------------|----------|----------------------------------------------------------------------|\n| `entity_id`               |      yes | Only act on a specific xiaomi miio entity. Else targets all.         |\n\n#### Service `xiaomi_miio_fan.fan_set_buzzer_on`\n\nTurn the buzzer on.\n\n| Service data attribute    | Optional | Description                                                          |\n|---------------------------|----------|----------------------------------------------------------------------|\n| `entity_id`               |      yes | Only act on a specific xiaomi miio entity. Else targets all.         |\n\n#### Service `xiaomi_miio_fan.fan_set_buzzer_off`\n\nTurn the buzzer off.\n\n| Service data attribute    | Optional | Description                                                          |\n|---------------------------|----------|----------------------------------------------------------------------|\n| `entity_id`               |      yes | Only act on a specific xiaomi miio entity. Else targets all.         |\n\n#### Service `xiaomi_miio_fan.fan_set_child_lock_on`\n\nTurn the child lock on.\n\n| Service data attribute    | Optional | Description                                                          |\n|---------------------------|----------|----------------------------------------------------------------------|\n| `entity_id`               |      yes | Only act on a specific xiaomi miio entity. Else targets all.         |\n\n#### Service `xiaomi_miio_fan.fan_set_child_lock_off`\n\nTurn the child lock off.\n\n| Service data attribute    | Optional | Description                                                          |\n|---------------------------|----------|----------------------------------------------------------------------|\n| `entity_id`               |      yes | Only act on a specific xiaomi miio entity. Else targets all.         |\n\n#### Service `xiaomi_miio_fan.fan_set_led_brightness`\n\nSet the led brightness. Supported values are 0 (Bright), 1 (Dim), 2 (Off).\n\n| Service data attribute    | Optional | Description                                                          |\n|---------------------------|----------|----------------------------------------------------------------------|\n| `entity_id`               |      yes | Only act on a specific xiaomi miio entity. Else targets all.         |\n| `brightness`              |       no | Brightness, between 0 and 2.                                         |\n\n#### Service `xiaomi_miio_fan.fan_set_anion_on`\n\nTurn the ionizer on.\n\n| Service data attribute    | Optional | Description                                                          |\n|---------------------------|----------|----------------------------------------------------------------------|\n| `entity_id`               |      yes | Only act on a specific xiaomi miio entity. Else targets all.         |\n\n#### Service `xiaomi_miio_fan.fan_set_anion_off`\n\nTurn the ionizer off.\n\n| Service data attribute    | Optional | Description                                                          |\n|---------------------------|----------|----------------------------------------------------------------------|\n| `entity_id`               |      yes | Only act on a specific xiaomi miio entity. Else targets all.         |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyssi%2Fxiaomi_fan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsyssi%2Fxiaomi_fan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyssi%2Fxiaomi_fan/lists"}