Mi Cloud Connect Library

Common errors

• ModuleNotFoundError: No module named 'micloud'

  cause The `micloud` package is not installed in your current Python environment.
  fix Install the package using pip: `pip install micloud`

• micloud.exceptions.MiCloudAccessDenied: Invalid credentials

  cause The provided username (email/phone) or password for your Xiaomi account is incorrect.
  fix Double-check your Xiaomi account credentials for typos or ensure the account exists and is active. You might also try logging in via the official Xiaomi Home app or website to confirm.

• micloud.exceptions.MiCloudException: Unexpected response from server: HTTP 403 (or 'No devices found' when devices are expected)

  cause This often indicates that the specified server region does not match the region your Xiaomi account is registered in. The default server is 'de'.
  fix When initializing `MiCloud`, explicitly set the `server` parameter to your account's region (e.g., 'cn', 'us', 'ru', 'de'): `micloud = MiCloud(username, password, server='cn')`

Warnings

• breaking As of v0.4, failed login attempts due to invalid credentials now raise a specific `MiCloudAccessDenied` exception. Code that previously caught generic exceptions for authentication failures might need an update.
  Fix: Update your error handling to catch `micloud.exceptions.MiCloudAccessDenied` specifically when dealing with login failures.
• gotcha The `MiCloud` constructor defaults the `server` parameter to 'de' (Germany). If your Xiaomi account is registered to a different region (e.g., US, CN, RU), you must explicitly specify it, or you may encounter 'no devices found' or login issues.
  Fix: Pass the correct server region to the `MiCloud` constructor: `MiCloud(username, password, server='cn')`. Common server codes include 'cn' (China), 'us' (USA), 'ru' (Russia), 'de' (Germany).
• gotcha Versions prior to 0.5 may experience issues with ARC4 encryption, potentially leading to connection failures or incorrect data for some devices or specific API calls.
  Fix: Upgrade to `micloud` version 0.5 or newer to ensure correct encryption handling: `pip install --upgrade micloud`.

Install

• pip install micloud Install latest version

Imports

• MiCloud

  from micloud import MiCloud

• MiCloudAccessDenied

  from micloud.exceptions import MiCloudAccessDenied

Quickstart

This quickstart logs into the Xiaomi Cloud using environment variables for credentials and then retrieves a list of connected devices. It's crucial to specify the correct `server` region matching your Xiaomi account.

import os
from micloud import MiCloud

# It's highly recommended to specify your server region explicitly.
# Common regions: 'de' (Germany, default), 'cn' (China), 'us' (USA), 'ru' (Russia).
# Replace with the region your Xiaomi account is registered in.
MI_CLOUD_SERVER = os.environ.get('MI_CLOUD_SERVER', 'de') 
MI_CLOUD_USERNAME = os.environ.get('MI_CLOUD_USERNAME', 'your_email@example.com')
MI_CLOUD_PASSWORD = os.environ.get('MI_CLOUD_PASSWORD', 'your_password')

try:
    micloud = MiCloud(MI_CLOUD_USERNAME, MI_CLOUD_PASSWORD, server=MI_CLOUD_SERVER)
    micloud.login()
    print(f"Successfully logged in to Xiaomi Cloud (server: {MI_CLOUD_SERVER}).")
    
    devices = micloud.get_devices()
    if devices:
        print(f"Found {len(devices)} devices:")
        for device in devices:
            print(f"  - Name: {device.get('name', 'N/A')}, Model: {device.get('model', 'N/A')}, ID: {device.get('did', 'N/A')}")
    else:
        print("No devices found associated with this account and server.")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please check your credentials, server region, and network connection.")