Skip to content

vrachieru/xiaomi-flower-care-api

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

4 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation


Version Version
Poll Xiaomi Flower Care (MiFlora) sensors without relying on the official app

About Mi Flora

  • Xiaomi Flower Care (MiFlora) sensors (e.g. 12-17€) are meant to keep your plants alive by monitoring their environment
  • Has sensors to relay temperature, light intensity, soil moisture and soil fertility (via electrical conductivity)
  • Uses Bluetooth Low Energy (BLE) and has a rather limited range
  • A coin cell battery is used as power source, which should last between 1.5 to 2 years under normal conditions
  • Food for thought: The sensor can also be used for other things than plants, like in the fridge or as door and blind sensor

Features

  • Device discovery
  • Read name
  • Read firmware version
  • Read battery level
  • Read real-time sensor values
  • Read historical sensor values
  • Clear historical sensor values
  • Blink LED

Install

$ pip3 install git+https://github.com/vrachieru/xiaomi-flower-care-api.git

or

$ git clone https://github.com/vrachieru/xiaomi-flower-care-api.git
$ pip3 install ./xiaomi-flower-care-api

Usage

Device discovery

import json
from collections import OrderedDict
from flowercare import FlowerCare, FlowerCareScanner

# Initialize the scanner with BT interface and a 
# custom callback for newly discovered devices.
scanner = FlowerCareScanner(
    interface='hci0',  # hci0 is default, explicitly stating for demo purpose
    callback=lambda device: print('Found device', device.addr) # any lambda with the device as the sole argument will do
)

# Scan advertisements for 10 seconds 
# and return found device list.
devices = scanner.scan(timeout=10)

# Iterate over results and query the information 
# for each individual device.
device_information = OrderedDict()
for device in devices:
    device = FlowerCare(
        mac=device.addr, # address of the device to connect to
        interface='hci0' # hci0 is default, only explicitly stating for demo purpose
    )
    device_information[device.mac] = OrderedDict([
        ('name', device.name),
        ('firmware', device.firmware_version),
        ('battery', device.battery_level),
        ('measurements', device.real_time_data.__dict__)
    ])

# Pretty print device information
print(json.dumps(device_information, indent=4))
$ sudo python3 scan.py
Found device c4:7c:8d:xx:xx:xx
Found device c4:7c:8d:yy:yy:yy

{
    "c4:7c:8d:xx:xx:xx": {
        "name": "Flower care",
        "firmware": "3.1.9",
        "battery": 99,
        "measurements": {
            "temperature": 23.7,
            "moisture": 23,
            "conductivity": 210,
            "light": 89
        }
    },
    "c4:7c:8d:yy:yy:yy": {
        "name": "Flower care",
        "firmware": "3.1.9",
        "battery": 100,
        "measurements": {
            "temperature": 25.2,
            "moisture": 68,
            "conductivity": 1980,
            "light": 3587
        }
    }
}

Reading device information and sensor data

from flowercare import FlowerCare

# Initialize FlowerCare device
device = FlowerCare(
    mac='c4:7c:8d:xx:xx:xx', # device address
    interface='hci0' # hci0 is default, explicitly static for demo purpose
)

print('Getting data from device..\n')

# Display generic device information
print('Name: {}'.format(device.name))
print('Address: {}'.format(device.mac))
print('Firmware: {}'.format(device.firmware_version))
print('Battery: {}%'.format(device.battery_level))

# Display current sensor readings
print('\nReal-time data\n----')
real_time_data = device.real_time_data
print('Temperature: {}°C'.format(real_time_data.temperature))
print('Moisture: {}%'.format(real_time_data.moisture))
print('Light: {} lux'.format(real_time_data.light))
print('Conductivity: {} µS/cm'.format(real_time_data.conductivity))

# Display historical sensor readings
print('\nHistorical data\n----')
historical_data = device.historical_data
for entry in historical_data:
    print('Timestamp: {}'.format(entry.timestamp))
    print('Temperature: {}°C'.format(entry.temperature))
    print('Moisture: {}%'.format(entry.moisture))
    print('Light: {} lux'.format(entry.light))
    print('Conductivity: {} µS/cm\n'.format(entry.conductivity))
$ sudo python3 read.py
Getting data from device..

Name: Flower care
Address: C4:7C:XX:XX:XX:XX
Firmware: 3.1.9
Battery: 99%

Real-time data
----
Temperature: 23.6°C
Moisture: 23%
Light: 68 lux
Conductivity: 211 µS/cm

Historical data
----
Timestamp: 2018-09-30 23:00:00
Temperature: 23.7°C
Moisture: 23%
Light: 24 lux
Conductivity: 211 µS/cm

Timestamp: 2018-09-30 22:00:00
Temperature: 24.1°C
Moisture: 24%
Light: 24 lux
Conductivity: 212 µS/cm

Timestamp: 2018-09-30 21:00:00
Temperature: 24.5°C
Moisture: 24%
Light: 164 lux
Conductivity: 212 µS/cm

...

Blink

from flowercare import FlowerCare

# Initialize the FlowerCare device
device = FlowerCare(
    mac='c4:7c:8d:xx:xx:xx', # device address
    interface='hci0' # hci0 is default, explicitly static for demo purpose
)

# Blink
device.blink()

Protocol

The device uses BLE GATT for communication, but the sensor values are not immediately available.
When the original app connects to the device, it performs an elaborate initialization, but most of it isn't required.

BLE & GATT

The basic technologies behind the sensors communication are Bluetooth Low Energy (BLE) and GATT.
They allow the devices and the app to share data in a defined manner and define the way you can discover the devices and their services.
In general you have to know about services and characteristics to talk to a BLE device.

Adafruit's Kevin Townsend has published a really nice introduction on the subject and if you don't know about BLE and/or GATT you should definitely give it a look.

Services, characteristics and handles

Root service
Service UUID Characteristic UUID Handle Read/Write Description
0000fe95-0000-1000-8000-00805f9b34fb - - - used for device discovery
Generic access
Service UUID Characteristic UUID Handle Read/Write Description
00001800-0000-1000-8000-00805f9b34fb 00002800-0000-1000-8000-00805f9b34fb 0x0003 read device name
Data service
Service UUID Characteristic UUID Handle Read/Write Description
00001204-0000-1000-8000-00805f9b34fb 00001a00-0000-1000-8000-00805f9b34fb 0x0033 write device mode change (send command)
00001204-0000-1000-8000-00805f9b34fb 00001a01-0000-1000-8000-00805f9b34fb 0x0035 read get real-time sensor values
00001204-0000-1000-8000-00805f9b34fb 00001a02-0000-1000-8000-00805f9b34fb 0x0038 read get firmware version and battery level
00001204-0000-1000-8000-00805f9b34fb 00001a11-0000-1000-8000-00805f9b34fb 0x003c read get historical sensor values
00001204-0000-1000-8000-00805f9b34fb 00001a10-0000-1000-8000-00805f9b34fb 0x003e write
00001204-0000-1000-8000-00805f9b34fb 00001a12-0000-1000-8000-00805f9b34fb 0x0041 read device time

Little endian

Data structure

The data is encoded on bytes in Little endian.
This means that the data is represented with the least significant byte first.

To understand multi-byte integer representation, you can consult this Wikipedia page.

Name

A read request to the 0x03 handle will return n bytes of data, for example 0x466c6f7765722063617265 corresponding to the device name.

Position 00 01 02 03 04 05 06 07 08 09 10
Value 46 6c 6f 77 65 72 20 63 61 72 65
Bytes Type Value Description
all ASCII text Flower Care device name

Firmware and battery

A read request to the 0x38 handle will return 7 bytes of data, for example 0x6328332e312e39.

Position 00 01 02 03 04 05 06
Value 63 28 33 2e 31 2e 39
Bytes Type Value Description
00 uint8 99 battery level in %
02-06 ASCII text 3.1.8 firmware version

The second byte (0x28) seems to be a separator. In older firmware versions it always read 0x13.
Both are control characters in the ASCII table.

Device time

A read request to the 0x41 handle will return 4 bytes of data, for example 0x09ef2000.

Position 00 01 02 03
Value 09 ef 20 00
Bytes Type Value Description
00-03 uint32 2158345 seconds since device epoch (boot)

Considering the device's epoch as second 0, the value obtained is a delta from now from which we can determine the actual time.
We use this method while determining the datetime of historical entries.

Real-time data

In order to read the sensor values you need to change its mode.
This can be done by writing 2 bytes (0xa01f) to the mode change handle (0x33).
After writing them you can read the actual sensor values from the data handle (0x35).

A read request will return 16 bytes of data, for example 0xea0000ab00000015b200023c00fb349b.

Position 00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15
Value ea 00 00 ab 00 00 00 15 b2 00 02 3c 00 fb 34 9b
Bytes Type Value Description
00-01 uint16 234 temperature in 0.1 °C
02 ? ? ?
03-06 uint32 171 brightness in lux
07 uint8 21 moisture in %
08-09 uint16 178 conductivity in µS/cm
10-15 ? ? ?

Historical data

The device stores historical data when not connected that can be later synchronized.
As with reading real-time sensor information, we need to change the device mode by writing 3 bytes (0xa00000) to the history control handle (0x3e).

Entry count

The next step is to get information about the stored history by reading from the history data handle (0x3c).
This will return 16 bytes of data, for example 0x2b007b04ba130800c815080000000000.

Position 00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15
Value 2b 00 7b 04 ba 13 08 00 c8 15 08 00 00 00 00 00
Bytes Type Value Description
00-01 unint16 43 number of stored historical records
02-15 ? ? ?
Read entry

Next we need to read each historical entry individually.
To do so we need to calculate it's address, write it to the history control handle (0x3e) and then read the entry from the history data handle (0x3c).

The address for each individual entry is computed by adding two bytes representing the entry index to 0xa1.
Entry 0's address will be 0xa10000, entry 1's address 0xa10100, entry 16's address 0xa11000, and so on...

After writing the address of the entry to be read, be can do so by requesting the payload from the history read handle (0x3c).
This will return 16 bytes of data, for example 0x70e72000eb00005a00000015b3000000.

Position 00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15
Value 70 e7 20 00 eb 00 00 5a 00 00 00 15 b3 00 00 00
Bytes Type Value Description
00-03 uint32 2156400 timestamp, seconds since device epoch (boot)
04-05 uint16 235 temperature in 0.1 °C
06 ? ? ?
07-09 uint32 90 brightness in lux
10 ? ? ?
11 uint8 21 moisture in %
12-13 uint16 179 conductivity in µS/cm
14-15 ? ?
Clear entries

Once all entries have been read, they can be wiped from the device by marking the process as successful.
This can be achieved by writing 3 bytes (0xa20000) to the history control handle (0x3e).

Blink

Writing 2 bytes (0xfdff) to the mode change handle (0x33) will make the device blink the top LED once.

Reference

[1] https://wiki.hackerspace.pl/projects:xiaomi-flora
[2] https://github.com/open-homeautomation/miflora
[3] https://github.com/ChrisScheffler/miflora

License

MIT