Proxmark3 Setup

ATLAS connects to a Proxmark3 over Bluetooth Classic (RDV4 with Blueshark module) or directly over USB-OTG (RDV4 and Easy). The detected variant is shown on the home connection card.

Battery Warning: Always use the Proxmark3 on a full charge in operational environments. As the battery depletes, RF capabilities degrade significantly. Low battery will cause connectivity issues and failure to perform RF-related tasks.

---

Supported Hardware

Variant	Bluetooth	USB	Notes
Proxmark3 RDV4	Yes (with Blueshark)	Yes	Recommended. Battery + Bluetooth.
Proxmark3 Easy	No	Yes	USB-OTG only. Lower cost; no RDV4 hardware extras.

All variants require Iceman firmware (RfidResearchGroup/proxmark3). The vanilla proxmark.org firmware is not compatible.

For Bluetooth, you also need:

• Blueshark Bluetooth module (RDV4 only)
• Charged battery or USB power

For USB, you need:

• A USB-OTG-capable Android device
• A data USB cable (charging-only cables will not enumerate)

---

Initial Pairing (Bluetooth)

Because the Proxmark3 uses Bluetooth Classic (not BLE), you must first pair it in your Android Bluetooth settings before ATLAS can connect.

1. Power On the Proxmark3

Insert the battery or connect USB power. The Blueshark module LED should start blinking.

2. Pair in Android Bluetooth Settings

1. Open Settings → Connected devices → Pair new device
2. Scan for available Bluetooth devices
3. Look for PM3_RDV4.0 (the default Blueshark name)
4. Tap to pair and enter PIN: 1234
5. Confirm pairing

Note: After pairing, the device appears in your paired devices list but shows “Not connected”. This is expected for Bluetooth Classic. ATLAS handles the actual connection.

---

Connecting over USB

USB-OTG support covers the Proxmark3 RDV4 and Easy.

1. Cable In

Plug your Proxmark3 into the Android device with a data USB cable. On most modern Android phones and tablets a direct USB-C-to-USB-C cable works; older phones may need a USB-OTG adapter.

The Proxmark3 LED and the Android USB icon should both indicate the device is recognized.

2. Grant USB Permission (First Time Only)

The first time you cable a given device, Android asks whether to allow ATLAS access. Tick “Always open ATLAS when this USB device is connected” and tap OK. Subsequent attaches are silent - Android remembers the choice.

3. Connect in ATLAS

When your Transport Policy allows USB (the default Auto does), ATLAS auto-connects to the Proxmark3 on cable attach. No taps required. The home connection card switches to the USB transport icon and shows the detected variant (e.g. PM3 RDV4, PM3 Easy).

To pick a specific transport policy, go to Settings → Connection Settings → PM3 Transport Policy and choose Auto, USB only, or Bluetooth only. The setting persists across launches.

---

Connecting in ATLAS

From Home Screen

1. Tap the PM3 connection card on the home screen
2. Your paired Proxmark3 (Bluetooth) or attached Proxmark3 (USB) appears in the device list
3. Tap to connect

From Connection Settings

1. Go to Settings → Connection Settings
2. Under Proxmark3 Devices, tap CONNECT
3. Select your device from the scanner

The connection card turns green when connected.

---

Paired Devices vs Saved Devices

ATLAS shows two categories in Bluetooth Settings:

Category	Source	Description
Paired Devices	Android Bluetooth Settings	Devices you’ve paired with your phone.
Saved Devices	ATLAS Internal	Devices you’ve saved in ATLAS with custom names. Stored locally for quick reconnection.

Saving a Device

1. Connect to a paired device
2. Long-press or tap save icon
3. Enter a custom name (e.g., “Kit #1”, “Lab Reader”)
4. The device moves from Paired to Saved

Saved devices appear first and can be renamed or deleted within ATLAS.

---

Troubleshooting

Can’t find PM3_RDV4.0 in Bluetooth scan?

• Ensure the Blueshark module is properly seated
• Toggle the Blueshark Bluetooth power switch off and back on
• Ensure Bluetooth is enabled on your Android device
• The Blueshark LED should be blinking when discoverable

Device paired but ATLAS can’t connect?

• Toggle the Blueshark Bluetooth power switch to restart
• Make sure the Proxmark3 isn’t connected to another device
• Try forgetting the device in Android settings and re-pairing

Connection drops frequently?

• Stay within 10 meters of the Proxmark3
• Avoid interference from other Bluetooth devices
• Check battery level

Commands fail or timeout?

• Disconnect and reconnect in ATLAS
• Power cycle the Proxmark3

Bluetooth disconnects during sniff operations?

This is a known hardware limitation. The Proxmark3’s Blueshark Bluetooth module can become unresponsive during intensive RF operations (like sniffing). When the device is actively listening for RF signals, it may not respond to Bluetooth keepalive pings in time, causing a connection timeout.

ATLAS will automatically attempt to reconnect after detecting this condition. If auto-reconnect fails:

• Press the PM3 button to stop the sniff before timeout
• Reconnect manually via Settings → Connection Settings
• Keep sniff durations shorter when possible
• Ensure the PM3 battery is fully charged (low battery worsens this issue)

USB

Cable plugs in but ATLAS doesn’t pick up the device?

• Confirm the cable is a data cable, not charge-only. Many bundled charging cables omit the data lines.
• Try a different USB-OTG adapter if you’re using one.
• Check that Connection Settings → PM3 Transport Policy is not set to Bluetooth only.

PM3 Easy wedges the phone’s USB stack on cable yank?

Some inexpensive PM3 boards trigger the Pixel USB host controller to tear down aggressively when the cable is unplugged mid-session. ATLAS issues a clean release on Disconnect, which avoids the wedge in nearly all cases.

To minimize risk:

• Tap Disconnect in ATLAS before pulling the cable.
• If a subsequent USB device fails to enumerate, plug another USB-C device in and out once to nudge the host controller back, or reboot the phone to fully reset it.

This is hardware behavior in the cheap PM3 boards combined with the Pixel xHCI driver - it is not specific to ATLAS, and it does not occur with the RDV4.

---

Flashing Iceman Firmware

ATLAS requires the Iceman firmware (RfidResearchGroup/proxmark3). The official Proxmark.org firmware is not compatible.

Pre-Flashed Options: If you’re uncomfortable flashing bootloaders or need devices ready to go, pre-assembled and pre-flashed Proxmark3 units are available for volume purchase. Contact sales@mwgroup.io.

Never flash in a nested environment. WSL2 does not support nested virtual machines. VirtualBox or VMware running inside another hypervisor will fail. Flash from bare metal OS only (physical hardware with direct USB access).

Critical Flashing Requirements

Requirement	Why It Matters
Use the original USB cable	Third-party cables often lack adequate data lines or power delivery, causing flash failures
Bare metal OS	Nested VMs (VM inside VM) cannot reliably pass USB to the bootloader
Full battery charge	Low battery can cause incomplete flash and potential brick
Read the Iceman docs	Always check the official documentation for updates

Device Detection Issues (Stock Firmware)

If you have a new Proxmark3 with stock/factory firmware and the Iceman bootloader flasher doesn’t detect it:

1. Unplug the Proxmark3
2. Press and hold the physical button on the Proxmark3
3. While holding the button, plug the USB cable into your computer
4. Continue holding for 2-3 seconds after plugging in
5. The device should now be detected in bootloader mode

This forces the device into bootloader mode, bypassing the incompatible stock firmware.

Installation Methods

Option 1: Doppelgänger Assistant (Recommended)

The Doppelgänger Assistant provides automated installers that build and flash Iceman firmware with correct platform settings.

macOS:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/tweathers-sec/doppelganger_assistant/main/installers/doppelganger_install_macos.sh)"

Linux:

curl -sSL https://raw.githubusercontent.com/tweathers-sec/doppelganger_assistant/main/installers/doppelganger_install_linux.sh | sudo bash

Windows (WSL):

irm https://raw.githubusercontent.com/tweathers-sec/doppelganger_assistant/main/installers/doppelganger_install_windows.ps1 | iex

The installer prompts for your device type (RDV4, RDV4+Blueshark, Easy 512KB) and configures everything automatically.

Option 2: Manual Build with Bluetooth

If building manually for an RDV4 with Blueshark Bluetooth module, first install dependencies for your platform:

macOS Dependencies (Homebrew):

brew install readline qt5 pkgconfig coreutils gnu-getopt libusb

Linux Dependencies (Debian/Ubuntu/Kali):

sudo apt install --no-install-recommends git ca-certificates build-essential pkg-config \
  libreadline-dev gcc-arm-none-eabi libnewlib-dev qtbase5-dev \
  libbz2-dev liblz4-dev libbluetooth-dev libpython3-dev libssl-dev libgd-dev

Then clone, configure, and flash:

# Clone the Iceman repository
git clone https://github.com/RfidResearchGroup/proxmark3.git
cd proxmark3

# Create platform config with Bluetooth enabled (one-liner)
echo -e "PLATFORM=PM3RDV4\nPLATFORM_EXTRAS=BTADDON\nINSTALLSUDO=sudo" > Makefile.platform

# Build and flash
make clean && make -j
./pm3-flash-all

Makefile.platform options:

Device	Configuration
RDV4 + Blueshark	PLATFORM=PM3RDV4
Blueshark	PLATFORM_EXTRAS=BTADDON
Install w/sudo	INSTALLSUDO=sudo

Option 3: Homebrew (macOS)

Install the latest development version directly via Homebrew with Blueshark support:

# Tap the RFID Research Group repository
brew tap rfidresearchgroup/proxmark3

# Remove any existing stable installation
brew remove proxmark3

# Install HEAD (latest code) with Blueshark Bluetooth support
brew install --HEAD --with-blueshark proxmark3

# Flash using the Homebrew-installed binaries
cd /opt/homebrew/Cellar/proxmark3/HEAD-*/bin
./pm3-flash-fullimage

Why --HEAD? The --HEAD flag builds from the latest source code in the repository rather than a tagged stable release. This ensures you have the most recent features, bug fixes, and ATLAS compatibility improvements.

Option 4: Pre-Compiled Build (Windows)

If you’re on Windows and prefer not to compile from source, proxmarkbuilds.org provides pre-compiled Iceman firmware builds ready to flash. No ProxSpace or build toolchain required.

1. Download the latest RDV4 + Blueshark build from proxmarkbuilds.org
2. Extract the .7z archive to a path with no spaces (e.g., C:\proxmark3)
3. Open Device Manager and note the COM port assigned to your Proxmark3 (listed under Ports)
4. Run FLASH - All.bat from the extracted folder to flash both the bootloader and firmware
5. Run pm3.bat to launch the client

Drivers: Windows 10/11 typically detects the device automatically. On older versions, point Device Manager to the extracted folder when prompted for drivers.

Post-Flash Verification

After flashing, verify the firmware:

pm3 -c "hw version"

You should see Iceman/master/v4.20728-312-g7522652ad-suspect in the version output. If connected via Bluetooth, the device is ready for ATLAS.

Wrong Version? If you see Iceman/master/v4.20728 2025-09-11 in the output, you’re running the stable release which has known connectivity issues with ATLAS.