From 73be5943087bd9cc8b55ffd637cefb0ff574e429 Mon Sep 17 00:00:00 2001 From: Innocent Bystander Date: Tue, 10 Nov 2026 00:09:54 -0500 Subject: [PATCH] Streamlined the Getting Started Guide, offloaded the FPGA build instructions to a different file as it is not critical path to getting started with the Proxmark5 --- CHANGELOG.md | 1 + README.md | 3 +-- doc/md/PM5_Start_Here/Compiling_the_FGPA.md | 23 +++++++++++++++++++ .../Getting_Started_With_PM5.md | 15 ++++-------- 4 files changed, 29 insertions(+), 13 deletions(-) create mode 100644 doc/md/PM5_Start_Here/Compiling_the_FGPA.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 4153d5358..c6acfd500 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ All notable changes to this project will be documented in this file. This project uses the changelog in accordance with [keepchangelog](http://keepachangelog.com/). Please use this to write notable changes, which is not the same as git commit log... ## [unreleased][unreleased] +- Updated `/Getting_Started_With_PM5.md` (@innocentbystanderproxmark) - Changed PM5 FPGA image - `client/resources/fpga_pm5.bin` is now built from the repo sources (`make -C fpga fpga_pm5_release`) and replaces the vendor built `PM5_FPGA_fix_loedge_bug.bin` (@iceman1001) - Changed `hf mf info`, `hf mfu info`, `hf mfdes info`, `hf felica info`, `hf 14b info`, `hf calypso info` and `hf 14a info` - identify transit cards by keys, AIDs, system codes or data, show card number / balance where free to read and hint at the full decode (@iceman1001) - Fixed PM5 `hf mf sim` and other 14a sims - the RSSI ADC was reset and recalibrated before every listen, missing fast reader frames such as the auth nR/aR (@iceman1001) diff --git a/README.md b/README.md index bac556b49..4a9d5b24c 100644 --- a/README.md +++ b/README.md @@ -78,11 +78,10 @@ The last hardware generation is called Proxmark5. It has - 125, 134, 250, 375, 500 KHz Low Frequency Antenna (LF) - 13.56 MHz High Frequency Antenna (HF) - as a addon: 860-960 MHz Ultra High Frequency Antenna (UHF), ** not developed yet ** - + At the moment, Proxmark5-specific instructions are all grouped in [a single Getting Started guide](doc/md/PM5_Start_Here/Getting_Started_With_PM5.md). Read it to build, flash and run your Proxmark5 device. See the instruction links in the tables above to get the compilation environment. - ⚠ The firmware is not stable at the moment and is actively being developed at. -- ⚠ Don't install the BWM addon board for now. ## Proxmark3 RDV4 diff --git a/doc/md/PM5_Start_Here/Compiling_the_FGPA.md b/doc/md/PM5_Start_Here/Compiling_the_FGPA.md new file mode 100644 index 000000000..6c744a68f --- /dev/null +++ b/doc/md/PM5_Start_Here/Compiling_the_FGPA.md @@ -0,0 +1,23 @@ +# Compiling the FGPA code + +## Contents + +- [Build the FPGA image from source](#Build-the-FPGA-Image-From-Source) +--- + + +## Build the FPGA Image From Source +The PM5 bitstream is built with the open source toolchain (yosys, nextpnr-himbaechel, apicula) from [oss-cad-suite](https://github.com/YosysHQ/oss-cad-suite-build/releases). Use the release pinned in `.github/workflows/fpga-pm5.yml`: older yosys builds give images with a weaker antenna drive. Unpack it next to the repository (`../oss-cad-suite`) or point `OSS_CAD_SUITE` at it. + +Build the fpga/fpga_pm5.bin binary +``` +make -C fpga pm5 +``` + +Build the fpga/fpga_pm5.bin binary and copy it to client/resources This is where `script run upgrade_fpga` looks to for an image to flash. +``` +make -C fpga fpga_pm5_release +``` + +The build is reproducible: the same sources and toolchain give the same bytes as the CI artifact. To try an image without touching the FPGA flash, load it into SRAM with `hw fpga config -s -f fpga/fpga_pm5.bin`. A power cycle returns to the image in flash. + diff --git a/doc/md/PM5_Start_Here/Getting_Started_With_PM5.md b/doc/md/PM5_Start_Here/Getting_Started_With_PM5.md index fdc9d6e5d..bb9277acb 100644 --- a/doc/md/PM5_Start_Here/Getting_Started_With_PM5.md +++ b/doc/md/PM5_Start_Here/Getting_Started_With_PM5.md @@ -82,22 +82,12 @@ For more options, look [here](#Build-Extras) ## Flash the FPGA +This writes `client/resources/fpga_pm5.bin` to the FPGA flash. ``` ./pm3 script run update_fpga ``` -This writes `client/resources/fpga_pm5.bin` to the FPGA flash. - -### Build the FPGA image from source -The PM5 bitstream is built with the open source toolchain (yosys, nextpnr-himbaechel, apicula) from [oss-cad-suite](https://github.com/YosysHQ/oss-cad-suite-build/releases). Use the release pinned in `.github/workflows/fpga-pm5.yml`: older yosys builds give images with a weaker antenna drive. Unpack it next to the repository (`../oss-cad-suite`) or point `OSS_CAD_SUITE` at it. - -``` -make -C fpga pm5 # builds fpga/fpga_pm5.bin -make -C fpga fpga_pm5_release # also copies it to client/resources -``` - -The build is reproducible: the same sources and toolchain give the same bytes as the CI artifact. To try an image without touching the FPGA flash, load it into SRAM with `hw fpga config -s -f fpga/fpga_pm5.bin`. A power cycle returns to the image in flash. ## I Have A BWM Now What @@ -166,6 +156,8 @@ On Windows, you can try the following: - Open the proxmark client to try to connect to verify your device is re-working. +## + ## Build Extras The Proxmark5 platform must be specified when compiling the firmware. You have several options: @@ -198,3 +190,4 @@ Do not use them unless you fully understand what you're doing. - [PM5 RGB Controller](./PM5_Controllers/PM5_RGB_Controller_RM.md) - [PM5 BWM Install](https://github.com/RfidResearchGroup/Proxmark5_BWM_esp32/blob/master/INSTALL.md) - [PM5 <--> Flipper Usage](./PM5-FLIPPER-USAGE.md) +- [Compile the FPGA Image From Source](./Compiling_the_FGPA.md)