Home

Awesome

DEV Build Status 0.4.X.X Build codecov Documentation PyPI version Downloads PyPI - Downloads

⚠ !Attention! ⚠

Meross did change the login API without notice and that caused the library to break. Please make sure to upgrade your library to v0.4.7.3 to fix the issue.

Meross IoT library

A pure-python based library providing API for controlling Meross IoT devices over the internet.

To see what devices are currently supported, checkout the Currently supported devices section. However, some devices might work as expected even if they are not listed among the supported devices. In such cases, you're invited to open an issue and report tbe working/non-working status of your device. This will help us to keep track of new devices and current support status of the library.

This library is still work in progress, therefore use it with caution.

Requirements

This library requires Python 3.7+. Previous versions won't be supported by this library. In case working with previous versions of python is mandatory for your project, consider using 0.3.X.X versions of this library (although it's highly recommended to migrate to 0.4.X.X).

Installation

Due to the popularity of the library, I've decided to list it publicly on the Pipy index. So, the installation is as simple as typing the following command:

pip install meross_iot==0.4.7.3

Usage & Full Documentation

Refer to the documentation pages for detailed usage instructions, or simply have a look at the /examples directory.

If you are really impatient to use this library, refer to the following snippet of code that looks for a mss310 smart plug and turns it on/off.

import asyncio
import os

from meross_iot.http_api import MerossHttpClient
from meross_iot.manager import MerossManager

EMAIL = os.environ.get('MEROSS_EMAIL') or "YOUR_MEROSS_CLOUD_EMAIL"
PASSWORD = os.environ.get('MEROSS_PASSWORD') or "YOUR_MEROSS_CLOUD_PASSWORD"


async def main():
    # Setup the HTTP client API from user-password
    # When choosing the API_BASE_URL env var, choose from one of the above based on your location.
    # Asia-Pacific: "iotx-ap.meross.com"
    # Europe: "iotx-eu.meross.com"
    # US: "iotx-us.meross.com"
    http_api_client = await MerossHttpClient.async_from_user_password(api_base_url='https://iotx-eu.meross.com',
                                                                      email=EMAIL, 
                                                                      password=PASSWORD)

    # Setup and start the device manager
    manager = MerossManager(http_client=http_api_client)
    await manager.async_init()

    # Retrieve all the MSS310 devices that are registered on this account
    await manager.async_device_discovery()
    plugs = manager.find_devices(device_type="mss310")

    if len(plugs) < 1:
        print("No MSS310 plugs found...")
    else:
        # Turn it on channel 0
        # Note that channel argument is optional for MSS310 as they only have one channel
        dev = plugs[0]

        # The first time we play with a device, we must update its status
        await dev.async_update()

        # We can now start playing with that
        print(f"Turning on {dev.name}...")
        await dev.async_turn_on(channel=0)
        print("Waiting a bit before turing it off")
        await asyncio.sleep(5)
        print(f"Turing off {dev.name}")
        await dev.async_turn_off(channel=0)

    # Close the manager and logout from http_api
    manager.close()
    await http_api_client.async_logout()


if __name__ == '__main__':
    # Windows and python 3.8 requires to set up a specific event_loop_policy.
    #  On Linux and MacOSX this is not necessary.
    if os.name == 'nt':
        asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
    loop = asyncio.get_event_loop()
    loop.run_until_complete(main())
    loop.stop()

Currently supported devices

Starting from v0.4.0.0, this library should support the majority of Meross devices on the market. The list of tested devices is the following:

I'd like to thank all the people who contributed to the early stage of library development, who stimulated me to continue the development and making this library support more devices.

Thanks to DanoneKiD, virtualdj, ictes, soberstadt, ping-localhost, tdippon.

Special thanks go to the github sponsors supporting this and other projects. Thanks a lot!

Unsupported device or feature?

In case you own a Meross Device that is not currently supported by this library, you may ask the developers to add specific support for that device. To do so, you will need to "sniff" low-level communication between your Meross App and the specific device. Such data can help the developers to add support for that device.

Please have a look at there to discover how to use the Meross Sniffing tool to do so.

Homeassistant integration

Yeah, it happened. As soon as I started developing this library, I've discovered the HomeAssistant world. Thus, I've decided to spend some time to develop a full featured Homeassistant custom component, that you find here. Thanks to @troykelly who made a wish and supported my efforts in developing such component!

Running on OSX?

If so, please make sure you did install client certificates. Follow instructions here.

Donate!

I like reverse engineering and protocol inspection, I think it keeps your mind trained and healthy. However, if you liked or appreciated by work, why don't you buy me a beer? It would really motivate me to continue working on this repository to improve documentation, code and extend the supported meross devices.

Moreover, donations will make me raise money to spend on other Meross devices. So far, I've bought the following devices:

By issuing a donation, you will:

  1. Give me the opportunity to buy new devices and support them in this library
  2. Pay part of electricity bill used to keep running the plugs 24/7 (Note that they are used for Unit-Testing on the continuous integration engine when someone pushes a PR... I love DEVOPing!)
  3. You'll increase the quality of my coding sessions with free-beer!

Buy me a coffee! Apply for GitHub sponsorship

Look at these babies!

<p> Look at the test environment that ensures high quality code of the library! </p> <img src="ext-res/plugs/test-env.jpg" alt="Current test environemnt" width="400" /> <p>When a pull-request is performed against this repository, a CI pipeline takes care of building the code, testing it on Python 3.5/3.6/3.7, relying on some junit tests and, if all the tests pass as expected, the library is released on Pypi. However, to ensure that the code <i>really works</i>, the pipeline will issue on/off commands against real devices, that are dedicated 24/7 to the tests. Such devices have been bought by myself (with contributions received by donors). However, keeping such devices connected 24/7 has a cost, which I sustain happily due to the success of the library. Anyway, feel free to contribute via donations! </p>

Changelog

0.4.7.3

<details> <summary>Older</summary> #### 0.4.7.1 - Updated requirements to use pycryptodomex instead of Crypto

0.4.7.0

0.4.6.2

0.4.6.0

0.4.5.9

0.4.5.7

0.4.5.4

0.4.5.4-rc1

0.4.5.3

0.4.5.2

0.4.5.1

0.4.5.0

0.4.4.7

0.4.4.5

0.4.4.4

0.4.4.3

0.4.4.2

0.4.3.1

0.4.3.0

0.4.2.4

0.4.2.3

0.4.2.2

0.4.2.1

0.4.2.0

0.4.1.0rc8

0.4.1.0rc7

0.4.0.6

0.4.0.5

0.4.0.3

0.4.0.2

0.4.0.1

0.4.0.0

Complete re-engineerization of the library.

0.3.4.0RC

0.3.3.3

0.3.3.0

0.3.2.22

0.3.2.21

0.3.2.20

0.3.2.17

0.3.2.15

0.3.2.14

0.3.2.12

0.3.2.9

0.3.2.7

0.3.2.6

0.3.2.5

0.3.2.4

0.3.1.12

0.3.1.11

0.3.1.10

0.3.1.9

0.3.1.8

0.3.1.6

0.3.1.5

0.3.1.3

0.3.0.2

0.3.0.1

0.3.0.0rc4

0.3.0.0rc3

0.3.0.0rc2

0.3.0.0rc1

0.3.0.0b1

0.2.2.1

0.2.1.1

0.2.1.0

</details>