From 8005b7dbe072b1957c2fe1c1c4e3bd7ef9b0c121 Mon Sep 17 00:00:00 2001 From: Mike Reinhart Date: Tue, 10 Jul 2018 17:48:42 -0400 Subject: [PATCH 1/3] Create MacInstallation.md --- MacInstallation.md | 110 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 MacInstallation.md diff --git a/MacInstallation.md b/MacInstallation.md new file mode 100644 index 00000000..140eaee0 --- /dev/null +++ b/MacInstallation.md @@ -0,0 +1,110 @@ +### Installing Tezos Applications on the Ledger Nano S + +## Overview +These installation instructions have been adapted from our Universal Installation Instructions to be mac-specific. If you have questions regarding this installation, we recommend you refer to those instructions. + +*Note* - this guide makes 2 assumptions: +1. You have XCode and Homebrew installed. Both are available for free to download via those links. +2. You have updated your Ledger firmware to 1.4.2. You can do so through Ledger Manager or Ledger Live. + +## Installing Python3 + +First, check if you have Python3 installed: + +`python3 --version` + +If this returns a version, such as `Python 3.6.5`, you can skip to the next section. If it returns nothing or you get an error, such as ‘command not found’, you’ll need to install it with homebrew: + +`brew install python` + +This step may take some time. When complete, you can confirm with `python3 --version`. It should now return a version. + +## Installing Virtualenv + +Check if you have virtualenv installed: + +`virtualenv --version` + +If this returns a version, such as `16.0.0`, you can skip to the next section. If it returns nothing or you get an error, such as ‘command not found’, you’ll need to install it: + +`pip3 install virtualenv` + +After that successfully installs, running `virtualenv --version` should now return it’s version number. + +## Clone This Repo + +Clone the Obsidian Systems Ledger App repo: + +`git clone https://github.com/obsidiansystems/ledger-app-tezos.git` + +This gives you all the tools to install the applications, but not the app files themselves. We’ll get those later. Enter the folder you just downloaded. + +`cd ledger-app-tezos` + +## Run virtualenv + +From within `/ledger-app-tezos`, run the following two commands: + +`virtualenv ledger -p python3` +`source ledger/bin/activate` + +Your terminal session (and only that terminal session) will now be in the `virtualenv`. To have a new terminal session enter the `virtualenv`, run the above source command only in the same directory in the new terminal session. +In the shell that starts with (ledger), run (don’t use `sudo` or `pip3`!): + +`pip install ledgerblue` + +If you have to use `sudo` or `pip3` here, that is an indication that you have not correctly set up `virtualenv`. It will still work in such a situation, but please research other material on troubleshooting `virtualenv` setup. + +## Download the Application(s) + +Next you'll use the installation script to install the app on your Ledger Nano S. Let’s start by downloading the application(s) from here - `https://github.com/obsidiansystems/ledger-app-tezos/releases/`. Download the most recent version (currently 1.1 at the time of this writing). To download, use the `release.tar.gz` link - that’s where you’ll find the application hex files. Once you’ve downloaded them, move them into the `/ledger-app-tezos` folder. + +## Install the Application(s) + +We’re now ready to do the installation! The Ledger must be in the following state: +*Plugged into your computer +*Unlocked (enter your PIN) +*On the home screen (do not have any app open) +* Not asleep (you should not see vires in numeris is scrolling across the screen) + +In `virtualenv`, in the `/ledger-app-tezos` folder, run the following: +*To install the Baking app - `./install.sh "Tezos Baking" baking.hex` +*To install the Wallet App - `./install.sh "Tezos Wallet" wallet.hex` + +Pay attention to your Ledger during this process, as you’ll be prompted to confirm the installation. + +You should now see the applications on your Ledger! + +### Upgrading Applications + +Periodically, we’ll update these applications. To do the upgrade yourself, run the same commands you used for the installation! Just make sure to update the hex files you are upgrading to the new version by moving the new `baking.hex` or `wallet.hex` file to `/ledger-app-tezos`. The installation script will automatically remove the old version of the app. + +### Deleting Applications + +In that same `virtualenv` we created to install the applications, run the following command to delete them: + +`python -m ledgerblue.deleteApp --targetId 0x31100003 --appName "Tezos Baking"` + +Note: The part in quotes needs to be the name of the application you are trying to delete. So if you are trying to delete the Wallet App, you should change it to say “Tezos Wallet” + +### Troubleshooting + +### Ledger Prompt: “Allow unknown manager?” + +This prompt indicates that the application interacting with the Ledger is not the Ledger Manager or Ledger Live. It is expected, and not a cause for concern. + +### Ledger Prompt: “Open non-genuine app?” + +If the ledger says “Open non-genuine app?” then freezes, this is a sign that the install was unsuccessful. You probably need to update your Ledger’s firmware to 1.4.2, then restart the process. + +### “Broken certificate chain - loading from user key” + +If you are running the installation script and you already have a version of the application on your Ledger, you will see this message. This is normal, and not a cause for concern. + +### Removing a virtualenv + +Each time you create a virtualenv, it makes a folder with that instance in it with the name you chose to call it. In these docs, we called it ledger. If you try and run virtualenv ledger and you’ve already made a ledger virtualenv, you’ll need to delete it first: + +`/ledger-app-tezos$ rm -rf ledger` + +Another alternative is to create future virtualenvs with a different name, such as ledger1. From a2a95f0167fd561995b3d88d513b8e5ed1a7e0c5 Mon Sep 17 00:00:00 2001 From: Mike Reinhart Date: Tue, 10 Jul 2018 18:01:38 -0400 Subject: [PATCH 2/3] Update MacInstallation.md --- MacInstallation.md | 43 ++++++++++++++++++++++--------------------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/MacInstallation.md b/MacInstallation.md index 140eaee0..0735dc02 100644 --- a/MacInstallation.md +++ b/MacInstallation.md @@ -1,13 +1,13 @@ -### Installing Tezos Applications on the Ledger Nano S +# Installing Tezos Applications on the Ledger Nano S ## Overview -These installation instructions have been adapted from our Universal Installation Instructions to be mac-specific. If you have questions regarding this installation, we recommend you refer to those instructions. +These installation instructions have been adapted from our [README](https://github.com/obsidiansystems/ledger-app-tezos/blob/master/README.md) to be mac-specific. If you have questions regarding this installation, we recommend you refer to those instructions. -*Note* - this guide makes 2 assumptions: -1. You have XCode and Homebrew installed. Both are available for free to download via those links. -2. You have updated your Ledger firmware to 1.4.2. You can do so through Ledger Manager or Ledger Live. +**Note** - this guide makes 2 assumptions: +1. You have [XCode](https://developer.apple.com/xcode/) and [Homebrew](https://brew.sh/) installed. Both are available for free to download via those links. +2. You have updated your Ledger firmware to 1.4.2. You can do so through [Ledger Manager](https://www.ledgerwallet.com/apps/manager) or [Ledger Live](https://www.ledgerwallet.com/live). -## Installing Python3 +### Installing Python3 First, check if you have Python3 installed: @@ -19,7 +19,7 @@ If this returns a version, such as `Python 3.6.5`, you can skip to the next sect This step may take some time. When complete, you can confirm with `python3 --version`. It should now return a version. -## Installing Virtualenv +### Installing Virtualenv Check if you have virtualenv installed: @@ -31,7 +31,7 @@ If this returns a version, such as `16.0.0`, you can skip to the next section. I After that successfully installs, running `virtualenv --version` should now return it’s version number. -## Clone This Repo +### Clone This Repo Clone the Obsidian Systems Ledger App repo: @@ -41,11 +41,12 @@ This gives you all the tools to install the applications, but not the app files `cd ledger-app-tezos` -## Run virtualenv +### Run virtualenv From within `/ledger-app-tezos`, run the following two commands: `virtualenv ledger -p python3` + `source ledger/bin/activate` Your terminal session (and only that terminal session) will now be in the `virtualenv`. To have a new terminal session enter the `virtualenv`, run the above source command only in the same directory in the new terminal session. @@ -55,39 +56,39 @@ In the shell that starts with (ledger), run (don’t use `sudo` or `pip3`!): If you have to use `sudo` or `pip3` here, that is an indication that you have not correctly set up `virtualenv`. It will still work in such a situation, but please research other material on troubleshooting `virtualenv` setup. -## Download the Application(s) +### Download the Application(s) Next you'll use the installation script to install the app on your Ledger Nano S. Let’s start by downloading the application(s) from here - `https://github.com/obsidiansystems/ledger-app-tezos/releases/`. Download the most recent version (currently 1.1 at the time of this writing). To download, use the `release.tar.gz` link - that’s where you’ll find the application hex files. Once you’ve downloaded them, move them into the `/ledger-app-tezos` folder. -## Install the Application(s) +### Install the Application(s) We’re now ready to do the installation! The Ledger must be in the following state: -*Plugged into your computer -*Unlocked (enter your PIN) -*On the home screen (do not have any app open) -* Not asleep (you should not see vires in numeris is scrolling across the screen) +- Plugged into your computer +- Unlocked (enter your PIN) +- On the home screen (do not have any app open) +- Not asleep (you should not see vires in numeris is scrolling across the screen) In `virtualenv`, in the `/ledger-app-tezos` folder, run the following: -*To install the Baking app - `./install.sh "Tezos Baking" baking.hex` -*To install the Wallet App - `./install.sh "Tezos Wallet" wallet.hex` +- To install the Baking app - `./install.sh "Tezos Baking" baking.hex` +- To install the Wallet App - `./install.sh "Tezos Wallet" wallet.hex` Pay attention to your Ledger during this process, as you’ll be prompted to confirm the installation. You should now see the applications on your Ledger! -### Upgrading Applications +# Upgrading Applications Periodically, we’ll update these applications. To do the upgrade yourself, run the same commands you used for the installation! Just make sure to update the hex files you are upgrading to the new version by moving the new `baking.hex` or `wallet.hex` file to `/ledger-app-tezos`. The installation script will automatically remove the old version of the app. -### Deleting Applications +# Deleting Applications In that same `virtualenv` we created to install the applications, run the following command to delete them: `python -m ledgerblue.deleteApp --targetId 0x31100003 --appName "Tezos Baking"` -Note: The part in quotes needs to be the name of the application you are trying to delete. So if you are trying to delete the Wallet App, you should change it to say “Tezos Wallet” +**Note**: The part in quotes needs to be the name of the application you are trying to delete. So if you are trying to delete the Wallet App, you should change it to say “Tezos Wallet” -### Troubleshooting +# Troubleshooting ### Ledger Prompt: “Allow unknown manager?” From 558a20e15279ca02ff394ca315da3838264d6fc2 Mon Sep 17 00:00:00 2001 From: Mike Reinhart Date: Tue, 10 Jul 2018 18:04:00 -0400 Subject: [PATCH 3/3] Update MacInstallation.md --- MacInstallation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/MacInstallation.md b/MacInstallation.md index 0735dc02..78fc30f3 100644 --- a/MacInstallation.md +++ b/MacInstallation.md @@ -96,11 +96,11 @@ This prompt indicates that the application interacting with the Ledger is not th ### Ledger Prompt: “Open non-genuine app?” -If the ledger says “Open non-genuine app?” then freezes, this is a sign that the install was unsuccessful. You probably need to update your Ledger’s firmware to 1.4.2, then restart the process. +As these applications are not coming directly from Ledger Live or Ledger Manager, you should expect to see this prompt under all circumstances when following these instructions. If the ledger says “Open non-genuine app?” then freezes, this is a sign that the install was unsuccessful. You probably need to update your Ledger’s firmware to 1.4.2, then restart the process. ### “Broken certificate chain - loading from user key” -If you are running the installation script and you already have a version of the application on your Ledger, you will see this message. This is normal, and not a cause for concern. +If you are running the installation script and you already have a version of the application on your Ledger, you will see this message. This is normal, and not a cause for concern. ### Removing a virtualenv