Skip to Content
HardwareLeitfaden zur Core-API

Hardware-SDK-Core-API-Anleitung

Lebenszyklusanleitung: initialisieren → suchen → Ereignisse → erster geschützter Aufruf → bereinigen.

Parametertabellen befinden sich unter Gemeinsame Parameter. Geräte- und Protokollunterschiede finden Sie unter Geräte und Protocol V1 und V2.

Kurzablauf

  • Aufrufformat: HardwareSDK.method(connectId, deviceId?, params) → Promise<{ success, payload }>; prüfen Sie immer success vor dem Zugriff auf payload.
  • Kennungen: connectId aus searchDevices; deviceId aus getDeviceState (für BLE erforderlich, für WebUSB empfohlen). Aktualisieren Sie deviceId nach Zurücksetzen/Wiederherstellung. Vollständige Tabelle: Kennungen.
  • UI-Vertrag: abonnieren Sie UI_EVENT einmal; rufen Sie nur uiResponse bei Eingabe-UI_REQUEST auf (PIN / Passphrase / Bootloader-Auswahl). Ordnen Sie bei mehreren verbundenen Geräten pro Gerät zu.
  • Führen Sie Aufrufe pro Gerät nacheinander aus. Verwenden Sie eine versteckte Wallet erneut, indem Sie passphraseState an spätere Methoden übergeben (Kompatibilitätspfad: initSession + passphraseState). Rufen Sie dafür nicht erneut openWalletSession auf.
const res = await HardwareSDK.evmGetAddress(connectId, deviceId, { path: "m/44'/60'/0'/0/0", useEmptyPassphrase: true, }); if (!res.success) throw new Error(res.payload.error); console.log(res.payload.address);

Interaktionsablauf

Core-Kennungen & Umgebungen

IDZweckAbrufen überÄndert sich bei
connectIdWelche VerbindungsearchDevices()USB erneut anschließen, BLE neu koppeln, Transport wechseln
deviceIdWelche Seed-LebensdauergetDeviceState (getFeatures ist veraltet)Löschen, Wiederherstellung, Seed-Wechsel

USB- und BLE-connectId-Werte für dasselbe Gerät unterscheiden sich — speichern Sie sie getrennt zwischen. Siehe Kennungen und Verbindungsabbrüche und Wiederverbindung.

Laufzeitanforderungen

  • webusb — HTTPS + Nutzeraktion.
  • react-native — BLE-Berechtigung + (häufig) Standortberechtigung.
  • lowlevel — Host-BLE-Adapter, der rohe Benachrichtigungsblöcke weiterleitet.
  • Firmware — einige APIs schlagen im Bootloader fehl.

Welche Kennungen sind erforderlich?

AnforderungBeschreibungBeispiel-APIs
🟢 Keine KennungenSDK-Initialisierung, Konfiguration, Ereignisverwaltunginit on/off searchDevices getLogs dispose uiResponse
🟡 connectId nurGeräteverwaltung, Status, Firmware-VorgängegetDeviceState openWalletSession cancel deviceSettings
🔵 connectId + deviceIdBlockchain-Signieren, Adressen, VerschlüsselungevmSignTransaction btcSignTransaction solSignMessage allNetworkGetAddress

init → search → getDeviceState → subscribe UI/DEVICE/FIRMWARE → call + uiResponse → cleanup

import HardwareSDK from '@onekeyfe/hd-common-connect-sdk'; import { UI_EVENT, UI_REQUEST, UI_RESPONSE } from '@onekeyfe/hd-core'; const initialized = await HardwareSDK.init({ env: 'webusb', fetchConfig: true, debug: false }); if (!initialized) throw new Error('SDK initialization failed'); const devices = await HardwareSDK.searchDevices(); if (!devices.success || !devices.payload.length) throw new Error('No device'); // Select explicitly in the application when more than one device is available. if (devices.payload.length !== 1) throw new Error('Select exactly one device before continuing'); const { connectId } = devices.payload[0]; if (!connectId) throw new Error("Missing connectId"); 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"); // Register the UI_EVENT handler shown below before any protected call. HardwareSDK.on(UI_EVENT, handleUiEvent); const address = await HardwareSDK.evmGetAddress(connectId, deviceId, { path: "m/44'/60'/0'/0/0", useEmptyPassphrase: true, }); if (!address.success) throw new Error(address.payload.error);

Pro Gerät serialisieren. Aktualisieren Sie getDeviceState nach einem Gerätewechsel. Entfernen Sie Listener beim Unmount. Rufen Sie HardwareSDK.dispose() nur beim Beenden des Transports auf — siehe Verbindungsabbrüche und Wiederverbindung.

Gemeinsame Parameter

Die vollständige Tabelle, Transportmatrix, Kombinationen und HD-Pfade befinden sich jetzt unter Gemeinsame Parameter.

HD-Pfadbeispiele: Gemeinsame Parameter → HD-Pfad.

Zum PIN- und Passphrase-Nutzererlebnis siehe PIN und Passphrase. Neuer Code zum Öffnen einer Wallet sollte der Anleitung unter Wallet-Sitzungen folgen.

Ereignisse & UI-Anbindung

Abonnieren Sie einmal nahe dem App-Start. Rufen Sie nur uiResponse für Eingabeanfragen auf. Kopieren Sie payload.responseCorrelation, sofern vorhanden, in jede Antwort; es identifiziert die ausstehende Interaktion. Machen Sie Dialog-Callbacks nach Abbruch oder UI-Schließereignis ungültig und brechen Sie die ausgewählte Verbindung ab, wenn der Nutzer die Eingabe schließt. Protokollieren Sie keine UI-Ereignisnutzlasten oder Eingabewerte.

UI-Anfragen, die Folgendes erfordern: uiResponse

UI_REQUESTWann ausgelöstAntworten mit
REQUEST_PINHost-PIN-Eingabeanfrage; reine Geräteaufforderungen benötigen keine AntwortUI_RESPONSE.RECEIVE_PIN
REQUEST_PASSPHRASEHost- oder Geräteeingabe wählen (value: "", passphraseOnDevice: true für Geräteeingabe)UI_RESPONSE.RECEIVE_PASSPHRASE
REQUEST_DEVICE_IN_BOOTLOADER_FOR_WEB_DEVICEWeb-Bootloader-AuswahlUI_RESPONSE.SELECT_DEVICE_IN_BOOTLOADER_FOR_WEB_DEVICE

UI-Benachrichtigungen (kein uiResponse)

UI_REQUESTZweck
REQUEST_PASSPHRASE_ON_DEVICEPassphrase auf dem Gerät eingeben; nur Benachrichtigung
REQUEST_BUTTONAuf dem Gerät bestätigen. Firmware-Update verwendet reason='firmware-update' — weiterhin kein uiResponse
DEVICE_PROGRESSFortschritt lang laufender Aufgaben
FIRMWARE_PROCESSING / FIRMWARE_PROGRESS / FIRMWARE_TIPFirmware-Upgrade-Zustände
BLUETOOTH_PERMISSION / LOCATION_PERMISSIONBLE-Berechtigungsaufforderungen
BOOTLOADER / REQUIRE_MODE / NOT_INITIALIZE / FIRMWARE_NOT_SUPPORTEDModus- oder Unterstützungshinweise

Geräte-/Firmware-Ereignisse

KanalEreignisÜbliche Behandlung
DEVICE.CONNECTdirekte NutzlastGeräteliste aktualisieren
DEVICE.DISCONNECTdirekte NutzlastVerbindung ungültig machen; Aufrufe mit Nebenwirkungen nicht wiederholen. Wiederverbinden
DEVICE.STATE / DEVICE.FEATURES / DEVICE.SUPPORT_FEATURESdirekte NutzlastGerätestatus / Features / unterstützte Funktionen aktualisieren
FIRMWARE_EVENTRELEASE_INFO / BLE_RELEASE_INFOUpgrade anbieten, wenn sicher. Firmware-Update
import HardwareSDK from '@onekeyfe/hd-common-connect-sdk'; import { UI_EVENT, UI_REQUEST, UI_RESPONSE } from '@onekeyfe/hd-core'; import type { UiEventMessage } from '@onekeyfe/hd-core'; // These modal functions are provided by your application's UI. declare function openPinModal(submit: (input: { value: string }) => void): void; declare function openPassphraseModal(submit: (input: { value: string; onDevice: boolean; save: boolean }) => void): void; const handleUiEvent = (msg: UiEventMessage) => { switch (msg.type) { case UI_REQUEST.REQUEST_PIN: if (msg.payload.deviceOnly || msg.payload.type === 'ButtonRequest_PinEntry' || msg.payload.type === 'ButtonRequest_AttachPin') { // Display an on-device prompt; no uiResponse is needed. return; } openPinModal(({ value }) => HardwareSDK.uiResponse({ ...msg.payload.responseCorrelation, type: UI_RESPONSE.RECEIVE_PIN, payload: value }) ); return; case UI_REQUEST.REQUEST_PASSPHRASE: if (msg.payload.deviceOnly) { HardwareSDK.uiResponse({ ...msg.payload.responseCorrelation, type: UI_RESPONSE.RECEIVE_PASSPHRASE, payload: { value: '', passphraseOnDevice: true, save: false }, }); return; } openPassphraseModal(({ value, onDevice, save }) => HardwareSDK.uiResponse({ ...msg.payload.responseCorrelation, type: UI_RESPONSE.RECEIVE_PASSPHRASE, payload: { value: onDevice ? "" : value, passphraseOnDevice: onDevice, attachPinOnDevice: false, save }, }) ); return; default: break; } }; HardwareSDK.on(UI_EVENT, handleUiEvent);

Fehler

GruppeHäufige UrsachenEmpfohlene Maßnahmen
Gerät (101–118, 200)Falscher Modus, beschäftigt, deviceId-Abweichung, nicht initialisiertModus prüfen, wiederverbinden, erneut ausführen: init + getDeviceState
IFrame (300–305)Initialisierung fehlt, Laden/Zeitüberschreitung/BlockierungSicherstellen, dass init erfolgreich war; CSP / Iframe prüfen
Methode/Firmware (400–418)Ungültige Parameter, Firmware erforderlich, unzulässiger PfadHD-Pfad validieren; Firmware-Update
Transport (600–603)Transport nicht konfiguriert, gleichzeitiger AufrufPrüfung env, Aufrufe serialisieren
Bluetooth (700–722)Scan/Berechtigung/Verbindung/ZeitüberschreitungBerechtigung, Nähe; nicht mit veralteter Kopplung in einer Schleife versuchen
Laufzeit/Bridge (800–822)PIN abgebrochen, Bridge-ZeitüberschreitungAbbruch respektieren; Verbindung wiederherstellen, ohne Signieren automatisch zu wiederholen
Webgerät (901–902)WebUSB nicht autorisiertHTTPS + Nutzeraktion

Zuordnen: payload.code, nicht den payload.error-Text. Definitionen: HardwareError.ts.

Zuletzt aktualisiert am