Web USB/HID | Developers

Web USB/HID

Estimated reading time: More than 10 minutes

Introduction

In this section, we will guide you through the creation of a web application. This application will connect to your Nano to display the address of a Bitcoin account. If you want it for Ethereum you can easily modify it.

Web USB and Web HID applications are implemented with @ledgerhq/hw-transport-webusb and @ledgerhq/hw-transport-webhid respectively.

Prerequisites

Before starting ensure you have gone through the prerequisites.

Coding

Initialization

First, open a terminal and create a new folder in your usual working directory. For this tutorial, the folder will be named “example-web-hid-usb”.

Run:

mkdir example-web-hid-usb
cd example-web-hid-usb

Initialize the project by running:

npm init

Answer the questions displayed or by default press enter. There is no incidence on the execution.

Run:

mkdir src
touch src/index.html
touch src/main.js

Your folder must look like this.

Folder USB and HID
Fig. 1: File structure

Coding

Open the folder example-web-hid-usb in an code editor.

index.html

In index.html copy-paste the following code :

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8"/>
    <title>My First Embedded App</title>
    <script type="module" src="main.js"></script>
  </head>
  <body id="main">

  </body>
</html>

main.js

In main.js copy-paste the following code:

Important
Comment out or remove the Transport package you are not using (@ledgerhq/hw-transport-webusb or @ledgerhq/hw-transport-webhid) and the corresponding const.
import 'core-js/actual';
import { listen } from "@ledgerhq/logs";
import AppBtc from "@ledgerhq/hw-app-btc";

// Keep this import if you want to use a Ledger Nano S/X/S Plus with the USB protocol and delete the @ledgerhq/hw-transport-webhid import
import TransportWebUSB from "@ledgerhq/hw-transport-webusb";
// Keep this import if you want to use a Ledger Nano S/X/S Plus with the HID protocol and delete the @ledgerhq/hw-transport-webusb import
import TransportWebHID from "@ledgerhq/hw-transport-webhid";

//Display the header in the div which has the ID "main"
const initial = "<h1>Connect your Nano and open the Bitcoin app. Click anywhere to start...</h1>";
const $main = document.getElementById("main");
$main.innerHTML = initial;

document.body.addEventListener("click", async () => {
  $main.innerHTML = initial;
  try {

    // Keep if you chose the USB protocol
    const transport = await TransportWebUSB.create();

    // Keep if you chose the HID protocol
    const transport = await TransportWebHID.create();

    //listen to the events which are sent by the Ledger packages in order to debug the app
    listen(log => console.log(log))

    //When the Ledger device connected it is trying to display the bitcoin address
    const appBtc = new AppBtc(transport);
    const { bitcoinAddress } = await appBtc.getWalletPublicKey(
      "44'/0'/0'/0/0",
      { verify: false, format: "legacy"}
    );

    //Display your bitcoin address on the screen
    const h2 = document.createElement("h2");
    h2.textContent = bitcoinAddress;
    $main.innerHTML = "<h1>Your first Bitcoin address:</h1>";
    $main.appendChild(h2);

    //Display the address on the Ledger device and ask to verify the address
    await appBtc.getWalletPublicKey("44'/0'/0'/0/0", {format:"legacy", verify: true});
  } catch (e) {

    //Catch any error thrown and displays it on the screen
    const $err = document.createElement("code");
    $err.style.color = "#f66";
    $err.textContent = String(e.message || e);
    $main.appendChild($err);
  }
});

Dependencies Installation

Install the packages

Run:

npm install --save core-js
npm install --save @ledgerhq/logs
npm install --save-dev parcel
npm install --save @ledgerhq/hw-app-btc
Package What does it do?
core-js Modular standard library for JavaScript.
@ledgerhq/logs It provides you the log of all the errors from your connection with your Nano that may appear when developing.
parcel It is a build tool that will help you package your application to run it in the browser.
@ledgerhq/hw-app-btc It will help you ask your Nano to access the Bitcoin address.

Install the Transport HID or USB package

Then depending on your choice install one of the corresponding packages:

  • Install the Ledger package @ledgerhq/hw-transport-webhid which provide you with all the methods to interact with your Nano with an HID connection:
      npm install --save @ledgerhq/hw-transport-webhid
    
  • Install the Ledger package @ledgerhq/hw-transport-webusb which provide you with all the methods to interact with your Nano with a USB connection:
      npm install --save @ledgerhq/hw-transport-webusb
    

Package.json

Modify "main": "index.js" to "source": "src/index.html".

And ensure you have this line in your package.json:

  "scripts": {
    "build": "parcel build", 
    "start": "parcel"
  },

Add this at the end of the script:

  "alias": {
    "@ledgerhq/devices": "@ledgerhq/devices/lib-es"
  }

Your “package.json” should look like this:

{
  "name": "example-web-hid-usb",
  "version": "1.0.0",
  "description": "",
  "source": "src/index.html",
  "dependencies": {
    "@ledgerhq/hw-app-btc": "^6.24.1",
    "@ledgerhq/hw-transport-webhid": "^6.24.1", 
    "@ledgerhq/hw-transport-webusb": "^6.24.1", 
    "@ledgerhq/logs": "^6.10.0",
    "core-js": "^3.21.1"
  },
  "devDependencies": {
      "parcel": "^2.0.0"
  },
  "scripts": {
    "build": "parcel build", 
    "start": "parcel"
  },
  "author": "",
  "license": "ISC",

  "alias": {
    "@ledgerhq/devices": "@ledgerhq/devices/lib-es"
  }
}
Important
In package.json, remove the Transport package you are not using (@ledgerhq/hw-transport-webusb or @ledgerhq/hw-transport-webhid).

Launch

Start the Development Server

Now that the Setup is finished, the app has to be built to be displayed. Start the development server:

npm run start

Now the application is up and running. Open the browser and go to localhost:1234, it will display :

Application running on browser
Fig. 3: Application Running on Browser

Plug your Nano

Before clicking on the text connect your Nano to the USB port, unlock it and run the bitcoin application. The steps are described below.

Enter Pin
Fig. 4: Enter Pin

Selection Bitcoin
Fig. 5: Select Bictoin

Run App
Fig. 6: The App is running

Connect Your Nano to the Application

Now you can click on the text and a popup will be prompt. Choose your Nano and click connect:

Connect your Nano
Fig. 7: Connect your Nano

Then if all goes well you must have the bitcoin address you just create previously

Address Account Displayed
Fig. 8: Address Account Displayed

Congratulations, you have successfully built your first application connected with a Nano !

Note
Note that if your finalize the operation on your Nano by accepting or rejecting, the corresponding message appears on your web application.

Android chrome

Android chrome supports the use of the Ledger device by HID and USB. On a mobile phone, only android can support the web application. Moreover, on android, just chrome can support the web application.

Launch on Android chrome

To test your application on android, a little change has to be made. Just add the “–https” flag in your start script, and run the script.

package.json

{
  "name": "example-web-hid-usb",
  "version": "1.0.0",
  "description": "",
  "source": "src/index.html",
  "dependencies": {
    "@ledgerhq/hw-app-btc": "^6.12.1",
    "@ledgerhq/hw-transport-webhid": "^6.11.2", 
    "@ledgerhq/hw-transport-webusb": "^6.11.2",
    "@ledgerhq/logs": "^6.10.0",
    "core-js": "^3.20.2"
  },
  "devDependencies": {
    "parcel": "^2.0.0"
  },
  "scripts": {
    "build": "parcel build",
    "start": "parcel --https" 
  },
  "author": "",
  "license": "ISC"
}
Important
In package.json, remove the Transport package you are not using (@ledgerhq/hw-transport-webusb or @ledgerhq/hw-transport-webhid).

The browser will ask you that the website is malicious, to continue, click on “advanced settings” and then on “continue to the localhost site”. Now you can test to connect your Nano on your android just like the previous step.


Did you find this page helpful?


How would you improve this page for developers?



Prerequisites
Web Bluetooth
Getting Started
Theme Features
Customization

Connect your app