Skip to Content
HardwareTransportDisconnects and reconnection
On this page

Disconnects and reconnection

USB unplugging, loss of BLE signal, Bluetooth resets, and firmware reboots can interrupt a connection. Follow these steps to end the interrupted operation, reconnect the device, and reuse the selected wallet safely.

What the SDK already does

  • Ordinary disconnect / reconnect does not forget the confirmed connectProtocol. You do not re-pick V1 vs V2 after a drop.
  • In-flight calls fail. The SDK does not replay signing, wipe, or firmware update.
  • Protocol V2 keeps per-device call ordering. Do not overlap a second business call while the first is recovering.

What you must do

  1. Subscribe to DEVICE.CONNECT / DEVICE.DISCONNECT once at app start.
  2. On DISCONNECT, mark that connectId busy/invalid and fail the current UI flow. Do not retry the same side-effecting method.
  3. Search again (searchDevices) when the user is ready. USB replug and BLE re-pair can mint a new connectId. Cache USB and BLE IDs separately. See Identifiers.
  4. After a new connection, refresh device state with getDeviceState. Reuse persisted deviceId + passphraseState; do not persist firmware session_id.
  5. On the next address / sign call, pass the persisted passphraseState or useEmptyPassphrase: true. Core resumes the firmware session inside that method. Do not reopen a wallet session just to reconnect.
import { DEVICE } from '@onekeyfe/hd-core';
 
HardwareSDK.on(DEVICE.DISCONNECT, (payload) => {
  markDisconnected(payload);
  // Fail the open UI flow; do not replay signing or firmware updates.
});
HardwareSDK.on(DEVICE.CONNECT, () => {
  refreshDeviceList();
});

BLE-specific

  • Permissions (BLUETOOTH_SCAN / CONNECT, iOS Bluetooth usage strings, often location on Android) must still be granted after process death. See React Native BLE.
  • retryCount / timeout control connection setup before a device call. They do not retry signing or replace application-level recovery.
  • If the OS bond is stale, stop looping connect. Ask the user to forget the device in system Bluetooth settings and pair again.
  • Mini has no BLE. Neo has BLE but no camera. See Devices.

USB-specific

  • WebUSB needs a user gesture to show the chooser again unless you pass skipWebDevicePrompt on a still-authorized device. See Common Params.
  • Another tab or Bridge holding the device can cause an acquire/open error. Close the other owner; do not dispose() as a first reaction.

dispose()

await HardwareSDK.dispose();

Call dispose() only when you are tearing down the SDK or switching env / transport stack (for example WebUSB → low-level). It drops every link and Protocol V2 transport cursor.

Do not call dispose() on a routine BLE drop or USB unplug. Search and connect again on the same HardwareSDK instance.

After dispose(), you must init() again before searchDevices.

Firmware reboot

firmwareUpdateV2 / V3 / V4 may disconnect on purpose. Wait, reconnect, then read versions. Do not treat that drop as a failed update to replay. See Firmware Update.

Next

Last updated on
Flutter (Native)Overview