API References

Mijia Smart Home API reference

class index:

mijia API Documentation

Class LumiGateway

This class is used to access a Lumi Gateway device (provided by Xiaomi / Aqara). It will automatically try to discover devices on your network, using the Lumi LAN protocol. It installs a thread to listen for incomming events, and also allows you to change the device light color.

illumination

[read only property] Stores the Gateway’s provided value for its light sensor. It’s updated when a change event arrives, and on start-up.

status

A property that provides the status of this device, which could be:

__init__

def __init__(self, passwd=None, mcast_member=None)

LumiGateway constructor. This is the starting point of the library. You will need to create an instance of this class, and use it access other devices.

Parameters:

get_devices

def get_devices(self, filter=None)

Returns a dictionary (pairs of sid and Device objects) with the currently linked devices.

Parameters:

gw.get_devices(filter=Switch) gw.get_devices(filter=Switch.type) gw.get_devices(filter="switch")

light_off

def light_off(self)

Switch off Gateway’s light. The same result could be achieved providing 0 as intensity on set_light_color().

on_change

def on_change(self, cb)

Stablish a callback to be called when the Gateway’s light sensor changes. The callback signature should be as follows:

def callback([self,] event, device)

Where event is the name of this event (change), and device is the Gateway device. To retrieve the current value of the light sensor, use the property illumination.

on_heartbeat

def on_heartbeat(self, cb)

Installs an event handler that will be called when this device sends a heartbeat message.

Parameters:

set_light_color

def set_light_color(self, r=0, g=0, b=0, i=0)

Changes the Gateway’s light to the given color (by RGB components) and intensity. Note that the provided values are relative to each other, so a value of (1, 0, 0) will produce the same result as (255, 0, 0).

Parameters:

start

def start(self)

Start the discovery process. It will search for an active gateway, and then list its linked devices. It also starts the listening thread to receive messages from the Gateway. You usually will need to call this method.

wait_until_break

def wait_until_break(self)

Blocks the calling thread execution until it receives a KeyboardInterrupt (Ctrl+C) Use it (or use instead an event loop) to keep the application running while you wait for incoming events.

mijia.devices API Documentation

Class CubeAqgl01

Mi Cube Controller, which is a device that detects different movements or actions performed on itself: tap, double tap, flips of 90 and 180 degrees, rotation, move, shake, swing and free fall. It also works as a motion sensor: when you touches it after a while, it will send an alert event.

Except for the rotate event, all the attached callbacks should be in the form:

def callback([self,], event, device)

Where event is the name of this event, and device is the device object that produced the event.

status

A property that provides the status of this device, which could be:

on_alert

def on_alert(self, cb)

Attach a callback handler for alert events. These events are sent when the cube is moved after some time of inactivity (no movement).

on_flip180

def on_flip180(self, cb)

Attach a callback handler for flip180 events. These events are produced when the cube is flipped 180 degrees (i.e rotated on X and Y axis).

on_flip90

def on_flip90(self, cb)

Attach a callback handler for flip90 events. These events are produced when the cube is flipped 90 degrees (i.e rotated on X and Y axis).

on_free_fall

def on_free_fall(self, cb)

Attach a callback handler for free_fall events, which are sent when you drop the cube (or it experiments some acceleration on the vertical axis).

on_heartbeat

def on_heartbeat(self, cb)

Installs an event handler that will be called when this device sends a heartbeat message.

Parameters:

on_move

def on_move(self, cb)

Attach a callback handler for move events, generated when you displace the cube some small distance on the horizontal plane.

on_rotate

def on_rotate(self, cb)

Attach a callback handler for rotate events, which are sent when you rotate the cube along the vertical axis (Z axis).

The attached callbacks should be in the form:

def callback([self,], event, device, degrees, time)

Where event is the name of this event, device is the device object that produced the event, degrees is the angle of the rotation, and time is the time that took the sensor to measure the angle.

on_shake_air

def on_shake_air(self, cb)

Attach a callback handler for shake_air events, which are sent when you take the cube and shake it on the air.

on_swing

def on_swing(self, cb)

Attach a callback handler for swing events. These events are signaled when the cube makes a fast swing movement (one single shot is enough). Note that it is also a trigger for the iam event (used to link the cube to a Gateway).

on_tap_twice

def on_tap_twice(self, cb)

Attach a callback handler for tap_twice events. These events are sent when the cube is knocked twice on an horizontal hard surface.

Class Magnet

Aqara reed sensor (magnet) for detection of opening and close of doors and windows. It emits an open event when the two components of the sensor are separated, and a close event when they are joined together. Also, no_close events are sent when the elapsed time from the last open event reaches some pre-established thresholds (in the sensor firmware or in the Gateway).

elapsed_no_close

Gives the amount of elapsed time (in seconds) from the last open event. It is provided with the no_close event from the sensor (not computed locally).

open

True if the sensor detects that the door/window is open (or the two components of the sensore are not together). False otherwise.

status

A property that provides the status of this device, which could be:

on_close

def on_close(self, cb)

Attach a callback handler for close events, which are sent when the sensor detects the closing of the door/window. The attached callback should be in the form:

def callback([self,], event, device)

Where event is the name of this event, and device is the device object that produced the event.

on_heartbeat

def on_heartbeat(self, cb)

Installs an event handler that will be called when this device sends a heartbeat message.

Parameters:

on_no_close

def on_no_close(self, cb)

Attach a callback handler for no_close events, which are sent when the elapsed time from the last open event reaches certain thresholds (120 seconds, 300, 600, and so on). The elapsed time is provided in the event, so the attached callback should be in the form:

def callback([self,], event, device, elapsed)

Where event is the name of this event, and device is the device object that produced the event.

on_open

def on_open(self, cb)

Attach callback handler for open events, which are sent when the sensor detects the opening of the door/window. The attached callback should be in the form:

def callback([self,], event, device)

Where event is the name of this event, and device is the device object that produced the event.

Class Motion

This is the Aqara PIR (or motion) sensor. It emits an event when a moving object is detected, and some other events when the elapsed time from the last motion detected reaches some pre-established thresholds (in the sensor firmware or in the Gateway).

elapsed_no_motion

Gives the amount of elapsed time (in seconds) between the last motion event and the last no_motion event. It is provided with the no_motion event from the sensor (not computed locally).

status

A property that provides the status of this device, which could be:

on_heartbeat

def on_heartbeat(self, cb)

Installs an event handler that will be called when this device sends a heartbeat message.

Parameters:

on_motion

def on_motion(self, cb)

Attach a callback handler for motion events, which are sent when a moving object passes through the field of view of the sensor. The attached callback should be in the form:

def callback([self,], event, device)

Where event is the name of this event, and device is the device object that produced the event.

on_no_motion

def on_no_motion(self, cb)

Attach a callback handler for no_motion events, which are sent when the elapsed time from the last detected motion reaches certain thresholds (120 seconds, 300, 600, and so on). The elapsed time is provided in the event, so the attached callback should be in the form:

def callback([self,], event, device, elapsed)

Where event is the name of this event, and device is the device object that produced the event.

Class Plug

This is the Aqara plug controller. Emits 2 different events, to notify if someone enabled or disabled the plug. You can also change the state of the plug: enable or disable it. The properties enabled and inuse will give you information about the plug usage.

All event callbacks should met the following signature:

def callback([self,], event, device)

Where event is the name of the event, and device is the device object that produced this event.

enabled

True if the plug is enabled (provides energy to the connected appliance), False otherwise.

inuse

True if there are a connected appliance, and it is currently consuming energy. False otherwise.

load_power

Connected appliance (load) power usage, in watts (W).

power_consumed

The cumulative load power consumption since the product was used, in Wh.

status

A property that provides the status of this device, which could be:

on_heartbeat

def on_heartbeat(self, cb)

Installs an event handler that will be called when this device sends a heartbeat message.

Parameters:

on_switch_off

def on_switch_off(self, cb)

Attach callback handler for switch_off events, which are sent when someone presses the built-in button of the plug (or otherwise changes the enabled state), and the state goes from on to off.

on_switch_on

def on_switch_on(self, cb)

Attach callback handler for switch_on events, which are sent when someone presses the built-in button of the plug (or otherwise changes the enabled state), and the state goes from off to on.

switch_off

def switch_off(self)

Call this method to disable the plug (does not provide energy to connected appliance). Remember that you must provide a password on the Gateway construction for this method to work.

switch_on

def switch_on(self)

Call this method to enable the plug (provide energy to connected appliance). Remember that you must provide a password on the Gateway construction for this method to work.

Class Switch

This is the Aqara push button that emits 4 different events. All event callbacks should met the following signature:

def callback([self,], event, device)

Where event is the name of the event, and device is the device object that produced this event.

pressed

Property to retrieve the current state of the push button: true is pressed, false is not pressed.

status

A property that provides the status of this device, which could be:

on_click

def on_click(self, cb)

Attach callback handler for click events, which is a single press on the button.

on_double_click

def on_double_click(self, cb)

Attach callback handler for double_click events, which is a double press on the button.

on_heartbeat

def on_heartbeat(self, cb)

Installs an event handler that will be called when this device sends a heartbeat message.

Parameters:

on_long_click_press

def on_long_click_press(self, cb)

Attach callback handler for long_click_press events. These events are produced when the button is pressed and maintained for more that 1 second. It is paired with the long_click_release event.

on_long_click_release

def on_long_click_release(self, cb)

Attach callback handler for long_click_release events. These events are produced when the button is pressed, maintained for more that 1 second and then released. It is paired with the long_click_press event.

Class WeatherV1

Aqara weather sensor (version 1.0). It provides readings for temperature, humidity and air pressure. The latest provided values for these magnitudes could be read any time from the corresponding properties.

All event callbacks should met the following signature:

def callback([self,], event, device, value)

Where event is the name of the event, device is the device object that produced this event, and value is the provided value (as integer) for that magnitude.

humidity

Last value provided on a humidity event (or retrieved on startup).

pressure

Last value provided on a pressure event (or retrieved on startup).

status

A property that provides the status of this device, which could be:

temperature

Last value provided on a temperature event (or retrieved on startup).

on_heartbeat

def on_heartbeat(self, cb)

Installs an event handler that will be called when this device sends a heartbeat message.

Parameters:

on_humidity

def on_humidity(self, cb)

Attach callback handler for humidity events. Only sent when value changes from previous one.

on_pressure

def on_pressure(self, cb)

Attach callback handler for pressure events. Only sent when value changes from previous one.

on_temperature

def on_temperature(self, cb)

Attach callback handler for temperature events. Only sent when value changes from previous one.