ha_ecovacs_bumper/README.md

sucks

A simple command-line python script to drive a robot vacuum. Currently known to work with the Ecovacs Deebot N79, M81, and M88 Pro from North America and Europe. Does it work for your model as well? Join the discussion on the sucks-users mailing list.

If you're curious about the protocol, I have a rough doc started. I'll happily accept pull requests for it.

Why the project name? Well, a) it's ridiculous that I needed to MITM my own vacuum. This is not the future I signed up for. There should be a nice, tidy RESTful API. That would be easy enough to make. And b), it's a vacuum.

Installation

Check out this code, do pipenv install, and then call the script sucks. If that doesn't work for you, please open an issue.

Usage

To get started, you'll need to have already set up an EcoVacs account using your smartphone. I've only tested this with Android, but I expect it will work with iPhone-created accounts as well.

Step one is to log in:

    % sucks login
    Ecovacs app email: [your email]
    Ecovacs app password: [your password]
    your two-letter country code: us
    your two-letter contienent code: na
    Config saved.

That creates a config file in ~/.config.sucks.conf. The password is hashed before saving, so it's reasonably safe.

With that set up, you could have it clean in auto mode for 10 minutes and return to its charger:

    % sucks clean 10

You could have it clean for 15 minutes and then do an extra 10 minutes of edging:

    % sucks clean 15 edge 10

If you wanted it to clean for 5 minutes and then stop where it was, either of these would work:

    % sucks clean 5 stop
    % sucks --no-charge clean 5

If it's running amok and you'd just like it to stop where it is:

    % sucks stop

To tell it to go plug in:

    % sucks charge

I run mine from my crontab, but I didn't want it to clean every day, so it also has a mode where it randomly decides to run or not based on a frequency you give it. My crontab entry looks like this:

0 10 * * * /home/william/projects/sucks/sucks clean -f 4/7 15 edge -f 1/14 10

This means that every day at 10 am, it might do something. 4 days out of 7, it will do 15 minutes of automatic cleaning. 1 day out of 14, it will do another 10 minutes of edging. And afterward it will always go back to charge.

Thanks

My heartfelt thanks to:

• xmpppeek, a great library for examining XMPP traffic flows (yes, your vacuum speaks Jabbber!),
• mitmproxy, a fantastic tool for analyzing HTTPS,
• click, a wonderfully complete and thoughtful library for making Python command-line interfaces,
• requests, a polished Python library for HTTP requests,
• Decompilers online, which was very helpful in figuring out what the Android app was up to, and
• Albert Louw, who was kind enough to post code from his own experiments with his device.

To Do

• add a status commmand