Homebridge-xiaomi-plant-monitor-improved NPM

Homebridge Xiaomi Plant Monitor (Improved)

A robust Homebridge plugin for Xiaomi Mi Flora plant sensors with improved Bluetooth connectivity and reliability

Acknowledgments

This plugin is a fork of the original homebridge-xiaomi-plant-monitor with improvements to Bluetooth connectivity, device discovery, and error handling.

Overview

This Homebridge plugin integrates Xiaomi Mi Flora plant sensors (also known as Flower Care, Flower Mate, or Flower Monitor) with HomeKit, allowing you to monitor your plants' health directly from the Home app on your Apple devices.

This improved version features enhanced Bluetooth connectivity, robust error handling, and better device discovery - making it more reliable, especially in challenging environments with weak Bluetooth signals.

Key Features

Core Functionality

Automatic Discovery: Finds your Mi Flora sensors on the network
Multiple Sensor Types:
- Moisture level (displayed as humidity in HomeKit)
- Battery level with low battery alerts
- Temperature readings
- Light level measurements
- Soil fertility (conductivity) data

Improved Reliability

Enhanced Bluetooth Connectivity:
- Robust retry logic with exponential backoff
- Better handling of weak Bluetooth signals
- Graceful degradation when devices can't be reached
Manual Device Configuration: Option to specify device addresses directly
Comprehensive Error Handling: Prevents plugin crashes due to connectivity issues

Developer-Friendly

TypeScript Implementation: Improved type safety and code quality
Extensive Documentation: Clear setup and troubleshooting guides
Regular Updates: Maintained for compatibility with latest Homebridge versions

System Requirements

Homebridge: v1.4.0 or newer
Node.js: v16 or newer
Bluetooth: Hardware support required

Platform-Specific Prerequisites

Linux (Ubuntu/Debian/Raspbian)

sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev

macOS

No additional dependencies required, but you must ensure Bluetooth is enabled in System Settings.

Windows

No additional dependencies required, but you must ensure Bluetooth is enabled in Settings.

Raspberry Pi Specific Notes

If running on a Raspberry Pi:

Ensure your Raspberry Pi has Bluetooth capability (built-in on Pi 3/4/5)
Position the Pi within reasonable proximity to your plant sensors
Consider using a USB Bluetooth adapter if signal strength is poor

Installation

Via Homebridge UI (Recommended)

Open your Homebridge UI dashboard
Navigate to the "Plugins" tab
Search for "xiaomi plant monitor improved"
Click "Install"

Via Command Line

npm install -g homebridge-xiaomi-plant-monitor-improved

Configuration

Basic Configuration

Add the platform to your Homebridge config.json file:

"platforms": [
    {
        "platform": "xiaomi-plant-monitor",
        "name": "Plant Monitor",
        "fetchDataIntervalInMs": 3600000,
        "displayTemperature": true,
        "displayLightLevel": true,
        "displayFertility": true,
        "lowBatteryThreshold": 10
    }
]

Manual Device Configuration (Recommended)

For more reliable operation, especially with weak Bluetooth signals, manually specify your devices:

"platforms": [
    {
        "platform": "xiaomi-plant-monitor",
        "name": "Plant Monitor",
        "fetchDataIntervalInMs": 7200000,
        "devices": [
            {
                "address": "c4:7c:8d:6c:09:00",
                "name": "Monstera Plant"
            },
            {
                "address": "c4:7c:8d:6c:09:01",
                "name": "Fiddle Leaf Fig"
            }
        ]
    }
]

Configuration Options

Option	Type	Default	Description
`platform`	string	Required	Must be "xiaomi-plant-monitor"
`name`	string	"Plant Monitor"	Name for the platform in HomeKit
`fetchDataIntervalInMs`	number	3600000	Interval in milliseconds between data updates (default: 1 hour)
`displayTemperature`	boolean	true	Whether to display temperature sensors in HomeKit
`displayLightLevel`	boolean	true	Whether to display light level sensors in HomeKit
`displayFertility`	boolean	true	Whether to display fertility sensors in HomeKit
`lowBatteryThreshold`	number	10	Battery percentage threshold for low battery warnings
`devices`	array	[]	Optional array of manually specified devices
`devices[].address`	string	-	Bluetooth MAC address of the device
`devices[].name`	string	-	Custom name for the device in HomeKit

Troubleshooting Guide

Common Issues and Solutions

Device Not Discovered

Bluetooth Enabled: Verify Bluetooth is enabled on your system
Battery Check: Ensure the Mi Flora device has a working battery (CR2032)
Proximity: Move the Homebridge server closer to the Mi Flora device
Manual Configuration: Add the device address manually in your config (see Manual Device Configuration)

Inaccurate Moisture Readings (0% or 100%)

Sensor Placement: Ensure all 4 sensor prongs are fully inserted into the soil
Soil Contact: Clean the metal prongs if they appear dirty or corroded
Calibration: Remove and reinsert the sensor into the soil
Water Level: If soil is completely dry, readings of 0% may be accurate

Connection Timeouts

Signal Strength: Check the RSSI value in logs (values below -80 indicate weak signal)
Interference: Move the sensor away from other electronic devices
Retry Settings: Increase the retry count in your configuration
Update Interval: Consider increasing fetchDataIntervalInMs to reduce connection frequency

Finding Your Device Address

To find your Mi Flora device's Bluetooth address:

sudo hcitool lescan

Look for devices named "Flower care" or "Flower mate" in the output.

Enabling Debug Logs

For detailed logging, start Homebridge with the debug flag:

DEBUG=homebridge-xiaomi-plant-monitor-improved homebridge

For even more detailed Bluetooth logs:

DEBUG=homebridge-xiaomi-plant-monitor-improved,miflora* homebridge

Development

Building from Source

# Clone the repository
git clone https://github.com/grego360/homebridge-xiaomi-plant-monitor-improved.git
cd homebridge-xiaomi-plant-monitor-improved

# Install dependencies
npm install

# Build the TypeScript code
npm run build

# Watch mode for development
npm run watch