{"id":34656927,"url":"https://github.com/cmgrayb/hass-dyson","last_synced_at":"2026-04-18T07:04:02.918Z","repository":{"id":311502163,"uuid":"1043356454","full_name":"cmgrayb/hass-dyson","owner":"cmgrayb","description":"Unofficial Dyson integration, focusing on device capabilities and connection information to maximize compatibility","archived":false,"fork":false,"pushed_at":"2026-04-13T02:11:24.000Z","size":3181,"stargazers_count":52,"open_issues_count":5,"forks_count":6,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-13T02:25:31.987Z","etag":null,"topics":["air-purifier","custom-component","dyson","hacs","home-assistant","integration","iot","mqtt","python","smart-home"],"latest_commit_sha":null,"homepage":"","language":"Python","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/cmgrayb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"docs/SUPPORTED_DEVICES.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"cmgrayb"}},"created_at":"2025-08-23T17:21:12.000Z","updated_at":"2026-04-13T00:00:39.000Z","dependencies_parsed_at":"2026-01-17T01:02:18.456Z","dependency_job_id":null,"html_url":"https://github.com/cmgrayb/hass-dyson","commit_stats":null,"previous_names":["cmgrayb/ha-dyson-alt","cmgrayb/hass-dyson"],"tags_count":152,"template":false,"template_full_name":null,"purl":"pkg:github/cmgrayb/hass-dyson","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmgrayb%2Fhass-dyson","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmgrayb%2Fhass-dyson/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmgrayb%2Fhass-dyson/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmgrayb%2Fhass-dyson/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cmgrayb","download_url":"https://codeload.github.com/cmgrayb/hass-dyson/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmgrayb%2Fhass-dyson/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31959886,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"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":["air-purifier","custom-component","dyson","hacs","home-assistant","integration","iot","mqtt","python","smart-home"],"created_at":"2025-12-24T18:22:27.793Z","updated_at":"2026-04-18T07:04:02.907Z","avatar_url":"https://github.com/cmgrayb.png","language":"Python","funding_links":["https://github.com/sponsors/cmgrayb"],"categories":[],"sub_categories":[],"readme":"# Dyson Integration for Home Assistant\r\n\r\n\u003cp align=\"center\"\u003e\r\n  \u003cimg src=\"https://raw.githubusercontent.com/cmgrayb/hass-dyson/main/custom_components/hass_dyson/brand/logo.png\" alt=\"Dyson Logo\" width=\"400\"/\u003e\r\n\u003c/p\u003e\r\n\r\n\r\n\u003c!-- Badge Links --\u003e\r\n\r\n[releases-shield]: https://img.shields.io/github/release/cmgrayb/hass-dyson.svg?style=for-the-badge\r\n[releases]: https://github.com/cmgrayb/hass-dyson/releases\r\n[commits-shield]: https://img.shields.io/github/commit-activity/y/cmgrayb/hass-dyson.svg?style=for-the-badge\r\n[commits]: https://github.com/cmgrayb/hass-dyson/commits/main\r\n[hacs]: https://github.com/hacs/integration\r\n[hacsbadge]: https://img.shields.io/badge/HACS-Default-41BDF5.svg?style=for-the-badge\r\n[license-shield]: https://img.shields.io/github/license/cmgrayb/hass-dyson.svg?style=for-the-badge\r\n[codecov-shield]: https://img.shields.io/codecov/c/github/cmgrayb/hass-dyson?token=AG0CK5SE4R\u0026style=for-the-badge\r\n[codecov]: https://codecov.io/github/cmgrayb/hass-dyson\r\n\r\n[![GitHub Release][releases-shield]][releases]\r\n[![GitHub Activity][commits-shield]][commits]\r\n[![License][license-shield]](LICENSE)\r\n[![hacs][hacsbadge]][hacs]\r\n[![Codecov][codecov-shield]][codecov]\r\n\r\nA core-ready Home Assistant integration for Dyson air purifiers, heaters, humidifiers, fans, and robotic vacuums featuring real-time MQTT communication and complete platform coverage.\r\n\r\n## Current Features\r\n\r\n### All Supported Devices\r\n\r\n- **Cloud Discovery** - Automatic device detection via Dyson API\r\n- **Manual Setup** - Sticker-based or network-isolated configuration for local devices\r\n- **Static IP Configuration** - Bypass mDNS with static IP/hostname for reliable connectivity\r\n- **Capability Based Detection** - Automatic platform setup based on device features\r\n\r\n### Environmental Cleaners (Fans/Purifiers)\r\n\r\n- **Fan Control** - Speed adjustment (1-10), on/off, night mode\r\n- **Air Quality Monitoring** - PM2.5, PM10, real-time sensor data\r\n- **Smart Controls** - Auto mode, oscillation\r\n- **Status Monitoring** - Connectivity, filter life, fault detection, firmware version\r\n- **Precise Adjustments** - Timers, oscillation angles\r\n- **Heating Support** - Climate Control with Heater mode, Heater Thermostat, and Fan Direction\r\n- **Humidifier Support** Humidifier entity with set point, current level and empty tank alerts\r\n- **Climate Control** - Climate Control with Humidistat (Experimental)\r\n\r\n### Robotic Vacuums\r\n\r\n- **Mid-run Controls** - Pause, Resume, and Stop (Return to Dock)\r\n- **Vacuum Status** - Battery level, Unique Identifier for Current Cleaning Session (for future use)\r\n\r\n## Planned Features\r\n\r\n### BLE Devices\r\n\r\n- **lec Support** - We hope to someday support Dyson \"lec\" or BLE devices such as lights via BLE proxy devices\r\n- **Vacuum Start Controls** - Support the start in room functionality introduced in Home Assistant 2026.2.0 as well as \"global\" (all defined rooms)\r\n\r\n## Quick Start\r\n\r\n### Installation\r\n\r\n1. **Install Integration via HACS**\r\n   - Open **HACS** in Home Assistant\r\n   - Search for \"**Dyson**\"\r\n   - Click **Download**\r\n   - Restart Home Assistant\r\n\r\n   \u003e **Can't find it?** If the integration does not appear in HACS search, you can add it manually as a custom repository:\r\n   \u003e - Go to **Settings** (three dots menu) in HACS\r\n   \u003e - Select **Custom repositories**\r\n   \u003e - Add repository URL: `https://github.com/cmgrayb/hass-dyson`\r\n   \u003e - Select category: **Integration**\r\n   \u003e - Click **Add**, then search for and download **Dyson** as above\r\n\r\n### Setup\r\n\r\n1. Go to **Settings** → **Devices \u0026 Services** → **Add Integration**\r\n2. Search for \"**Dyson**\"\r\n3. Choose setup method:\r\n   - **Cloud Discovery** - Enter Dyson account credentials\r\n   - **Manual Setup** - Enter device details from sticker or information gained through the Get Cloud Devices Action, or external tooling such as libdyson-rest or opendyson\r\n\r\n## Configuration\r\n\r\n### Cloud Account Configuration (**Recommended**)\r\n\r\nWhen selecting **Cloud Discovery**, you'll be guided through the following steps:\r\n\r\n#### **Step 1: Account Credentials**\r\n\r\n- **Email or Mobile Number**: Your Dyson account email address or mobile number if in CN region\r\n- **Country**: Verify your country and culture (affects API region and localization)\r\n\r\n- **Password**: Your Dyson account password if using email\r\n- **OTP**: The one-time password sent to your email by Dyson if using email, or the one-time password sent to your mobile device if not\r\n\r\n#### **Step 2: Default Connection Method**\r\n\r\nChoose your preferred default connection method for your devices:\r\n\r\n- **Local Only**: Talks to the device only through the device's MQTT server\r\n  - Maximum privacy, can be used without internet access for the device\r\n  - Susceptible to local device MQTT server failures and mDNS resolution issues\r\n  - Note: This mode is most similar to the [ha-dyson](https://github.com/libdyson-wg/ha-dyson) integration\r\n  - When using this approach, we highly recommend assigning a DHCP reservation or using a static IP to minimize mDNS broadcast issues\r\n\r\n- **Local with Cloud Fallback**: Stays local until and unless the local server cannot be\r\n    reached, then reconnects to the device through the Dyson-hosted MQTT Proxy service.\r\n  - Balances privacy and uptime by only using cloud when necessary\r\n  - Attempts to reconnect to local periodically\r\n  - Allows the user to reconnect to local manually through the Reconnect button\r\n\r\n- **Cloud with Local Fallback**: Stays on the Dyson MQTT Proxy service until and unless\r\n    internet access is lost, then reconnects to the device directly\r\n  - Uses an encrypted connection as often as possible but switches to local to maintain connectivity in the event of internet outage\r\n  - Attempts to reconnect to cloud periodically\r\n  - Allows the user to reconnect to cloud manually through the Reconnect button\r\n\r\n- **Cloud Only**: Stays on the Dyson MQTT Proxy\r\n  - Useful for environments which cannot support mDNS\r\n  - Can be used to control Dyson devices on other networks for remote management\r\n  - All communication with the device is encrypted in transit\r\n\r\n**Note**: Each device may individually override its preferred connection method once discovered\r\n\r\n#### **Step 3: Device Discovery Configuration**\r\n\r\nChoose your preference for level of control of discovery:\r\n\r\n- **Poll for New Devices**: If selected, the API will be queried for new devices periodically, making them available for discovery\r\n- **Automatically Add Discovered Devices**: Uses the information from polling your Dyson account to connect to the devices using your Default Connection Method\r\n\r\nScenarios:\r\n\r\n1. I want my Dyson devices to show up in Home Assistant as soon as they are found\r\n    - Leave both checkboxes selected\r\n\r\n2. I want Home Assistant to ask me to add my devices as they are found so I can choose which ones to add or ignore\r\n    - Only select Poll for New Devices, leave Automatically Add Discovered Devices unchecked.\r\n\r\n3. I want to add my Dyson devices individually and manually or I am only interested in using the Get Cloud Devices Action\r\n    - Deselect both checkboxes\r\n    - For more information, see: [Actions](docs/ACTIONS.md)\r\n\r\n#### **Expected Entities Per Device**\r\n\r\nBased on your device capabilities and category, you'll automatically get:\r\n\r\n**All Devices (Basic Support):**\r\n\r\n- Basic binary sensors (online/offline, faults)\r\n\r\n**WiFi-Enabled Devices (EC/Robot Categories):**\r\n\r\n- Connection status sensor (Local/Cloud/Disconnected)\r\n- Reconnect button to attempt to re-establish preferred connectivity\r\n- WiFi signal strength sensor (diagnostic)\r\n- Temperature sensor\r\n- Humidity sensor\r\n- Carbon filter sensors\r\n- HEPA filter sensors\r\n\r\n**Air Quality Models (ExtendedAQ Capability):**\r\n\r\n- PM2.5 air quality sensor\r\n- PM10 air quality sensor\r\n- HEPA filter life sensor (%)\r\n- HEPA filter type sensor\r\n- Carbon filter life sensor (%)\r\n- Carbon filter type sensor\r\n- VOC sensor\r\n- NO2/NOx sensor\r\n- CO2 sensor\r\n- HCHO/Formaldehyde sensor\r\n\r\n**Heating models (Heating Capability):**\r\n\r\n- **Climate control platform**\r\n- **HVAC Controls**:\r\n  - Mode control: Heat/Fan only/Off\r\n  - Heat minimum temperature (thermostat)\r\n\r\n**Humidifier models (Humidifier Capability):**\r\n\r\n- **Climate control platform**\r\n- **Humidifier Controls**:\r\n  - Mode control: Humidify/Fan only/Off\r\n  - Humidifier minimum humidity (humidistat)\r\n  - Empty tank diagnostic sensor\r\n\r\n**Robotic Vacuum models (Robot Category) (360/Heurist/Vis Nav, etc.)**:\r\n\r\n- **Vacuum platform**\r\n  - **Mid-run Controls** - Pause, Resume, and Stop (Return to Dock)\r\n  - **Vacuum Status** - Battery level, Unique Identifier for Current Cleaning Session\r\n\r\n\r\n#### **Setup Time**\r\n\r\n- **Initial connection**: 10-30 seconds\r\n- **Device discovery**: 5-15 seconds per device\r\n- **Entity creation**: Values may take a minute or two to show up after new device creation or boot\r\n\r\n#### **Troubleshooting Cloud Setup**\r\n\r\n- **Invalid credentials**: Verify email/password and account region\r\n- **No devices found**: Ensure devices are registered in Dyson app\r\n- **Connection timeout**: Check internet connection and Dyson API status\r\n- **Partial device data**: Some devices may need additional setup time\r\n\r\n### Manual/Sticker Setup (Advanced Use Case such as isolated network)\r\n\r\n**Please note: some features (like Firmware version) will not work without access to the Cloud API**\r\n\r\nRequired information from device sticker, libdyson-rest, or opendyson:\r\n\r\n- **Serial Number** (e.g., MOCK-SERIAL-TEST123)\r\n- **Device Password** (from sticker)\r\n- **MQTT Prefix** (e.g., 438M for Pure Cool models)\r\n- **Device Type** (e.g., EC for air purifiers)\r\n\r\n### YAML Configuration (Optional, **Not** Recommended)\r\n\r\n```yaml\r\nhass_dyson:\r\n  devices:\r\n    - serial_number: \"MOCK-SERIAL-TEST123\"\r\n      discovery_method: \"sticker\"\r\n      hostname: \"192.168.1.100\" # Optional: IP address\r\n      credential: \"your_device_password\"\r\n      device_type: \"ec\"\r\n      mqtt_prefix: \"438M\"\r\n      capabilities: [\"AdvanceOscillationDay1\", \"Scheduling\", \"ExtendedAQ\"]\r\n```\r\n\r\n## Documentation\r\n\r\n### **Additional Information**\r\n\r\n- **[Actions](docs/ACTIONS.md)** - Information on included Home Assistant Actions\r\n- **[Controls](docs/CONTROLS.md)** - Information on included controls for devices\r\n- **[Device Compatibility Matrix](docs/DEVICE_COMPATIBILITY.md)** - Complete breakdown of which entities are available for each device type and capability\r\n- **[Device Management](docs/DEVICE_MANAGEMENT.md)** - Information on device discovery and configuration\r\n- **[Entities](docs/ENTITIES.md)** - Information on entities to expect for a given device type\r\n- **[Sensors](docs/SENSORS.md)** - Information on included sensors for devices\r\n- **[Supported Devices](docs/SUPPORTED_DEVICES.md)** - Information on devices tested and known to be supported\r\n\r\n### **Quick References**\r\n\r\n- **[Setup Guide](docs/SETUP.md)** - Detailed installation and configuration instructions\r\n- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Troubleshooting Guide\r\n\r\n### **For Developers**\r\n\r\n- **[API Documentation](docs/API.md)** - Comprehensive API documentation with code examples and usage patterns for developers\r\n- **[Developers Guide](docs/DEVELOPERS_GUIDE.md)** - See something you can help with?  This is where to start!\r\n- **[Integration Flow Diagrams](docs/INTEGRATION_FLOW.md)** - Visual flow diagrams showing the integration architecture and operation\r\n\r\n## Requirements\r\n\r\n- **Home Assistant** 2025.12+\r\n- **Python** 3.11+\r\n- **Dependencies** (auto-installed):\r\n  - `libdyson-rest\u003e=0.12.1`\r\n  - `paho-mqtt\u003e=2.1.0`\r\n  - `cryptography\u003e=45.0.7`\r\n\r\n## Acknowledgments\r\n\r\n- **libshenxn** - For getting the Dyson community started with the original libdyson\r\n- **dotvezz** - For maintaining the libdyson-wg working group, ha-dyson, and opendyson, the inspiration for this integration\r\n- **libdyson-wg** - For maintaining excellent documentation and tooling without which this integration would not have been possible\r\n- **paho-mqtt** - Reliable MQTT communication library\r\n- **Home Assistant** - Amazing home automation platform\r\n- **Dyson** - For making great products worth putting in the work for\r\n\r\n## Star History\r\n\r\n[![Star History Chart](https://api.star-history.com/svg?repos=cmgrayb/hass-dyson\u0026type=date\u0026legend=top-left)](https://www.star-history.com/#cmgrayb/hass-dyson\u0026type=date\u0026legend=top-left)\r\n\r\nIf you like our work, please give us a star!\r\n\r\n## Sponsorship\r\n\r\nThis integration is provided free of charge and there is no requirement expressed or implied to donate.  Any money contributed through the sponsorship button as a gift goes to development devices to further improve this integration.\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n---\r\n\r\n**⚠️ Disclaimer**: This is an unofficial integration not affiliated with Dyson Ltd. Use at your own risk.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmgrayb%2Fhass-dyson","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcmgrayb%2Fhass-dyson","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmgrayb%2Fhass-dyson/lists"}