node-red-contrib-mi-fan

Node-RED nodes for controlling Xiaomi Mi Smart Fans over the local network using the MIoT protocol.

Built on top of the excellent xmihome library.

Installation

Install via the Node-RED Manage Palette menu, or run:

cd ~/.node-red
npm install node-red-contrib-mi-fan

Requirements

• Node.js >= 18.0.0
• Node-RED >= 4.0.0
• A Xiaomi Mi Smart Fan on the same local network
• The fan's device token (see Getting the Token)

Nodes

Fan Out (mi-fan)

Sends commands to a Xiaomi Mi Smart Fan. Set msg.payload to an object with one or more of the following properties:

| Property | Type | Values | Description | |---|---|---|---| | power | boolean | true / false | Turn the fan on or off | | mode | string | "straight", "natural" | Wind mode | | fanLevel | number | 1–4 | Fan level preset | | fanSpeed | number | 1–100 | Fan speed percentage | | swingMode | boolean | true / false | Oscillation on/off | | swingModeAngle | number | 30, 60, 90, 120, 140 | Oscillation angle in degrees | | childLock | boolean | true / false | Child lock on/off | | buzzer | boolean | true / false | Buzzer on/off | | light | boolean | true / false | LED indicator on/off | | setMove | string | "left", "right" | Nudge the fan head |

Only include the properties you want to change — omitted properties are left untouched. The message is passed through on success, so you can chain multiple nodes together.

Fan In (mi-fan-status)

Queries all current properties from the fan. Send any message to trigger a status request. The node replaces msg.payload with an object containing all readable properties:

power, mode, fanLevel, fanSpeed, swingMode, swingModeAngle, childLock, buzzer, light, powerOffTime

Mi Fan Config (mi-fan-config)

Shared configuration node used by both Fan Out and Fan In. Stores:

• IP Address — the fan's local IP
• Token — the device token (encrypted by Node-RED's credential system)
• Model — the fan model identifier

Getting the Token

Every Xiaomi MiIO device requires a device token for local communication. The config node includes a built-in Scan Network feature that makes this easy:

1. Open any Fan Out or Fan In node and click the edit button next to the config
2. Click Scan Network — this discovers all Xiaomi MiIO devices on your local network
3. Devices are shown in a list; fans are highlighted with a green badge
4. If the device token was obtained during discovery, click Use to auto-fill the IP and token
5. If the token is blanked out (this is common), click Get Token to retrieve it from the Xiaomi Cloud
6. Enter your Mi Home account credentials and select your region (de, us, cn, sg, in, ru, tw)
7. If your account has two-factor authentication enabled, you will be prompted for the verification code

[!IMPORTANT] Your Mi Home credentials are used once for the cloud request and are never stored. Only the retrieved device token is saved, encrypted by Node-RED's credential system.

Alternative Methods

• xmihome CLI — Run npx xmihome to discover devices and retrieve tokens from the command line
• Manual entry — If you already know your fan's IP and token, enter them directly in the config node

Example Flow

Import this flow into Node-RED to get started quickly:

[
    {
        "id": "a1b2c3d4e5f60001",
        "type": "inject",
        "z": "a1b2c3d4e5f60000",
        "name": "Fan On – Natural 50%",
        "props": [{ "p": "payload" }],
        "repeat": "",
        "payload": "{\"power\":true,\"fanSpeed\":50,\"mode\":\"natural\"}",
        "payloadType": "json",
        "x": 190,
        "y": 100,
        "wires": [["a1b2c3d4e5f60002"]]
    },
    {
        "id": "a1b2c3d4e5f60002",
        "type": "mi-fan",
        "z": "a1b2c3d4e5f60000",
        "name": "",
        "fan": "a1b2c3d4e5f60010",
        "x": 430,
        "y": 100,
        "wires": [[]]
    },
    {
        "id": "a1b2c3d4e5f60003",
        "type": "inject",
        "z": "a1b2c3d4e5f60000",
        "name": "Get Status",
        "props": [{ "p": "payload" }],
        "repeat": "",
        "payload": "{}",
        "payloadType": "json",
        "x": 170,
        "y": 220,
        "wires": [["a1b2c3d4e5f60004"]]
    },
    {
        "id": "a1b2c3d4e5f60004",
        "type": "mi-fan-status",
        "z": "a1b2c3d4e5f60000",
        "name": "",
        "fan": "a1b2c3d4e5f60010",
        "x": 370,
        "y": 220,
        "wires": [["a1b2c3d4e5f60005"]]
    },
    {
        "id": "a1b2c3d4e5f60005",
        "type": "debug",
        "z": "a1b2c3d4e5f60000",
        "name": "Fan Status",
        "active": true,
        "tosidebar": true,
        "console": false,
        "tostatus": false,
        "complete": "payload",
        "x": 570,
        "y": 220,
        "wires": []
    },
    {
        "id": "a1b2c3d4e5f60010",
        "type": "mi-fan-config",
        "name": "Living Room Fan",
        "ip": "192.168.1.42",
        "model": ""
    }
]

[!TIP] After importing, double-click the Living Room Fan config node to set your fan's actual IP address and token.

Credits

All Xiaomi device communication — local MiIO protocol, cloud authentication, device discovery, and MIoT spec support — is provided by the excellent xmihome library.

Dependencies

• xmihome — Xiaomi MiIO/MIoT device communication
• zod — Runtime type validation

License

MIT