Skip to content

Rewrite README with formal professional language #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
PurpleMoosePython wants to merge 2 commits into
base: main
Choose a base branch
from
+84 −85
Open

Rewrite README with formal professional language #5

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4d4d52d
Rewrite README with formal professional language
PurpleMoosePython Nov 30, 2025
dd05867
Merge branch 'main' into main
PurpleMoosePython Jan 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
169 changes: 84 additions & 85 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<img src="https://github.com/user-attachments/assets/0eba90bc-2ff5-40df-88a1-92e23396d1d3" alt="logo" width="100" height="auto" />

<h1>nyanBOX</h1>
<p>All-in-One Gadget for BLE and 2.4GHz Networks</p>
<p>Integrated Platform for BLE and 2.4GHz Wireless Analysis</p>
<p>By Nyan Devices | Maintained by jbohack & zr_crackiin</p>

<!-- Badges -->
Expand All @@ -20,7 +20,7 @@

<h3>
<a href="https://nyandevices.com">🌐 Learn More</a> ·
<a href="https://shop.nyandevices.com">🛒 Buy nyanBOX</a> ·
<a href="https://shop.nyandevices.com">🛒 Purchase nyanBOX</a> ·
<a href="https://discord.gg/J5A3zDC2y8">💬 Join Discord</a>
</h3>
</div>
Expand All @@ -29,35 +29,35 @@

## What is nyanBOX?

**nyanBOX** is your pocket-sized 2.4GHz wireless lab. Think of it as a swiss army knife for the entire 2.4GHz spectrum - Bluetooth, BLE, WiFi, and everything in between. Perfect for security researchers, pentesters, hackers, and curious tinkerers who want to understand how wireless protocols really work.
**nyanBOX** is a compact, comprehensive 2.4GHz wireless analysis device designed for professionals working with Bluetooth, BLE, Wi-Fi, and other protocols operating within the 2.4GHz spectrum. It functions as a versatile, portable platform suitable for security researchers, penetration testers, engineers, and technical hobbyists seeking an in-depth understanding of wireless communication and device behavior.

Built around an ESP32 with triple NRF24 modules, a crisp OLED display, and a 2500mAh rechargeable battery, nyanBOX lets you explore the invisible world of 2.4GHz radio anywhere - no cables needed. Scan for hidden Bluetooth devices, detect AirTags tracking you, find credit card skimmers, analyze RF signals, test wireless security, and way more.
Powered by an ESP32, three NRF24 modules, a high-clarity OLED display, and a 2500mAh rechargeable battery, nyanBOX enables effective wireless scanning, detection, and analysis in the field with no external hardware required. Typical applications include identifying BLE devices, detecting tracking beacons such as AirTags, locating skimming devices, examining RF channel activity, and performing authorized wireless security evaluations.

**→ [Check out all the features at nyandevices.com](https://nyandevices.com)**
**→ [Learn more at nyandevices.com](https://nyandevices.com)**

<div align="center">
<img src="https://github.com/user-attachments/assets/530e5686-09db-4f02-aabe-80a8abcbb036" alt="nyanBOX Interface" width="650" />
</div>

---

## ⚡ Why You'll Love It
## ⚡ Key Advantages

- **Plug & Play** – USB-C powered, works right out of the box
- **All-Day Battery** – 2500mAh battery provides up to a full day of portable use
- **Level Up System** – Built-in RPG mechanics track your progress as you explore wireless protocols
- **Open Source** – Fully customizable firmware with active community development
- **Complete 2.4GHz Toolkit** – 20+ built-in features for Bluetooth, BLE, WiFi, and RF analysis
- **Pocket-Sized** – Take it anywhere, scan everything
- **Active Updates** – New features added regularly by the community
- **Plug & Play Operation** – USB-C powered and ready for immediate use
- **Extended Battery Life** – 2500mAh battery supports up to a full day of typical operation
- **Progress Monitoring System** – Integrated leveling system providing usage insights
- **Open-Source Firmware** – Fully customizable with active community contributions
- **Comprehensive 2.4GHz Suite** – Over 20 integrated tools for BLE, Bluetooth, Wi-Fi, and RF diagnostics
- **Portable Design** – Compact form factor optimized for field work
- **Regular Updates** – Ongoing feature additions and improvements

**Ready to dive in? [Purchase nyanBOX at shop.nyandevices.com](https://shop.nyandevices.com)**
**Interested? [Purchase nyanBOX at shop.nyandevices.com](https://shop.nyandevices.com)**

---

## 🎯 What Can It Do?
## 🎯 Features & Capabilities

> **⚠️ Note:** Additional advanced tools can be enabled in the Settings menu.
> **⚠️ Note:** Some advanced tools may require activation through the Settings menu.

### 📶 WiFi Tools
- **WiFi Scanner** – Detects nearby WiFi access points with full client detection. View connected clients for each network, monitor their signal strength, packet activity, and deauthenticate individual clients.
Expand Down Expand Up @@ -93,119 +93,118 @@ Built around an ESP32 with triple NRF24 modules, a crisp OLED display, and a 250
- **Scanner** – Scans the 2.4GHz frequency band to detect active channels and devices
- **Analyzer** – Real-time spectrum analyzer with channel filters for targeted RF analysis. Features dynamic display with auto-scaling, peak frequency detection, and instant filter switching via left/right buttons. Analyze WiFi, Bluetooth, or custom frequency bands.

### 🎮 Leveling System
nyanBOX features a built-in RPG-style leveling system that tracks your usage throughout using the device:
---

## 🎮 Leveling System

The integrated leveling system offers structured, persistent feedback on device usage:

- **Level Progression** – Gain XP by using different tools and features
- **Rank System** – Progress through 9 different ranks
- **Usage Tracking** – Different XP rates for scanning, attacks, and utilities/misc
- **Session Bonuses** – Extra XP for extended tool usage
- **Level Display** – Current level shown on main menu, detailed stats accessible via RIGHT arrow
- **Progress Persistence** – Level data saved to EEPROM, survives power cycles
- **XP Reset** – Reset progress via Settings menu if desired
- **Device Networking** – Your level and version are automatically broadcasted to nearby nyanBOX devices for discovery
- **Progress Tracking** – XP earned by using various tool categories
- **Rank Advancement** – Nine rank tiers available
- **Usage Analysis** – Tools award XP at varying rates
- **Session Bonuses** – Extended use yields additional progression
- **Persistent Storage** – Data stored in EEPROM across power cycles
- **Reset Option** – Users may reset progress via the Settings menu
- **Device Networking** – Level and version broadcast for discovery by other nyanBOX units

Hit RIGHT in the main menu to check your stats. Level up by tinkering with RF signals and unlock ranks as you progress. Other nyanBOX users can see your progress when they scan for nearby devices!
Access detailed statistics via the RIGHT directional button in the main menu.

---

## 🛠️ Hardware Specs
## 🛠️ Hardware Specifications

| Component | Details |
|-----------:|------------------------------------------|
| Microcontroller | ESP32 WROOM‑32U (dual‑core, Wi‑Fi + BT) |
| Wireless Modules | 3× NRF24 GTmini modules |
| Display | 0.96" OLED |
| Power | USB‑C + 2500mAh rechargeable battery |
| Battery | Up to a full day typical use |
| Case | Protective enclosure included |
| Debug | UART |
| Component | Details |
|-----------------:|----------------------------------------------|
| Microcontroller | ESP32 WROOM-32U (dual-core, Wi-Fi + BLE) |
| Wireless Modules | 3× NRF24 GTmini modules |
| Display | 0.96" OLED |
| Power | USB-C + 2500mAh rechargeable battery |
| Battery Life | Up to one full day of typical usage |
| Case | Protective enclosure included |
| Debug Interface | UART |

Get yours: https://shop.nyandevices.com
Purchase: https://shop.nyandevices.com

---

## 🚀 Getting Started

### First Time Setup
### First-Time Setup

Purchase a nyanBOX from **[shop.nyandevices.com](https://shop.nyandevices.com)** and flash the firmware in minutes using our web-based flasher!
Purchase a nyanBOX from **[shop.nyandevices.com](https://shop.nyandevices.com)** and install firmware within minutes using the web-based flashing tool.

### Firmware Installation & Updates

Get up and running or update to the latest features:
#### Recommended: Web Flasher
1. Visit **[nyandevices.com/flasher](https://nyandevices.com/flasher)**
2. Connect the device via USB-C
3. Select **Install nyanBOX Firmware**
4. The installation completes automatically

#### Easy Mode - Web Flasher (Recommended)
1. Head to **[nyandevices.com/flasher](https://nyandevices.com/flasher)**
2. Plug in your nyanBOX via USB-C
3. Click **Install nyanBOX Firmware**
4. Done!
#### Advanced: PlatformIO
1. Install [VS Code](https://code.visualstudio.com/) and [PlatformIO](https://platformio.org/install/ide?install=vscode)
2. Clone or download the repository
3. Open the project in VS Code
4. Select Upload in PlatformIO
5. The device will flash and restart

#### Advanced - PlatformIO
For developers who want to build from source or customize the firmware:

1. Install [VS Code](https://code.visualstudio.com/) and [PlatformIO](https://platformio.org/install/ide?install=vscode)
2. Clone or download this repo
3. Open the folder in VS Code
4. Hit Upload in PlatformIO
5. Flash complete!

**Troubleshooting:**
- Can't find the port? Install [CP210x drivers](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers)
- Upload failing? Hold the BOOT button while flashing
- Still stuck? Hit up our [Discord](https://discord.gg/J5A3zDC2y8) - we're here to help!
**Troubleshooting:**
- Port unavailable: install [CP210x drivers](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers)
- Upload failure: hold the BOOT button during flashing
- Need assistance? Join the [Discord community](https://discord.gg/J5A3zDC2y8)

---

## ⚠️ Legal Disclaimer

**Use nyanBOX responsibly.** It's built for education, security research, and authorized testing only.
**Use nyanBOX responsibly and ethically.**
It is designed strictly for authorized testing, research, and educational purposes.

- Don’t attack networks you don’t own
- Always obtain permission before testing
- Know your local laws; some features may be restricted
- You’re responsible for how you use it
- Do not perform unauthorized network attacks
- Obtain explicit permission prior to conducting assessments
- Comply with all applicable local laws and regulations
- Users are fully responsible for their actions

By using nyanBOX, you agree to use it ethically and legally. We're not liable for misuse.
By using nyanBOX, you agree to adhere to lawful and ethical usage practices.

---

## ❓ FAQ

**Is nyanBOX legal to own?**
Yes, but some features may be restricted depending on your location and use. Follow local laws and obtain permission.
Yes. Ownership is legal, though specific features may be subject to local restrictions.

**How long does the battery last?**
Up to a full day of typical use. Heavy continuous scanning may reduce runtime; lighter intermittent use can extend it.
Up to one full day during typical operation. Continuous intensive scanning may reduce runtime.

**Can I develop my own tools?**
Yes. The firmware is open source. You can customize and add features. Join our Discord if you need help.
Yes. The firmware is open source and supports extensive customization.

**Does it come with firmware pre‑installed?**
nyanBOX ships ready to flash. Use the web flasher at https://nyandevices.com/flasher to get running in minutes.
**Does it come with firmware pre-installed?**
Devices ship ready for flashing. The web flasher enables installation in minutes.

---

## 💬 Join the Community

Got questions? Want to show off your device? Need help?
Have questions or need assistance?

- **[Discord](https://discord.gg/J5A3zDC2y8)** - Most active community spot
- **[GitHub Issues](https://github.com/jbohack/nyanBOX/issues)** - Report bugs or request features
- **[nyandevices.com](https://nyandevices.com)** - Full docs and guides
- **[Discord](https://discord.gg/J5A3zDC2y8)** – Primary community hub
- **[GitHub Issues](https://github.com/jbohack/nyanBOX/issues)** – Bug reports and feature requests
- **[nyandevices.com](https://nyandevices.com)** – Documentation and guides

---

## 💝 Support the Project

Love nyanBOX? Here's how you can help:
If you find nyanBOX valuable, consider supporting development:

- ⭐ Star this repo
- 🛒 **[Buy nyanBOX at shop.nyandevices.com](https://shop.nyandevices.com)**
- ☕ Buy us a coffee:
- [jbohack's Ko-fi](https://ko-fi.com/jbohack)
- [zr_crackiin's Ko-fi](https://ko-fi.com/zrcrackiin)
- 🗣️ Spread the word!
- ⭐ Star this repository
- 🛒 **[Purchase at shop.nyandevices.com](https://shop.nyandevices.com)**
- ☕ Support the developers:
- [jbohack on Ko-fi](https://ko-fi.com/jbohack)
- [zr_crackiin on Ko-fi](https://ko-fi.com/zrcrackiin)
- 🗣️ Share with others interested in wireless research

### Built By
- [jbohack](https://github.com/jbohack)
Expand All @@ -228,20 +227,20 @@ Love nyanBOX? Here's how you can help:
- [Flock You](https://github.com/colonelpanichacks/flock-you)
- [Original nRFBOX Project](https://github.com/cifertech/nrfbox)

And thanks to everyone who's contributed code, reported bugs, purchased a device, or just shared the love. You're awesome!
Thank you to all contributors, testers, supporters, and community members.

---

## 📜 License

MIT License - see [LICENSE](LICENSE) for details.
MIT License – see [LICENSE](LICENSE) for details.

---

<div align="center">
<h3>Ready to explore the 2.4GHz spectrum?</h3>
<p>
<a href="https://shop.nyandevices.com"><strong>🛒 Buy nyanBOX Now</strong></a>
<a href="https://shop.nyandevices.com"><strong>🛒 Purchase nyanBOX</strong></a>
</p>
<p>#BadgeLife</p>
</div>
</div>