doc/termux_notes.md

   1 # Proxmark 3 on Android
   2 <a id="top"></a>
   3
   4 ## Table of Contents
   5 - [Proxmark 3 on Android](#proxmark-3-on-android)
   6   - [Table of Contents](#table-of-contents)
   7   - [Requirements](#requirements)
   8   - [Notes](#notes)
   9   - [Setup](#setup)
  10     - [Setting up Termux](#setting-up-termux)
  11     - [Install Proxmark3 package which follows tagged releases](#install-proxmark3-package-which-follows-tagged-releases)
  12     - [Optional: Install Proxmark3 package which offers a more up to date version from git `master` branch](#optional-install-proxmark3-package-which-offers-a-more-up-to-date-version-from-git-master-branch)
  13     - [Optional: Building Proxmark3 client from source](#optional-building-proxmark3-client-from-source)
  14   - [PC-like method](#pc-like-method)
  15     - [Specific requirements](#specific-requirements)
  16     - [USB\_ACM](#usb_acm)
  17       - [Enable the driver](#enable-the-driver)
  18       - [Building the kernel](#building-the-kernel)
  19       - [Flashing the kernel](#flashing-the-kernel)
  20       - [Testing](#testing)
  21       - [Troubleshooting](#troubleshooting)
  22   - [TCP/UDP bridge method](#tcpudp-bridge-method)
  23     - [USB connection](#usb-connection)
  24       - [USB-UART Bridge Application for TCP to USB bridging](#usb-uart-bridge-application-for-tcp-to-usb-bridging)
  25       - [USB-UART Bridge Application for UDP to USB bridging](#usb-uart-bridge-application-for-udp-to-usb-bridging)
  26     - [Bluetooth connection](#bluetooth-connection)
  27       - [BT-UART Bridge Application for TCP to BT bridging](#bt-uart-bridge-application-for-tcp-to-bt-bridging)
  28     - [TCP connection](#tcp-connection)
  29     - [UDP connection](#udp-connection)
  30     - [Troubleshooting](#troubleshooting-1)
  31       - [BTADDON Missing in Firmware of PM3](#btaddon-missing-in-firmware-of-pm3)
  32   - [Compiling and Flashing a Proxmark3 Firmware from non-root Android](#compiling-and-flashing-a-proxmark3-firmware-from-non-root-android)
  33     - [Compiling the Proxmark3 Firmware](#compiling-the-proxmark3-firmware)
  34     - [Flashing the Proxmark3 Firmware](#flashing-the-proxmark3-firmware)
  35 ## Requirements
  36 ^[Top](#top)
  37
  38 - Android phone
  39 - [F-Droid](https://f-droid.org/)
  40 - [Termux](https://f-droid.org/en/packages/com.termux/)
  41 - [Proxmark3](https://www.proxmark.com/proxmark-3-hardware/proxmark-3-rdv4)
  42 - [Blueshark Standalone Module](https://www.proxmark.com/proxmark-news/proxmark3-blueshark-bluetooth-released) **(ONLY if using Bluetooth)**
  43 - [Proxmark with BTADDON compiled Firmware](https://github.com/RfidResearchGroup/proxmark3/blob/master/doc/md/Use_of_Proxmark/4_Advanced-compilation-parameters.md#platform_extras) **(ONLY if using Bluetooth)**
  44
  45
  46 ## Notes
  47 ^[Top](#top)
  48 From official Proxmark3 wiki:
  49  > In any case, you would need a USB-C to A or USB-OTG cable to connect Proxmark3 to your Android device. Some Android devices may not supply enough power (USB-OTG = 100mA), and need a USB Y-cable and external battery, otherwise they will get strange failures.
  50 ref : https://github.com/Proxmark/proxmark3/wiki/android
  51
  52 ## Setup
  53 ^[Top](#top)
  54
  55 ### Setting up Termux
  56 ^[Top](#top)
  57
  58 Use [F-Droid](https://f-droid.org/) to install [Termux](https://f-droid.org/en/packages/com.termux/) and start it.
  59
  60 It is recommended to use the F-Droid version of Termux as it will be the latest. The [Play Store version](https://play.google.com/store/apps/details?id=com.termux) is not maintained (as stated in the description: "Updates over Google Play [are] currently halted due to technical reasons").
  61
  62 ### Install Proxmark3 package which follows tagged releases
  63 ^[Top](#top)
  64
  65 Run the following commands:
  66 ```
  67 pkg install proxmark3
  68 ```
  69 ### Optional: Building Proxmark3 client from source
  70 ```
  71 pkg install make clang readline libc++ git binutils
  72 git clone https://github.com/RfidResearchGroup/proxmark3.git
  73 cd proxmark3
  74 make clean && make client
  75 ```
  76
  77 ## PC-like method
  78 ^[Top](#top)
  79
  80 ### Specific requirements
  81 ^[Top](#top)
  82
  83 - Kernel with one of:
  84     - USB_ACM driver
  85     - module loading enabled
  86     - published sources
  87 - Root
  88
  89 termux shell:
  90 ```
  91 pkg install tsu
  92 ```
  93
  94 ### USB_ACM
  95 ^[Top](#top)
  96
  97 You need the `USB_ACM` driver enabled and working to communicate with the Proxmark3. To see if it's working, run `tsudo ls /dev/tty*` and it should list `/dev/ttyACM0` (or similar). If you see this, congratulations, skip this step!
  98
  99 #### Enable the driver
 100 ^[Top](#top)
 101
 102 If  your kernel has module loading enabled, you should be able to build the module separately and load it on your system without any changes. Otherwise, grab your kernel sources and edit your build config to include `CONFIG_USB_ACM=y`. On the tested kernel, this was under: `android_kernel_oneplus_msm8998/arch/arm64/configs/omni_oneplus5_defconfig`
 103
 104 #### Building the kernel
 105 ^[Top](#top)
 106
 107 If using a custom kernel, refer to the build instructions provided by its maintainer. Otherwise, follow the standard Linux kernel build procedure
 108
 109 #### Flashing the kernel
 110 ^[Top](#top)
 111
 112 You can flash the kernel however it suits you. On the tested device, this was achieved using [TWRP](https://twrp.me/), the most popular custom recovery
 113
 114 #### Testing
 115 ^[Top](#top)
 116
 117 Open Termux and start the Proxmark3 client:
 118 ```
 119 tsudo proxmark3/client/proxmark3 /dev/ttyACM0
 120 ```
 121 Everything should work just like if it was your PC!
 122
 123 #### Troubleshooting
 124 ^[Top](#top)
 125
 126 - `dmesg | grep usb` - useful debug info
 127 - `/proc/config.gz` - contains your kernel's build configuration. Look for `CONFIG_USB_ACM`, which should be enabled
 128
 129 ## TCP/UDP bridge method
 130 ^[Top](#top)
 131
 132 Termux doesn't come with usb serial neither bluetooth serial drivers.
 133 However, it is fully integrated with phone's network, so we need to talk to the proxmark using serial to TCP/UDP sockets (carried out by other android apps).
 134
 135 ```
 136 |Client in Termux| <--TCP/UDP--> |Bridge App| <--USB/Bluetooth--> |Proxmark3|
 137 ```
 138
 139 ### USB connection
 140 ^[Top](#top)
 141
 142 #### USB-UART Bridge Application for TCP to USB bridging
 143 ^[Top](#top)
 144
 145 Install [this free TCPUART app](https://play.google.com/store/apps/details?id=com.hardcodedjoy.tcpuart) on the Play Store
 146
 147 The app lets you choose the baudrate. Default value (115 200 baud) is fine.
 148 Plug the PM3 in and click connect.
 149 Set the toggle in server mode and choose a random port not used by system (e.g. 4321) and start the server.
 150
 151 Alternatively, use the [paid version of the BT/USB/TCP Bridge app](https://play.google.com/store/apps/details?id=masar.bluetoothbridge.pro) which includes USB bridge as well.
 152
 153 In this app, select TCP server as 'Device A' and choose an unused port (e.g. 4321).
 154 Choose your registered PM3 device as 'Device B' -> 'Connect to USB device'.
 155 Ensure 'Retransmission' is set to 'both ways'.
 156 It is possible to record the config as autostart, cf 'Settings' -> 'Autostart setting'.
 157
 158 #### USB-UART Bridge Application for UDP to USB bridging
 159 ^[Top](#top)
 160
 161 Install [this free SerialPipe app](https://f-droid.org/packages/io.github.wh201906.serialpipe/) on [F-Droid](https://f-droid.org/).
 162 You can download the apk on this website without installing F-Droid.
 163
 164 The app lets you choose the baudrate. Default value (115 200 baud) is fine.
 165 Plug the PM3 in and click `Connect`.
 166 Choose a random port not used by system (e.g. 4321) and click `Start Server`.
 167
 168 Note: This app uses foreground service to keep the connection alive, so you can safely put it in the background without suspending the transmission. However, you will see a dummy notification in the status bar which is required for foreground service.
 169
 170 ### Bluetooth connection
 171 ^[Top](#top)
 172
 173 #### BT-UART Bridge Application for TCP to BT bridging
 174 ^[Top](#top)
 175
 176 Install [this free app](https://play.google.com/store/apps/details?id=masar.bb) or [the paid version](https://play.google.com/store/apps/details?id=masar.bluetoothbridge.pro) (which includes usb bridge)
 177
 178 You need to pair the proxmark3 in the Android settings.
 179 In the app, select TCP server as 'Device A' and choose an unused port (e.g. 4321).
 180 Choose your registered PM3 device as 'Device B' -> 'Connect to classic Bluetooth device'.
 181 Ensure 'Retransmission' is set to 'both ways'.
 182 It is possible to record the config as autostart, cf 'Settings' -> 'Autostart setting'.
 183
 184 ### TCP connection
 185 ^[Top](#top)
 186
 187 Start a new session, then:
 188 ```
 189 proxmark3 tcp:localhost:<chosenPort>
 190 ```
 191 Alternatively, if you have made the client in the git repo:
 192 ```
 193 ./client/proxmark3 tcp:localhost:<chosenPort>
 194 ```
 195 If the last colon and the chosen port are missing, the client will use `18888` as the default port.
 196
 197 ### UDP connection
 198 ^[Top](#top)
 199
 200 Start a new session, then:
 201 ```
 202 proxmark3 udp:localhost:<chosenPort>
 203 ```
 204 Alternatively, if you have made the client in the git repo:
 205 ```
 206 ./client/proxmark3 udp:localhost:<chosenPort>
 207 ```
 208 If the last colon and the chosen port are missing, the client will use `18888` as the default port.
 209
 210 You can also specify the outbound port for UDP connections, which might be required for some UDP to USB/BT bridge app as the target port of it.
 211 The format is
 212 ```
 213 proxmark3 udp:localhost:<chosenPort>,bind=:<outboundPort>
 214 ```
 215 Some examples:
 216 ```
 217 # The bridge app listens on Port 12345, and the client listens on Port 12355
 218 proxmark3 udp:localhost:12345,bind=:12355
 219
 220 # 127.0.0.1 is also a valid local address
 221 proxmark3 udp:127.0.0.1:12345,bind=:12355
 222
 223 # The bridge app listens on the default port 18888, and the client listens on Port 12355
 224 proxmark3 udp:127.0.0.1,bind=:12355
 225
 226 # OutboundPort is randomly picked by the system, which requires the "UDP server" mode for the bridge app
 227 proxmark3 udp:localhost:12345
 228 ```
 229
 230
 231 ### Troubleshooting
 232 ^[Top](#top)
 233
 234 #### BTADDON Missing in Firmware of PM3
 235 ^[Top](#top)
 236
 237 1. Phone and pm3 are connected, blue led is on and *not* blinking
 238 2. BTUART Tool TCP Server at Port 4321
 239 3. Using proxmark3 in termux shows the following error message:
 240 ```
 241 $ proxmark3 tcp:localhost:4321
 242
 243 [=] Session log /data/data/com.termux/files/home/.suroot /.proxmark3/log_20210519.txt
 244
 245 [=] Loading Preferences...
 246
 247 [+] loaded from JSON file /data/data/com.termux/files/ho me/.suroot/.proxmark3/preferences.json
 248
 249 Using UART port tcp:localhost:4321
 250
 251 [!!] ERROR: cannot communicate with the Proxmark3
 252 ```
 253 Solution:
 254
 255 Make sure you have installed a firmware with BTADDON compiled.
 256 See: https://github.com/RfidResearchGroup/proxmark3/blob/master/doc/md/Use_of_Proxmark/4_Advanced-compilation-parameters.md#platform_extras
 257
 258 ## Compiling and Flashing a Proxmark3 Firmware from non-root Android
 259
 260 READ ME:
 261 * If you can compile and flash your device from a PC, do it! It's probably much confortable than following this method.
 262 * Flashing is possible only via USB-UART, *not* via BT-UART
 263 * Avoid flashing the Bootloader from non-root Android as the connection is probably less stable than with pure USB and you don't want to brick your device...
 264
 265 ### Compiling the Proxmark3 Firmware
 266
 267 Assuming we're using the Github repo sources as explained above.
 268
 269 ```
 270 pkg install make clang readline libc++ git binutils
 271 cd
 272 git clone https://github.com/RfidResearchGroup/proxmark3.git
 273 cd proxmark3
 274 make clean && make -j client
 275 ```
 276
 277 Termux doesn't have the ARM cross-compiler, so we'll install a Debian within Termux.
 278
 279 ```
 280 $ pkg install proot-distro
 281 $ proot-distro install debian
 282 $ proot-distro login debian --termux-home
 283 ```
 284 At this point we should be on a Debian root prompt in the user directory. We install only the requirements to compile the Proxmark3 firmware.
 285 ```
 286 # apt-get update
 287 # apt-get install -y --no-install-recommends make gcc g++ libc6-dev gcc-arm-none-eabi libnewlib-dev
 288 # cd proxmark3
 289 # make -j fullimage
 290 # exit
 291 ```
 292 At this point we're back to the Termux prompt.
 293
 294 ### Flashing the Proxmark3 Firmware
 295
 296 Plug the Proxmark3 while pressing the button, to enter into bootloader mode manually.
 297
 298 Activate the USB-UART to TCP Bridge with one of the applications as explained above.
 299
 300 ```
 301 cd proxmark3
 302 ./client/proxmark3 tcp:localhost:<chosenPort> --flash --image armsrc/obj/fullimage.elf
 303 ```
 304 Once the Proxmark3 has rebooted, reconnect it to the bridge in the app.
 305 The freshly flashed device is now ready to be used.
 306
 307 ```
 308 ./client/proxmark3 tcp:localhost:<chosenPort>
 309 ```