Description:

imowwebapi 0.8.4

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 state
from the mowers and to send actions.
I wrote this library to implement an integration for the Home Assistant Smart Home System, which you can find here.
iMOW compatibility
STIHL uses different webapps for their iMOW generations. Currently only the iMOW RMI series are supported by this library, because i'm not able to reverse engineer the newer generation.
This is simply because I do not own them.
If you use this webapp, https://app.imow.sithl.com, this library should work for your mower.
Also see here: Issue #13
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
If you want to

Prerequisites
Python 3.8+ 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
Python Import and Usage
Import the module and instantiate the IMowApi() constructor with credentials. Afterwards, initiate the get_token() method.
Or place credentials in the get_token() method.
from imow.api import IMowApi
from imow.common.actions import IMowActions
import asyncio
import aiohttp


async def main():
async with aiohttp.ClientSession() as session:
api = IMowApi(aiohttp_session=session, lang="de")
# 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("email@account.stihl", "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(f"Currently: {mower.stateMessage['short']}")
await mower.update_setting("gpsProtectionEnabled", True)

print(mower.stateMessage)
print(mower.machineState)
await mower.intent(IMowActions.TO_DOCKING)
print(await mower.update_from_upstream())
print(await mower.get_startpoints())


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

Selection of outputs from above statements:
> Mährlin @ 54.123456,10.12345
> Currently: Hood blocked
> {'short': 'Hood blocked', 'long': 'The hood is blocked. Please check the hood and press the OK button on your machine (M1120).', 'legacyMessage': 'Abschaltung Automatikmode durch Bumper', 'errorId': '', 'error': False}
> HOOD_BLOCKED
> <imow.common.mowerstate.MowerState object at 0x000001B034C245F8>

Example: Receive startpoints and intent mowing
Save the following as myscript.sh and execute chmod +x myscript.sh. Make sure you install the api via pip3 install imow-webapi
Afterwards you can execute via ./myscript.sh
#!/usr/bin/env python3
from imow.api import IMowApi
from imow.common.actions import IMowActions
import asyncio
import aiohttp
import logging

logger = logging.getLogger("imow")
# Enable DEBUG output
logging.basicConfig(level=logging.DEBUG)

async def main():
async with aiohttp.ClientSession() as session:
api = IMowApi(aiohttp_session=session, lang="de")
# 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("email@account.stihl", "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(f"Currently: {mower.stateMessage['short']}")

startpoints = await mower.get_startpoints()
for i in range(len(startpoints)):
print("Startpoint {}: {}".format(i, startpoints[i]))

# if your mower supports the "startMowing" call, use this action (i.e iMow 600 series)
await mower.intent(IMowActions.START_MOWING, starttime="2023-08-12 20:50")
# await mower.intent(IMowActions.START_MOWING, endtime="2023-08-12 22:50")
# await mower.intent(IMowActions.START_MOWING, starttime="2023-08-12 20:50", endtime="2023-08-12 22:50")

# if your mower supports the "startMowingFromPoint" call, use this action (i.e iMow 400 series)
await mower.intent(IMowActions.START_MOWING_FROM_POINT, duration=50)
# await mower.intent(IMowActions.START_MOWING_FROM_POINT, startpoint=2)
# await mower.intent(IMowActions.START_MOWING_FROM_POINT, duration=50, startpoint=2)


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 = "email@account.stihl"
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




chris@homeset.de
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.8.4 (2023-12-09)
Fix

Loosen the version requirements for dependency libs
update the tested python version placed inside setup and PyPi to python 3.12

Version 0.8.2 (2023-08-26)
Fix

validation of values in keyword arguments

BREAKING CHANGE
The iMow action IMowActions.START_MOWING now creates a startMowing action and no longer a startMowingFromPoint action.
To issue a startMowingFromPoint, the new IMowAction.START_MOWING_FROM_POINT needs to be used.
Added

keywork arguments starttime and endtime in IMow.intent() call to be used with IMowActions.START_MOWING
Updated Readme with IMow.intent exampes
added debug log output in intent() call

Version 0.7.10 (2023-05-13)

Bugfix http_session not present on logout

Version 0.7.9 (2023-05-13)

remove unnecessary http_session closes

Version 0.7.8 (2022-03-06)

Implement a logout function ImowAPI.api_logout(). Use within re-authentication

Version 0.7.7 (2022-03-06)

Use more async withs

Version 0.7.6 (2022-03-05)
Dependency updates

Update dependencies to latest

Version 0.7.4 (2021-09-06)
Bugfxes

Allow handling of timestamps on mower intents (StartTime/Endtime)

Version 0.7.3 (2021-07-03)
Bugfxes

Always return a MowerState on settings update

Version 0.7.2 (2021-07-03)
await mower.update_setting("gpsProtectionEnabled", True)

Features

Possibility to update a specific settings for a mower like gpsProtection on/off

Version 0.7.0 (2021-06-30)
Breaking Changes

IMowApi.intent Parameter mower_action_id is renamed to mower_external_id to match the upstream api expectation.

Features

If an api_request is intended, and the used access_token expires in less than one day, it's automatically renewed.

Version 0.6.0 (2021-06-28)


mower.machineError = 'M1120',
mower.machineState = 'HOOD_BLOCKED',
mower.stateMessage: dict = {
'short': 'Hood blocked',
'long': 'The hood is blocked. Please check the hood and press the OK button on your machine (M1120).',
'legacyMessage': 'Abschaltung Automatikmode durch Bumper',
'errorId': 'M1120',
'error': True
}



Breaking Changes

Migrated all own MowerState attributes to camelCase to match the upstream attributes style.
- MowerState.stateMessage = None
- MowerState.machineError = None
- MowerState.machineState = None



Version 0.5.2 (2021-06-15)
Bugfixes

Also quote password string in auth request to support more special chars

Version 0.5.1 (2021-06-13)
Features


mower.machine_error = 'M1120',
mower.machine_state = 'HOOD_BLOCKED',
mower.state_message: dict = {
'short': 'Hood blocked',
'long': 'The hood is blocked. Please check the hood and press the OK button on your machine (M1120).',
'legacyMessage': 'Abschaltung Automatikmode durch Bumper',
'errorId': 'M1120',
'error': True
}

Provide a machine usable string from the short message in english

Version 0.5.0 (2021-06-12)
Breaking Changes

The MowerTask class is removed in favor of the new state_message property on th MowerState object.
The MowerState.get_current_task() method now returns the short property of the state message instead of a MowerTask
property and is now longer an async method.

Features


mower.state_message -> dict
{
'short': 'Hood blocked',
'long': 'The hood is blocked. Please check the hood and press the OK button on your machine (M1120).',
'errorId': 'M1120',
'error': True
}

The MowerState Class now provides a state_message property which gives a short andlong text for
description (Besides an error indication and errorId). All error and status codes are now dynamically matched and
human readable available.
This makes the MowerTask obsolete and it is removed with this release.
api = IMowApi(lang="en")
The imow api can now be instanced with a language code (fallback to en).
The state_message property displays the messages in the corresponding language.

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

License

For personal and professional use. You cannot resell or redistribute these repositories in their original state.

Share

• Share on Facebook
• Share on Twitter