PiTrezor : A DIY bitcoin hardware wallet based on trezor and raspberry pi zero

Hardware wallets are one of the most secure way to handle your cryptocurrency like bitcoin.

The trezor is a hardware bitcoin and other cryptocurrency wallet made by satoshilabs  used to secure online transactions. The security reside in the fact that the private key used to sign a transaction never leave the device to your computer.


The hardware wallet device connect via USB to a host computer. Any transaction that would imply sending money to someone must be signed to be considered valid by the cryptocurrency network, like the bitcoin network. To perform that, the transaction is sent to the hardware wallet device via USB. The user can confirm its authenticity on the device display and press a button on the device to sign it with the private key. The hardware wallet device will send back the signed transaction to the computer to be broadcasted to the internet. In this process, the private key is never accessed by the computer.

On the other hand, the raspberry pi zero is a low cost and small but powerful computer. It is used on numerous projects by ton of developers and hobbyists around the world.

In this web page I will show you how to create your own hardware bitcoin wallet based on the original trezor source code and that run on it on a raspberry pi zero (or pi 4). This is a fun, low cost, D.I.Y. project for any cryptocurrency enthusiasm!

Last minute note: with the latest Trezor application, if you see an issue about the device compromised, don’t panic. The latest update of the application validates if the firmware is legit. Since this is a custom firmware for the raspberry pi, it is not officially supported. But here is how to modify the app to support it:

Click the gear in the top right corner.Select the device tab. Scroll to the bottom and click “turn off firmware revision check”. Select the “I understood” option and click “Turn off” button

News: 

 refer to update procedure below before reflashing the SD card

• Update 10 May 2023: pitrezor 1.12.1.0
• Based on trezor firmware 1.12.1
• Update 28 August 2022 :  pitrezor 1.11.2.0
• Based on trezor firmware 1.11.2
  
• Update 31 May 2022:  pitrezor 1.11.1.0
• Based on trezor firmware 1.11.0
• Update 3 February 2021: pitrezor 1.10.5.0
• Based on trezor firmware 1.10.5
• Now support Pi 0-2w. Still supporting Pi 0 and Pi 4
• Migrated yocto to version "honister"
  
• Update 20 December 2021: pitrezor 1.10.4.0
• Based on trezor firmware 1.10.4
  
• Update 29 September 2021: pitrezor 1.10.3.0
• Based on trezor firmware 1.10.3
• Update 26 July 2021: pitrezor 1.10.2.0
• Based on trezor firmware 1.10.2
  
• Update 23 May 2021: pitrezor 1.10.0.0
• Based on trezor firmware 1.10.0
• Update 30 March 2021: pitrezor 1.9.4.1
• Support of raspberry pi 4
  
• Update 18 February 2021: pitrezor-1.9.4.0.zip
• Based on trezor firmware 1.9.4
• Updated linux yocto platform to dunfell
  

Features:

• Low cost
• Easy to build if an existing raspberry pi hat is used
• Run on pi zero, pi zero 2w and pi 4.
• Use the original trezor One code. Only a thin layer is used to adapt the code to the raspberry pi Linux platform. 
• All code modifications are open source, like the original trezor code.
• 100% Compatible with trezor web wallet to perform transactions.
• Use the hardware random number generator of the raspberry pi for more security.
• Can be very secure if you use a pass phrase (see security section below)
• Support small 128x64 OLED display and/or display via HDMI output.
• Adjustable display scale factor on HDMI output
• Fast boot (around 5 seconds)
• Software is free (but donations are accepted!)

Block diagram

 

The block diagram shows the different possibilities to run the pitrezor:

• A raspberry 0 or raspberry pi 4 can be used
• An HDMI monitor can be used as the only display or as a second display with the OLED
  
• The OLED must have a 128x64 resolution, I2C or SPI
• The OLED and the the push buttons can be installed manually or a HAT can be used, as long as the OLED resolution is 128x64
• For the pi 4, a keyboard can be used as input.

Thus for the pi 4, it is possible to build a pitrezor with just the pi 4, a keyboard and a hdmi screen.

For the pi 0, you need the buttons as input (as part of the hat or soldered directly). The display can be HDMI and/or OLED. Starting with HDMI is a simpler solution when beginning and testing.

Photos

OLED Display: 

 

A small OLED display can be attached to the pi zero. In that case, I recommend to use a small plastic box to protect the components and to give a more professional look!

Raspberry pi HAT:

(Picture courtesy of Damian Bevan)

It is also possible to use the Adafruit bonnet (see https://www.adafruit.com/product/3531) or similar HAT. In that case you just have to install the pins on the pi if required and connect the bonnet!

Quick start guide:

List of required components:

Required components for the PiTrezor

1. A raspberry pi zero (v1.3 to avoid unknown compatibility issue). You don't need the pi zero W, it cost probably a little bit more than the regular pi zero, but it will work anyway. The difference is that pi zero W has wifi and bluetooth but this project don't use it. The network drivers are not loaded by the platform so the W can be considered as secure. As mentionnend, you can use a pi 4 also if you already have one but it is more expensive than the pi 0.
   
2. An SD card. The image to write on the SD card is very small (around 100 Megs) so virtually any decent SD card should work. Make sure you have one that is compatible with the pi.
3. A good micro-usb to usb cable.
4. A mini HDMI male to HDMI female adapter to verify the output via the HDMI output. You need HDMI cable and a TV or monitor too!
5. Two push buttons (normally open contact, SPST)
6. Some wires to solder the buttons to the p.
7. Optionally, an I2C or SPI OLED display. Supported OLED are based on the SH1106 controller or Adafruit controller.
8. Optionally, a box or enclosure for a more professional look. 

You will also need standard tool like solder iron, pliers, ...

Of course, If you are using the Adafruit bonnet, you don't need separate push buttons or OLED. Refer to Hat documentation about how to connect the bonnet to the pi zero.

Videos:

Some users had the courtesy of making videos to help you build your pitrezor. Here are some links:

• (English): https://youtu.be/YrKo0QGWIuY

• (Spanish): https://lbry.tv/@Loquesemepone:a/DIY-hardware-wallet-basada-en-Trezor:3

• https://www.youtube.com/watch?v=smNDVt1GyL0
  

Step-By-Step instructions:

1. If you don't have the software called "etcher" already installed in your computer, download it here : https://etcher.io/ . This software is used to write the program image to the SD card.
2. Download the latest pitrezor SD card image by clicking here and select "save" to save the zip file
3. Start etcher and follow the instructions. You will need to connect the SD card to your computer to flash the pitrezor image file.
4. After the card is flashed, put it in the SD card slot in the pi.
5. Connect the HDMI output to a monitor or tv using the cable and adapter. On the pi 4, use the mini HDMI connector just beside the usb-c connector.
   
6. Connect the USB cable in the USB port near the center of the pi, not the one near the corner. Refer to next picture. For the pi 4, the usb-c connector is used.
   
   
7. Connect the other end of the USB cable to your computer or a USB power supply. You should see the pi boot sequence in the monitor and after 4-5 seconds the trezor logo should appear. Good! That confirms that your pi and SD card are working correctly.
8. At this point you cannot do much, so disconnect the USB cable, HDMI adapter and cable and remove SD card.
9. If you are using the Adafruit bonnet, it is time to connect it and go straight to the "Configuration" section below. Otherwise, continue reading
10. Solder the 2 buttons to the pi as showed in the following diagram. The left button (called "no") is connected to the pins 30 and 32 (in yellow in the next picture). The right button (called "yes") is connected to the pins 34 and 36 (in red in the picture). This is the default setup but can be tweaked from configuration file. The pi 4 use the same pins.
    

    

    connecting the button

11. Put back the SD card in the pi and reconnect the HDMI and USB cable back to your computer.
12. It should boot again, otherwise that means something went bad during the soldering of the buttons :(
13. Open a browser on your computer and navigate to https://suite.trezor.io/web/
14. You can be requested to install the trezor bridge but on chrome it is not absolutly necessary if your system support webusb. Select your operating system to download the correct bridge software if required and perform installation
15. If you installed the bridge, close and reopen your browser and go back to https://suite.trezor.io/web/
16. If you don't plan to use the bridge on Linux, don't forget to set the permission accordingly. Refer to setting up chrome on linux. 
17. If the bridge is already installed, you should see a message that invites you to connect your trezor. Connect the USB cable of your pi.
18. The browser application should detect the device and invite you to perform the trezor setup.
19. During the setup you will need the buttons to, at least, go from one seed word to another.
20. If all is working correctly you can disconnect everything to solder the OLED display. The I2C OLED display need 4 wires to solder and the SPI OLED uses 7 wires. Refer to the next picture to determine how to solder the OLED depending on interface. The pins are the same for the pi 4:
    
21. Connect the SD card back to your computer and refer to the configuration section below to correctly configure your OLED model and orientation. Their is only 2 possibles orientations so you can try both and see which one is better for you.
22. Reconnect everything and retry your device. Now you should see the output on the HDMI connector if connected and also on the OLED at the same time.
23. If that work, put everything in a box!
24. Enjoy! And please don't forget to send a donation to continue the support this project update (see below). Any amount is welcome.

Download

The latest pitrezor SD card images:

For Pi 0 : click here for version 1.12.1.0

md5sum of the zip is e1140edb9b73270b02066d202d8ae665

For Pi 0 2W : click here for version 1.12.1.0

md5sum of the zip is 54a17e6afa7555af6a6471dfa1926f94

 

For Pi 4: click here for version 1.12.1.0

md5sum of the zip is 9497443c921375a508bf5429779d7917

Configuration

If you connect the SD card in your computer you should see a file named "pitrezor.config" in the first partition (boot partition). You can open this file with your favorite text editor. You will be able to change the configuration variables which are:

• TREZOR_OLED_SCALE : This control the scale factor of the display to apply when using the HDMI output. A scale factor of 1 means the default size of 128x64 pixel. A scale factor of 2 will stretch the image to 256x128 and so on.
• TREZOR_OLED_TYPE: Specify the type of OLED connected to the pi zero. The file enumerate the different value and their meaning. Select the one that match your OLED display.
• TREZOR_OLED_FLIP: Set to 0 or 1 to control the image vertically (normal or inverted) This is useful depending how you assemble the OLED in n enclosure.
• TREZOR_GPIO_YES and TREZOR_GPIO_NO : Specify the GPIO number to use for the yes/no button. If you soldered the buttons like mentionned in the tutorial, you can keep the default values.

When you change a value, keep the line formating as-is with the export statement. Just change the number after the equal sign. If you change something else, this could prevent the pi trezor application to start correctly.

For the Adafruit bonnet, you must change the values to these:

export TREZOR_OLED_TYPE=1
export TREZOR_OLED_FLIP=1
export TREZOR_GPIO_YES=6
export TREZOR_GPIO_NO=5

Is this secure ?

The main difference of this device versus the real trezor device is that the pi zero stores everything on the SD card. The equivalent of the flash memory for the trezor is stored in a file on the first partition. That means that anybody that has your SD card can access your seed words and private key.

However, the wallet supports the usage of a passphrase. The passphrase is a kind of an extra seed word that is not stored on SD card. By using a passphrase, you would prevent a thief that could have your SD card to empty your wallet.

Thus, the recommendation is to always use a passphrase!

Updating from previous pitrezor image

If you are updating your pitrezor to the latest image you will need your seed words with you:

1. Make sure that you have seed backup available. This mean your word list !! If not, you'll need to transfer all your funds to another wallet and disconnect other services (like U2F, password manager etc.
2. Erase (Wipe) your pitrezor from trezor wallet or trezor suite application. This step improve the security before putting back the SD card in a PC in case it is infected.
3. Put the SD card in a PC and copy your pitrezor.config file from the SD card to the computer
4. Flash the SD card with the latest downloaded image
5. Disconnect and reconnect the SD card to your computer
6. Copy your pitrezor.config file from the computer to the SD card to overwrite the default version with your own version.
   
7. Eject the SD card from your computer and install it in the pi zero
8. Boot your pitrezor as usual
9. When you will go to the wallet web site, your pitrezor will be detected as a new device. Select the recover option. You will have to enter all the words of your seed word list (advanced recovery mode is recommended so that your seed will never be entered on a computer).
10. Don't forget to enable the passphrase option after if you were using one before. You should! If you haven't you can create new hidden wallet with a passphrase.
    

For developers

The modification to trezor original code are available in this repo: https://github.com/heneault/trezor-firmware

The platform code is based on yocto to which I added my own layer and some build scripts. The repo is there: https://github.com/heneault/yocto-pitrezor

Questions ?

Comments are welcome in the comment section below. You can also reach me at info@pitrezor.com

Scan to send bitcoin donation!

Donation !

A lot of work and effort has been put in this project and still needed to keep it up to date. If you like it, please consider giving a donation. Any amount is welcome!

Bitcoin: 1trezor8MpRmFHcMCLdANpiVoEM9zqe2n

Paypal:

Copyright and Legal Warning

There are inherent dangers in the use of any software available for download on the Internet, and I caution you to make sure that you completely understand the potential risks before downloading any of the software.
The Software and SD card image available on this website are provided "as is" without warranty of any kind, either express or implied. Use at your own risk.
The use of the software and SD card image downloaded on this site is done at your own discretion and risk and with agreement that you will be solely responsible for any damage to your computer system or loss of data that results from such activities. You are solely responsible for adequate protection and backup of the data and equipment used in connection with any of the software, and I will not be liable for any damages that you may suffer in connection with using, modifying or distributing any of this software. No advice or information, whether oral or written, obtained by you from me or from this website shall create any warranty for the software.
I make no warranty that:

• the software will meet your requirements
• the software will be uninterrupted, timely, secure or error-free
• the results that may be obtained from the use of the software will be effective, accurate or reliable
• the quality of the software will meet your expectations
• any errors in the software obtained from me will be corrected.

The software, SD card image and its documentation made available on this website:

• could include technical or other mistakes, inaccuracies or typographical errors. I may make changes to the software or documentation made available on its web site at any time without prior-notice.
• may be out of date, and I make no commitment to update such materials.

I assume no responsibility for errors or omissions in the software or documentation available from its web site.
In no event shall I be liable to you or any third parties for any special, punitive, incidental, indirect or consequential damages of any kind, or any damages whatsoever, including, without limitation, those resulting from loss of use, data or profits, and on any theory of liability, arising out of or in connection with the use of this software. 

© Yannick Heneault, 2018 and up. Unauthorized use and/or duplication of this material without express and written permission from this blog’s author and owner is strictly prohibited. Excerpts and links may be used, provided that full and clear credit is given to Yannick Heneault with appropriate and specific direction to the original content.

The name and logo trezor are the properties of satoshilabs
The name and logo raspberry pi and raspberry pi zero are properties of the raspberry pi foundation