- Before you start
- Flash sections
- Revision history and flashing procedures
Before you start
This document has been created assuming that you have read the relevant Getting Started guide and configured your development environment accordingly.
Note: Some have problems running the Proxmark3 in a virtual machine environment. The USB can be problematic.
For Windows users - Everything in this document is done from the Minimalist GNU terminal window. Start by running "runme.bat".
Proxmark firmware is comprised of three logical sections:
|Runs on ARM processor||Runs on FPGA||Runs on ARM processor|
|Rarely updated||Infrequently updated||Very frequently updated|
|Supports reflashing over USB||Intermediate processing of RF Signals||Communicates with client over USB|
|Transfers execution to OS||Makes signals available to ARM processor||Implements most of the Proxmark's functionality|
|Safety in case the OS is corrupted|
An ELF (Executable and Linkable Format) and a S19 (Motorola S-record) file is produced for each logical section:
- ELF files are used with the flasher program for upgrading the Proxmark over USB.
- S19 files are used with a JTAG programmer for upgrading the Proxmark.
The bootloader (sometimes also called bootrom) is a small piece of code that enables writing to the flash over USB in the first place, and knows how to transfer execution to the operating system. It's updated very infrequently and, due to its importance, should be left alone most of the time.
As long as your bootloader is intact you can recover any firmware error of your proxmark3 with just an USB connection and the provided flash tools.
Upgrading the bootrom of your Proxmark can brick the device. Please exercise caution when upgrading the bootloader. If the bootloader is corrupted, the only way to restore your Proxmark to working order will be through the use of a JTAG programmer.
armsrc/obj/fpgaimage.elf(now included in
The FPGA image is the configuration/code that runs on the FPGA that sits on the proxmark3. It processes analogue signals coming from the antennas and makes those signals available to the ARM. Like the bootrom code, the FPGA code is not frequently updated.
Since the FPGA doesn't have flash memory of its own, this configuration is stored in the flash memory of the ARM processor and downloaded into the FPGA on each boot of the device.
The FPGA code (called bit stream) is updated fairly infrequently, and special tools are needed to compile the bit stream from the Verilog sources. The proxmark3 firmware source releases and GitHub checkouts always contain a compiled bit stream (in
fpga/fpga.bit) which is then simply wrapped into an image file for you to flash onto the proxmark3.
armsrc/obj/osimage.elf(now included in
The OS image is the main firmware code that runs on your proxmark3.
It is developed and regularly updated in the GitHub, but if you don't need the latest features you are well off using the provided binary releases. (Note also: since the GitHub is considered eternal work-in-progess, a current GitHub version might not work or even build.)
The OS image and FPGA image work in tandem, so you should always flash them from the same GitHub revision.
Likewise, a firmware image and the PM3 client version work in tandem, so you should always build both your client and firmware from the same revision.
The full image is a union of the FPGA and OS images.
Using the full image will keep the version of your FPGA and OS images in sync, and you should normally flash this file to your PM3.
Revision history and flashing procedures
As mentioned above, the Proxmark3 is largely a constant work in progress. Its firmware started off as a big update from the older ProxmarkII project, and was mainly aimed at demonstrating a few key concepts rather than provide a polished end-user interface.
Over time, and thanks to the many contributions of all the developers on the project, the firmware has evolved in many ways: new commands and features, more refined firmware architecture, etc.
The firmware shipped with most Proxmark3 devices is generally outdated, and won't work with the current version of the Proxmark3 client.
You will need to reflash it.
Ensure that you have read the prior section before proceeding. In order to upgrade to the latest version of firmware, you will need to first upgrade the Proxmark's bootloader.
The PM3 is a USB CDC-ACM device, and doesn't need device drivers on most platforms. These instructions assume that your PM3 device is
/dev/ttyACM0, which is true for Linux systems with 1 serial device (the PM3).
If you have multiple USB serial devices on Linux, it may be something like
- On Android, you need to flash the firmware with a PC.
On OSX, it is something like
On Windows, it is a COM port like
COM3. Consult Device Manager for a list.
To compile the firmware, bootloader and flasher:
The normal compilation process will build all of these (
make). However, if you just want to build these targets and not the rest of the PM3 client, you can do so with:
make armsrc/obj/fullimage.elf bootrom/obj/bootrom.elf client/flasher
To update the Proxmark bootloader:
The steps below will upgrade the Proxmark bootloader to the version you checked out previously using the procedure from the getting started guide.
- Optional: Update your working copy to the latest revision. (Refer to the getting started documentation).
- Open up a terminal and go to the proxmark3 directory.
- Press and hold the button on the Proxmark while connecting it to your computer. Continue to hold the button until the yellow and red LEDs stay lit, then release the button. [sidenote: on RDV4 the LED's A and C lights up]
- Upgrade the Proxmark bootrom by executing the following command:
./client/flasher /dev/ttyACM0 -b bootrom/obj/bootrom.elf
At this point the bootrom has been updated and the Proxmark is now in a position to have its OS upgraded.
To update the Proxmark firmware and FPGA code:
- Open a terminal in the proxmark3 directory.
- Connect the Proxmark to your PC (no need to to hold the button this time)
./client/flasher /dev/ttyACM0 armsrc/obj/fullimage.elf.
Once flashing has completed, you can run the PM3 client, and you should see the new firmware version in the status message:
[..] bootrom: master/v3.0.1 2018-01-01 00:00:00 os: HEAD/v3.0.1 2018-01-01 00:00:00 fpga_lf.bit built for 2s30vq100 on 2015/03/06 at 07:38:04 fpga_hf.bit built for 2s30vq100 on 2018/08/13 at 21:22:51 [...] proxmark3>
JTAG Recovery Procedure
If for whatever reason the USB upgrade procedure (section above) failed and the Proxmark will no longer boot, you will need to load the bootrom on to the Proxmark using the JTAG interface. This procedure assumes that you have a Segger J-LINK (or clones) for the recovery process and J-link commander installed.
Plug both the Proxmark and the Segger J-LINK in to the computer. Attach the J-LINK to the Proxmark JTAG port.
Run J-link commander. Then:
exec device = AT91SAM7S256 exec EnableFlashDL h loadbin "C:\proxmark3\recovery\proxmark3_recovery.bin" 0x100000
that is it!
for flashing either the bootrom or firmware, these are the files and addresses:
bootrom.bin = 0x100000 fullimage.bin = 0x102000
Now un-plug the proxmark USB and JTAG and re-plug the Proxmark USB to the computer.