Proxmark3 Setup

ATLAS connects to your Proxmark3 RDV4 via Bluetooth Classic. No cables. No laptop.

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.

---

Requirements

• Proxmark3 RDV4 (other versions not supported)
• Iceman firmware (RfidResearchGroup/proxmark3)
• Blueshark Bluetooth module (must be installed)
• Charged battery or USB power

---

Initial Pairing

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 in ATLAS

From Home Screen

1. Tap the PM3 connection card on the home screen
2. Your paired Proxmark3 appears in the device list
3. Tap to connect

From Bluetooth Settings

1. Go to Settings → Bluetooth Settings
2. Under Proxmark3 RDV4 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 → Bluetooth
• Keep sniff durations shorter when possible
• Ensure the PM3 battery is fully charged (low battery worsens this issue)

---

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 [email protected].

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.

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.