AUX Cloud Integration for Home Assistant

Warning

This integration is currently a work in progress. Some features may not be fully implemented or stable.

Unofficial integration for Aux Cloud connected appliances like air conditioners and heat pumps. Aux Cloud is a service based on the Broadlink platform that allows you to control your appliances from anywhere. This is a cloud alternative to replacing wifi module in your AC. This integration will also allow you to control AUX heat pumps. The implementation of API requests are based on public resources from Broadlink documentation and reverse engineering.

Features

• Control AUX air conditioners and heat pumps from Home Assistant
• View device status and sensor readings
• Support for both personal and shared devices
• Secure credential storage(when configured through UI)

Installation

HACS Installation (Recommended)

1. Make sure you have HACS installed
2. Go to HACS > Integrations
3. Click the "+" button and search for "AUX Cloud"

Note

The integration is not available in HACS yet. You can install it by adding custom repository instead.

4. Install the integration
5. Restart Home Assistant

Manual Installation

1. Download this repository
2. Copy the custom_components/aux_cloud folder to your Home Assistant custom_components directory
3. Restart Home Assistant

Configuration

UI Configuration (Recommended)

The recommended way to set up this integration is through the Home Assistant UI:

1. Go to Settings > Devices & Services
2. Click the + Add Integration button
3. Search for "AUX Cloud" and select it
4. Enter your AUX Cloud email and password
5. Select your region (e.g., Europe, USA or China - based on your AUX Cloud account)
6. Select which devices you want to add to Home Assistant

Tip

Make sure that your devices are online when setting up the integration. If you add a device that is offline, it will not add all the entities. You will need to reload the integration manually.

Your credentials will be stored securely in Home Assistant's .storage/core.config_entries storage.

Usage

After setting up the integration, your AUX devices will be available as climate entities in Home Assistant. You can control them through:

• The Home Assistant UI
• Automations
• Scripts
• Voice assistants integrated with Home Assistant

Troubleshooting

If you encounter issues:

1. Check the Home Assistant logs for error messages
2. Verify your AUX Cloud credentials and selected region are correct
3. Ensure your devices are online and accessible through the AUX Cloud app
4. If you've recently changed your password, you'll need to reconfigure the integration

Known Issues

• Logging in in the App: The login process in the app will log out any existing sessions (at least on Android). If you log in the app, reload the integration.

Note

There are plans to implement automatic relogging if the request fails due to session expiry.

• Shared devices: If your account have shared devices, you might encounter an issue that Platform aux_cloud does not generate unique ids, check your HA logs and transfer ownership of the device to your account.

Development

This integration is still in development. Current status:

• Reverse engineer the AUX Cloud API
• [API] Implement login
• [API] Implement getting devices information
• [Home Assistant] Config flow with device selection
• [API] Implement updating device state
• [Home Assistant] Cloud data fetcher
• [Home Assistant] Data coordinator
• [Home Assistant] climate entity
• [Home Assistant] sensor entity
• [Home Assistant] water heater entity
• [Home Assistant] basic sensor entities
• [Home Assistant] switch entity
• [Home Assistant] Fix reconfigure - adding new devices requires reload of integration
• [Home Assistant] Parallelize data fetching for devices - don't wait for one device to finish before starting another
• [Home Assistant] Add icon to https://github.com/home-assistant/brands
• [API] Implement session check and re-login
• [Home Assistant] services
• [Home Assistant] Manual tests
• [Home Assistant] Unit tests
• [API] WebSocket connection for instant updates
• Documentation
• Add to HACS
• Translations

Privacy

This integration communicates with the AUX Cloud servers but stores your credentials locally in Home Assistant's internal storage (when configured through the UI). No data is shared with third parties beyond what's necessary to communicate with AUX Cloud services.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Testing

This document describes how to run tests and perform code quality checks for the AUX Cloud Integration.

Prerequisites

Before running tests, ensure you have all the required dependencies installed:

pip install -r requirements.test.txt

Running Tests with pytest

Basic Test Run

Run all tests:

pytest

Test with Coverage Reporting

Run tests and show coverage information:

pytest --cov=custom_components

Additional Testing Options

Run specific test file:

pytest tests/test_init.py

Code Quality Checks with pylint

Basic pylint Check

Run pylint on the entire component:

pylint custom_components/aux_cloud

Targeted pylint Checks

Check a specific file:

pylint custom_components/aux_cloud/api/aux_cloud.py

Set a minimum score threshold (useful for CI/CD):

pylint --fail-under=8.0 custom_components/aux_cloud

Code formatting

The project uses Black for code formatting. To format the code, run:

black custom_components/aux_cloud