Metadata-Version: 2.2
Name: pyechorobotics
Version: 1.0.0rc1
Summary: Access API for echorobotics robot lawn mowers
Author-email: functionpointer <suspendfunction@gmail.com>
License: GNU General Public License v3 or later (GPLv3+)
Project-URL: homepage, https://github.com/functionpointer/pyechorobotics
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: aiohttp
Requires-Dist: yarl
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: python-dateutil

pyechorobotics
=============

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://brands.home-assistant.io/_/echorobotics/dark_logo@2x.png">
  <img alt="Echorobotics Logo" src="https://brands.home-assistant.io/_/echorobotics/logo@2x.png">
</picture>

Allows control and reads status of robot lawn mowers by echorobotics.

Used by [Home Assistant Echorobotics integration](https://github.com/functionpointer/home-assistant-echorobotics-integration).

Example:
```python
import sys

import echoroboticsapi
import aiohttp
import asyncio
import logging


async def main():
    async with aiohttp.ClientSession(cookies=echoroboticsapi.create_cookies(user_id="your-user-id", user_token="user-user-token")) as session:
        api = echoroboticsapi.Api(session, robot_ids=["your-robot-id"])
        print(await api.last_statuses())
        print(await api.set_mode("chargeAndWork"))


if __name__ == "__main__":
    logging.basicConfig(stream=sys.stdout, level=logging.DEBUG)
    loop = asyncio.new_event_loop()
    loop.run_until_complete(main())

```

Unfortunately, the API doesn't tell is which mode ("chargeAndWork", "work" or "chargeAndStay") the robot is in.
We can make an educated guess though, depending on what we set ourselves, history events and the status.
This is what SmartMode does:

```python
import sys

import echoroboticsapi
import aiohttp
import asyncio
import logging


async def main():
    async with aiohttp.ClientSession(cookies=echoroboticsapi.create_cookies(user_id="your-user-id", user_token="user-user-token")) as session:
        api = echoroboticsapi.Api(session, robot_ids=["your-robot-id"])
        smartmode = echoroboticsapi.SmartMode("your-robot-id")
        api.register_smart_mode(smartmode)
        
        print(await api.history_list())
        print(await api.last_statuses())
        print(smartmode.get_robot_mode())


if __name__ == "__main__":
    logging.basicConfig(stream=sys.stdout, level=logging.DEBUG)
    loop = asyncio.new_event_loop()
    loop.run_until_complete(main())

```

See also src/main.py

SmartFetch
==========

While calling `last_statuses()` and `history_list()` regularly (suggestion every 2min and 15min), this is somewhat wasteful of bandwidth.
Especially ``history_list()`` uses some 60KiB of data volume. If calling this every 15mins is an issue for you, you may be interested in
SmartFetch.

```python
import sys

import echoroboticsapi
import aiohttp
import asyncio
import logging


async def main():
    async with aiohttp.ClientSession(cookies=echoroboticsapi.create_cookies(user_id="your-user-id", user_token="user-user-token")) as session:
        api = echoroboticsapi.Api(session, robot_ids=["your-robot-id"])
        smartmode = echoroboticsapi.SmartMode("your-robot-id")
        api.register_smart_mode(smartmode)
        smartfetch = echoroboticsapi.SmartFetch(api)
        
        last_statuses = await smartfetch.smart_fetch()
        print(last_statuses)
        print(smartmode.get_robot_mode())


if __name__ == "__main__":
    logging.basicConfig(stream=sys.stdout, level=logging.DEBUG)
    loop = asyncio.new_event_loop()
    loop.run_until_complete(main())

```

Dev notes
=========

To make a new release, use GitHub website and draft a release manually.
Make sure the version number in pyproject.toml matches the new tag.
GitHub Actions will publish it to pypi.

Adding a new state
------------------

If a new state is found, it must be added to ``models.py``.
Also check ``notify_laststatuses_received()`` in ```smart_mode.py``` if it should be recognized as a specific Mode.

Finally, in home-assistant-echorobotics-integration, increment the version number in the manifest.json.
Also check the translations in echorobotics/translations, and any custom dashboard code.
