Package: imow-webapi
STIHL iMow unofficial Python API wrapperThis 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 theHome Assistant Smart Home System, which you can findhere.iMOW compatibilitySTIHL uses different webapps for their iMOW generations. Currently only theiMOW RMI series are supportedby 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 #13Getting StartedThese 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/imowIf you want toPrerequisitesPython 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.InstallingTo install the library is as simple as cloning the repository and runningpipinstall-e.It is recommended to create an virtual environment prior to installing this library. Alternatively, you can also install
this library via Pip:pipinstallimow-webapiAnd have fun!UsagePython Import and UsageImport the module and instantiate theIMowApi()constructor with credentials. Afterwards, initiate theget_token()method.
Or place credentials in theget_token()method.fromimow.apiimportIMowApifromimow.common.actionsimportIMowActionsimportasyncioimportaiohttpasyncdefmain():asyncwithaiohttp.ClientSession()assession: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 daystoken,expire_time=awaitapi.get_token("email@account.stihl","supersecret",return_expire_time=True)print(awaitapi.get_token())mowers=awaitapi.receive_mowers()mower=mowers[0]print(f"{mower.name}@{mower.coordinateLatitude},{mower.coordinateLongitude}")print(f"Currently:{mower.stateMessage['short']}")awaitmower.update_setting("gpsProtectionEnabled",True)print(mower.stateMessage)print(mower.machineState)awaitmower.intent(IMowActions.TO_DOCKING)print(awaitmower.update_from_upstream())print(awaitmower.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 mowingSave the following asmyscript.shand executechmod +x myscript.sh. Make sure you install the api viapip3 install imow-webapiAfterwards you can execute via./myscript.sh#!/usr/bin/env python3fromimow.apiimportIMowApi
fromimow.common.actionsimportIMowActions
importasyncio
importaiohttp
importlogginglogger=logging.getLogger("imow")# Enable DEBUG outputlogging.basicConfig(level=logging.DEBUG)asyncdefmain():asyncwithaiohttp.ClientSession()assession: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 daystoken,expire_time=awaitapi.get_token("email@account.stihl","supersecret",return_expire_time=True)print(awaitapi.get_token())mowers=awaitapi.receive_mowers()mower=mowers[0]print(f"{mower.name} @ {mower.coordinateLatitude},{mower.coordinateLongitude}")print(f"Currently: {mower.stateMessage['short']}")startpoints=awaitmower.get_startpoints()foriinrange(len(startpoints)):print("Startpoint {}: {}".format(i,startpoints[i]))# if your mower supports the "startMowing" call, use this action (i.e iMow 600 series)awaitmower.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)awaitmower.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())TestingFor unit testing runpytest -s tests/test_unit*. For upstream integration testing, provide a/secrets.pywith the following contents:EMAIL="email@account.stihl"PASSWORD="supersecret"MOWER_NAME="MyRobot"and runpytest -s tests/test_integration*orpytest -s.Built WithaiohttpBeautifulSoupasyncioVersioningNavigate totags on this repositoryto see all available versions.AuthorsMail AddressGitHub Profilechris@homeset.deChrisHaPunktLicenseThis project is licensed under the MIT License - see theLICENSE.mdlicense file for more details.AcknowledgesThanks tohttps://github.com/nstrydom2/anonfile-apihttps://github.com/OpenXbox/xbox-webapi-pythonfor repo structure inspirationChangelogVersion 0.8.4 (2023-12-09)FixLoosen the version requirements for dependency libsupdate the tested python version placed inside setup and PyPi to python 3.12Version 0.8.2 (2023-08-26)Fixvalidation of values in keyword argumentsBREAKING CHANGEThe iMow actionIMowActions.START_MOWINGnow creates astartMowingaction and no longer astartMowingFromPointaction.
To issue astartMowingFromPoint, the newIMowAction.START_MOWING_FROM_POINTneeds to be used.Addedkeywork argumentsstarttimeandendtimeinIMow.intent()call to be used with IMowActions.START_MOWINGUpdated Readme withIMow.intentexampesadded debug log output inintent()callVersion 0.7.10 (2023-05-13)Bugfix http_session not present on logoutVersion 0.7.9 (2023-05-13)remove unnecessary http_session closesVersion 0.7.8 (2022-03-06)Implement a logout functionImowAPI.api_logout(). Use within re-authenticationVersion 0.7.7 (2022-03-06)Use moreasync withsVersion 0.7.6 (2022-03-05)Dependency updatesUpdate dependencies to latestVersion 0.7.4 (2021-09-06)BugfxesAllow handling of timestamps on mower intents (StartTime/Endtime)Version 0.7.3 (2021-07-03)BugfxesAlways return a MowerState on settings updateVersion 0.7.2 (2021-07-03)awaitmower.update_setting("gpsProtectionEnabled",True)FeaturesPossibility to update a specific settings for a mower like gpsProtection on/offVersion 0.7.0 (2021-06-30)Breaking ChangesIMowApi.intentParametermower_action_idis renamed tomower_external_idto match the upstream api expectation.FeaturesIf anapi_requestis intended, and the usedaccess_tokenexpires 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 ChangesMigrated all own MowerState attributes to camelCase to match the upstream attributes style.- MowerState.stateMessage = None
- MowerState.machineError = None
- MowerState.machineState = NoneVersion 0.5.2 (2021-06-15)BugfixesAlso quote password string in auth request to support more special charsVersion 0.5.1 (2021-06-13)Featuresmower.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 englishVersion 0.5.0 (2021-06-12)Breaking ChangesTheMowerTaskclass is removed in favor of the newstate_messageproperty on thMowerStateobject.TheMowerState.get_current_task()method now returns theshortproperty of the state message instead of aMowerTaskproperty and is now longer anasyncmethod.Featuresmower.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 astate_messageproperty which gives ashortandlongtext for
description (Besides an error indication and errorId). All error and status codes are now dynamically matched and
human readable available.This makes theMowerTaskobsolete and it is removed with this release.api = IMowApi(lang="en")The imow api can now be instanced with a language code (fallback toen).
Thestate_messageproperty displays the messages in the corresponding language.Version 0.4.5 (2021-06-01)FeaturesAdd 2 new identified Tasks withinMowerTask(Thanks to @lausser)Addcheck_api_maintenance()method toIMowAPIClass. 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 newclose()method for theIMowAPIClass when finishing the api interactions to correctly
close the http session.BugfixesIssue #8- Example not workingVersion 0.4.4 (2021-05-28)FeaturesAddvalidate_token()method toIMowAPIClass. Test if a token is valid and is able to call the webapi.Version 0.4.3 (2021-05-27)FeaturesAllowIMowAPIClass to use predefinedaiohttpsession when instantiatingVersion 0.4.1 (2021-05-24)ChangesEven more asynchronously with switch fromrequeststoaiohttpVersion 0.4.0 (2021-05-17)Breaking ChangesReworked everything to use asyncio where possible. See Readme.md for new usage example.Renamed MowerState methodupdatetoupdate_from_upstreamRenamed MowerState methodget_statustoget_current_statusVersion 0.3.0 (2021-05-17)Breaking ChangesRenamed Class/EnumMowerStatetoMowerTaskbecause it describes the current task not the stateRenamed ClassMowertoMowerStatebecause it's just a snapshot of the last upstream stateFeaturesAdd methods to work onMowerStateobjects, like action intents or statistic receiveAdd PDoc documents, available
onhttps://chrishapunkt.github.io/stihl-imow-webapi/imowBugfixesReturn a valid error message and raise if provided login credentials are wrongVersion 0.2.2 (2021-05-00)Initial release