Skip to content

Latest commit

 

History

History
144 lines (118 loc) · 6.94 KB

README.md

File metadata and controls

144 lines (118 loc) · 6.94 KB
Raw

codecov PyPI PyPI - Downloads GitHub

sharkiq

Unofficial SDK for Shark IQ robot vacuums, designed primarily to support an integration for Home Assistant.

This library is heavily based off of sharkiq by @ajmarks, with a few minor changes to allow it to work on newer versions of the Shark API.

Installation

pip install sharkiq

Usage

Simple Operation

from sharkiq import get_ayla_api, OperatingModes, Properties, PowerModes

USERNAME = '[email protected]'
PASSWORD = '$7r0nkP@s$w0rD'

ayla_api = get_ayla_api(USERNAME, PASSWORD)
ayla_api.sign_in()

shark_vacs = ayla_api.get_devices()
shark = shark_vacs[0]

shark.update()
shark.set_operating_mode(OperatingModes.START)
shark.return_to_base()

Async operation

import asyncio
from sharkiq import get_ayla_api, OperatingModes, SharkIqVacuum

USERNAME = '[email protected]'
PASSWORD = '$7r0nkP@s$w0rD'

async def main(ayla_api) -> SharkIqVacuum:
    await ayla_api.async_sign_in()
        
    shark_vacs = await ayla_api.async_get_devices()
    shark = shark_vacs[0]
    await shark.async_update()
    await shark.async_find_device()
    await shark.async_set_operating_mode(OperatingModes.START)

    return shark


ayla_api = get_ayla_api(USERNAME, PASSWORD)
shark = asyncio.run(main(ayla_api))

Documentation

get_ayla_api(username, password, websession=None)

Returns and AylaApi object to interact with the Ayla Networks Device API conrolling the Shark IQ robot, with the app_id and app_secret parameters set for the Shark IQ robot.

class AylaAPI(username, password, app_id, app_secret, websession)

Class for interacting with the Ayla Networks Device API underlying the Shark IQ controls.

  • username: str
  • password: str
  • app_id: str
  • app_secret: str
  • websession: Optional[aiohttp.ClientSession] = None Optional aiohttp.ClientSession to use for async calls. If one is not provided, a new aiohttp.ClientSession will be created at the first async call.

Methods

  • get_devices()/async_get_devices() Get a list of SharkIqVacuums for every device found in list_devices()
  • list_devices()/async_list_devices() Get a list of known device description dicts
  • refesh_auth()/async_refesh_auth() Refresh the authentication token
  • request(method, url, headers = None, auto_refresh = True, **kwargs)/async_request(...) Submit an HTTP request to the Ayla networks API with the auth header
    • method: str An HTTP method, usually 'get' or 'post'
    • url: str
    • headers: Optional[Dict] = None Optional dict of HTTP headers besides the auth header, which is included automatically
    • auto_refresh: bool = True If True, automatically call refesh_auth()/async_refesh_auth() if the auth token is near expiration
    • **kwargs Passed on to requests.request or aiohttp.ClientSession.request
  • sign_in()/async_sign_in() Authenticate
  • sign_out()/async_sign_out() Sign out

class SharkIqVacuum(ayla_api, device_dct)

Primary API for interacting with Shark IQ vacuums

  • ayla_api: AylaApi An AylaApi with an authenticated connection
  • device_dct: Dict A dict describing the device, usually obtained from AylaApi.list_devices()

Methods

  • find_device()/async_find_device() Cause the device to emit an annoying chirp
  • get_file_property_url(property_name)/async_get_file_property_url(property_name) Get the URL for the latest version of a 'file'-type property
    • property_name: Union[str, PropertyName] Either a str or PropertyNames value for the desired property
  • get_file_property(property_name)/async_get_file_property(property_name) Get the contents of the latest version of a 'file'-type property
    • property_name: Union[str, PropertyName] Either a str or PropertyNames value for the desired property
  • get_metadata()/async_get_metadata() Update some device metadata (vac_model_number and vac_serial_number)
  • set_operating_mode(mode)/async_set_operating_mode(mode) Set the operating mode. This is just a thin wrapper around set_property_value/async_set_property_value provided for convenience.
    • mode: OperatingModes Mode to set, e.g., OperatingModes.START to start the vacuum
  • get_property_value(property_name)/async_get_property_value(property_name) Returns the value of property_name, cast to the appropriate type
    • property_name: Union[str, PropertyName] Either a str or PropertyNames value for the desired property
  • set_property_value(property_name, property_value)/async_set_property_value(property_name, property_value) Set the value of property_name
    • property_name: Union[str, PropertyName] Either a str or PropertyName value for the desired property
    • property_value: Any New value. Type checking is currently left to the remote API.
  • update()/async_update(property_list=None) Fetch the updated robot state from the remote api
    • property_list: Optional[Interable[str]] An optional iterable of property names. If specified, only those properties will be updated.
  • get_room_list() Get a list of known room strs
  • clean_rooms(List[str]) Start cleaning a subset of rooms

Properties

  • ayla_api The underlying AylaApi object
  • error_code Error code, if any. NB: these can be very stale as they are not immediately reset in the API when the error is cleared.
  • error_text English description of the error_code. The same caveat applies.
  • name The device name as it appears in the SharkClean app
  • oem_model_number A "rough" model number that does not distinguish, for example, between robots with and without a self-emptying base
  • properties_full A dictionary representing all known device properties and their metadata (type Dict[str, Dict])
  • property_values A convenience accessor into properties_full mapping property names to values
  • serial_number The unique device serial number used with the Ayla Networks API (NB: this name may change)
  • vac_model_number The precise model number
  • vac_serial_number The serial number printed on the device

Enums

  • OperatingModes Operation modes to control the vacuum (START, STOP, PAUSE, RETURN)
  • PowerModes Vacuum power mode (ECO, NORMAL, MAX)
  • Properties Properties to use with get_property_value/set_property_value

TODOs:

  • Add support for mapping
  • Once we have mapping, it may be possible to use the RSSI property combined with an increased update frequency to generate a wifi strength heatmap. Kind of orthogonal to the main purpose, but I really want to do this.

License

MIT