All Projects β†’ wpietri β†’ Sucks

wpietri / Sucks

Licence: gpl-3.0
Simple command-line script for the Ecovacs series of robot vacuums

Programming Languages

python
139335 projects - #7 most used programming language

Projects that are alternatives of or similar to Sucks

Best Of Python
πŸ† A ranked list of awesome Python open-source libraries and tools. Updated weekly.
Stars: ✭ 1,869 (+688.61%)
Mutual labels:  cli, library
Simplecli
Command Line Interface Library for Arduino
Stars: ✭ 135 (-43.04%)
Mutual labels:  cli, library
Riko
A Python stream processing engine modeled after Yahoo! Pipes
Stars: ✭ 1,571 (+562.87%)
Mutual labels:  cli, library
Transit Map
Generate a schematic map (β€œmetro map”) for a given (transit) network graph using Mixed Integer Programming.
Stars: ✭ 98 (-58.65%)
Mutual labels:  cli, library
Autoserver
Create a full-featured REST/GraphQL API from a configuration file
Stars: ✭ 188 (-20.68%)
Mutual labels:  cli, library
Unix Permissions
Swiss Army knife for Unix permissions
Stars: ✭ 106 (-55.27%)
Mutual labels:  cli, library
Csv2ofx
A Python library and command line tool for converting csv to ofx and qif files
Stars: ✭ 133 (-43.88%)
Mutual labels:  cli, library
Kit
Tools for developing, documenting, and testing React component libraries
Stars: ✭ 1,201 (+406.75%)
Mutual labels:  cli, library
Bt
BitTorrent library and client with DHT, magnet links, encryption and more
Stars: ✭ 2,011 (+748.52%)
Mutual labels:  cli, library
Passw0rd
πŸ”‘securely checks a password to see if it has been previously exposed in a data breach
Stars: ✭ 159 (-32.91%)
Mutual labels:  cli, library
Gowebdav
A golang WebDAV client library and command line tool.
Stars: ✭ 97 (-59.07%)
Mutual labels:  cli, library
Python Trezor
🐍 Don't use this repo, use the new monorepo instead:
Stars: ✭ 198 (-16.46%)
Mutual labels:  cli, library
Angular Librarian
An Angular 2+ scaffolding setup for creating libraries
Stars: ✭ 92 (-61.18%)
Mutual labels:  cli, library
Py7zr
7zip in python3 with ZStandard, PPMd, LZMA2, LZMA1, Delta, BCJ, BZip2, and Deflate compressions, and AES encryption.
Stars: ✭ 110 (-53.59%)
Mutual labels:  cli, library
Spider
A small dart library to generate Assets dart code from assets folder.
Stars: ✭ 90 (-62.03%)
Mutual labels:  cli, library
Typin
Declarative framework for interactive CLI applications
Stars: ✭ 126 (-46.84%)
Mutual labels:  cli, library
Hadotnet
🏑 A .NET Standard library for Home Assistant.
Stars: ✭ 52 (-78.06%)
Mutual labels:  home-automation, library
Instascrape
πŸš€ A fast and lightweight utility and Python library for downloading posts, stories, and highlights from Instagram.
Stars: ✭ 76 (-67.93%)
Mutual labels:  cli, library
Envy
Envy automatically exposes environment variables for all of your Go flags
Stars: ✭ 150 (-36.71%)
Mutual labels:  cli, library
Rpi Backlight
πŸ”† A Python module for controlling power and brightness of the official Raspberry Pi 7" touch display
Stars: ✭ 190 (-19.83%)
Mutual labels:  cli, library

Linux: Build Status Windows: Build Status

sucks

Caution: Abandonware ahead

As of March 2020, this is no longer an active project. My Ecovacs robot died and has since been replaced with a Roomba. That means I can't see if code changes work, so I can't even usefully approve patches. As of yet, nobody has agreed to take it over. If you are interested in doing so, please join the mailing list and discuss it there.

Overview

A simple command-line python script to drive a robot vacuum. Currently known to work with the Ecovacs Deebot N79, M80 Pro, M81, M88 Pro, and R95 MKII from both 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. And b), it's a vacuum.

Installation

If you have a recent version of Python 3, you should be able to do pip install sucks to get the most recently released version of this.

Usage

To get started, you'll need to have already set up an EcoVacs account using your smartphone.

With that ready, 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 continent code: na
    Config saved.

That creates a config file in a platform-appropriate place. The password is hashed before saving, so it's reasonably safe. (If it doesn't appear to work for your continent, try "ww", their world-wide catchall.)

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 without charging:

    % sucks clean 5 stop

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.sh 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 10 minutes of edging. And afterward it will always go back to charge.

Library use

You are welcome to try using this as a python library for other efforts. The API is still experimental, so expect changes. Please join the mailing list to participate in shaping the API.

A simple usage might go something like this:

import sucks

config = ...

api = EcoVacsAPI(config['device_id'], config['email'], config['password_hash'],
                         config['country'], config['continent'])
my_vac = api.devices()[0]
vacbot = VacBot(api.uid, api.REALM, api.resource, api.user_access_token, my_vac, config['continent'])
vacbot.connect_and_wait_until_ready()

vacbot.run(Clean())  # start cleaning
time.sleep(900)      # clean for 15 minutes
vacbot.run(Charge()) # return to the charger

Developing

If you'd like to join in on developing, I recommend checking out the code, setting up a virtual environment, and installing this package in editable mode. You can confirm your environment works by running the tests. And please do join the mailing list to discuss your plans.

For more information see the development documentation.

See also

There are now similar libraries in Javascript and Go.

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,
  • Albert Louw, who was kind enough to post code from his own experiments with his device, and
  • All the users who have given useful feedback and contributed code!
Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].