本页目录

搜索设备

searchDevices() 发现候选连接，返回结果对象。只有 success 为 true 时，payload 才是设备列表。

发现设备不代表设备已初始化或钱包已解锁。BLE 扫描可能在建立连接前就返回广播名称和连接 ID；USB 发现也可能只返回尚未补齐身份字段的描述符。

搜索设备


const result = await HardwareSDK.searchDevices();
if (!result.success) throw new Error(result.payload.error);
if (!result.payload.length) throw new Error('No OneKey device found');
 
// For this example, select the only connected device.
// In an app, ask the user to choose when multiple devices are present.
if (result.payload.length !== 1) throw new Error('Select a device before continuing');
const { connectId } = result.payload[0];
if (!connectId) throw new Error('Device connection is unavailable');
 
const state = await HardwareSDK.getDeviceState(connectId);
if (!state.success) throw new Error(state.payload.error);
const deviceId = state.payload.identity.deviceId;
if (!deviceId) throw new Error('Device has no wallet identity');

WebUSB 授权必须由用户主动操作触发。BLE 扫描需要平台要求的蓝牙权限。参见 WebUSB 或 React Native BLE。

参数

参数对象可省略。请对照所安装版本的 searchDevices 类型和通用参数。

示例

上面的示例只接受一个候选设备。实际应用在发现多个候选设备时，应让用户选择，再用非空 connectId 读取设备状态。

返回结果

字段	类型	含义
`connectId`	`string \| null`	传输路由标识；后续设备调用需要非空值。
`connectProtocol`	`'V1' \| 'V2' \| undefined`	主动探测协议后才可用，不要根据广播名称推断。
`serialNo`	`string \| null \| undefined`	初始化后可获取的设备物理序列号。
`deviceId`	`string \| null`	种子生命周期内的身份；通过 `getDeviceState` 刷新。
`uuid`	`string`	已废弃的兼容字段，初始化前可能为空；物理身份优先用 `serialNo`。
`deviceType`	`IDeviceType`	探测出的机型，初始化前可能未知。
`name`	`string`	用于显示的名称，不是唯一标识。
`commType`	`OneKeyDeviceCommType`	传输层报告的通信类型。

完整公开类型为 SearchDevice。不要依赖 path 等内部附加字段。

同一物理设备的 USB 与 BLE connectId 不同。重连后重新枚举并刷新状态，再复用钱包绑定。参见标识符。

错误

失败时，payload 包含 error 和可选的 code。根据错误码处理，不要匹配错误文案。成功但列表为空表示没有发现候选设备，不是 SDK 调用失败。