armsrc/Standalone/readme.md

   1 # Standalone Modes
   2 <a id="Top"></a>
   3
   4
   5 # Table of Contents
   6 - [Standalone Modes](#standalone-modes)
   7 - [Table of Contents](#table-of-contents)
   8   - [Implementing a standalone mode](#implementing-a-standalone-mode)
   9   - [Naming your standalone mode](#naming-your-standalone-mode)
  10   - [Update MAKEFILE.HAL](#update-makefilehal)
  11   - [Update MAKEFILE.INC](#update-makefileinc)
  12   - [Adding identification string of your mode](#adding-identification-string-of-your-mode)
  13   - [Compiling your standalone mode](#compiling-your-standalone-mode)
  14   - [Submitting your code](#submitting-your-code)
  15
  16
  17
  18 This contains functionality for different StandAlone modes. The fullimage will be built given the correct compiler flags used. Build targets for these files are contained in `Makefile.inc` and `Makefile.hal`
  19
  20 If you want to implement a new standalone mode, you need to implement the methods provided in `standalone.h`.
  21 Have a look at the skeleton standalone mode, in the file `lf_skeleton.c`.
  22
  23 As it is now, you can only have one standalone mode installed at the time unless you use the dankarmulti mode (see `dankarmulti.c` on how to use it).
  24
  25 To avoid clashes between standalone modes, protect all your static variables with a specific namespace. See how it is done in the existing standalone modes.
  26
  27 ## Implementing a standalone mode
  28 ^[Top](#top)
  29
  30 We suggest you keep your standalone code inside the `armsrc/Standalone` folder. And that you name your files according to your standalone mode name.
  31
  32 The `standalone.h` states that you must have two functions implemented.
  33
  34 The ModInfo function, which is your identification of your standalone mode.  This string will show when running the command `hw status` on the client.
  35
  36 The RunMod function, which is your "main" function when running.  You need to check for Usb commands, in order to let the pm3 client break the standalone mode.  See this basic skeleton of main function RunMod() and Modinfo() below.
  37
  38 ````
  39 void ModInfo(void) {
  40     DbpString("  LF good description of your mode - aka FooRun (your name)");
  41 }
  42
  43 void RunMod(void) {
  44     // led show
  45     StandAloneMode();
  46
  47     // Do you target LF or HF?
  48     FpgaDownloadAndGo(FPGA_BITSTREAM_LF);
  49
  50     // main loop
  51     for (;;) {
  52         WDT_HIT();
  53
  54         // exit from standalone mode, just send a usbcommand
  55         if (data_available()) break;
  56
  57         // do your standalone stuff..
  58     }
  59 ````
  60
  61 ## Naming your standalone mode
  62 ^[Top](#top)
  63
  64 We suggest that you follow these guidelines:
  65 - Use HF/LF to denote which frequency your mode is targeting.
  66 - Use you own github name/similar for perpetual honour to denote your mode.
  67
  68 sample:
  69  `LF_FOO`
  70
  71 Which indicates your mode targets LF and is called FOO.
  72
  73 This leads to your next step, your DEFINE name needed in Makefile.
  74
  75 `WITH_STANDALONE_LF_FOO`
  76
  77
  78 ## Update MAKEFILE.HAL
  79 ^[Top](#top)
  80
  81 Add your mode to the `Makefile.hal` help and modes list (alphabetically):
  82 ```
  83 +==========================================================+
  84 | STANDALONE      | DESCRIPTION                            |
  85 +==========================================================+
  86 ...
  87 +----------------------------------------------------------+
  88 | LF_FOO          | My foobar mode will make you coffee    |
  89 +----------------------------------------------------------+
  90
  91 STANDALONE_MODES := LF_... LF_FOO
  92 STANDALONE_MODES += HF_...
  93 ```
  94
  95 If your mode is using one of the unique features of the RDV4, add it to the proper list:
  96
  97 ```
  98 STANDALONE_MODES_REQ_SMARTCARD :=
  99 STANDALONE_MODES_REQ_FLASH :=
 100 STANDALONE_MODES_REQ_BT :=
 101 ```
 102
 103 Please respect alphabetic order!
 104
 105 ## Update MAKEFILE.INC
 106 ^[Top](#top)
 107
 108 Add your source code files like the following sample in the `Makefile.inc`
 109
 110 ```
 111 # WITH_STANDALONE_LF_SKELETON
 112 ifneq (,$(findstring WITH_STANDALONE_LF_SKELETON,$(APP_CFLAGS)))
 113     SRC_STANDALONE = lf_skeleton.c
 114 endif
 115
 116 # WITH_STANDALONE_LF_FOO
 117 ifneq (,$(findstring WITH_STANDALONE_LF_FOO,$(APP_CFLAGS)))
 118     SRC_STANDALONE = lf_foo.c
 119 endif
 120 ```
 121
 122 Please respect alphabetic order!
 123
 124 ## Adding identification string of your mode
 125 ^[Top](#top)
 126
 127 Do please add a identification string in a function called `ModInfo` inside your source code file.
 128 This will enable an easy way to detect on client side which standalone mode has been installed on the device.
 129
 130 ````
 131 void ModInfo(void) {
 132     DbpString("  LF good description of your mode - aka FooRun (your name)");
 133 }
 134 ````
 135
 136 ## Compiling your standalone mode
 137 ^[Top](#top)
 138
 139 Once all this is done, you and others can now easily compile different standalone modes by just selecting one of the standalone modes (list in `Makefile.hal` or ) , e.g.:
 140
 141 - rename  Makefile.platform.sample -> Makefile.platform
 142 - edit the "STANDALONE" row inside Makefile.platform.  You need to uncomment it and add your standalone mode name
 143
 144 Makefile.platform.sample
 145 ```
 146 # If you want to use it, copy this file as Makefile.platform and adjust it to your needs
 147 PLATFORM=PM3RDV4
 148 #PLATFORM_EXTRAS=BTADDON
 149 #STANDALONE=LF_SAMYRUN
 150 ```
 151  becomes
 152
 153  Makefile.platform
 154  ```
 155 # If you want to use it, copy this file as Makefile.platform and adjust it to your needs
 156 PLATFORM=PM3RDV4
 157 #PLATFORM_EXTRAS=BTADDON
 158 STANDALONE=LF_FOO
 159 ```
 160
 161 Remember only one can be selected at a time for now.
 162
 163 The final steps is to
 164 - force recompilation of all code.  ```make clean```
 165 - compile ```make -j```
 166 - flash your device
 167 - connect to your device
 168 - press button long time to trigger ledshow and enter your new standalone mode
 169 - if connected with usb / fpc ,  you can also see debug statements from your device in standalone mode. Useful for debugging :)
 170
 171 When compiling you will see a header showing what configurations your project compiled with.
 172 Make sure it says your standalone mode name.
 173
 174 ## Submitting your code
 175 ^[Top](#top)
 176
 177 Once you're ready to share your mode, please
 178
 179 * add a line in CHANGELOG.md
 180 * add your mode in the modes table in `doc/md/Use_of_Proxmark/4_Advanced-compilation-parameters.md`
 181 * add your mode in `tools/build_all_firmwares.sh` such that it reflects `armsrc/Standalone/Makefile.hal` list of firmwares to build.
 182
 183 Please respect alphabetic order of standalone modes everywhere!
 184
 185 Then submit your PR.
 186
 187 Once approved, add also your mode in https://github.com/RfidResearchGroup/proxmark3/wiki/Standalone-mode
 188
 189 Happy hacking!