xmihome/README.md

The core library for interacting with Xiaomi Mi Home devices via Cloud, MiIO, and Bluetooth.

# xmihome

[[RU]](./docs/ru/README.md) | [EN]

**A Node.js library for controlling Xiaomi Mi Home devices.**

`xmihome` provides a simple and convenient interface for interacting with
various Xiaomi Mi Home smart devices through Node.js. The library supports
multiple connection types, including MiIO, Bluetooth, and the Xiaomi
cloud, allowing you to integrate Xiaomi devices into your Node.js
applications.

This package is the core dependency for
[`node-red-contrib-xmihome`](https://www.npmjs.com/package/node-red-contrib-xmihome).

## Features

- **Multiple Connection Types:**
  - **MiIO:** Direct local control via the MiIO protocol (token + IP
    address).
  - **Bluetooth:** Control Bluetooth LE devices (MAC address + model).
  - **Xiaomi Cloud:** Control via the Xiaomi cloud (login/password +
    device ID).
- **Automatic Connection Type Detection:** The library automatically
  determines the connection type for an *individual* device based on the
  provided configuration data.
- **Customizable Device Discovery:**
  - Get a list of devices from the Xiaomi cloud.
  - Scan for MiIO devices on the local network.
  - Scan for Bluetooth LE devices.
- **Dynamic Device Support and Extensibility:**
  - The library can interact with **most Xiaomi Mi Home devices**, even if
    there is no specific definition file for them.
  - Definition files provide **optimized support** for specific models,
    including user-friendly property names and specific logic.
  - Easily add support for new devices.
- **Bluetooth LE Support on Linux:** Includes automatic installation of
  `dbus-next` and generation of a configuration file to resolve Bluetooth
  permission issues.

## Installation

```bash
npm install xmihome
```

**Important for Linux users with Bluetooth:**

During installation, the library will automatically check for a Bluetooth
adapter and install `dbus-next` if necessary.

If you are not a root user, a Bluetooth configuration file
`xmihome_bluetooth.conf` will be created in the `node_modules/xmihome/`
directory during installation.

For Bluetooth LE functions to work correctly, you may need to copy this file
to the system's D-Bus directory and restart the service:

```bash
sudo cp node_modules/xmihome/xmihome_bluetooth.conf /etc/dbus-1/system.d/
sudo systemctl restart bluetooth
```

## Usage

```javascript
import { XiaomiMiHome } from 'xmihome';

async function main() {
  const miHome = new XiaomiMiHome({
    credentials: {
      username: process.env.XIAOMI_USERNAME,
      password: process.env.XIAOMI_PASSWORD,
      country: 'sg'
    },
    connectionType: 'cloud',
    logLevel: 'error'
  });

  try {
    const devices = await miHome.getDevices({
      timeout: 30000,
      onDeviceFound: (device, devices, type) => {
        // Return true to include the device, false to ignore, or
        // an object { include?: boolean, stop?: boolean } to control discovery.
        return true;
      }
    });
    console.log('Found devices:', devices);

    if (devices.length === 0)
      throw new Error('Device not found');

    // Select a device to control
    const device = await miHome.getDevice(devices[0]);

    // Connect to the device (connection type will be determined automatically)
    await device.connect();
    console.log(`Connected to "${device.getName()}" via: ${device.connectionType}`);

    // Get the current properties of the device
    const properties = await device.getProperties();
    console.log('Current properties:', properties);

    // Set a new property value
    if (!properties.on) {
      await device.setProperty('on', true);
      console.log('Device turned on');
    }

    // Disconnect from the device
    await device.disconnect();
    console.log('Disconnected from device');

  } catch (error) {
    console.error('Error:', error);
  } finally {
    // Release resources
    miHome.destroy();
  }
}

main();
```

## Command-Line Interface (CLI)

To simplify initial setup, authentication, and device discovery, the
project includes a convenient command-line interface (CLI). It allows you
to easily log into the Xiaomi Cloud and get a list of your devices
without writing any code, which can be useful for obtaining tokens or
device IDs.

[**→ Read more about all commands and features in the CLI documentation**](./docs/en-US/CLI.md)

## Configuration

The configuration object passed to the `XiaomiMiHome` constructor can
contain:

- **`credentials`:** Xiaomi cloud connection credentials.
  - `username` (string): Xiaomi account username.
  - `password` (string): Xiaomi account password.
  - `country` (string): Xiaomi account region (e.g., 'ru', 'cn', 'us').
- **`devices` (array of objects):** An array of objects with device
  information. Used to provide static information about devices or to
  specify tokens for MiIO devices.
  - `id` (string): Device ID in the Xiaomi cloud (for cloud connection).
  - `address` (string): Device IP address (for MiIO connection).
  - `token` (string): Device token (for MiIO connection).
  - `mac` (string): Device MAC address (for Bluetooth connection).
  - `model` (string): Device model (e.g., 'deerma.humidifier.jsq2w').
  - `name` (string, optional): Device name (for convenience).
- **`connectionType` (string):** Defines the **device discovery method**
  when calling `getDevices()` and the **default connection type** when
  calling `device.connect()` without explicitly specifying a type.
  - **When calling `getDevices()`:**
    - `'cloud'`: Search for devices only in the Xiaomi cloud (requires
      `credentials`).
    - `'miio'`: Search for devices only via MiIO on the local network.
    - `'bluetooth'`: Search for devices only via Bluetooth.
    - *Not specified (default):* If `credentials` are present, searches
      in the cloud. If `credentials` are not present, performs a
      combined MiIO + Bluetooth search.
  - **When calling `device.connect()` without an argument:** Used as the
    preferred connection type if it matches the device data (e.g., if
    `connectionType: 'miio'`, the device must have `address` and `token`).
- **`logLevel`**: Logging level (`'none'`, `'error'`, `'warn'`,
  `'info'`, `'debug'`).

## API Reference

For detailed information about classes and methods, see the full API
documentation:

- [**XiaomiMiHome**](./docs/en-US/api/XiaomiMiHome.md) - The main class
  for managing connections and devices.
- [**Device**](./docs/en-US/api/Device.md) - The base class for all
  devices, providing methods for connecting, getting/setting properties,
  etc.
- [**Miot**](./docs/en-US/api/Miot.md) - The class for working with Cloud
  and MiIO protocols.
- [**Bluetooth**](./docs/en-US/api/Bluetooth.md) - The class for working
  with Bluetooth LE at a low level.

## How to Add Support for New Devices

If your Xiaomi Mi Home device is not on the list of devices with optimized
support, you can still try to control it using `xmihome`.

To **improve support** and add user-friendly property names for your device,
you can:

1.  **Investigate your device's specification:** Look for information about
    the MiIO protocol or Bluetooth GATT services and characteristics that
    your device uses. [Miot-spec.org](https://miot-spec.org/) can be a
    useful resource.
2.  **Create a device definition file:** Create a new `.js` file in the
    `packages/devices/src/devices/` directory, based on the example of
    existing files.
3.  **Define static properties:** Fill in `static name`, `static models`,
    `static properties`, and `static actions` according to your device's
    specification.
4.  **Submit a Pull Request:** If you want to share your work with the
    community, submit a Pull Request to the `xmihome` GitHub repository with
    your device definition file.

## Logging

The library supports two logging methods:

1.  **Environment variable `NODE_DEBUG=xmihome`** for detailed output via
    `util.debuglog`.
2.  **Constructor option `logLevel`** for output to the `console`.