Nyan Box · Volume 8

Nyan Box Volume 8 — Firmware Ecosystem

The MIT-licensed stock firmware and its published source, the gamified XP system, the alternative-firmware paths


8.1 About this volume

Vol 8 covers what runs on the nyanBOX. There are really three firmware questions:

  1. The stock firmware — where is the source, what licence, how is it updated? (§ 2-3)
  2. The XP system — is the gamification just a wrapper, or does it actually gate tools, and can you skip it? (§ 4)
  3. Alternative firmware — can the hardware run Marauder / Ghost ESP instead, and should it? (§ 5)

The answers shape whether the nyanBOX is “the device as the vendor designed it” or “a nice piece of triple-NRF24 hardware running whatever firmware you prefer.”

Figure 1 — The stock firmware's gamified XP system on the OLED: Level 8 with its XP progress counter, the level screen whose behaviour this volume examines. Photo: still from the video "NyanBox - A…
Figure 1 — The stock firmware's gamified XP system on the OLED: Level 8 with its XP progress counter, the level screen whose behaviour this volume examines. Photo: still from the video "NyanBox - A Compact Toolkit For Wireless Security" (youtube.com/watch?v=ek2OoneqBxM), cropped.

8.2 The stock firmware source — MIT-licensed, on GitHub

8.2.1 The facts (checked 2026-10-13)

The nyanBOX firmware is open source under the MIT License. Its home is the public repository https://github.com/jbohack/nyanBOX (created 2025-04-18), described there as “A compact ESP32 Wroom32U toolkit for wireless security—scan, analyze, and spoof RF, Wi-Fi, and BLE protocols, all from an intuitive menu-driven interface.” The LICENSE file is the plain MIT text with two copyright lines — “Copyright (c) 2025 jbohack / Original work Copyright (c) 2022 CiferTech” — which is why GitHub’s licence detector labels it “Other”. The source files carry SPDX-License-Identifier: MIT headers.

The second copyright line is the lineage: the nyanBOX descends from CiferTech’s nRFBOX (https://github.com/cifertech/nrfbox), which the README credits as the original project. The README also credits the community code it builds on — among them opendroneid-core-c (RemoteID), AppleJuice and ESP32-Sour-Apple (BLE pairing spam), ESP32-AirTag-Scanner, Flock You and the RF24 library.

8.2.2 What is actually in the repository — a source snapshot, not a live tree

One detail matters for anyone planning to build from source. The repository’s history shows:

Table 1 — One detail matters for anyone planning to build from source. The repository's history shows

DateCommitWhat changed
to 2026-04-13—The full PlatformIO project (VScode Platformio/) lived at the repo root alongside the release binaries
2026-04-13”Restructure repository layout”The source tree moved to firmware-files/old/legacy-src/. From here on, feature commits (Camera Detector 2026-04-21, Packet Monitor, Jam Detector, iBeacon Detector/Spoofer and later) change only firmware.bin + manifest.json and the README — no source
2026-06-27”Restructure flashing backend & compress legacy files”The binaries left the repo (flashing moved to the vendor web flasher) and the source snapshot was packed into firmware-files/legacy-src.tar.xz

So the published, MIT-licensed source is a snapshot of the firmware as of April 2026. The current release on the web flasher carries tools that are not in that snapshot. Whether newer source will be published is not stated in the repository; the licence imposes no obligation to publish it.

Table 2 — 2.2 What is actually in the repository — a source snapshot, not a live tree

FeatureIn the published MIT source?Where
Drone RemoteID detection (Vol 6)Yessrc/drone_detector.cpp — its header notes code derived from opendroneid-core-c
RemoteID spoofer (bench test)Yessrc/drone_spoofer.cpp
Flock Safety camera detectionYessrc/flock_detector.cpp
General Wi-Fi hidden-camera detector (Vol 7) — the OUI/frame-heuristic “Camera Detector”No — added 2026-04-21, binary-only so far—
XP / level system (§ 4)Yessrc/level_system.cpp, include/level_system.h, and the XP-award logic in src/nyanBOX.ino
OLED-to-host display mirrorYessrc/display_mirror.cpp + the host viewer tools/display_viewer.py in the repo

8.2.3 What this means in practice

  • Forking is a normal option. Unpack legacy-src.tar.xz and it is an ordinary PlatformIO/Arduino-ESP32 project (platformio.ini env nyanbox-main, plus a hardware-test env). Building, adding a tool, or changing the XP logic is ordinary source work (Vol 9) — no binary reverse-engineering is involved.
  • RemoteID detection is forkable and extendable from the published code. The general camera detector currently is not — the camera-signature database exists only in the vendor binary, so its freshness still depends on vendor releases (§ 3.2).
  • A source build is an April-2026 build. Building the snapshot drops every tool added since. The day-to-day choice is therefore between the current vendor binary (newest features) and a self-built fork (full control, older feature set).
  • The XP system can be changed at source (§ 4) rather than worked around.

8.3 Updating the stock firmware

8.3.1 The web-flasher path

The canonical update method, per DEVELOPMENT.md:

   nyanBOX stock firmware update
   ═══════════════════════════════

   1. Plug nyanBOX into a Chrome / Edge machine via USB-C
   2. Visit the vendor's web flasher (linked from nyandevices.com)
   3. Pick the firmware version → Flash
   4. The web flasher (WebSerial API) handles erase + write + verify

   Note: USB-C on the nyanBOX goes through a USB-serial
   bridge (the ESP32-WROOM-32 is not native-USB — Vol 2
   § 3.4), so the flasher talks to the bridge, which talks
   to the ESP32. Standard ESP32 flashing under the hood.

8.3.2 Why updating matters — the camera database

The single most important reason to keep the stock firmware current: the hidden-camera signature database is baked into the firmware (Vol 7 § 4.3). A year-old firmware has a year-old camera database. Before any real camera sweep, update.

RemoteID detection is less update-sensitive — the ASTM F3411 message format is a stable standard, so the RemoteID decoder doesn’t age the way the camera DB does. But firmware updates may still bring RemoteID improvements (better BT5 handling, new transports).

8.3.3 The re-flash resets XP state

From DEVELOPMENT.md: re-flashing resets the XP-progression state (it lives in EEPROM — Vol 2 § 7). If the XP state matters to you, back up the EEPROM first (the vendor may publish a backup tool). The XP state is not precious — but know that updating firmware zeroes it.

8.3.4 esptool.py as the fallback

If the web flasher is unavailable or you have a raw .bin:

esptool.py --chip esp32 -p /dev/ttyUSB0 -b 460800 \
    write_flash 0x0 firmware.bin

Standard ESP32 (original, not S3) flashing. The --chip esp32 is correct — the nyanBOX is original ESP32, not S3/C3.


8.4 The XP system — and bypassing it

8.4.1 What the XP system is

Vol 1 § 4 introduced the gamified XP-progression system and described it, before the source was checked, as a tiered model in which XP unlocks active and then disruptive tools. The published source does not bear that out. In the MIT source snapshot (§ 2.2) the XP system is a progression and identity layer, not a lock:

   The XP system as implemented (published source, April 2026)
   ═════════════════════════════════════════════════════════════

   Earning   every 60 s of active use inside a tool:
               recon tools (Scan / Detector / Scout /
                 Analyzer / Inspect)        +3 XP
               offensive tools (Deauth / Spam / Spoofer /
                 Sour Apple / Sour Droid / Swift Pair /
                 Evil Portal / SigKill)     +4 XP
               utilities (Settings / About) +2 XP
             session bonus on exit: +4 (≥5 min), +12 (≥10 min)
             no XP after 2 min without a button press

   Levels    XP needed for level L = L² + 10; cap Level 99
             (XP is a 16-bit counter, max 65535)
   Ranks     N00b → Skid → Wannabe → L33t → Hacker →
             Uber Hacker → Elite → Godlike → Legend (9 ranks)
   Storage   EEPROM bytes 100–102 (magic 0xAB + XP lo/hi)
   Shared    level + firmware version go out in the nyanBOX
             BLE advertisement — other units' "nyanBOX
             Detector" shows them
   Reset     Settings → "Reset XP Data?"

   Locks     NONE. No tool checks the level before it runs.

Code locations: src/level_system.cpp (levels, ranks, EEPROM), src/nyanBOX.ino (getXPAmount(), startAppTracking(), updateAppXP()), src/nyanbox_advertiser.cpp (the advertised level).

8.4.2 The one real gate — the “Dangerous” setting

The published source does gate exactly one tool, and not by XP. SigKill (the NRF24 2.4 GHz jammer — Vol 5 § 5) is hidden from the menus unless Settings → Dangerous is switched On, and switching it on first shows a legal disclaimer that must be accepted (shouldShowApp() in src/nyanBOX.ino, handleDangerousActions() in src/setting.cpp). That is a deliberate posture control, not friction to engineer around — see Vol 11 § 3 before ever enabling it.

Whether the current vendor binary (with the tools added since April 2026) has introduced any XP-based locks cannot be confirmed from the repository, because that code is not published. The README describes the system only as tracking usage and unlocking ranks, which matches the snapshot.

8.4.3 Changing the XP system

Because it is MIT source, nothing needs to be bypassed. In order of effort:

Table 3 — Because it is MIT source, nothing needs to be bypassed. In order of effort

ApproachEffortNotes
Ignore itNoneIt gates nothing in the published source; every tool is reachable from the first boot
Reset itLowSettings → Reset XP Data
Change it at sourceLowEdit the award rates in getXPAmount() or the curve in getXPRequiredForLevel(), or remove the advertiser’s level field, then rebuild (Vol 9) — at the cost of running the April-2026 feature set
Alternative firmwareMedium-HighFlash Marauder / Ghost ESP — no XP system at all (§ 5), but the nyanBOX-specific tools go with it

8.4.4 The pragmatic answer

Leave it alone. The XP counter is cosmetic: it does not stand between an experienced user and any tool, and the only real gate (the Dangerous setting for SigKill) exists for a legal reason. Changing the XP behaviour is a few lines of source if it ever matters.


8.5 Alternative firmware — Marauder, Ghost ESP

8.5.1 The hardware will run them

The nyanBOX hardware — ESP32-WROOM-32U + NRF24 over SPI + OLED + battery — is standard-enough ESP32-pentest hardware that it can run the major alternative firmwares:

Table 4 — The nyanBOX hardware — ESP32-WROOM-32U + NRF24 over SPI + OLED + battery — is standard-enough ESP32-pentest hardware that it can run the major alternative firmwares

Alt firmwareRuns on nyanBOX hardware?What you get
ESP32 MarauderYes (ESP32 build)Mature, deep Wi-Fi/BLE pentest; open-source; the canonical alt
Ghost ESPLikelyAnother popular open ESP32-pentest firmware
BrucePossibly (Bruce targets many boards; the nyanBOX isn’t a standard target)Would need a custom build / pin map

8.5.2 The catch — the UI + tool catalog won’t match

From DEVELOPMENT.md, stated plainly: “The ESP32-WROOM-32U + 3× NRF24 hardware will run those firmwares (with the NRF24s exposed via SPI or treated as auxiliary radios), but the OLED UI patches and tool catalog won’t match the stock UX.”

What “won’t match” means concretely:

  • The OLED is a specific size/controller; alt firmware needs its display driver configured for the nyanBOX’s exact OLED — may need a custom build, not a stock binary
  • The arrow-key input matrix needs its GPIO map configured
  • The three NRF24 radios — alt firmware typically expects one NRF24. The triple-radio arrangement (Vol 3) is a nyanBOX-firmware feature; Marauder won’t natively use all three. You’d get one NRF24 working, the other two idle, unless you customize.
  • The XP system is gone (it was cosmetic anyway — § 4)

8.5.3 The big loss — the two unique features

This is the decisive point. ESP32 Marauder and Ghost ESP do not have:

  • Drone RemoteID detection (Vol 6)
  • Hidden-camera detection (Vol 7)

Those two features are nyanBOX-firmware features — no other firmware in the lineup has them. They’re the entire reason the nyanBOX is interesting in the lineup (Vol 1 § 6). Flash Marauder onto the nyanBOX and it becomes a slightly-awkward Marauder box — and the lineup already has a good Marauder box (the AWOK Dual Touch V3).

Because the nyanBOX source is MIT-licensed, the loss is not absolute: the RemoteID decoder (src/drone_detector.cpp, itself derived from opendroneid-core-c) could in principle be ported into a Marauder build, subject to keeping the copyright notices. The general Wi-Fi camera detector cannot be ported the same way — it is not in the published source (§ 2.2).

   The alt-firmware tradeoff
   ════════════════════════════

   Flash Marauder onto the nyanBOX:
     GAIN:  open-source, no XP system, mature Wi-Fi/BLE
     LOSE:  RemoteID detection      ← the reason to own it
            hidden-camera detection ← the reason to own it
            native triple-NRF24 use ← the distinctive hardware
            (and the nyanBOX becomes a worse AWOK V3)

   Verdict: alt firmware on the nyanBOX is a FALLBACK for
   "the stock firmware disappointed me on the Wi-Fi/BLE
   side and I don't care about the unique features" — a
   narrow case. If you bought the nyanBOX for what makes
   it the nyanBOX, you run the stock firmware.

8.5.4 When alt firmware actually makes sense

The narrow legitimate cases for flashing alt firmware on the nyanBOX:

  • The stock firmware is abandoned (vendor stops updating — the camera DB rots, bugs go unfixed) and you want a maintained firmware. (A fork of the published nyanBOX source is the other salvage path here, and keeps RemoteID and the triple-NRF24 tools.)
  • You specifically want the nyanBOX hardware as a second Marauder box and don’t care about RemoteID/camera
  • You’re doing custom firmware development (Vol 9) and specifically want Marauder’s Wi-Fi/BLE depth as the base rather than the nyanBOX source

Otherwise: stock firmware is the answer, because stock firmware is the only firmware with the features that justify the device.


8.6 The firmware decision

   Firmware decision tree
   ═══════════════════════

   Did you buy the nyanBOX for RemoteID / camera detection
   / triple-NRF24 (i.e. the reasons it's distinctive)?
            │
       ┌────┴─────┐
      YES         NO (you wanted a 2nd Marauder box)
       │           │
       ▼           ▼
   Run STOCK    Consider alt firmware —
   firmware.    but honestly, the AWOK V3
   Keep it      already covers Marauder;
   UPDATED      buying a nyanBOX to flash
   (camera DB!) Marauder onto it is an
   Ignore the   odd choice. Reconsider the
   XP counter.  purchase.
       │
       ▼
   Need a change the vendor won't make?
   → fork the MIT source (Vol 9), accepting
     the April-2026 snapshot's feature set.
   Vendor abandons the firmware later?
   → fork, or alt firmware, as a salvage path.

Bottom line: for the nyanBOX, the current vendor build is almost always the right answer — it is the only build with every feature, including the camera detector. The XP system is cosmetic. Keep the firmware updated (for the camera database). The published MIT source makes a custom fork a genuine option when a specific change is needed; alt firmware is a salvage option, not a day-one move.


8.7 Resources

Stock firmware

Alternative firmware

Flashing tools

Sibling reference

End of Vol 8. Next: Vol 9 covers programming and custom firmware development — building and forking the published source, host-side scripts, and what’s worth customizing.

Comments (0)

  1. Loading…

Comments are held for moderation — nothing appears until approved.