iOS: hardware wallet connection reliability and UX polish

[piotr-iohk]

Part of #589.

Follow-up polish and parity items deferred from feat: home-screen hardware wallet (watch-only) #605. Android counterpart: synonymdev/bitkit-android#1030.

This issue tracks iOS-specific UX and connection-state gaps found during manual QA of #605. Scope may grow as later stacked PRs land (#611, settings screen, etc.).

Scope

Settings entry placement

Move Trezor Hardware Wallet from Settings → Advanced into Dev Settings, for consistency with the dev-gated entry point. Already agreed in #605 review; defer to a polish PR rather than blocking the home-screen slice.

Home connection indicator (QA 4a / 4b)

From #605 QA notes (manual tests 4a / 4b):

• 4a. BLE-connected device → disable phone Bluetooth: Home hardware-row indicator turns grey; watch-only balance stays visible.
• 4b. Re-enable Bluetooth: indicator turns green again on its own (auto-reconnect, no pairing prompt).

Current behaviour (4a fails): the Home BLE badge stays green when phone Bluetooth is disabled or the device is out of range. Android greys it out on disconnect.

Root cause: HwWalletConnectionIcon already supports green vs grey, but HwWallet.isConnected follows trezorManager.connectedDevice, which is only cleared on explicit disconnect / connect failure. iOS lacks Android's TrezorRepo.observeExternalDisconnects() / externalDisconnect wiring from TrezorBLEManager.didDisconnectPeripheral (and BT-off state) → TrezorManager.

Expected fix direction:

• On peripheral disconnect or bluetoothState != .poweredOn, clear live connection state for the Home badge (without suppressing auto-reconnect).
• Verify 4b end-to-end after 4a fix: BT back on → auto-reconnect → badge green again.

Related work

• Epic: epic: Trezor Hardware Wallet UI #589
• Shipped in: feat: home-screen hardware wallet (watch-only) #605
• Android tracking: Hardware wallet connection reliability and UX polish bitkit-android#1030

[jvsena42]

Thanks!

[jvsena42]

Device busy / ping cadence while Trezor is locked

Deferred from #611 QA (comment). Android counterpart: synonymdev/bitkit-android#1030 (device-state / ping-cadence).

Behaviour: while connecting with the Trezor locked (waiting for the user to unlock on-device), Bitkit keeps reopening the transport instead of backing off, which can keep the device busy. Observed in session logs ~09:10:41–09:11:02 UTC:

Time (UTC)	Event
09:10:41	User-initiated connect while device locked
09:10:49	THP handshake → DeviceLocked
09:10:49–51	Handshake retry: closeDevice → wait 2000ms → openDevice again
09:10:51 / 09:10:56 / 09:11:00	Further openDevice attempts on same path
09:11:02	Connection failed: THP handshake failed: … DeviceLocked

Root cause / where it lives: the closeDevice → wait 2000ms → openDevice reopen loop and the DeviceLocked outcome are not in this repo (nor in bitkit-core). They live inside the upstream trezor-connect-rs v0.2.2 crate (CallbackTransport::acquire), which is not vendored here. Locally:

• bitkit-core connect() does a single transport.acquire(...) with no retry wrapper.
• The Swift transport callbacks openDevice/closeDevice (TrezorTransport.swift) are pass-throughs with no back-off — each crate-driven openDevice re-runs the full TrezorBLEManager.connect() 3-attempt (1s/2s) BLE loop underneath, so one crate reopen can spawn several BLE link attempts.
• DeviceLocked is never surfaced as a distinct, retryable signal — it only arrives as the substring "THP handshake failed: DeviceLocked" (bitkit-core/.../errors.rs) after the crate's loop already failed, purely to produce a UI message (TrezorManager.swift, TrezorViewModel.swift).

So the loop cadence can't be changed at the level this repo can edit.

Expected fix direction:

• Classify DeviceLocked as a non-retryable / back-off state rather than a transient connect failure — requires an upstream trezor-connect-rs change (or a version bump that exposes such behaviour), then threading it through bitkit-core.
• Until then, consider whether the Swift side can avoid amplifying the churn (e.g. not re-running the 3-attempt BLE connect loop on every crate-driven openDevice, and not auto-reconnecting while a locked-device handshake is in flight).
• Align with Android's handling in Hardware wallet connection reliability and UX polish bitkit-android#1030.

Not introduced by #611.

[ovitrif]

Device busy / ping cadence while Trezor is locked
[…]

Should be fixable on latest version of bitkit-core (which android's #1030 requires), or else it might warrant additional changes in bitkit-core to expose a trustful mirror of Trezor's device lock state, this should be doable.

Please add issue to bitkit-core and check with @coreyphillips for implementation as needed 🙏🏻.

PS. I thought this core PR fixed the issue and opened up for more fine-tuning on this side:

• feat: surface typed Trezor PIN-failure errors via trezor-connect-rs 0.3.3 bitkit-core#106

If additional work is needed, then make sure it's clear what apps require in the new issue you add to bitkit-core.

IMHO the retry would be best owned by the apps, with bitkit-core exposing the APIs needed which thread to trezor-connect-rs. Reason for letting apps/consumers own the retry is to allow flexibility on how this is handled on UI side. Assumption unverified, feel free to diverge from it if investigation proves better resolve pathways.

[ovitrif]

I dug into this a bit more.

The issue described above is locked-device THP handshake churn, not the wrong/cancelled PIN failure typing fixed by synonymdev/bitkit-core#106.

What I think is happening:

• iOS starts trezorConnect(...).
• bitkit-core calls CallbackTransport.acquire(...) once.
• trezor-connect-rs hits THP DeviceLocked while the Trezor is locked.
• The crate treats that handshake error as retryable, so it closes/reopens the transport and retries after ~2s/3s.
• Each crate-level openDevice calls iOS TrezorBLEManager.connect(...), which itself has a 3-attempt BLE connect loop, so one upstream retry can fan out into multiple BLE link attempts.

bitkit-core#106 did land and is consumed here via bitkit-core 0.3.4, but it only maps protocol Failure codes (InvalidPin, PinCancelled, PinRequired, UserCancelled) after those failures are returned. This locked-device case happens earlier during THP session acquisition, before the app has a usable session/features result.

The more relevant core work is synonymdev/bitkit-core#104: TrezorFeatures.unlocked, trezor_refresh_features(), TrezorError.DeviceBusy, and TrezorTransportErrorCode.DeviceBusy. iOS is not fully using those yet: the Swift transport currently returns errorCode: nil for open/read/write/call failures, so core's structured DeviceBusy plumbing cannot trigger from Swift-originated transport failures.

So I think the remaining work is one or both of:

• upstream/core: make THP DeviceLocked during CallbackTransport.acquire(...) a non-retryable/backoff-aware state instead of continuing the close/open handshake retry loop;
• iOS: wire the new core primitives into the transport/manager layer so the app can back off and avoid amplifying retries while the device is locked/busy.

Small correction to the earlier note: the behavior is not limited to trezor-connect-rs v0.2.2; iOS is already pinned to bitkit-core 0.3.4, which includes trezor-connect-rs 0.3.3 and synonymdev/bitkit-core#106.

[jvsena42]

Home connection icon placement (Figma / Android parity)

Splitting this out from the §1 observation in #612 QA: the green/grey glyph state is correct, but on Home it's placed on the wrong row.

Current (iOS): in HardwareWalletsGrid.HardwareWalletCell the HwWalletConnectionIcon sits on the amount row, next to MoneyText (Bitkit/Components/HardwareWalletsGrid.swift:67):

VStack(alignment: .leading) {
    CaptionMText(wallet.name)          // name row  ← icon should live here
    HStack { btc-circle-blue; MoneyText; HwWalletConnectionIcon }  // amount row ← icon is here today
}

Expected (Figma 40364-130833): the glyph sits next to the device name, with the balance on its own row below.

Parity: Android Home renders it via WalletBalanceView titleTrailing — i.e. on the name row. This is a Home-only gap (from the #605 layout), not introduced by #612; Settings → Hardware Wallets already has the badge left of the name and matches.

Fix: move HwWalletConnectionIcon out of the amount HStack and onto the CaptionMText(wallet.name) row (name + trailing glyph), leaving the btc-circle-blue + MoneyText row unchanged. Small layout-only tweak to the shared home cell.

Note: distinct from the "Home connection indicator (QA 4a/4b)" grey/green state item already scoped in this issue — that one is the disconnect-state wiring; this one is purely icon placement.