Skip to Content
MatérielGuide de l’API principale

Guide de l’API Core du Hardware SDK

Guide du cycle de vie : initialisation → recherche → événements → premier appel protégé → nettoyage.

Les tableaux de paramètres se trouvent dans Paramètres communs. Les différences d’appareils et de protocoles se trouvent dans Appareils et Protocol V1 et V2.

Parcours rapide

  • Forme de l’appel : HardwareSDK.method(connectId, deviceId?, params) → Promise<{ success, payload }> ; vérifiez toujours success avant d’accéder à payload.
  • Identifiants : connectId depuis searchDevices ; deviceId depuis getDeviceState (obligatoire pour BLE, recommandé pour WebUSB). Actualisez deviceId après réinitialisation/récupération. Tableau complet : Identifiants.
  • Contrat d’interface : abonnez-vous à UI_EVENT une seule fois ; appelez uniquement uiResponse sur les événements de type saisie UI_REQUEST (PIN / phrase secrète / sélection du bootloader). Orientez les demandes par appareil lorsque plusieurs sont connectés.
  • Sérialisez les appels par appareil. Réutilisez un portefeuille caché en transmettant passphraseState aux méthodes ultérieures (parcours de compatibilité : initSession + passphraseState). N’appelez pas openWalletSession de nouveau pour cela.
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);

Déroulement de l’interaction

Identifiants et environnements Core

IDRôleObtenir viaChange lors de
connectIdQuelle connexionsearchDevices()Rebranchement USB, nouvel appairage BLE, changement de transport
deviceIdQuelle durée de vie de grainegetDeviceState (getFeatures est obsolète)Effacement, récupération, changement de graine

USB et BLE ont des valeurs de connectId différentes pour la même unité — mettez-les en cache séparément. Consultez Identifiants et Déconnexions et reconnexion.

Exigences d’exécution

  • webusb — HTTPS + action utilisateur.
  • react-native — autorisation BLE + (souvent) autorisation de localisation.
  • lowlevel — adaptateur BLE hôte transmettant les blocs bruts de notification.
  • Micrologiciel — certaines API échouent en mode Bootloader.

Quels identifiants sont obligatoires ?

ExigenceDescriptionExemples d’API
🟢 Aucun identifiantInitialisation, configuration et gestion des événements du SDKinit on/off searchDevices getLogs dispose uiResponse
🟡 connectId uniquementGestion, état et opérations de micrologiciel de l’appareilgetDeviceState openWalletSession cancel deviceSettings
🔵 connectId + deviceIdSignature blockchain, adresse, chiffrementevmSignTransaction 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);

Sérialisez par appareil. Actualisez getDeviceState après un changement d’appareil. Supprimez les écouteurs au démontage. Appelez HardwareSDK.dispose() uniquement lors de la fermeture du transport — consultez Déconnexions et reconnexion.

Paramètres communs

Le tableau complet, la matrice des transports, les combinaisons et les chemins HD ont été déplacés vers Paramètres communs.

Exemples de chemins HD : Paramètres communs → chemin HD.

Pour l’expérience PIN et phrase secrète, consultez PIN et Phrase secrète. Le nouveau code d’ouverture de portefeuille doit utiliser Sessions de portefeuille.

Connexion des événements et de l’interface

Abonnez-vous une seule fois au démarrage de l’application. Appelez uniquement uiResponse pour les demandes de saisie. Copiez payload.responseCorrelation sur chaque réponse lorsqu’il est présent ; il identifie l’interaction en attente. Invalidez les rappels de la fenêtre après une annulation ou un événement de fermeture d’interface, et annulez la connexion sélectionnée lorsque l’utilisateur ferme la saisie. Ne journalisez pas les données des événements d’interface ni les valeurs saisies.

Demandes d’interface nécessitant uiResponse

UI_REQUESTMoment du déclenchementRépondre avec
REQUEST_PINDemande de saisie de PIN sur l’hôte ; les demandes uniquement sur l’appareil n’exigent aucune réponseUI_RESPONSE.RECEIVE_PIN
REQUEST_PASSPHRASEChoisir la saisie sur l’hôte ou sur l’appareil (value: "", passphraseOnDevice: true pour la saisie sur l’appareil)UI_RESPONSE.RECEIVE_PASSPHRASE
REQUEST_DEVICE_IN_BOOTLOADER_FOR_WEB_DEVICESélecteur web du bootloaderUI_RESPONSE.SELECT_DEVICE_IN_BOOTLOADER_FOR_WEB_DEVICE

Notifications d’interface (sans uiResponse)

UI_REQUESTRôle
REQUEST_PASSPHRASE_ON_DEVICESaisir la phrase secrète sur l’appareil ; notification uniquement
REQUEST_BUTTONConfirmer sur l’appareil. La mise à jour du micrologiciel utilise reason='firmware-update' — toujours sans uiResponse
DEVICE_PROGRESSProgression d’une tâche longue
FIRMWARE_PROCESSING / FIRMWARE_PROGRESS / FIRMWARE_TIPÉtats de mise à niveau du micrologiciel
BLUETOOTH_PERMISSION / LOCATION_PERMISSIONDemandes d’autorisation BLE
BOOTLOADER / REQUIRE_MODE / NOT_INITIALIZE / FIRMWARE_NOT_SUPPORTEDIndications de mode ou de prise en charge

Événements d’appareil / de micrologiciel

CanalÉvénementTraitement habituel
DEVICE.CONNECTdonnées directesActualiser la liste des appareils
DEVICE.DISCONNECTdonnées directesInvalider la connexion ; ne pas rejouer les appels ayant des effets de bord. Reconnecter
DEVICE.STATE / DEVICE.FEATURES / DEVICE.SUPPORT_FEATURESdonnées directesMettre à jour l’état / les fonctionnalités / les fonctionnalités prises en charge de l’appareil
FIRMWARE_EVENTRELEASE_INFO / BLE_RELEASE_INFOProposer une mise à niveau lorsqu’elle peut être effectuée en toute sécurité. Mise à jour du micrologiciel
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);

Erreurs

GroupeCauses courantesActions recommandées
Appareil (101–118, 200)Mode incorrect, occupé, deviceId incohérent, non initialiséConfirmer le mode, reconnecter, exécuter de nouveau init + getDeviceState
IFrame (300–305)Initialisation absente, chargement/délai dépassé/blocageVérifier que init a réussi ; vérifier la CSP / l’iframe
Méthode/Micrologiciel (400–418)Paramètres incorrects, micrologiciel requis, chemin interditValider le chemin HD ; Mise à jour du micrologiciel
Transport (600–603)Transport non configuré, appel concurrentVérifier env, sérialiser les appels
Bluetooth (700–722)Scan/autorisation/connexion/délai dépasséAutorisation, proximité ; ne pas boucler sur un appairage obsolète
Exécution/Bridge (800–822)PIN annulé, délai Bridge dépasséRespecter l’annulation ; rétablir la connexion sans rejouer automatiquement la signature
Appareil web (901–902)WebUSB non autoriséHTTPS + action utilisateur

Associez les erreurs selon payload.code, pas selon le texte de payload.error. Définitions : HardwareError.ts.

Dernière mise à jour le