doc/termux_notes.md

   1 <a id="top"></a>
   2 # Proxmark 3 on Android
   3 ## Table of Contents
   4   * [ Requirements ](#requirements)
   5   * [ Notes ](#notes)
   6   * [ Tested setups ](#tested-setups)
   7     * OnePlus 5 (arm64, USB-C)
   8     * Nexus 5X (arm64, USB-C)
   9     * Xiaomi Mi Mix 2S (arm64, USB-C)
  10     * OnePlus 5T (arm64, USB-C)
  11     * Samsung Galaxy Tab S2 (arm64, MicroUSB)
  12   * [ Setup ](#setup)
  13     * [ Setting up Termux ](#setting-up-termux)
  14     * [ Install Proxmark3 package ](#install-proxmark3-package)
  15   * [ PC-like method ](#pc-like-method)
  16     * [ Specific requirements ](#specific-requirements)
  17     * [ USB_ACM ](#usb_acm)
  18     * [ Enable the driver ](#enable-the-driver)
  19     * [ Building the kernel ](#building-the-kernel)
  20     * [ Flashing the kernel ](#flashing-the-kernel)
  21     * [ Testing ](#testing)
  22     * [ Troubleshooting ](#troubleshooting)
  23   * [ TCP bridge method ](#tcp-bridge-method)
  24     * [ USB connection ](#usb-connection)
  25     * [ USB-UART bridge application ](#usb-uart-bridge-application)
  26     * [ Setting up usb socket ](#setting-up-usb-socket)
  27     * [ Bluetooth connection ](#bluetooth-connection)
  28     * [ BT-UART bridge application ](#bt-uart-bridge-application)
  29     * [ Setting up bt socket ](#setting-up-bt-socket)
  30     * [ Termux connection ](#termux-connection)
  31
  32 ## Requirements
  33 ^[Top](#top)
  34
  35 - Android phone
  36 - [Termux](https://play.google.com/store/apps/details?id=com.termux)
  37 - Proxmark3 RDV4 (https://www.proxmark.com/proxmark-3-hardware/proxmark-3-rdv4)
  38 - Blueshark Standalone Module (Bluetooth ONLY) (https://www.proxmark.com/proxmark-news/proxmark3-blueshark-bluetooth-released)
  39 - Proxmark with BTADDON compiled Firmware (Bluetooth ONLY) (https://github.com/RfidResearchGroup/proxmark3/blob/master/doc/md/Use_of_Proxmark/4_Advanced-compilation-parameters.md#platform_extras)
  40
  41
  42 ## Notes
  43 ^[Top](#top)
  44 From official Proxmark3 wiki:
  45  > 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.
  46 ref : https://github.com/Proxmark/proxmark3/wiki/android
  47
  48 ## Tested setups
  49 ^[Top](#top)
  50
  51 - OnePlus 5 (arm64, USB-C)
  52
  53   - [OmniROM (Android 9)](https://www.omnirom.org/)
  54   - [OmniROM kernel](https://www.omnirom.org/)
  55   - [Magisk 19.3](https://github.com/topjohnwu/Magisk/)
  56
  57 - Nexus 5X (arm64, USB-C)
  58
  59   - [LineageOS (Android 8.1)](https://download.lineageos.org/)
  60   - [LineageOS kernel](https://download.lineageos.org/)
  61   - [Magisk 19.3](https://github.com/topjohnwu/Magisk/)
  62
  63 - Xiaomi Mi Mix 2S (arm64, USB-C)
  64   - [LineageOS (Android 9.0)](https://download.lineageos.org/)
  65   - [Magisk 20.3](https://github.com/topjohnwu/Magisk/)
  66
  67 - OnePlus 5T (arm64, USB-C)
  68   - [LineageOS (Android 9.0)](https://download.lineageos.org/)
  69   - [Franko Kernel](https://franco-lnx.net/)
  70   - [Magisk 20.3](https://github.com/topjohnwu/Magisk/)
  71
  72 - Samsung Galaxy Tab S2 (arm64, MicroUSB)
  73   - [LineageOS (Android 9.0)](https://download.lineageos.org/)
  74   - [LineageOS kernel](https://download.lineageos.org/)
  75   - [Magisk 20.3](https://github.com/topjohnwu/Magisk/)
  76
  77
  78
  79 ## Setup
  80 ^[Top](#top)
  81
  82 ### Setting up Termux
  83 ^[Top](#top)
  84
  85 Install [Termux](https://play.google.com/store/apps/details?id=com.termux) and start it
  86
  87
  88 ### Install Proxmark3 package which follows tagged releases
  89 ^[Top](#top)
  90
  91 Run the following commands:
  92 ```
  93 pkg install proxmark3
  94 ```
  95 ### Install Proxmark3 package which offers a more up to date version from git `master` branch
  96 Run the following commands:
  97 ```
  98 pkg install proxmark3-git
  99 ```
 100 ### Optional: Building Proxmark3 client from source
 101 ```
 102 pkg install make clang clang++ readline libc++ git
 103 git clone https://github.com/RfidResearchGroup/proxmark3.git
 104 cd proxmark
 105 make clean && make client
 106 ```
 107
 108 ## PC-like method
 109 ^[Top](#top)
 110
 111 ### Specific requirements
 112 ^[Top](#top)
 113
 114 - Kernel with one of:
 115     - USB_ACM driver
 116     - module loading enabled
 117     - published sources
 118 - Root
 119
 120 termux shell:
 121 ```
 122 pkg install tsu
 123 ```
 124
 125 ### USB_ACM
 126 ^[Top](#top)
 127
 128 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!
 129
 130 #### Enable the driver
 131 ^[Top](#top)
 132
 133 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`
 134
 135 #### Building the kernel
 136 ^[Top](#top)
 137
 138 If using a custom kernel, refer to the build instructions provided by its maintainer. Otherwise, follow the standard Linux kernel build procedure
 139
 140 #### Flashing the kernel
 141 ^[Top](#top)
 142
 143 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
 144
 145 ### Testing
 146 ^[Top](#top)
 147
 148 Open Termux and start the Proxmark3 client:
 149 ```
 150 tsudo proxmark3/client/proxmark3 /dev/ttyACM0
 151 ```
 152 Everything should work just like if it was your PC!
 153
 154 ### Troubleshooting
 155 ^[Top](#top)
 156
 157 - `dmesg | grep usb` - useful debug info
 158 - `/proc/config.gz` - contains your kernel's build configuration. Look for `CONFIG_USB_ACM`, which should be enabled
 159
 160 ## TCP bridge method
 161 ^[Top](#top)
 162
 163 Termux doesn't come with usb serial neither bluetooth serial drivers.
 164 However, it is fully integrated with phone's network, so we need to talk to the proxmark using serial to tcp sockets (carried out by android apps).
 165
 166 ### USB connection
 167 ^[Top](#top)
 168
 169 ### USB-UART Bridge Application
 170 ^[Top](#top)
 171
 172 Install [this free app](https://play.google.com/store/apps/details?id=com.hardcodedjoy.tcpuart) on the Play Store
 173
 174 ### Setting up usb socket
 175 ^[Top](#top)
 176
 177 The app lets you choose the baudrate. Default value (115 200 baud) is fine.
 178 Plug the PM3 in and click connect.
 179 Set the toggle in server mode and choose a random port not used by system (e.g. 4321) and start the server.
 180
 181 ### Bluetooth connection
 182 ^[Top](#top)
 183
 184 ### BT-UART Bridge Application
 185 ^[Top](#top)
 186
 187 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)
 188
 189 ### Setting up bt socket
 190 ^[Top](#top)
 191
 192 You need to pair the proxmark3 in the Android settings.
 193 In the app choose your registered PM3 device as 'device A'.
 194 Select TCP server as 'Device B' and choose an unused port (e.g. 4321).
 195 Ensure 'Retransmission' is set to 'both ways'.
 196
 197 ### Termux connection
 198 ^[Top](#top)
 199
 200 Start a new session, then:
 201 ```
 202 proxmark3 tcp:localhost:<chosenPort>
 203 ```
 204 Alternatively, if you have made the client in the git repo:
 205 ```
 206 ./client/proxmark3 tcp:localhost:<chosenPort>
 207 ```
 208 ### Troubleshooting
 209 ^[Top](#top)
 210
 211 #### BTADDON Missing in Firmware of PM3
 212
 213 1. Phone and pm3 are connected, blue led is on and *not* blinking
 214 2. BTUART Tool TCP Server at Port 4321
 215 3. Using proxmark3 in termux shows the following error message:
 216 ```
 217 $ proxmark3 tcp:localhost:4321
 218
 219 [=] Session log /data/data/com.termux/files/home/.suroot /.proxmark3/log_20210519.txt
 220
 221 [=] Loading Preferences...
 222
 223 [+] loaded from JSON file /data/data/com.termux/files/ho me/.suroot/.proxmark3/preferences.json
 224
 225 Using UART port tcp:localhost:4321
 226
 227 [!!] ERROR: cannot communicate with the Proxmark
 228 ```
 229 Solution:
 230
 231 Make sure you have installed a firmware with BTADDON compiled.
 232 See: https://github.com/RfidResearchGroup/proxmark3/blob/master/doc/md/Use_of_Proxmark/4_Advanced-compilation-parameters.md#platform_extras
 233
 234 ENJOY !