Skip to main content

Library to read data from the BMW Connected Drive portal

Project description

bimmer_connected

https://badge.fury.io/py/bimmer-connected.svg https://github.com/bimmerconnected/bimmer_connected/actions/workflows/test.yml/badge.svg?branch=master https://readthedocs.org/projects/bimmer-connected/badge/?version=latest https://codecov.io/gh/bimmerconnected/bimmer_connected/branch/master/graph/badge.svg?token=qNT50j82f6 https://static.pepy.tech/badge/bimmer_connected/week https://static.pepy.tech/badge/bimmer_connected/month https://static.pepy.tech/badge/bimmer_connected

This is a simple library to query and control the status of your BMW, Mini, or Toyota Supra vehicle from the MyBMW portal.

Installation

bimmer_connected is tested against Python 3.8 or above. Just install the latest release from PyPI using pip3 install --upgrade bimmer_connected.

Alternatively, clone the project and execute pip install -e . to install the current master branch.

Usage

While this library is mainly written to be included in Home Assistant, it can be use on its own.

After installation, execute bimmerconnected from command line for usage instruction or see the full CLI documentation.

Please be aware that bimmer_connected is an async library when using it in Python code. The description of the modules can be found in the module documentation.

Example in an asyncio event loop

import asyncio
from bimmer_connected.account import MyBMWAccount
from bimmer_connected.api.regions import Regions

async def main():
    # 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)

    result = await vehicle.remote_services.trigger_remote_light_flash()
    print(result.state)

asyncio.run(main())

Example in non-async code

import asyncio
from bimmer_connected.account import MyBMWAccount
from bimmer_connected.api.regions import Regions

# 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)

result = asyncio.run(vehicle.remote_services.trigger_remote_light_flash())
print(result.state)

Compatibility

This works with BMW/Mini/Toyota Supra vehicles with a MyBMW account. So far it is tested on vehicles with a ‘MGU’, ‘NBTEvo’, ‘EntryEvo’, ‘NBT’, or ‘EntryNav’ navigation system. If you have any trouble with other navigation systems, please create an issue with your server responses (see next section).

To use this library, your BMW/Mini/Toyota Supra must have the remote services enabled for your vehicle. You might need to book this in the MyBMW/Mini Connected/Supra Connect portal and this might cost some money. In addition to that you need to enable the Remote Services in your infotainment system in the vehicle.

Different models of vehicles and infotainment systems result in different types of attributes provided by the server. So the experience with the library will certainly vary across the different vehicle models.

Data Contributions

If some features do not work for your vehicle, we would need the data returned form the server to analyse this and potentially extend the code. Different models and head unit generations lead to different responses from the server.

If you want to contribute your data, perform the following steps:

# get the latest version of the library
pip3 install --upgrade bimmer_connected

# run the fingerprint function
bimmerconnected fingerprint <username> <password> <region>

This will create a set of log files in the “vehicle_fingerprint” folder. Before sending the data to anyone please check for any personal data such as dealer name or country.

The following attributes are by default replaced with anonymized values:

  • vin (Vehicle Identification Number)

  • lat and lon (GPS position)

  • licensePlate

  • information of dealer

Create a new fingerprint data contribution and add the files as attachment to the discussion.

Please add your model and year to the title of the issue, to make it easier to organize. If you know the “chassis code” of your car, you can include that too. (For example, googling “2017 BMW X5” will show a Wikipedia article entitled “BMW X5 (F15)”. F15 is therefore the chassis code of the car.)

Note: We will then use this data as additional test cases. So we will publish (parts of) it (after checking for personal information again) and use this as test cases for our library. If you do not want this, please let us know in advance.

Code Contributions

Contributions are welcome! Please make sure that your code passes the checks in .github/workflows/test.yml. We currently test against flake8, pylint and our own pytest suite. And please add tests where it makes sense. The more the better.

See the contributing guidelines for more details.

Thank you

Thank you to all contributors for your research and contributions! And thanks to everyone who shares the fingerprint data of their vehicles which we use to test the code. A special thanks to @HuChundong, @muxiachuixue, @vividmuse for figuring out how to solve login issues!

This library is basically a best-of of other similar solutions, yet none of them provided a ready to use library with a matching interface to be used in Home Assistant and is available on pypi.

Thank you for your great software!

License

The bimmer_connected library is licensed under the Apache License 2.0.

Disclaimer

This library is not affiliated with or endorsed by BMW Group.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

bimmer_connected-0.17.2.tar.gz (7.2 MB view details)

Uploaded Source

Built Distribution

bimmer_connected-0.17.2-py3-none-any.whl (165.3 kB view details)

Uploaded Python 3

File details

Details for the file bimmer_connected-0.17.2.tar.gz.

File metadata

  • Download URL: bimmer_connected-0.17.2.tar.gz
  • Upload date:
  • Size: 7.2 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.12.7

File hashes

Hashes for bimmer_connected-0.17.2.tar.gz
Algorithm Hash digest
SHA256 b1fa68caee58699ab9908d03d20cd37a97d1ac225565b839ec5bca9d79cfc7e3
MD5 05b1f62a99ada5611e2e1a6c08954c1e
BLAKE2b-256 2f60194ff75f4ad17c4aed1936f0004f8a19a556832c131476429381efd8d29d

See more details on using hashes here.

File details

Details for the file bimmer_connected-0.17.2-py3-none-any.whl.

File metadata

File hashes

Hashes for bimmer_connected-0.17.2-py3-none-any.whl
Algorithm Hash digest
SHA256 874d1ff4d2db534de6947bb9849b1e292cdaa169e6558a53b99b69a79d3ebea2
MD5 4f72e0fd27553879d3d69ef299d70bed
BLAKE2b-256 628b937534262943d276b54ed310096fa4af0f478c5b2515375983d99bdf4a2c

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page