NRSuite

NRSuite turns a phone and a cheap ESP32 board into a portable Wi-Fi/BLE security research platform - no laptop required.

Install the Android app, flash an ESP32 over USB-OTG with NRSuite firmware, and the app drives it as a combined offense/defense toolkit: Wi-Fi recon and attack modules, passive threat detection, BLE tooling, IR, BadUSB/HID, and more - all from a single pocketable setup.

Authorized use only. NRSuite is for security research and testing on networks and devices you own or are explicitly authorized to test. See LEGAL.md.

---

Quick Start

# 1. Clone and build the app
git clone https://github.com/7wp81x/nrsuite-android.git
cd nrsuite-android
./gradlew assembleDebug

# 2. Flash an ESP32 with NRSuite firmware (in-app flasher, or see nrsuite-firmware)
# 3. Connect ESP32 <-> phone via USB-OTG, open the app, grant USB permission

Prefer not to build from source? Grab the latest signed prebuilt APK instead - see Installation.

---

Community

Join the NRSuite Discord server for setup help, build showcases, release news, and development discussion:

Use #support for help, #showcase for builds, and #github for repo/code discussion.

---

Table of Contents

• Quick Start
• Community
• Features
• Usage Guide
• Installation
• Getting Started
• Requirements
• Building from Source
• Wire Protocol
• Screenshots
• Hardware Images
• Contributing
• Related Repos
• Versioning
• Security
• License
• Disclaimer

---

Features

Wireless

• Wi-Fi Scan - AP/channel discovery with SSID, BSSID, RSSI, security, and WPS flags; AUTO 2.4/5 GHz and regulatory-country channel filtering on C5-capable firmware
• Beacon Spam - broadcast custom or hidden SSIDs
• Deauthentication - finite burst or stoppable duration-based loop mode, with mutually exclusive count/duration controls
• Evil Twin - rogue AP with captive portal
• Captive Portal - custom HTML credential capture
• Portal authoring guide - Captive Portal / Evil Twin HTML authoring
• Packet Sniffer - monitor-mode capture with PCAP export; per-module Auto/2.4/5 GHz hopping, target-channel-aware fixed capture, and retrying deauth assist that starts after the sniffer
• Hidden AP Revealer - passive hidden AP detection, probe-request SSID candidates, and association-based SSID resolution
• PMKID Capture

Detection

• Deauth Detector - passive deauth/disassoc monitoring with BSSID, client, RSSI, and reason filters; async alerts; live logs
• Rogue AP Detector - compares nearby visible APs and OUI rules to flag duplicate SSIDs, security downgrades, and suspected impersonation
• Client/Presence Detector - passive probe/assoc/reassoc/auth monitoring with optional active deauth-trigger mode
• Tracker Detector - Find My / AirTag-style advertisement detection with repeated sightings
• Karma/MANA Detector
• Unauthorized RFID Reader Detector
• Jam Detector (detection only - see FEATURES.md)

IR

• IR Remotes - Flipper .ir import, Flipper-IRDB download/update, local library, favorites, search, categories, brands, and loop mode
• IR Receiver - ESP32 RMT raw capture, pending capture naming, replay, learned-button storage, and .ir export
• IR Finder - category/brand targeting, common-button selection, auto-step, loop, pause/resume, previous/next, manual send, and saved results
• IR Jammer - supervised timed/unlimited modes, authorization confirmation, wake-lock, and automatic stop
• IR Configuration - category-level Phone/ESP32/Auto backend, ESP32 TX/RX GPIO selection, loop interval, and IRDB management
• Phone and ESP32 IR TX - shared encoded signal path with dynamic backend selection

BLE

• BLE Scanner - device discovery with names, RSSI, manufacturer data, service UUIDs, service badges, and module-owned scan lifecycle
• BLE GATT Profile - read-only service/characteristic enumeration with integrated BLE target scanner
• BLE HID - Bluetooth LE keyboard/mouse HID and DuckyScript payloads
• FastPair Model Identification - map FastPair model IDs to known device names/types

Sensors

• mmWave Radar (LD2450) - 120° fan with green blurred dots, heartbeat scan/sleep mode, position-based dot persistence, configurable dot cap, scan wave animation, max-range display control, and no-data/parse-error/zero-target states
• Zone alerts / mesh broadcast - disabled until firmware zone commands or the mesh branch is integrated

HID / BadUSB

• Ducky Script Editor - create, import, and export DuckyScript payloads
• BadUSB - HID injection via USB
• PIN Bruteforce - Supervised native-HID range/wordlist tester; one-shot boot-arm like BadUSB; max-attempt cap, progress/ETA, configurable typing/start delays, saved sessions, compact attempt feed
• BLE HID PIN Bruteforce - Hidden/experimental BLE-HID tester retained for future unlocked-host and mesh HID work; lock-screen use is unsupported
• Multi-device USB sessions - connect and use multiple USB serial devices independently, with per-device permissions and connection state
• BadUSB device picker - choose the target USB device without interrupting other connections

Credentials

• WPA Handshake Capture/Crack - capture and offline dictionary cracking
• Nrugochi - Pwnagotchi-style channel-density RECON/INTERACT loop, multi-AP authorized deauth with frame telemetry, all-EAPOL/all-beacon capture, per-BSSID HS_<BSSID>.pcap output, mood UI, and today/total stats
• Credential Manager - local storage and management of captured credentials

Storage, Firmware & Tools

• Mass Storage - list/delete files on ESP32 flash and enter USB MSC mode
• ESP32 Flasher - flash merged NRSuite firmware directly from the app over USB; supports ESP32, S2, S3, C3, and C5 images with target-chip validation
• Serial Monitor - raw USB serial monitor with reliable clipboard copy, bounded log retention, and visible save/export feedback
• BSSID Geolocation - offline OUI/vendor lookup plus approximate Wi-Fi access-point location, persistent lookup history, and an embedded Leaflet map with external Google Maps fallback
• Persistent firmware device ID - NRxxxxxxx NVS ID shown in the app so devices remain identifiable across reconnects

Visible but not yet functional

The following modules appear in the app as disabled ("Unavailable") placeholder cards, reserving their place in the catalog ahead of hardware support:

• RF (Sub-GHz)
• RFID/NFC - PN532 code is retained but hidden/disabled pending reliable hardware validation

Planned

For a full status and roadmap breakdown across every phase, see FEATURES.md.

Mesh (ESP-NOW) - Experimental

Mesh code from the merged mesh branches is present but remains experimental and is not part of the non-mesh release acceptance matrix.

• Shared Group Key Provisioning
• Dynamic Master Election
• Client Idle/Standby Mode
• Encrypted ESP-NOW Transport
• Activation Handshake
• Session Locking
• Heartbeat/Auto-Timeout
• Peer snapshots, chip metadata, RSSI, and online state
• Configurable mesh channel 1..13 and recovery hopping
• Master-requested channel switching with ACK/commit flow
• Distributed node-health sensor reporting
• Distributed same-channel Deauth Detector reporting - hardware-validated on S3 + S2
• Fixed/hop detector windows final hardware validation
• Same-frame deauth correlation
• Distributed Rogue AP evidence
• Triangulation / RSSI locator

Mesh Chat - Planned

• ESP-NOW Chat Transport
• Multi-hop Relay
• Store-and-Forward
• Message Fragmentation
• Sender Aliases
• Quick/Canned Messages
• Chat/Sensor Traffic Prioritization

Remote Camera Node - Planned

• Live Feed Streaming
• Snapshot-on-Trigger
• Motion Detection
• Deep-sleep/Low-power Mode
• SD Card Buffering
• Mesh Manager Integration

Peripheral Radios - Planned

• Sub-GHz (CC1101) - Scanner, Capture/Replay, Protocol Decoder
• nRF24 - RC/Device Scanner, MouseJack-style analysis, Packet Sniffer
• RFID/NFC - Read, Emulate, Write/Clone, Access Control Analyzer
• LoRa - long-range relay node support

---

Usage Guide

See docs/USAGE-GUIDE.md for:

• First connection and root-directory setup
• Navigation and category-level configuration
• WiFi Config, shared channel controls, and Packet Sniffer workflows
• IR Config, IR Remotes, Receiver, Finder, and Jammer usage
• Sensor Config and HLK-LD2450 UART wiring
• BLE/USB essentials, troubleshooting, and safety notes

The guide is intentionally general and is not tied to a single release version.

---

Installation

Option A - Prebuilt APK (recommended for beta)

1. Download the latest nrsuite-vX.X.X-beta.apk from Releases.
2. Verify the SHA256 checksum listed in the release notes before installing:

   # Linux / macOS
   sha256sum nrsuite-vX.X.X-beta.apk
   
   # Windows (PowerShell)
   certutil -hashfile nrsuite-vX.X.X-beta.apk SHA256

3. Enable Install from unknown sources on your device if needed - Settings → Security.
4. Install the APK.

Option B - Build from source

git clone https://github.com/7wp81x/nrsuite-android.git
cd nrsuite-android
./gradlew assembleDebug

Output: app/build/outputs/apk/debug/app-debug.apk

You can also open the project in Android Studio and sync Gradle - see Building from Source for prerequisites.

Flashing the ESP32

You also need an ESP32 dev board flashed with NRSuite firmware. Flash it directly from inside the app using the built-in flasher, or manually via PlatformIO - see nrsuite-firmware for supported boards and instructions.

---

Getting Started

1. Flash NRSuite firmware to your ESP32 - use the in-app flasher, or PlatformIO from nrsuite-firmware.
2. Connect your ESP32 to your phone via a USB-OTG cable.
3. Open NRSuite - the app auto-detects the connected device.
4. Grant USB host permission when prompted (one-time per device).
5. Select a module from the home screen and start testing.

---

Requirements

Android device

• Android 8.0 (API 26) or higher
• USB-OTG support (required - the app uses USB host mode to communicate with the ESP32)
• USB-OTG cable or adapter

Hardware

• Any ESP32 development board flashed with NRSuite firmware
• See nrsuite-firmware for supported boards and flashing instructions

---

Building from Source

Prerequisites

• Android Studio Ladybug or newer (latest stable recommended)
• JDK 11 (bundled with Android Studio)
• Android SDK with API 36 (compileSdk) and API 26 (minSdk) installed

Steps

git clone https://github.com/7wp81x/nrsuite-android.git
cd nrsuite-android
./gradlew assembleDebug

Signed release APKs are published by the maintainer. For testing your own changes, the debug build is sufficient.

Project Structure

app/src/main/java/com/swp81x/nrsuite/
  core/
    ble/               # BLE scan/profile/tracker models and scan limits
    credentials/       # Credential storage models and store
    defense/           # Rogue AP / client-presence / hidden-AP / deauth-alert models, OUI heuristics
    eapol/             # EAPOL frame parser (for WPA handshake capture)
    flasher/           # ESP32 in-app flasher (SLIP codec, USB serial transport)
    history/           # Session history entries
    log/               # Log entry model (Logs screen, live module logs)
    oui/               # Offline OUI/vendor database (BSSID Geolocation, defense modules)
    geo/               # Independent BSSID/WLOC client and persistent lookup history
    pcap/              # Pcap file reader and writer
    protocol/          # Frame codec and NrJson wire protocol (shared with firmware)
    session/           # Connection state and NrSession manager
    sniff/             # Sniff request model
    hid/               # PIN Bruteforce models/state
    storage/           # Mass storage models (ESP32 flash file browser)
    usb/               # USB serial transport, device catalog, NrTransport
    wifi/              # Pcap SSID parser
    wpa/               # WPA handshake parser, verifier, and cracker
  service/
    NrSuiteForegroundService.kt   # Foreground service keeping USB session alive
  ui/
    components/       # Reusable Compose components
    theme/            # Color, typography, theme
    NRSuiteApp.kt     # App entry point and module catalog
    NRSuiteContent.kt # Shell navigation, permission flow, screen dispatch
    HomeScreen.kt     # Dashboard, categories, module list
    LogsScreen.kt     # Logs and session history
    DeviceScreen.kt   # USB device selection and connection state
    SettingsScreen.kt # Settings and firmware flasher
    ModuleAvailability.kt # Shared "module unavailable on this board" banner/FAB gating
    RogueApScreen.kt / DeauthDetectorScreen.kt / ClientPresenceScreen.kt /
    HiddenApScreen.kt / TrackerDetectorScreen.kt   # Defense modules
    BleScannerScreen.kt / BleProfileScreen.kt / BleScreen.kt   # BLE recon + BLE HID
    BlePinBruteforceScreen.kt                                  # BLE HID PIN live controls
    MacLookupScreen.kt / SerialMonitorScreen.kt    # Tools / firmware utilities
    *Screen.kt        # Remaining feature module screens
  MainActivity.kt
  MainViewModel.kt               # Application-scoped controller
  MainViewModelUsb.kt            # USB discovery, permission, connection lifecycle
  MainViewModelFlasher.kt        # Firmware image selection and flashing
  MainViewModelWifi.kt           # Scan, deauth, beacon, sniff
  MainViewModelPortal.kt         # Captive Portal and Evil Twin
  MainViewModelBle.kt            # BLE HID
  MainViewModelBleScanner.kt     # BLE device discovery
  MainViewModelBleProfile.kt     # BLE GATT enumeration
  MainViewModelStorage.kt        # Mass storage, BadUSB, DuckyScript
  MainViewModelPinBruteforce.kt  # PIN Bruteforce HID session state
  MainViewModelBlePinBruteforce.kt # BLE HID PIN live session state
  MainViewModelCredentials.kt    # Credential sessions and WPA cracking
  MainViewModelDefense.kt        # Shared defense-module plumbing
  MainViewModelRogueAp.kt        # Rogue AP Detector
  MainViewModelHiddenAp.kt       # Hidden AP Revealer
  MainViewModelClientPresence.kt # Client Detector
  MainViewModelTracker.kt        # Tracker Detector
  MainViewModelOui.kt            # Vendor/OUI lookup
  MainViewModelBssidGeo.kt       # BSSID geolocation lookup
  MainViewModelSerialMonitor.kt  # Serial Monitor
  NrSuiteApplication.kt

---

Wire Protocol

NRSuite uses a custom framing protocol (FrameCodec / NrJson) over USB serial between the app and the ESP32 firmware. The protocol spec is versioned separately in nrsuite-protocol so the app and firmware can evolve independently without silent breaking changes.

If your contribution touches any app ↔ firmware communication, update the protocol spec first and reference the spec version in your PR.

---

Screenshots

Home	Modules	Logs

Device Manager	WiFi Scan	Packet Sniffer

Deauth Detector	Rogue AP Detector	BLE Scanner

BadUSB	Credential Manager	Firmware Flasher

More screenshots in ./screenshots/.

---

Hardware Images

USB hub + ESP32-S2	ESP32-S3 SuperMini

---

Contributing

See CONTRIBUTING.md for the full guide: branching model, PR process, testing expectations, and legal/ethical scope boundaries.

Short version:

• Open an issue before starting any non-trivial feature.
• Branch from develop, not main.
• One feature or fix per PR.
• Test on real hardware for anything touching USB serial, the flasher, or module screens.
• Jamming features (RF/Wi-Fi/BLE denial-of-service transmission) will not be merged - see CONTRIBUTING.md.

---

Related Repos

Repo	Contents
nrsuite-firmware	ESP32 firmware (PlatformIO / ESP-IDF)
nrsuite-protocol	Wire protocol specification

---

Versioning & Compatibility

App version	Firmware version	Protocol spec
v1.0.0-beta.3	v1.0.0-beta.3	v1.0 (non-mesh); mesh protocol 1.1 is experimental

This table is updated with each release. Always check compatibility before mixing app and firmware versions.

---

Security

If you find a vulnerability in NRSuite itself (for example, a flaw in the mesh encryption scheme, credential storage, or the USB flasher), please report it privately rather than opening a public issue. See SECURITY.md.

---

License

GNU General Public License v3.0 or later

NRSuite is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This license covers redistribution of the code. It does not authorize use of the tool against systems you do not own or lack explicit permission to test. See LEGAL.md and THIRD_PARTY_NOTICES.md.

---

Disclaimer

NRSuite is a tool for security research and authorized red-team operations, intended for legal and authorized security testing purposes only. Use of this software for any malicious or unauthorized activity is strictly prohibited. By downloading, installing, or using NRSuite, you agree to comply with all applicable laws and regulations. This software is provided free of charge; the developers assume no liability for any misuse. Use at your own risk. See LEGAL.md for full terms.