py-livewire 0.1.0__py3-none-any.whl

py_livewire/const.py

@@ -0,0 +1,36 @@
+"""Constants of the LiveWire mobile API, as used by the LiveWire EV app 1.9.0."""
+
+API_URL = "https://mobileapi.livewire.com/api"
+GIGYA_URL = "https://accounts.us1.gigya.com"
+
+# The app logs in with the global Gigya key and data center, regardless of the
+# user's region
+GIGYA_API_KEY = "4_6aX8cf8RFVt6F3JQQZaF3A"
+DATA_CENTER = "us1"
+
+BRAND = "LiveWire"
+APP_VERSION = "1.9.0"
+
+# What the app reports about the phone: "<manufacturer> <model>" and the
+# Android SDK level
+DEVICE_MODEL = "Google Pixel 8"
+OS_VERSION = "34"
+LANGUAGE = "en-US"
+
+KM_PER_MILE = 1.609344
+
+# Values of error.code in the response envelope
+CODE_OK = "0"
+CODE_PARTIAL = "-300"  # the app still shows the charging data that comes with it
+CODE_NOT_PAIRED = "3000"
+CODE_MAINTENANCE_OK = "5101"
+
+# Values of the top-level "code" when verifying a pairing code
+CODE_ATTEMPTS_EXCEEDED = 4003
+CODE_WRONG_CODE = 4004
+
+# Top-level "code" of the tire pressure response when the bike reported none
+CODE_NO_DATA = 3000
+
+# Charging schedules use English short day names
+DAYS = ("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun")

py_livewire/exceptions.py

@@ -0,0 +1,33 @@
+class LivewireError(Exception):
+    """Base class of all errors raised by this library."""
+
+
+class AuthenticationError(LivewireError):
+    """Logging in failed."""
+
+
+class ApiError(LivewireError):
+    """The backend answered with an error, as HTTP status or as error envelope."""
+
+    def __init__(
+        self, message: str, *, code: str | None = None, status: int | None = None
+    ):
+        super().__init__(message)
+        self.code = code
+        self.status = status
+
+
+class NotPairedError(ApiError):
+    """The bike did not answer for this device UUID (error code 3000).
+
+    The backend reports this when the device UUID is not paired with the bike,
+    and also when it cannot reach the bike at all.
+    """
+
+
+class PairingError(LivewireError):
+    """Requesting or verifying a pairing code failed."""
+
+    def __init__(self, message: str, *, code: int | None = None):
+        super().__init__(message)
+        self.code = code

py_livewire/models.py

@@ -0,0 +1,245 @@
+from dataclasses import dataclass, field
+from datetime import datetime, time, timedelta
+from typing import Any
+
+from .const import KM_PER_MILE
+from .utils import to_bool, to_datetime, to_float, to_int, to_timedelta
+
+
+def _str(value: Any) -> str | None:
+    return None if value is None else str(value)
+
+
+def _miles_to_km(value: float | None) -> float | None:
+    return None if value is None else value * KM_PER_MILE
+
+
+@dataclass
+class Bike:
+    id: str
+    vin: str | None
+    name: str | None
+    make: str | None
+    model: str | None
+    model_code: str | None
+    model_number: str | None
+    year: int | None
+    color: str | None
+    created: datetime | None
+    primary: bool
+    # Whether the client's device UUID is paired with the bike, None if the
+    # response did not tell
+    paired: bool | None
+    raw: dict[str, Any] = field(repr=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Bike":
+        return cls(
+            id=str(data["id"]),
+            vin=data.get("vin"),
+            name=data.get("name"),
+            make=data.get("make"),
+            model=data.get("model"),
+            model_code=data.get("modelCode"),
+            model_number=data.get("modelNumber"),
+            year=to_int(data.get("year")),
+            color=data.get("color"),
+            created=to_datetime(data.get("createdTime")),
+            primary=bool(to_bool(data.get("primaryBike"))),
+            paired=to_bool(data.get("pairingStatus")),
+            raw=data,
+        )
+
+
+@dataclass
+class ChargingStatus:
+    battery_level: float | None  # percent
+    charging: bool
+    plugged_in: bool
+    charge_limit: int | None  # percent
+    time_to_limit: timedelta | None
+    range_miles: float | None
+    odometer_miles: float | None
+    # How long ago the bike reported this data
+    data_age: timedelta | None
+    # Enhanced vehicle tracking: SAFE, STOLEN or PENDING
+    tracking_status: str | None
+    raw: dict[str, Any] = field(repr=False)
+
+    @property
+    def range_km(self) -> float | None:
+        return _miles_to_km(self.range_miles)
+
+    @property
+    def odometer_km(self) -> float | None:
+        return _miles_to_km(self.odometer_miles)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ChargingStatus":
+        status = data.get("bikeChargingData") or {}
+        time_to_limit = to_float(status.get("timeToMaxLimit"))
+
+        return cls(
+            battery_level=to_float(status.get("batteryPercentage")),
+            charging=bool(to_bool(status.get("chargingStatus"))),
+            plugged_in=bool(to_bool(status.get("pluggedIn"))),
+            charge_limit=to_int(status.get("maxLimit")) or None,
+            time_to_limit=None
+            if time_to_limit is None
+            else timedelta(minutes=time_to_limit),
+            range_miles=to_float(status.get("range")),
+            odometer_miles=to_float(status.get("odometer")),
+            data_age=to_timedelta(
+                status.get("durationElapsed"), status.get("durationUnit")
+            ),
+            tracking_status=data.get("trackingStatus"),
+            raw=data,
+        )
+
+
+@dataclass
+class Location:
+    latitude: float | None
+    longitude: float | None
+    altitude: float | None  # meters
+    speed_kmh: float | None
+    gps_time: datetime | None
+    reported_at: datetime | None
+    fix_type: int | None
+    raw: dict[str, Any] = field(repr=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Location":
+        return cls(
+            latitude=to_float(data.get("latitude")),
+            longitude=to_float(data.get("longitude")),
+            altitude=to_float(data.get("altitude")),
+            speed_kmh=to_float(data.get("speed_km")),
+            gps_time=to_datetime(data.get("gps_time")),
+            reported_at=to_datetime(data.get("tcu_timestamp")),
+            fix_type=to_int(data.get("fix_type")),
+            raw=data,
+        )
+
+
+@dataclass
+class TirePressure:
+    front: float | None
+    rear: float | None
+    front_recommended: float | None
+    rear_recommended: float | None
+    unit: str | None
+    front_low: bool
+    rear_low: bool
+    raw: dict[str, Any] = field(repr=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "TirePressure":
+        front = data.get("TirePressureFront") or {}
+        rear = data.get("TirePressureRear") or {}
+
+        def value(key: str) -> float | None:
+            return to_float((data.get(key) or {}).get("value"))
+
+        return cls(
+            front=to_float(front.get("value")),
+            rear=to_float(rear.get("value")),
+            # sic, the backend misspells these
+            front_recommended=value("RecomendedTirePressureFront"),
+            rear_recommended=value("RecomendedTirePressureRear"),
+            unit=front.get("UnitOfMeasure") or rear.get("UnitOfMeasure"),
+            front_low=bool(to_int(data.get("FrontTireLow"))),
+            rear_low=bool(to_int(data.get("RearTireLow"))),
+            raw=data,
+        )
+
+
+def _to_time(value: Any) -> time | None:
+    try:
+        return time.fromisoformat(value)
+    except (TypeError, ValueError):
+        return None
+
+
+@dataclass
+class ChargingSchedule:
+    id: str
+    # ACTIVE, INACTIVE or PENDING while the bike has not confirmed a change yet
+    status: str | None
+    days: list[str]
+    # Local time of the offset below, the window may cross midnight
+    start: time | None
+    end: time | None
+    timezone_offset_minutes: int | None
+    raw: dict[str, Any] = field(repr=False)
+
+    @property
+    def enabled(self) -> bool:
+        return (self.status or "").upper() == "ACTIVE"
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ChargingSchedule":
+        window = data.get("time") or {}
+
+        return cls(
+            id=str(data.get("scheduleId")),
+            status=data.get("status"),
+            days=list(data.get("days") or []),
+            start=_to_time(window.get("start")),
+            end=_to_time(window.get("end")),
+            timezone_offset_minutes=to_int(data.get("timezoneOffsetMinutes")),
+            raw=data,
+        )
+
+
+@dataclass
+class PairedUser:
+    user_id: str | None
+    device_uuid: str | None
+    device_model: str | None
+    device_type: str | None
+    email: str | None
+    first_name: str | None
+    last_name: str | None
+    paired_since: datetime | None
+    ready_to_unpair: bool
+    raw: dict[str, Any] = field(repr=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "PairedUser":
+        return cls(
+            user_id=_str(data.get("userId")),
+            device_uuid=data.get("deviceUUID"),
+            device_model=data.get("deviceModel"),
+            device_type=data.get("deviceType"),
+            email=data.get("userEmail"),
+            first_name=data.get("userFirstName"),
+            last_name=data.get("userLastName"),
+            paired_since=to_datetime(data.get("createdTime")),
+            ready_to_unpair=bool(to_bool(data.get("readyToUnpair"))),
+            raw=data,
+        )
+
+
+@dataclass
+class SoftwareVersion:
+    bike_id: str
+    vin: str | None
+    current: str | None
+    latest: str | None
+    # MATCH, MISMATCH or NEW_FEATURE_AVAILABLE
+    status: str | None
+    feature_ids: list[str]
+    raw: dict[str, Any] = field(repr=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "SoftwareVersion":
+        return cls(
+            bike_id=str(data.get("bikeId")),
+            vin=data.get("vin"),
+            current=data.get("currentVsbVersion"),
+            latest=data.get("maxAvailableVsbVersion"),
+            status=data.get("vsbMatchStatus"),
+            feature_ids=list(data.get("featureIds") or []),
+            raw=data,
+        )

py_livewire/utils.py

@@ -0,0 +1,87 @@
+import hashlib
+import math
+import re
+import uuid
+from datetime import datetime, timedelta
+from typing import Any
+
+
+def to_float(value: Any) -> float | None:
+    """Convert a number arriving as JSON number or string, None if unparseable."""
+    if value is None or isinstance(value, bool):
+        return None
+    try:
+        res = float(value)
+    except (TypeError, ValueError):
+        return None
+    return res if math.isfinite(res) else None
+
+
+def to_int(value: Any) -> int | None:
+    res = to_float(value)
+    return None if res is None else int(res)
+
+
+def to_bool(value: Any) -> bool | None:
+    if isinstance(value, bool) or value is None:
+        return value
+    if isinstance(value, str):
+        return {"true": True, "false": False}.get(value.strip().lower())
+    if isinstance(value, (int, float)):
+        return bool(value)
+    return None
+
+
+def to_datetime(value: Any) -> datetime | None:
+    if not isinstance(value, str) or not value:
+        return None
+    try:
+        return datetime.fromisoformat(value)
+    except ValueError:
+        return None
+
+
+_DURATION_UNITS = {
+    "second": "seconds",
+    "minute": "minutes",
+    "hour": "hours",
+    "day": "days",
+    "week": "weeks",
+}
+
+
+def to_timedelta(value: Any, unit: str | None) -> timedelta | None:
+    """Convert a value like ("2", "days") as used by the charging status."""
+    amount = to_float(value)
+    if amount is None or not unit:
+        return None
+    name = _DURATION_UNITS.get(unit.strip().lower().rstrip("s"))
+    return timedelta(**{name: amount}) if name else None
+
+
+def uuid_from_android_id(android_id: str) -> str:
+    """Derive the device UUID the Android app uses from an ANDROID_ID.
+
+    The app computes UUID.nameUUIDFromBytes(ANDROID_ID), i.e. an MD5 based version 3
+    UUID without namespace. Since Android 8 the ANDROID_ID differs per app signing key,
+    so the value of "adb shell settings get secure android_id" is not the one the app
+    sees; with root it is in /data/system/users/0/settings_ssaid.xml. Easier is reading
+    the UUID the app logs, see device_uuids_in_log().
+    """
+    digest = hashlib.md5(android_id.encode()).digest()
+    return str(uuid.UUID(bytes=digest, version=3))
+
+
+# The app logs its device UUID with this tag whenever it uses it, e.g. on launch
+LOG_TAG = "## UUID ##"
+
+_LOGGED_UUID = re.compile(
+    re.escape(LOG_TAG)
+    + r".*?\b([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b",
+    re.IGNORECASE,
+)
+
+
+def device_uuids_in_log(log: str) -> list[str]:
+    """Device UUIDs the app logged in logcat output, in order, without repeats."""
+    return list(dict.fromkeys(_LOGGED_UUID.findall(log)))

py_livewire-0.1.0.dist-info/METADATA

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: py-livewire
+Version: 0.1.0
+Summary: Async Python client for the LiveWire electric motorcycle cloud API
+Author-email: Igor Novgorodov <igor@novg.net>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/hass-livewire/py-livewire
+Project-URL: Issues, https://github.com/hass-livewire/py-livewire/issues
+Keywords: livewire,harley-davidson,motorcycle,electric,ev,api,cloud
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.10
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Provides-Extra: dev
+Requires-Dist: py-livewire[test]; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: license-file
+
+# py-livewire
+
+Async Python client for the LiveWire motorcycle cloud: the same API the LiveWire EV app
+(Android 1.9.0) uses, covering bikes, pairing, charging status and control, position, tire
+pressure, analytics, charging schedules, maintenance, roadside assistance, rides and dealers.
+
+> This project is not affiliated with LiveWire or Harley-Davidson. It uses an undocumented
+> API that may change or stop working at any time.
+
+## The device UUID
+
+Every session with the backend is opened for a *device UUID*. The app generates it on the
+phone (`UUID.nameUUIDFromBytes(ANDROID_ID)`); it is no secret, just an identifier. The backend
+only answers the **charging status** for device UUIDs that are **paired** with the bike, and
+otherwise returns error code `3000` ("Command manager api failed"), raised as `NotPairedError`.
+In testing, other data like the position, tire pressure and analytics was also served to
+unpaired UUIDs.
+
+There are two ways to get a paired UUID:
+
+- **Pair a new one** (recommended). Pairing happens through the cloud, no Bluetooth needed:
+  the backend makes the bike show a 6-digit code on its display, which is sent back. You have
+  to be at the bike once, with the ignition on, not in propulsion mode, not charging and with
+  cellular reception. `livewire pair` does this and prints the UUID to keep.
+- **Reuse an already paired UUID**, e.g. the one of your phone, see below.
+
+A paired UUID keeps working across logins. A new UUID needs pairing again.
+
+### Finding your phone's UUID
+
+The app doesn't show the UUID anywhere, but it writes it to the Android system log (logcat)
+with the tag `## UUID ##` whenever it uses it, including on launch. The log can be read without
+root:
+
+- **From a computer:** enable USB (or wireless) debugging on the phone, connect it, and run
+  `livewire phone-uuid`, then open the LiveWire app. This needs `adb` from the
+  Android platform tools. By hand, `adb logcat -v tag | grep "## UUID ##"` shows the same.
+- **On the phone alone** (Android 11+): enable wireless debugging and run `adb logcat` from a
+  local adb client such as LADB or `adb` in Termux, or use a log viewer app after granting it
+  access once with `adb shell pm grant <app package> android.permission.READ_LOGS`.
+
+With root, the UUID is in `/data/data/com.livewire.arrow/shared_prefs/locale.xml`, key
+`device_uuid`. The UUID survives reinstalling the app, but changes with a factory reset.
+
+Other routes don't work. Another app can't compute the UUID, because the device ID it is
+derived from differs per app since Android 8. The app is excluded from backups, and it trusts
+no user-installed certificates, so a TLS proxy needs root. Also, the backend's list of paired
+devices answers HTTP 401.
+
+Some phone makers' builds drop the debug log messages this relies on.
+
+## Installation
+
+Python 3.11 or newer.
+
+```
+pip install py-livewire
+```
+
+This also installs the `livewire` command line tool (or run `python -m py_livewire`).
+
+## Command line
+
+Credentials come from `LW_EMAIL` and `LW_PASSWORD` (prompted for otherwise), the device UUID
+from `LW_DEVICE_UUID` or `--device-uuid`.
+
+```
+livewire pair       # once, at the bike: pairs a new UUID and prints it
+export LW_DEVICE_UUID=<the printed UUID>
+livewire status     # battery, charging, range, odometer, position
+livewire bikes      # bikes of the account and their pairing state
+```
+
+With several bikes on the account, choose one with `--bike <id or VIN>`.
+
+## Library
+
+```python
+import asyncio
+
+from py_livewire import Client
+
+
+async def main():
+    async with Client("user@example.org", "password", device_uuid="…") as client:
+        bike = (await client.get_bikes())[0]
+
+        status = await client.get_charging_status(bike.id)
+        print(status.battery_level, status.range_km, status.charging)
+
+        location = await client.get_location(bike.id)
+        print(location.latitude, location.longitude)
+
+
+asyncio.run(main())
+```
+
+Pairing from code: `await client.pair(bike.id, get_code)`, where `get_code` is a plain or
+coroutine function returning the code from the bike's display. Afterwards `client.device_uuid`
+is the UUID to keep.
+
+`Client` logs in on the first request, and logs in again once if the backend rejects the
+session token. Pass `session=` to use your own `aiohttp.ClientSession`.
+
+### Methods
+
+| Area | Methods |
+|---|---|
+| Bikes | `get_bikes`, `get_vin_info`, `add_bike`, `update_bike`, `delete_bike` |
+| Pairing | `is_paired`, `pair`, `request_pairing_code`, `verify_pairing_code`, `get_paired_users`, `request_unpairing_code`, `verify_unpairing_code` |
+| Vehicle data | `get_charging_status`, `get_location`, `get_tire_pressure`, `get_software_versions`, `get_software_release_notes`, `get_charging_analytics`, `get_ride_analytics` |
+| Charging | `set_charge_limit`, `start_charging`, `get_charging_schedules`, `add_charging_schedule`, `update_charging_schedule`, `delete_charging_schedule` |
+| Tracking | `set_enhanced_tracking`, `set_tracking_consent` |
+| Maintenance | `get_maintenance_records`, `get_maintenance_schedule`, `add/update/delete_maintenance_record`, `get/add/update/delete_roadside_assistance` |
+| Rides | `get_rides`, `get_my_rides`, `get_ride`, `get_shared_ride`, `save_ride`, `update_ride`, `rename_ride`, `delete_ride`, `convert_recorded_ride`, `get_bookmarked_rides`, `bookmark_ride`, `remove_bookmark` |
+| Dealers | `get_dealers` |
+| Account and app | `get_notification_settings`, `update_notification_setting`, `set_language`, `get_external_urls`, `get_app_config`, `get_minimum_app_version`, `get_release_notes`, `get_countries`, `delete_account` |
+
+Vehicle data comes as dataclasses (`Bike`, `ChargingStatus`, `Location`, `TirePressure`,
+`ChargingSchedule`, `PairedUser`, `SoftwareVersion`), each with the full response in `raw`.
+Range and odometer arrive in miles; `ChargingStatus` also offers them in km. The rest returns
+the parsed JSON.
+
+Errors are `AuthenticationError`, `ApiError` (with `code` and `status`), its subclass
+`NotPairedError`, and `PairingError`, all derived from `LivewireError`.
+
+### Backend quirks
+
+- Errors mostly arrive with HTTP 200 as `{"error": {"code": …, "description": …}}`.
+- Numbers like the battery level arrive as JSON numbers or strings; both are handled.
+- `get_paired_users` was answered with HTTP 401 in testing, even for a paired UUID.
+- There is no working endpoint to cancel a pairing request; the app's is broken. An unused code
+  expires.
+- The app's endpoints for ride tags and the home screen battery status no longer exist on the
+  backend and are left out.
+
+## Development
+
+```sh
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+ruff check . && ruff format --check . && mypy && pytest
+```
+
+The tests run against a local fake backend and need no account.
+
+To release, bump `__version__` in `py_livewire/__init__.py` and push a `v*` tag (or
+publish a GitHub release); the PyPI Release workflow tests, builds and uploads it.

py_livewire-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+py_livewire/__init__.py,sha256=_2MM92LJ53Es1MTifh5p_bN_-8MXt_DmLzHZH0TV934,731
+py_livewire/__main__.py,sha256=PCX2FOCmvd5pI59rpBnS8s0RYcHHIx98eMfBGAVldyo,8479
+py_livewire/auth.py,sha256=bAZDNeqnic_dYLNuENx-NKdVUPj2potaLnTyt6Z03mg,3897
+py_livewire/client.py,sha256=GwDYJJkNX7p6aqdSgj2vlBu8BN4y4OcBsuwMsrWk8_g,34416
+py_livewire/const.py,sha256=tBFoHZvgkCrYjPY8mfNz6unSDqaFZOI_EFkSf-AnN5Y,1084
+py_livewire/exceptions.py,sha256=wx7usyjPZH5GPpFVZEwGzBmfnpzK0aLlBcud7z8uxEs,940
+py_livewire/models.py,sha256=7ylhhcHAWlwYtKMdVOBJujO0YGbXOEtP2_aqyAJ1fp4,7683
+py_livewire/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+py_livewire/utils.py,sha256=Z2_5IaR5j0hEeTgoSeOMKlErlWk3Hb7MmkEAS2kw2BQ,2649
+py_livewire-0.1.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+py_livewire-0.1.0.dist-info/METADATA,sha256=4lyiKtvlxhTlvGm2QEdA8tZB9AW8s6AO-xfH6Foea1M,8180
+py_livewire-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+py_livewire-0.1.0.dist-info/entry_points.txt,sha256=F-PA9oTW3Mb4cx-dNYs7kJ7gFAJMuGei6ZNAnqwGtVY,55
+py_livewire-0.1.0.dist-info/top_level.txt,sha256=71YccZC1kY0V-PvjIBZaCnGqxyWb35AlmVVIo1h9uTI,12
+py_livewire-0.1.0.dist-info/RECORD,,

py_livewire-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

py_livewire-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+livewire = py_livewire.__main__:main