DEPRECATED: this repo is not maintained anymore. Please see https://github.com/Danielhiversen/PyXiaomiGateway instead.

Python binding for the Aqara devices, based on protocol defined here

The aim of this project is to abstract the protocol implementation details away and let developer focus on developing features and integrations on top of the Aqara hardware, with a focus on HomeAssistant integration. It also protect developers from breaking changes in the API.

Package available on Pypi

$ pip3 install pyaqara

Supported Features

• Gateway discovery
• Sensor discovery
• Listen on sensor update
• Read sensor state

Supported Hardwares

• Temperature and Humidity Sensor
• Contact Sensor
• Motion Sensor
• Aqara Switch Sensor
• Gateway LED (brightness and color)
• Gateway Ringtone

Create an instance of AqaraClient, and provide your gateway SIDs and secrets as a dictionary, for Example

from aqara.client import AqaraClient

client = AqaraClient({
  "my_gateway_sid": "my_gateway_secret",
  "my_second_gateway_sid": "my_second_gateway_secret"
})

The API need to be running in an event loop.

import asyncio

loop = asyncio.get_event_loop()
loop.run_until_complete(client.start(loop))

try:
  loop.run_forever()
except KeyboardInterrupt:
  pass
client.stop()
loop.close()

Currently the library allow subscription to two events.

This event is fired by the ** client ** when a new gateway is discovered. Caller must subscribe after client is created but before starting the client to avoid missing events. Usually you would also need to initialise the gateway in the handler.

from aqara.const import AQARA_EVENT_NEW_GATEWAY

def handle_new_gateway(sender, gateway):
    _LOGGER.info('Discovered new gateway %s, connecting...', gateway.sid)
    gateway.subscribe(handle_new_device)
    gateway.connect()

client.subscribe(handle_new_gateway)

This event is fired by the ** gateway ** when a new device is discovered. Caller must subscribe after a gateway is discovered, this usually happens in the new gateway handler (see above). If you are integrating this library with other system, this is a good chance to add new devices to the system.

from aqara.const import AQARA_EVENT_NEW_DEVICE

def handle_new_device(sender, device):
    _LOGGER.info('Discovered new device %s', device.sid)

gateway.subscribe(handle_new_device)

Once started, the client will automatically discover all gateways. Once a gateway is discovered, you can initialise it by calling gateway.connect(), which will fetch its state and trigger a device discover.

You can trigger a manual discovery of gateways later

client.discover_gateways()

Get a list of discovered gateways

gateways = client.gateway

Get a list of discovered devices of a gateway

devices = gateways[0].devices

Trigger a manual discovery of devices on a gateway

gateway.discover_devices()

To get type of a device (sensor)

print(device.model)

To access device data

# sensor_ht
>>> print(sensor_ht.temperature)
23.51

>>> print(sensor_ht.humidity)
60.15

# motion
>>> print(sensor_motion.triggered)
True | False

# magnet
>>> print(sensor_magnet.triggered)
True | False

# switch
>>> print(sensor_switch.action)
click | double_click | long_click_press | long_click_release

Sensor properties are updated automatically when reports are received. To subscribe to updates, set a callback function:

def on_sensor_update():
  print(sensor.triggered)

sensor.subscribe_update(on_sensor_update)

Force update a sensor immediately

client.update_now()

You can set the brightness and color (RGB) of the gateway LED ring light, each parameter is an integer ranging from 0-255.

# brightness: 77
# red: 255
# green: 79
# blue: 0
gateway.set_light(77, 255, 79, 0) # warm orange

Play system ringtone via the gateway's built-in speaker

# mid range for system ringtone is 0-8, 10-13, 20-29, or > 10000 for user defined ringtones
gateway.mid_play(mid)