# 7wp81x/nrsuite-firmware architecture

> Architecture diagram of the GitHub repository 7wp81x/nrsuite-firmware, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/7wp81x/nrsuite-firmware
- Repository: https://github.com/7wp81x/nrsuite-firmware

## Overview

NRSuite Firmware is ESP32 firmware controlled by the NRSuite Android app over USB serial. The principal workflow is command framing and dispatch in the firmware, followed by a selected radio/device operation and responses, events, or captured data back to the app. Its capabilities span Wi-Fi discovery and monitoring, active Wi-Fi testing, WPS analysis, BLE and USB HID, and device peripherals/storage. The map uses README-described capabilities where implementation excerpts were unavailable; those links are documented workflows, not claims about unsampled call sites.

Main entry points: [`src/main.cpp`](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/main.cpp) (Command Dispatcher), [`src/wps_pixie.cpp`](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/wps_pixie.cpp) (WPS Pixie Flow), [`lib/BridgeProtocol/BridgeProtocol.cpp`](https://github.com/7wp81x/nrsuite-firmware/blob/main/lib/BridgeProtocol/BridgeProtocol.cpp) (Serial Bridge), [`src/wps_attempt_detector.cpp`](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/wps_attempt_detector.cpp) (WPS Attempt Detection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Command and Protocol"]
  node_firmware["Command Dispatcher<br/>[main.cpp]"]
  node_bridge["Serial Bridge<br/>[BridgeProtocol.cpp]"]
end

subgraph group_wifi["Wi-Fi Operations"]
  node_wifi_scan["Wi-Fi Scan<br/>[main.cpp]"]
  node_sniffer["Packet Sniffer<br/>[sniffer.cpp]"]
  node_deauth["Deauthentication<br/>[main.cpp]"]
  node_deauth_rules["Multi-Deauth Rules<br/>[DeauthMultiRules.h]"]
  node_detectors["Wi-Fi Detectors"]
  node_hidden_ap["Hidden AP Revealer<br/>[hidden_ap.cpp]"]
  node_beacon["Beacon Injection<br/>[beacon.cpp]"]
  node_portal["Captive Portal<br/>[portal.cpp]"]
end

subgraph group_wps["WPS Analysis"]
  node_wps_attempt["WPS Attempt Detection"]
  node_wps_lock["WPS Lock Detection"]
  node_wps_pixie["WPS Pixie Flow<br/>[wps_pixie.cpp]"]
  node_wps_parser["WPS Packet Parser<br/>[wps_parser.cpp]"]
  node_wps_registrar["WPS Registrar<br/>[wps_registrar.cpp]"]
end

subgraph group_hid["BLE and USB HID"]
  node_ble["BLE HID and Scan<br/>[ble_hid.cpp]"]
  node_ble_pin["BLE HID PIN Test"]
  node_usb_hid["USB HID and BadUSB<br/>[UsbHID.cpp]"]
  node_pin_test["USB PIN Test<br/>[pin_bruteforce.cpp]"]
end

subgraph group_peripherals["Peripherals and Storage"]
  node_mesh["Experimental Mesh<br/>[mesh.cpp]"]
  node_ir["IR Remote<br/>[ir_remote.cpp]"]
  node_radar["LD2450 Radar<br/>[ld2450.cpp]"]
  node_nfc["PN532 NFC<br/>[pn532_nfc.cpp]"]
  node_mass_storage[("Mass Storage<br/>[mass_storage.cpp]")]
  node_file_upload["File Upload<br/>[FileUpload.cpp]"]
end

node_android(("Android App"))

node_android -->|"sends commands"| node_bridge
node_bridge -.->|"dispatches frames"| node_firmware
node_firmware -->|"returns events"| node_android
node_firmware -.->|"starts scan"| node_wifi_scan
node_firmware -->|"starts capture"| node_sniffer
node_firmware -->|"dispatches commands"| node_deauth
node_deauth -.->|"uses limits"| node_deauth_rules
node_firmware -.->|"starts detection"| node_detectors
node_firmware -->|"starts detection"| node_hidden_ap
node_firmware -.->|"dispatches commands"| node_beacon
node_firmware -->|"dispatches commands"| node_portal
node_firmware -->|"starts detection"| node_wps_attempt
node_firmware -.->|"dispatches commands"| node_wps_lock
node_firmware -.->|"dispatches commands"| node_wps_pixie
node_wps_attempt -->|"parses frames"| node_wps_parser
node_wps_pixie -.->|"parses messages"| node_wps_parser
node_wps_pixie -.->|"uses registrar"| node_wps_registrar
node_firmware -.->|"dispatches commands"| node_ble
node_firmware -.->|"dispatches commands"| node_ble_pin
node_firmware -.->|"dispatches commands"| node_usb_hid
node_firmware -.->|"dispatches commands"| node_pin_test
node_firmware -.->|"dispatches commands"| node_mesh
node_firmware -.->|"dispatches commands"| node_ir
node_firmware -.->|"dispatches commands"| node_radar
node_firmware -.->|"dispatches commands"| node_nfc
node_firmware -->|"dispatches commands"| node_mass_storage
node_firmware -.->|"dispatches uploads"| node_file_upload
node_file_upload -.->|"writes files"| node_mass_storage

click node_firmware "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/main.cpp"
click node_bridge "https://github.com/7wp81x/nrsuite-firmware/blob/main/lib/BridgeProtocol/BridgeProtocol.cpp"
click node_wifi_scan "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/main.cpp"
click node_sniffer "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/sniffer.cpp"
click node_deauth "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/main.cpp"
click node_deauth_rules "https://github.com/7wp81x/nrsuite-firmware/blob/main/lib/DeauthMulti/DeauthMultiRules.h"
click node_detectors "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/deauth_detector.cpp"
click node_hidden_ap "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/hidden_ap.cpp"
click node_beacon "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/beacon.cpp"
click node_portal "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/portal.cpp"
click node_wps_attempt "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/wps_attempt_detector.cpp"
click node_wps_lock "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/wps_lock_detector.cpp"
click node_wps_pixie "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/wps_pixie.cpp"
click node_wps_parser "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/wps_parser.cpp"
click node_wps_registrar "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/wps_registrar.cpp"
click node_ble "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/ble_hid.cpp"
click node_ble_pin "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/ble_pin_bruteforce.cpp"
click node_usb_hid "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/UsbHID.cpp"
click node_pin_test "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/pin_bruteforce.cpp"
click node_mesh "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/mesh.cpp"
click node_ir "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/ir_remote.cpp"
click node_radar "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/ld2450.cpp"
click node_nfc "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/pn532_nfc.cpp"
click node_mass_storage "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/mass_storage.cpp"
click node_file_upload "https://github.com/7wp81x/nrsuite-firmware/blob/main/src/FileUpload.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_firmware,node_bridge toneBlue
class node_wifi_scan,node_sniffer,node_deauth,node_deauth_rules,node_detectors,node_hidden_ap,node_beacon,node_portal toneAmber
class node_wps_attempt,node_wps_lock,node_wps_pixie,node_wps_parser,node_wps_registrar toneMint
class node_ble,node_ble_pin,node_usb_hid,node_pin_test toneRose
class node_mesh,node_ir,node_radar,node_nfc,node_mass_storage,node_file_upload,node_android toneIndigo
```

## Components

### Command and Protocol

- [Command Dispatcher](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/main.cpp): `src/main.cpp`
- [Serial Bridge](https://github.com/7wp81x/nrsuite-firmware/blob/main/lib/BridgeProtocol/BridgeProtocol.cpp): `lib/BridgeProtocol/BridgeProtocol.cpp`

### Wi-Fi Operations

- [Wi-Fi Scan](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/main.cpp): `src/main.cpp`
- [Packet Sniffer](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/sniffer.cpp): `src/sniffer.cpp`
- [Deauthentication](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/main.cpp): `src/main.cpp`
- [Multi-Deauth Rules](https://github.com/7wp81x/nrsuite-firmware/blob/main/lib/DeauthMulti/DeauthMultiRules.h): `lib/DeauthMulti/DeauthMultiRules.h`
- [Wi-Fi Detectors](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/deauth_detector.cpp): `src/deauth_detector.cpp`
- [Hidden AP Revealer](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/hidden_ap.cpp): `src/hidden_ap.cpp`
- [Beacon Injection](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/beacon.cpp): `src/beacon.cpp`
- [Captive Portal](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/portal.cpp): `src/portal.cpp`

### WPS Analysis

- [WPS Attempt Detection](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/wps_attempt_detector.cpp): `src/wps_attempt_detector.cpp`
- [WPS Lock Detection](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/wps_lock_detector.cpp): `src/wps_lock_detector.cpp`
- [WPS Pixie Flow](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/wps_pixie.cpp): `src/wps_pixie.cpp`
- [WPS Packet Parser](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/wps_parser.cpp): `src/wps_parser.cpp`
- [WPS Registrar](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/wps_registrar.cpp): `src/wps_registrar.cpp`

### BLE and USB HID

- [BLE HID and Scan](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/ble_hid.cpp): `src/ble_hid.cpp`
- [BLE HID PIN Test](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/ble_pin_bruteforce.cpp): `src/ble_pin_bruteforce.cpp`
- [USB HID and BadUSB](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/UsbHID.cpp): `src/UsbHID.cpp`
- [USB PIN Test](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/pin_bruteforce.cpp): `src/pin_bruteforce.cpp`

### Peripherals and Storage

- [Experimental Mesh](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/mesh.cpp): `src/mesh.cpp`
- [IR Remote](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/ir_remote.cpp): `src/ir_remote.cpp`
- [LD2450 Radar](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/ld2450.cpp): `src/ld2450.cpp`
- [PN532 NFC](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/pn532_nfc.cpp): `src/pn532_nfc.cpp`
- [Mass Storage](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/mass_storage.cpp): `src/mass_storage.cpp`
- [File Upload](https://github.com/7wp81x/nrsuite-firmware/blob/main/src/FileUpload.cpp): `src/FileUpload.cpp`

### Other components

- **Android App**

## Connections

- Android App → Serial Bridge: sends commands (evidence: `README.md`)
- Serial Bridge → Command Dispatcher: dispatches frames
- Command Dispatcher → Android App: returns events (evidence: `README.md`)
- Command Dispatcher → Wi-Fi Scan: starts scan (evidence: `src/main.cpp`)
- Command Dispatcher → Packet Sniffer: starts capture (evidence: `src/main.cpp`)
- Command Dispatcher → Deauthentication: dispatches commands (evidence: `src/main.cpp`)
- Deauthentication → Multi-Deauth Rules: uses limits (evidence: `src/main.cpp`)
- Command Dispatcher → Wi-Fi Detectors: starts detection
- Command Dispatcher → Hidden AP Revealer: starts detection (evidence: `src/main.cpp`)
- Command Dispatcher → Beacon Injection: dispatches commands
- Command Dispatcher → Captive Portal: dispatches commands (evidence: `src/main.cpp`)
- Command Dispatcher → WPS Attempt Detection: starts detection (evidence: `src/main.cpp`)
- Command Dispatcher → WPS Lock Detection: dispatches commands
- Command Dispatcher → WPS Pixie Flow: dispatches commands
- WPS Attempt Detection → WPS Packet Parser: parses frames (evidence: `src/wps_attempt_detector.cpp`)
- WPS Pixie Flow → WPS Packet Parser: parses messages
- WPS Pixie Flow → WPS Registrar: uses registrar
- Command Dispatcher → BLE HID and Scan: dispatches commands
- Command Dispatcher → BLE HID PIN Test: dispatches commands
- Command Dispatcher → USB HID and BadUSB: dispatches commands
- Command Dispatcher → USB PIN Test: dispatches commands
- Command Dispatcher → Experimental Mesh: dispatches commands
- Command Dispatcher → IR Remote: dispatches commands
- Command Dispatcher → LD2450 Radar: dispatches commands
- Command Dispatcher → PN532 NFC: dispatches commands
- Command Dispatcher → Mass Storage: dispatches commands (evidence: `src/main.cpp`)
- Command Dispatcher → File Upload: dispatches uploads
- File Upload → Mass Storage: writes files