Add SVM / Find My Car support for Hyundai BlueLink USA

[blka]

Summary

Add support for the Hyundai USA BlueLink 360 Surround View Monitor (SVM) / Find My Car camera feature.

Background

Upstream discussion #1194 captured the native iOS MyHyundai endpoints and confirmed the full flow works. This issue tracks library implementation; HA integration follow-up will be handled separately.

Endpoints

• GET https://api.telematics.hyundaiusa.com/ac/v2/svm/getSVMDetails — retrieve latest SVM image and metadata
• POST https://api.telematics.hyundaiusa.com/ac/v2/svm/findMyCarSVM — trigger a fresh capture

Proposed API surface

Add the following public methods to HyundaiBlueLinkApiUSA:

def get_svm_details(self, token: Token, vehicle: Vehicle) -> SVMDetailsResponse:
    ...

def request_svm_capture(
    self,
    token: Token,
    vehicle: Vehicle,
    acknowledged_warning: bool = False,
) -> SVMDetailsResponse:
    ...

Base class (ApiImpl) will define the same methods raising NotImplementedError so other regions fail clearly.

Key behavior

• request_svm_capture must require acknowledged_warning=True; otherwise raise an exception.
• Send blueLinkServicePin in both headers and JSON body, matching the working PoC in 360 Surround View Camera #1194.
• Decode svmImage base64 inside the library and return raw JPG bytes.
• Poll getSVMDetails every 10–15 s after triggering capture, comparing gpsDetail.time to detect a fresh image; timeout after 90–120 s.
• Map pending/cooldown error (errorSubCode: HT_533, HTTP 502) to existing DuplicateRequestError.
• Redact svmImage and gpsDetail coordinates from debug logs.
• V1 exposes only the full composite JPG. Panel splitting is out of scope until imageSize/boundaryArea geometry is understood.

Test plan

• Mock successful getSVMDetails response and verify decoded bytes + metadata.
• Mock findMyCarSVM → getSVMDetails polling flow with timestamp change.
• Mock HT_533 response and assert DuplicateRequestError.
• Mock missing acknowledged_warning and assert exception.
• Verify debug logs do not contain base64 image data or GPS coordinates.

References

• Discussion 360 Surround View Camera #1194 (research and PoC by @ijojog)

[ijojog]

Great, thank you for opening this. I’ll wait for a branch/PR and I’m happy to test SVM capture/retrieval again on my Hyundai USA Tucson when needed.

[blka]

Implementation complete and ready for PR.

Summary

Branch feature/svm-usa-support pushed to origin; PR against upstream/master will be opened shortly.

What was added

• hyundai_kia_connect_api/svm.py — SVMDetails dataclass, response parser, and log redaction helpers.
• hyundai_kia_connect_api/exceptions.py — SafetyAcknowledgmentError.
• hyundai_kia_connect_api/ApiImpl.py — get_svm_details / request_svm_capture stubs raising NotImplementedError.
• hyundai_kia_connect_api/HyundaiBlueLinkApiUSA.py — concrete SVM implementation:
  • get_svm_details retrieves and decodes the composite JPG.
  • request_svm_capture enforces safety acknowledgment, triggers capture, maps HT_533 to DuplicateRequestError, and polls until a fresh image is available.
• hyundai_kia_connect_api/__init__.py — exports SVMDetails at package root.
• tests/us_svm_test.py — 18 unit tests covering success path, polling, duplicate request, missing acknowledgment, debug-log redaction, POST body contract, empty 502 handling, and raw-string freshness.
• .ruff.toml — sets target-version = "py310" to prevent Python 3.10 syntax regressions.

Verification

• ruff check . and ruff format . pass.
• pytest -q passes: 244 passed, 8 skipped.

Notes

• V1 exposes only the full composite JPG; panel splitting is out of scope.
• USA Hyundai only; other regions inherit the base stubs.
• .ruff.toml is included because the previous default target version allowed Python 3.14-only syntax (bare multi-exception except) to slip through. This is a defensive build-config change scoped to the same PR.

[ijojog]

Great, thank you. I’ll wait for the PR and I’m happy to test the branch on my Hyundai USA Tucson when you need a real-vehicle test.

[github-actions]

This issue is stale because it has been open for 60 days with no activity. Are you still experiencing this issue?

[ijojog]

Yes, this is still relevant.

The Hyundai USA SVM / Find My Car flow was tested successfully on my 2025 Tucson Hybrid using the standalone PR branch/script.

Confirmed working in live testing:

• get_svm_details
• request_svm_capture
• fresh timestamp polling
• decoded JPG output

I believe the related API PR is still #1203:

#1203

So yes, this issue should remain open until the API work is merged/released, and then the Home Assistant integration can expose it.