diff --git a/README.rst b/README.rst index b544cda8..85e94cd1 100644 --- a/README.rst +++ b/README.rst @@ -39,13 +39,14 @@ While this library is mainly written to be included in `Home Assistant `_. +.. warning:: + + Login to **north american** and **rest of world** accounts requires a captcha to be solved. See `Using Captchas `_ for more information. + Please be aware that :code:`bimmer_connected` is an :code:`async` library when using it in Python code. The description of the :code:`modules` can be found in the `module documentation `_. -.. note:: - Login to **north american** accounts requires a captcha to be solved. See `Captcha (North America) `_ for more information. - Example in an :code:`asyncio` event loop ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: @@ -55,7 +56,8 @@ Example in an :code:`asyncio` event loop from bimmer_connected.api.regions import Regions async def main(): - account = MyBMWAccount(USERNAME, PASSWORD, Regions.REST_OF_WORLD) + # hcaptcha_token is only required for the first login, see the captcha documentation + account = MyBMWAccount(USERNAME, PASSWORD, Regions.REST_OF_WORLD, hcaptcha_token="P1_eY...") await account.get_vehicles() vehicle = account.get_vehicle(VIN) print(vehicle.brand, vehicle.name, vehicle.vin) @@ -75,8 +77,8 @@ Example in non-async code from bimmer_connected.account import MyBMWAccount from bimmer_connected.api.regions import Regions - - account = MyBMWAccount(USERNAME, PASSWORD, Regions.REST_OF_WORLD) + # hcaptcha_token is only required for the first login, see the captcha documentation + account = MyBMWAccount(USERNAME, PASSWORD, Regions.REST_OF_WORLD, hcaptcha_token="P1_eY...") asyncio.run(account.get_vehicles()) vehicle = account.get_vehicle(VIN) print(vehicle.brand, vehicle.name, vehicle.vin) diff --git a/docs/source/captcha.rst b/docs/source/captcha.rst index faf1683c..81bffdda 100644 --- a/docs/source/captcha.rst +++ b/docs/source/captcha.rst @@ -11,31 +11,18 @@ Depending on your region, you will need to solve a different captcha. Please sel - `North America `_ - `Rest of World `_ -.. note:: - The captcha token is only valid for a short time and can only be used once. - -Using the Python API ---------------------- - -When using the Python API, pass the token via the :code:`hcaptcha_token` argument when creating the account object. - -:: - - account = MyBMWAccount(USERNAME, PASSWORD, REGION, hcaptcha_token=HCAPTCHA_TOKEN) - .. warning:: + The captcha token is only valid for a short time and can only be used once. - Ensure to keep the current :code:`MyBMWAccount` instance in memory to avoid having to solve the captcha again. -For storing the data across restarts, an example implementation can be found in -`bimmerconnected.main() `_ -(with :code:`args.oauth_store` being a :code:`pathlib.Path()` object). +Using Home Assistant +-------------------- -If you are running this script inside another system (e.g. demoticz), you can also store and read the information using their native tools -- it does not have to be a JSON file, as long as the data is stored and read correctly. +When using the Home Assistant integration, simply paste the token into the config flow when configuring the account. Using the CLI ------------- + When using the CLI, pass the token via the :code:`--captcha-token` argument (see `CLI documentation `_). :: @@ -48,6 +35,26 @@ After a successful login, the :code:`--captcha-token` parameter can be omitted ( bimmerconnected status USERNAME PASSWORD REGION -.. warning:: +.. note:: Please make sure to use the :code:`--oauth-store` (used by default) to avoid having to solve the captcha again. + +Using the Python API +--------------------- + +When using the Python API, pass the token via the :code:`hcaptcha_token` argument when creating the account object. + +:: + + account = MyBMWAccount(USERNAME, PASSWORD, REGION, hcaptcha_token=HCAPTCHA_TOKEN) + +.. warning:: + + Ensure to keep the current :code:`MyBMWAccount` instance in memory to avoid having to solve the captcha again. + +For storing the data across restarts, an example implementation can be found in +`bimmerconnected.main() `_ +(with :code:`args.oauth_store` being a :code:`pathlib.Path()` object). + +If you are running this script inside another system (e.g. demoticz), you can also store and read the information using their native tools +- it does not have to be a JSON file, as long as the data is stored and read correctly. diff --git a/docs/source/captcha/north_america.rst b/docs/source/captcha/north_america.rst index 78ccb2de..422a4500 100644 --- a/docs/source/captcha/north_america.rst +++ b/docs/source/captcha/north_america.rst @@ -1,7 +1,7 @@ Captcha (North America) ======================= -Please see :doc:`../captcha` for general information on using captchas. +Please confirm that you are a human and submit the form. See :doc:`../captcha` for more information. .. raw:: html :file: north_america_form.html diff --git a/docs/source/captcha/rest_of_world.rst b/docs/source/captcha/rest_of_world.rst index 3204587e..678c364e 100644 --- a/docs/source/captcha/rest_of_world.rst +++ b/docs/source/captcha/rest_of_world.rst @@ -1,7 +1,7 @@ Captcha (Rest of World) ======================= -Please see :doc:`../captcha` for general information on using captchas. +Please confirm that you are a human and submit the form. See :doc:`../captcha` for more information. .. raw:: html :file: rest_of_world_form.html diff --git a/docs/source/conf.py b/docs/source/conf.py index 37d7ccc6..7c975957 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,3 +1,5 @@ +import datetime + # Configuration file for the Sphinx documentation builder. # # This file does only contain a selection of the most common options. For a @@ -17,8 +19,8 @@ # -- Project information ----------------------------------------------------- project = 'bimmer_connected' -copyright = '2018-2020, m1n3rva, gerard33' -author = 'rikroe' +copyright = f'2018-{datetime.datetime.now().year}, m1n3rva, gerard33, rikroe' +author = 'm1n3rva, gerard33, rikroe' # The short X.Y version # version = const.__version__