xmihome

[RU] | [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.

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

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:

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

Usage

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

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 - The main class for managing connections and devices.
• Device - The base class for all devices, providing methods for connecting, getting/setting properties, etc.
• Miot - The class for working with Cloud and MiIO protocols.
• Bluetooth - 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 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.