imow-webapi 0.4.5

A library to authenticate and interact with STIHL iMow mowers using their WebAPI

STIHL iMow unofficial Python API wrapper

This unofficial Python API was created to provide an interface to interact with the STIHL iMow mower WebAPI. This wrapper is able to receive the current status status from the mowers and to send actions.
I wrote this library to implement an integration for the Home Assistant Smart Home System

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

API Documentation is available on: https://chrishapunkt.github.io/stihl-imow-webapi/imow

Prerequisites

Python 3.7+ is required to run this application, other than that there are no prerequisites for the project, as the dependencies are included in the repository.

Installing

To install the library is as simple as cloning the repository and running

pip install -e .

It is recommended to create an virtual environment prior to installing this library. Alternatively, you can also install this library via Pip:

pip install imow-webapi

And have fun!

Usage

Import the module and instantiate the IMowApi() constructor with credentials.

from imow.api import IMowApi
from imow.common.actions import IMowActions
import asyncio

async def main():
    api = IMowApi()
    # save token for later use if you want to recreate IMowApi(token=my_token) because the created token is valid for
    # 30 days
    token, expire_time = await api.get_token("[e-mail]", "supersecret", return_expire_time=True)

    print(await api.get_token())

    mowers = await api.receive_mowers()
    mower = mowers[0]

    print(f"{mower.name} @ {mower.coordinateLatitude},{mower.coordinateLongitude}")
    print(await mower.get_current_task())
    await mower.intent(IMowActions.TO_DOCKING)
    print(await mower.update_from_upstream())
    print(await mower.get_startpoints())

    # Cleanup the created http session
    await api.close()


if __name__ == "__main__":
    asyncio.run(main())

Testing

For unit testing run pytest -s tests/test_unit*. For upstream integration testing, provide a /secrets.py with the following contents:

EMAIL = "[e-mail]"
PASSWORD = "supersecret"
MOWER_NAME = "MyRobot"

and run pytest -s tests/test_integration* or pytest -s.

Built With

• aiohttp
• BeautifulSoup
• asyncio

Versioning

Navigate to tags on this repository to see all available versions.

Authors

Mail Address	GitHub Profile
[e-mail]	ChrisHaPunkt

License

This project is licensed under the MIT License - see the LICENSE.md license file for more details.

Acknowledges

Thanks to

• https://github.com/nstrydom2/anonfile-api
• https://github.com/OpenXbox/xbox-webapi-python

for repo structure inspiration

Changelog

Version 0.4.5 (2021-06-01)

Features

• Add 2 new identified Tasks within MowerTask (Thanks to @lausser)
• Add check_api_maintenance() method to IMowAPI Class. Check if the api server is currently under maintenance.
  This method is automatically called if the api server returns a 500 error response for any request.
• One should call the new close() method for the IMowAPI Class when finishing the api interactions to correctly close the http session.

Bugfixes

• Issue #8 - Example not working

Version 0.4.4 (2021-05-28)

Features

• Add validate_token() method to IMowAPI Class. Test if a token is valid and is able to call the webapi.

Version 0.4.3 (2021-05-27)

Features

• Allow IMowAPI Class to use predefined aiohttp session when instantiating

Version 0.4.1 (2021-05-24)

Changes

• Even more asynchronously with switch from requests to aiohttp

Version 0.4.0 (2021-05-17)

Breaking Changes

• Reworked everything to use asyncio where possible. See Readme.md for new usage example.
• Renamed MowerState method update to update_from_upstream
• Renamed MowerState method get_status to get_current_status

Version 0.3.0 (2021-05-17)

Breaking Changes

• Renamed Class/Enum MowerState to MowerTask because it describes the current task not the state
• Renamed Class Mower to MowerState because it's just a snapshot of the last upstream state

Features

• Add methods to work on MowerState objects, like action intents or statistic receive
• Add PDoc documents, available on https://chrishapunkt.github.io/stihl-imow-webapi/imow

Bugfixes

• Return a valid error message and raise if provided login credentials are wrong

Version 0.2.2 (2021-05-00)

• Initial release