Code Maintainers Wanted
=======================
I no longer have a Kia or Hyundai so don't maintain this like I used to. Others who are interested in jumping in are welcome to join the project! Even just pull requests are appreciated!
Introduction
============
This is a Kia UVO, Hyundai Bluelink, Genesis Connect(Canada Only) written in python. It is primary consumed by home assistant. If you are looking for a home assistant Kia / Hyundai implementation please look here: https://github.com/Hyundai-Kia-Connect/kia_uvo. Much of this base code came from reading `bluelinky <https://github.com/Hacksore/bluelinky>`_ and contributions to the kia_uvo home assistant project.
Chat on discord:: |Discord|
.. |Discord| image:: https://img.shields.io/discord/652755205041029120
:target: https://discord.gg/HwnG8sY
:alt: Discord
API Usage
=========
This package is designed to simplify the complexity of using multiple regions. It attempts to standardize the usage regardless of what brand or region the car is in. That isn't always possible though, in particular some features differ from one to the next.
Python 3.10 or newer is required to use this package. Vehicle manager is the key class that is called to manage the vehicle lists. One vehicle manager should be used per login. Key data points required to instantiate vehicle manager are::
region: int
brand: int,
username: str
password: str
pin: str (required for CA, and potentially USA, otherwise pass a blank string)
Key values for the int exist in the `const.py <https://github.com/Hyundai-Kia-Connect/hyundai_kia_connect_api/blob/master/hyundai_kia_connect_api/const.py>`_ file as::
REGIONS = {1: REGION_EUROPE, 2: REGION_CANADA, 3: REGION_USA, 4: REGION_CHINA, 5: REGION_AUSTRALIA}
BRANDS = {1: BRAND_KIA, 2: BRAND_HYUNDAI, 3: BRAND_GENESIS}
Once this is done you can now make the following calls against the vehicle manager::
#Checks the token is still valid and updates it if not. Should be called before anything else if the code has been running for any length of time.
check_and_refresh_token(self)
Ideal refresh command. Checks if the car has been updated since the time in seconds provided. If so does a cached update. If not force calls the car.
check_and_force_update_vehicles(self, force_refresh_interval) # Interval in seconds - consider API Rate Limits https://github.com/Hacksore/bluelinky/wiki/API-Rate-Limits
Used to return a specific vehicle object:
get_vehicle(self, vehicle_id)
#Updates all cars with what is cached in the cloud:
update_all_vehicles_with_cached_state(self)
Updates a specific car with cached state:
update_vehicle_with_cached_state(self, vehicle_id)
Force refreshes all cars:
force_refresh_all_vehicles_states(self)
Force refreshes a single car:
force_refresh_vehicles_states(self, vehicle_id)
An example call would be::
from hyundai_kia_connect_api import *
vm = VehicleManager(region=2, brand=1, username="username@gmail.com", password="password", pin="1234")
vm.check_and_refresh_token()
vm.update_all_vehicles_with_cached_state()
print(vm.vehicles)
If geolocation is required you can also allow this by running::
vm = VehicleManager(region=2, brand=1, username="username@gmail.com", password="password", pin="1234", geocode_api_enable=True, geocode_api_use_email=True)
This will populate the address of the vehicle in the vehicle instance.
The Bluelink App is reset to English for users who have set another language in the Bluelink App in Europe when using hyundai_kia_connect_api.
To avoid this, you can pass the optional parameter language (default is "en") to the constructor of VehicleManager, e.g. for Dutch::
vm = VehicleManager(region=2, brand=1, username="username@gmail.com", password="password", pin="1234", language="nl")
Note: this is only implemented for Europe currently.
For a list of language codes, see here: https://www.science.co.il/language/Codes.php. Currently in Europe the Bluelink App shows the following languages::
- "en" English
- "de" German
- "fr" French
- "it" Italian
- "es" Spanish
- "sv" Swedish
- "nl" Dutch
- "no" Norwegian
- "cs" Czech
- "sk" Slovak
- "hu" Hungarian
- "da" Danish
- "pl" Polish
- "fi" Finnish
- "pt" Portuguese
In Europe and some other regions also trip info can be retrieved. For a month you can ask the days with trips. And you can ask for a specific day for all the trips of that specific day.::
- First call vm.update_month_trip_info(vehicle.id, yyyymm) before getting vehicle.month_trip_info for that month
- First call vm.update_day_trip_info(vehicle.id, day.yyyymmdd) before getting vehicle.day_trip_info for that day
Example of getting trip info of the current month and day (vm is VehicleManager instance)::
now = datetime.now()
yyyymm = now.strftime("%Y%m")
yyyymmdd = now.strftime("%Y%m%d")
vm.update_month_trip_info(vehicle.id, yyyymm)
if vehicle.month_trip_info is not None:
for day in vehicle.month_trip_info.day_list: # ordered on day
if yyyymmdd == day.yyyymmdd: # in example only interested in current day
vm.update_day_trip_info(vehicle.id, day.yyyymmdd)
if vehicle.day_trip_info is not None:
for trip in reversed(vehicle.day_trip_info.trip_list): # show oldest first
print(f"{day.yyyymmdd},{trip.hhmmss},{trip.drive_time},{trip.idle_time},{trip.distance},{trip.avg_speed},{trip.max_speed}")
CLI Usage
=========
A tool `bluelink` is provided that enable querying the vehicles and save the
state to a JSON file. Example usage:
::
bluelink --region Canada --brand Hyundai --username FOO --password BAR --pin 1234 info --json infos.json
Environment variables BLUELINK_XXX can be used to provide a default value for
the corresponding --xxx argument.
Raw data
{
"_id": null,
"home_page": "https://github.com/Hyundai-Kia-Connect/hyundai_kia_connect_api",
"name": "hyundai-kia-connect-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "hyundai_kia_connect_api",
"author": "Fuat Akgun",
"author_email": "fuatakgun@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c0/04/a810880833d3b620bcde2c790c5318af74cafcdf1b03fa8e40fc860ecb00/hyundai_kia_connect_api-3.30.1.tar.gz",
"platform": null,
"description": "Code Maintainers Wanted\n=======================\n\nI no longer have a Kia or Hyundai so don't maintain this like I used to. Others who are interested in jumping in are welcome to join the project! Even just pull requests are appreciated!\n\nIntroduction\n============\n\nThis is a Kia UVO, Hyundai Bluelink, Genesis Connect(Canada Only) written in python. It is primary consumed by home assistant. If you are looking for a home assistant Kia / Hyundai implementation please look here: https://github.com/Hyundai-Kia-Connect/kia_uvo. Much of this base code came from reading `bluelinky <https://github.com/Hacksore/bluelinky>`_ and contributions to the kia_uvo home assistant project.\n\nChat on discord:: |Discord|\n\n.. |Discord| image:: https://img.shields.io/discord/652755205041029120\n :target: https://discord.gg/HwnG8sY\n :alt: Discord\n\nAPI Usage\n=========\n\nThis package is designed to simplify the complexity of using multiple regions. It attempts to standardize the usage regardless of what brand or region the car is in. That isn't always possible though, in particular some features differ from one to the next.\n\nPython 3.10 or newer is required to use this package. Vehicle manager is the key class that is called to manage the vehicle lists. One vehicle manager should be used per login. Key data points required to instantiate vehicle manager are::\n\n region: int\n brand: int,\n username: str\n password: str\n pin: str (required for CA, and potentially USA, otherwise pass a blank string)\n\nKey values for the int exist in the `const.py <https://github.com/Hyundai-Kia-Connect/hyundai_kia_connect_api/blob/master/hyundai_kia_connect_api/const.py>`_ file as::\n\n REGIONS = {1: REGION_EUROPE, 2: REGION_CANADA, 3: REGION_USA, 4: REGION_CHINA, 5: REGION_AUSTRALIA}\n BRANDS = {1: BRAND_KIA, 2: BRAND_HYUNDAI, 3: BRAND_GENESIS}\n\nOnce this is done you can now make the following calls against the vehicle manager::\n\n #Checks the token is still valid and updates it if not. Should be called before anything else if the code has been running for any length of time.\n check_and_refresh_token(self)\n\n Ideal refresh command. Checks if the car has been updated since the time in seconds provided. If so does a cached update. If not force calls the car.\n check_and_force_update_vehicles(self, force_refresh_interval) # Interval in seconds - consider API Rate Limits https://github.com/Hacksore/bluelinky/wiki/API-Rate-Limits\n\n Used to return a specific vehicle object:\n get_vehicle(self, vehicle_id)\n\n #Updates all cars with what is cached in the cloud:\n update_all_vehicles_with_cached_state(self)\n\n Updates a specific car with cached state:\n update_vehicle_with_cached_state(self, vehicle_id)\n\n Force refreshes all cars:\n force_refresh_all_vehicles_states(self)\n\n Force refreshes a single car:\n force_refresh_vehicles_states(self, vehicle_id)\n\nAn example call would be::\n\n from hyundai_kia_connect_api import *\n vm = VehicleManager(region=2, brand=1, username=\"username@gmail.com\", password=\"password\", pin=\"1234\")\n vm.check_and_refresh_token()\n vm.update_all_vehicles_with_cached_state()\n print(vm.vehicles)\n\nIf geolocation is required you can also allow this by running::\n\n vm = VehicleManager(region=2, brand=1, username=\"username@gmail.com\", password=\"password\", pin=\"1234\", geocode_api_enable=True, geocode_api_use_email=True)\n\nThis will populate the address of the vehicle in the vehicle instance.\n\nThe Bluelink App is reset to English for users who have set another language in the Bluelink App in Europe when using hyundai_kia_connect_api.\nTo avoid this, you can pass the optional parameter language (default is \"en\") to the constructor of VehicleManager, e.g. for Dutch::\n\n vm = VehicleManager(region=2, brand=1, username=\"username@gmail.com\", password=\"password\", pin=\"1234\", language=\"nl\")\n\nNote: this is only implemented for Europe currently.\n\nFor a list of language codes, see here: https://www.science.co.il/language/Codes.php. Currently in Europe the Bluelink App shows the following languages::\n\n- \"en\" English\n- \"de\" German\n- \"fr\" French\n- \"it\" Italian\n- \"es\" Spanish\n- \"sv\" Swedish\n- \"nl\" Dutch\n- \"no\" Norwegian\n- \"cs\" Czech\n- \"sk\" Slovak\n- \"hu\" Hungarian\n- \"da\" Danish\n- \"pl\" Polish\n- \"fi\" Finnish\n- \"pt\" Portuguese\n\n\nIn Europe and some other regions also trip info can be retrieved. For a month you can ask the days with trips. And you can ask for a specific day for all the trips of that specific day.::\n- First call vm.update_month_trip_info(vehicle.id, yyyymm) before getting vehicle.month_trip_info for that month\n- First call vm.update_day_trip_info(vehicle.id, day.yyyymmdd) before getting vehicle.day_trip_info for that day\n\nExample of getting trip info of the current month and day (vm is VehicleManager instance)::\n\n now = datetime.now()\n yyyymm = now.strftime(\"%Y%m\")\n yyyymmdd = now.strftime(\"%Y%m%d\")\n vm.update_month_trip_info(vehicle.id, yyyymm)\n if vehicle.month_trip_info is not None:\n for day in vehicle.month_trip_info.day_list: # ordered on day\n if yyyymmdd == day.yyyymmdd: # in example only interested in current day\n vm.update_day_trip_info(vehicle.id, day.yyyymmdd)\n if vehicle.day_trip_info is not None:\n for trip in reversed(vehicle.day_trip_info.trip_list): # show oldest first\n print(f\"{day.yyyymmdd},{trip.hhmmss},{trip.drive_time},{trip.idle_time},{trip.distance},{trip.avg_speed},{trip.max_speed}\")\n\n\nCLI Usage\n=========\n\nA tool `bluelink` is provided that enable querying the vehicles and save the\nstate to a JSON file. Example usage:\n\n::\n\n bluelink --region Canada --brand Hyundai --username FOO --password BAR --pin 1234 info --json infos.json\n\nEnvironment variables BLUELINK_XXX can be used to provide a default value for\nthe corresponding --xxx argument.\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "Python Boilerplate contains all the boilerplate you need to create a Python package.",
"version": "3.30.1",
"project_urls": {
"Homepage": "https://github.com/Hyundai-Kia-Connect/hyundai_kia_connect_api"
},
"split_keywords": [
"hyundai_kia_connect_api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4008cdb749cff98e59accc4a34bbadc2eec0e49f3368cc8a1af8e1720ec18de9",
"md5": "b90c08eb1ef38107a8f4be577d448d43",
"sha256": "d128416b243dd9fa90a835c4a10c78182531c0c5a1587a9254e9d5b0af100d08"
},
"downloads": -1,
"filename": "hyundai_kia_connect_api-3.30.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "b90c08eb1ef38107a8f4be577d448d43",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.10",
"size": 74346,
"upload_time": "2024-12-24T21:22:54",
"upload_time_iso_8601": "2024-12-24T21:22:54.686854Z",
"url": "https://files.pythonhosted.org/packages/40/08/cdb749cff98e59accc4a34bbadc2eec0e49f3368cc8a1af8e1720ec18de9/hyundai_kia_connect_api-3.30.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c004a810880833d3b620bcde2c790c5318af74cafcdf1b03fa8e40fc860ecb00",
"md5": "b27f35b20a69e26b13d6fd05da4f98db",
"sha256": "9a23b9865e806cdd7c855938464c69bf6267d31835147b59ee1a0322f9461d07"
},
"downloads": -1,
"filename": "hyundai_kia_connect_api-3.30.1.tar.gz",
"has_sig": false,
"md5_digest": "b27f35b20a69e26b13d6fd05da4f98db",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 74262,
"upload_time": "2024-12-24T21:22:56",
"upload_time_iso_8601": "2024-12-24T21:22:56.223040Z",
"url": "https://files.pythonhosted.org/packages/c0/04/a810880833d3b620bcde2c790c5318af74cafcdf1b03fa8e40fc860ecb00/hyundai_kia_connect_api-3.30.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-24 21:22:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Hyundai-Kia-Connect",
"github_project": "hyundai_kia_connect_api",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "beautifulsoup4",
"specs": [
[
">=",
"4.10.0"
]
]
},
{
"name": "curlify",
"specs": [
[
">=",
"2.2.1"
]
]
},
{
"name": "python-dateutil",
"specs": []
},
{
"name": "pytz",
"specs": [
[
">=",
"2021.3"
]
]
},
{
"name": "certifi",
"specs": [
[
">=",
"2024.6.2"
]
]
}
],
"lcname": "hyundai-kia-connect-api"
}
JSON
