doc/md/Use_of_Proxmark/0_Compilation-Instructions.md

   1 <a id="Top"></a>
   2
   3 # Compilation instructions
   4
   5 # Table of Contents
   6 - [Compilation instructions](#compilation-instructions)
   7 - [Table of Contents](#table-of-contents)
   8   - [Tuning compilation parameters](#tuning-compilation-parameters)
   9     - [Compile for Proxmark3 RDV4](#compile-for-proxmark3-rdv4)
  10     - [Compile for generic Proxmark3 platforms](#compile-for-generic-proxmark3-platforms)
  11   - [Get the latest commits](#get-the-latest-commits)
  12   - [Clean and compile everything](#clean-and-compile-everything)
  13     - [if there are different Python 3 packages installed](#if-there-are-different-python-3-packages-installed)
  14     - [if you got an error](#if-you-got-an-error)
  15   - [Install](#install)
  16   - [Flash the BOOTROM & FULLIMAGE](#flash-the-bootrom--fullimage)
  17     - [The button trick](#the-button-trick)
  18   - [flasher stops and warns you about firmware image](#flasher-stops-and-warns-you-about-firmware-image)
  19   - [Run the client](#run-the-client)
  20   - [Next steps](#next-steps)
  21
  22
  23
  24 ## Tuning compilation parameters
  25 ^[Top](#top)
  26
  27 The client and the Proxmark3 firmware should always be in sync.
  28 Nevertheless, the firmware can be tuned depending on the Proxmark3 platform and options.
  29
  30 Indeed, the Iceman fork can be used on other Proxmark3 hardware platforms as well.
  31
  32 Via some definitions, you can adjust the firmware for a given platform, but also to add features like the support of the Blue Shark add-on or to select which standalone mode to embed. To learn how to adjust the firmware, please read [Advanced compilation parameters](/doc/md/Use_of_Proxmark/4_Advanced-compilation-parameters.md).
  33
  34 ### Compile for Proxmark3 RDV4
  35 ^[Top](#top)
  36
  37 The repo defaults for compiling a firmware and client suitable for Proxmark3 RDV4.
  38
  39 ### Compile for generic Proxmark3 platforms
  40 ^[Top](#top)
  41
  42 In order to build this repo for generic Proxmark3 platforms we urge you to read [Advanced compilation parameters](/doc/md/Use_of_Proxmark/4_Advanced-compilation-parameters.md)
  43
  44
  45 ## Get the latest commits
  46 ^[Top](#top)
  47
  48 ```sh
  49 cd proxmark3
  50 git pull
  51 ```
  52
  53 ## Clean and compile everything
  54 ^[Top](#top)
  55
  56 ```sh
  57 make clean && make -j
  58 ```
  59
  60 ### if there are different Python 3 packages installed
  61 ^[Top](#top)
  62
  63 It is possible to point to a different Python 3 package. For example, to build against Python 3.11:
  64
  65 ```sh
  66 make clean && make -j PYTHON3_PKGCONFIG=python-3.11
  67 ```
  68
  69 ### if you got an error
  70 ^[Top](#top)
  71
  72 Read the [troubleshooting guide](/doc/md/Installation_Instructions/Troubleshooting.md),
  73
  74 For instance,  on WSl-1 you usually get the `libQt5Core.so.5 not found` message
  75 [solution](/doc/md/Installation_Instructions/Troubleshooting.md#libQt5Coreso5-not-found)
  76
  77
  78 ## Install
  79 ^[Top](#top)
  80
  81 This is an optional step. If you do
  82
  83 ```sh
  84 sudo make install
  85 ```
  86
  87 Then the required files will be installed on your system, by default in `/usr/local/bin` and `/usr/local/share/proxmark3`.
  88 Maintainers can read [this doc](../Development/Maintainers.md) to learn how to modify installation paths via `DESTDIR` and `PREFIX` Makefile variables.
  89
  90 The commands given in the documentation assume you did the installation step. If you didn't, you've to adjust the commands paths and files paths accordingly,
  91 e.g. calling `./pm3` or `client/proxmark3` instead of just `pm3` or `proxmark3`.
  92
  93 ## Flash the BOOTROM & FULLIMAGE
  94 ^[Top](#top)
  95
  96 In most cases, you can run the following script which try to auto-detect the port to use, on several OS:
  97
  98 ```sh
  99 pm3-flash-all
 100 ```
 101
 102 For the other cases, specify the port by yourself. For example, for a Proxmark3 connected via USB under Linux (adjust the port for your OS):
 103
 104 ```sh
 105 proxmark3 /dev/ttyACM0 --flash --unlock-bootloader --image bootrom.elf --image fullimage.elf
 106 ```
 107
 108 The firmware files will be searched in the expected locations (installed files, working repo files, user folder, etc.). You can also specify their location:
 109
 110 ```sh
 111 pm3-flash -b /tmp/my-bootrom.elf /tmp/my-fullimage.elf
 112 ```
 113
 114 or
 115
 116 ```sh
 117 proxmark3 /dev/ttyACM0 --flash --unlock-bootloader --image /tmp/my-bootrom.elf --image /tmp/my-fullimage.elf
 118 ```
 119
 120 ### The button trick
 121 ^[Top](#top)
 122
 123 If the flasher can't detect your Proxmark3 (especially the very first time you flash a new device), force it to enter the bootloader mode as following:
 124
 125 With your Proxmark3 unplugged from your machine, press and hold the button on your Proxmark3 as you plug it into a USB port.
 126 You can release the button, two of the four LEDs should stay on.
 127 You're in bootloader mode, ready for the next step.
 128
 129 In case the two LEDs don't stay on when you're releasing the button, you've a very old bootloader, start over and keep the button pressed during the whole flashing procedure.
 130
 131
 132 ## flasher stops and warns you about firmware image
 133 ^[Top](#top)
 134
 135 The Proxmark3 software and firmware is connected tightly. The strong recommendation is to use the client with a Proxmark3 device flashed with firmware images from same source version.
 136 In the flash process you might get this message because the firmware images is downloaded or distributed and you have compiled your own client from a different source version.
 137 To minimize the risks the flasher warns about it and stops.
 138
 139 ```
 140     Make sure to flash a correct and up-to-date version
 141     You can force flashing this firmware by using the option '--force'
 142 ```
 143
 144 If you know what you are doing and want to proceed despite the mismatch, you need to add the `--force` param in order to continue flashing.
 145
 146 ```sh
 147 pm3-flash-all --force
 148 ```
 149
 150
 151
 152 ## Run the client
 153 ^[Top](#top)
 154
 155 In most cases, you can run the script `pm3` which try to auto-detect the port to use, on several OS.
 156 ```sh
 157 ./pm3
 158 ```
 159
 160 For the other cases, specify the port by yourself. For example, for a Proxmark3 connected via USB under Linux:
 161
 162 Here, for example, for a Proxmark3 connected via USB under Linux (adjust the port for your OS):
 163
 164 ```sh
 165 proxmark3 /dev/ttyACM0
 166 ```
 167
 168 or from the local repo
 169
 170 ```sh
 171 client/proxmark3 /dev/ttyACM0
 172 ```
 173
 174 ## Next steps
 175 ^[Top](#top)
 176
 177 For the next steps, please read the following pages:
 178
 179 * [Validating proxmark client functionality](/doc/md/Use_of_Proxmark/1_Validation.md)
 180 * [First Use and Verification](/doc/md/Use_of_Proxmark/2_Configuration-and-Verification.md)
 181 * [Commands & Features](/doc/md/Use_of_Proxmark/3_Commands-and-Features.md)
 182