Bruce Firmware — ESP32 Security Multi-Tool Firmware Platform

#BruceFirmware #ESP32 #W5500 #Ethernet #SecurityPlatform #PlatformIO #OpenSource #RedTeam #WIZnet #MultiProtocol

📚 Context: Actively maintained open-source ESP32 security firmware platform. Supports M5Stack Cardputer, M5StickC, M5Core, LilyGo T-Embed, T-Deck, CYD, and more. Self-described as offensive firmware for red team operations — integrating Wi-Fi, BLE, Sub-GHz, RFID/NFC, IR, USB, and Ethernet into a single handheld interface. Latest public release: v1.15. W5500 usage confirmed in source code: src/modules/ethernet/EthernetHelper.cpp, EthernetMenu.cpp, ARPScanner.cpp.

01 — What is this project?

Organizations hire security professionals to ask a simple but uncomfortable question: if an attacker walked into this building today, what could they do?

The people who answer that question are called red teams. Their job is to find out before a real attacker does. In practice, that means checking things like:

• Can the building's Wi-Fi be cracked or spoofed?
• Can an employee's RFID access card be cloned at the door?
• If someone plugs into a wired network port, what can they see inside?
• If a USB device is left on a desk and someone plugs it in, what happens?

Bruce is a tool built to answer these questions — from a single handheld device, on-site, in real time.

Portable security tools have historically been fragmented by protocol.

A Wi-Fi analysis session requires a laptop or a dedicated ESP32 Marauder-type device. Sub-GHz work calls for a CC1101 device. RFID and NFC need a PN532 or MFRC522. Infrared analysis, BLE testing, and USB keyboard emulation each come with their own toolchain. Flipper Zero addressed some of this — but at a fixed hardware spec and a steep price point that put it out of reach for many practitioners and students.

Bruce started from a different premise: the ESP32 ecosystem already provides the processing power, wireless interfaces, and modular peripheral support to build a capable multi-protocol security tool. The question was whether a single firmware could abstract across the hardware variation in the ESP32 device market — different MCU variants, display controllers, input mechanisms, storage configurations — and still give every supported board a consistent feature surface.

The answer is a PlatformIO-based firmware architecture that separates board-level hardware abstraction from protocol-level feature modules. A Cardputer, a T-Embed, a CYD, and a bare ESP32-S3 DevKit all run the same codebase. Each board's display driver, button mapping, SPI bus assignments, and peripheral availability are encapsulated in board configuration files. Above that layer, feature modules — Wi-Fi, BLE, RF, RFID, IR, USB, Ethernet, scripting — are written once and composed differently per build target.

The result is a firmware platform rather than a single application. That distinction matters for understanding not just Bruce itself, but the ecosystem of forks and hardware-specific implementations that have grown around it.

02 — Why a Platform Architecture?

🔷 The problem with single-purpose ESP32 security tools

Most ESP32 security projects are built around one protocol or one attack class. They work well for their intended use case, but they don't generalize. Moving from Wi-Fi packet capture to RFID tag analysis to Sub-GHz replay requires switching devices, switching firmware, and switching mental models.

Bruce's modular architecture was designed to eliminate that context-switching. The menu system presents all protocol domains in a unified interface. The board abstraction layer means that the same Wi-Fi deauth code, the same RFID read path, and the same Ethernet scanner run on hardware ranging from a pocket Cardputer to a desk-mounted CYD panel.

🔷 Board abstraction as the design center

The bruceConfigPins structure is the architectural key. Every peripheral — including the W5500 Ethernet controller — is accessed through this pin configuration object rather than hard-coded GPIO numbers. When Theo's T-Embed CC1101 implementation documents specific SPI pins for W5500 (MOSI GPIO9, MISO GPIO10, SCK GPIO11, CS GPIO44, INT GPIO43), those values exist because the platform provides a named slot — W5500_bus — that any board can populate differently.

This is not incidental. It is the explicit design that allows one firmware to span 15+ supported board variants without forking the core modules.

🔷 Extensibility as a first-class feature

Bruce ships with a JavaScript interpreter (mQuickJS). Users can write and deploy new application logic without recompiling the firmware. The Web UI supports file transfer over Wi-Fi or Ethernet. SD card and LittleFS storage make session captures, RF recordings, and RFID dumps persistent and portable.

This extensibility is what made Bruce the base for a hardening fork like Joseph's HeavyButter — the same modular structure that makes features easy to add also makes the runtime surface area large enough to need explicit security hardening.

03 — System Architecture

External module connections follow the same abstraction:

Sub-GHz RF      →  CC1101          (board-configurable SPI)
2.4GHz RF       →  NRF24L01        (board-configurable SPI)
RFID/NFC        →  PN532 / MFRC522
IR              →  IR LED + receiver
Wired Ethernet  →  WIZnet W5500    (W5500_bus in bruceConfigPins)
Storage         →  SD card / LittleFS
GPS             →  UART GPS module

04 — Why WIZnet W5500? ⭐

🔷 Filling the gap Wi-Fi cannot reach

The ESP32 is a Wi-Fi and BLE device by design. What it does not provide on most production boards is a wired Ethernet MAC and PHY. In practice, this means that any ESP32-based security tool without an external Ethernet controller is blind to wired-only network segments — the switches, POS terminals, industrial controllers, CCTV backbones, and building access systems that specifically do not run Wi-Fi.

W5500 closes that gap with four SPI lines. No RMII, no external clock, no PHY layout constraints. On a handheld board with limited I/O, that matters.

🔷 Integration mode: SPI Ethernet interface via esp_eth

In Bruce, W5500 is integrated through ESP-IDF's esp_eth and esp_netif layers rather than through WIZnet's ioLibrary socket API. The initialization path in EthernetHelper.cpp is precise:

mac_spi = esp_eth_mac_new_w5500(&w5500_config, &mac_config_spi); phy_spi = esp_eth_phy_new_w5500(&phy_config_spi);

This places W5500 as an external MAC and PHY feeding into the ESP32's LwIP network stack via esp_netif. TCP/IP processing runs on the ESP32 side. W5500 provides the physical Ethernet path: frame transmission, reception, link status, and the RJ45 connection to the LAN.

This is a different pattern from the classic WIZnet use case (bare-metal MCU calling socket(), connect(), send() directly into the W5500 register map). Bruce uses W5500 as a network interface controller under a full IP stack, which suits a firmware environment running ARP scanners, DHCP clients, SSH sessions, and a Web UI simultaneously.

🔷 Why this design is the right choice for the platform

The board abstraction layer (bruceConfigPins.W5500_bus) means no feature module ever hard-codes an SPI pin. The ARP scanner in ARPScanner.cpp calls into the LwIP ARP table. The DHCP client is part of the network stack. The Web UI binds to whatever interface — Wi-Fi or Ethernet — is active.

This is what makes the W5500 support genuinely platform-level: it is not a standalone Ethernet sketch, it is a network interface that all existing Bruce modules can use transparently.

🔷 Verified implementation

• src/modules/ethernet/EthernetHelper.cpp — SPI bus initialization, W5500 MAC/PHY driver creation, esp_netif attachment, DHCP bring-up
• src/core/menu_items/EthernetMenu.cpp — dedicated menu entry, connection error handling
• src/modules/ethernet/ARPScanner.cpp — subnet sweep via etharp_request(), ARP table read
• src/modules/gps/wardriving.cpp, gps_tracker.cpp — W5500_bus conflict checks with GPS UART bus

05 — Key Components

🌐 WIZnet W5500 — Wired Ethernet Interface (SPI MAC+PHY mode)

Extends the platform from a Wi-Fi-only tool to one that can place itself directly on wired LAN segments. Connected via SPI to the ESP32; integrated through esp_eth / esp_netif / LwIP. Provides a stable physical link unaffected by wireless channel conditions, AP association state, or signal quality. Enabled per-board by populating W5500_bus pin assignments in board configuration.

🧠 ESP32 / ESP32-S3 — Application Core

Runs the entire software stack: UI rendering, menu system, Wi-Fi, BLE, TCP/IP (LwIP), file systems, JavaScript interpreter, USB HID, and all protocol module logic. PlatformIO build system with Arduino framework on ESP-IDF 5.x. Board-specific configuration is isolated in bruceConfigPins; protocol modules are board-agnostic.

📐 Board Abstraction Layer (bruceConfigPins)

The architectural element that makes one codebase run on 15+ devices. Defines named peripheral buses — W5500_bus, SDCARD_bus, NRF24_bus, CC1101_bus, gps_bus — populated differently per board. SPI bus sharing logic in EthernetHelper.cpp resolves conflicts at runtime.

📡 Wi-Fi, BLE, CC1101, PN532, NRF24, IR, USB HID

Each is a protocol module sitting above the board abstraction layer. All run on the same ESP32 core and are accessible from the same menu hierarchy.

📜 mQuickJS Scripting Engine

JavaScript interpreter embedded in firmware. Allows custom apps, automation scripts, and protocol-specific tools to be deployed and updated without reflashing. RF and Wi-Fi JavaScript APIs added in v1.15.

06 — Application Scenarios

01. Classroom reference platform for multi-protocol security education

Instructors covering network security, wireless protocols, and embedded systems can use Bruce as a single physical demonstration device. Rather than switching between a Wi-Fi dongle, an SDR receiver, an RFID reader, and a USB rubber ducky, the same board demonstrates all of them from one menu. The W5500 module adds wired LAN coverage for ARP, DHCP, and switch-level topics.

02. Baseline for hardware-specific ports

The Bruce codebase is designed to be forked and extended for specific hardware targets. Understanding the platform architecture — board abstraction, pin configuration, module composition — is the prerequisite for any hardware port. Theo's T-Embed CC1101 implementation (documented separately on WIZnet Makers) is a direct example: it populates the W5500_bus fields for a specific T-Embed pinout and runs the same Ethernet modules with no changes to module code.

03. Starting point for firmware hardening projects

Joseph's HeavyButter fork (also documented on WIZnet Makers) hardened the Bruce runtime against the security risks that arise from its own power: WebUI authentication, script permissions, credential defaults, radio power-down behavior. That hardening work is only meaningful in the context of understanding what the base firmware exposes. Bruce's platform architecture is the baseline HeavyButter measures itself against.

04. Authorized wired + wireless network assessment

In a penetration testing engagement with explicit authorization, Bruce with W5500 covers network reconnaissance across both media: Wi-Fi scanning and packet capture on one interface, ARP host discovery and DHCP analysis on the wired segment. The portable form factor is suited to on-site assessment without a laptop.

05. ESP32 firmware architecture study

For embedded developers, Bruce's codebase is a concrete example of a multi-peripheral, multi-protocol firmware built on PlatformIO and ESP-IDF. The board abstraction pattern, the use of esp_eth for external Ethernet controllers, and the integration of LwIP into an application firmware are all directly applicable to other ESP32 projects.

Conclusion

Bruce is not a single-purpose ESP32 attack tool. It is the open-source platform that defines what a multi-protocol ESP32 security device looks like — and the architectural baseline that every fork, port, and hardening project builds on.

• ✅ PlatformIO + board abstraction layer enables one codebase to run on 15+ ESP32 devices
• ✅ Wi-Fi, BLE, Sub-GHz, RFID/NFC, IR, USB, and wired Ethernet in a single firmware
• ✅ W5500 integrated via esp_eth / esp_netif / LwIP — wired Ethernet as a first-class platform interface
• ✅ Dedicated Ethernet menu with ARP scanner, DHCP client, and MAC-level modules
• ✅ bruceConfigPins.W5500_bus abstraction makes Ethernet board-agnostic
• ✅ mQuickJS scripting engine for user-deployable apps without reflashing
• ✅ 6.1k GitHub stars, 2k forks, 99 contributors, 36 releases — actively maintained at scale
• ✅ Direct foundation for T-Embed CC1101 hardware port (Theo) and HeavyButter hardening fork (Joseph)
• ✅ Demonstrates W5500 as a platform-level network extension, not just an IoT connectivity module

07 — Similar Projects on WIZnet Makers

Two projects in the WIZnet Makers platform extend directly from the Bruce firmware platform documented here. Understanding Bruce is the prerequisite for understanding both.

T-EmbedCC1101 BruceUSB Firmware — Theo A hardware-specific implementation for the Lilygo T-Embed CC1101. Documents the exact W5500 pin mapping for this board (MOSI GPIO9, MISO GPIO10, SCK GPIO11, CS GPIO44, INT GPIO43), SPI Mode 0 configuration, and specific GPIO conflict considerations between W5500 and nRF24 peripherals. Includes code-level implementation notes from EthernetHelper.cpp and ARPScanner.cpp. Best read after understanding the base platform.

HeavyButter: A Hardened Bruce Firmware Fork — Joseph A security-hardened fork of Bruce addressing the runtime attack surface created by the platform's own capabilities — WebUI authentication, script permissions, credential defaults, radio power state. W5500 and Ethernet features are explicitly framed as ecosystem context. The hardening work is only meaningful relative to the base platform this document describes.

The three projects form a natural reading sequence: Bruce defines the platform → T-Embed shows how it lands on specific hardware → HeavyButter shows how the same platform surface is hardened for safer deployment.

Q&A

Q. What socket mode does W5500 use in Bruce?

Bruce uses W5500 via ESP-IDF's esp_eth_mac_new_w5500() and esp_eth_phy_new_w5500() — integrated as an external MAC and PHY under the ESP32's LwIP stack through esp_netif. Application code (ARP scanner, DHCP client, Web UI, SSH) uses the standard network API, not WIZnet's ioLibrary socket registers directly. This is SPI Ethernet interface mode, not the classic bare-metal TOE socket mode (Sn_MR_TCP, Sn_MR_UDP).

Q. Does Bruce work without a W5500 module?

Yes. W5500 is an optional peripheral. Boards without W5500_bus populated in their pin configuration skip Ethernet initialization. All other features function independently. The platform treats wired Ethernet as an additive capability, not a requirement.

Q. Why does the board abstraction layer matter for W5500?

Because it is what allows Theo's T-Embed implementation to use W5500 with a specific pinout, and a different board to use W5500 with entirely different pins, while running exactly the same ARPScanner.cpp and EthernetMenu.cpp code. The abstraction is the mechanism that makes the wired Ethernet feature platform-wide rather than board-specific.

Q. What does Bruce's WIZnet usage demonstrate beyond typical IoT use?

Most WIZnet Makers projects use W5500 to connect an embedded device to the internet — a sensor publishing MQTT, a controller serving HTTP, a Modbus gateway. Bruce inverts the direction: the device uses W5500 to observe and analyze the LAN it is connected to. ARP discovery, DHCP inspection, and port scanning are tools for understanding a network, not for joining one. This is W5500 used as a diagnostic and assessment interface, not a connectivity interface.

Original Link: https://github.com/BruceDevices/firmware

Bruce Firmware — ESP32 보안 멀티툴 펌웨어 플랫폼

#BruceFirmware #ESP32 #W5500 #Ethernet #SecurityPlatform #PlatformIO #OpenSource #RedTeam #WIZnet #MultiProtocol

📚 컨텍스트: 활발히 유지보수되는 오픈소스 ESP32 보안 펌웨어 플랫폼. M5Stack Cardputer, M5StickC, M5Core, LilyGo T-Embed, T-Deck, CYD 등 다수의 ESP32 장치를 지원한다. 레드팀 작업을 위한 offensive firmware로 정의하며, Wi-Fi·BLE·Sub-GHz·RFID/NFC·IR·USB·Ethernet을 하나의 휴대용 인터페이스에 통합한다. 최신 공개 릴리스: v1.15. W5500 실사용 확인: src/modules/ethernet/EthernetHelper.cpp, EthernetMenu.cpp, ARPScanner.cpp

01 — 이 프로젝트는 무엇인가?

회사나 건물의 보안을 점검할 때, "우리 시스템이 공격받으면 어떻게 되나"를 미리 실험하는 사람들이 있다. 이를 레드팀이라고 부른다.

레드팀이 현장에서 실제로 확인하는 질문들은 이런 것들이다.

• 이 건물 Wi-Fi가 뚫리나?
• RFID 출입카드가 복제되나?
• 유선 네트워크 포트에 꽂으면 내부에서 뭐가 보이나?
• USB를 꽂으면 PC가 어떻게 반응하나?

Bruce는 이 질문들을 손바닥만한 기기 하나로 현장에서 확인하는 도구다.

휴대용 보안 툴은 오랫동안 프로토콜별로 분리되어 있었다.

Wi-Fi 분석에는 노트북이나 ESP32 Marauder 계열 장치가 필요하고, Sub-GHz 신호에는 CC1101 장치가 필요하다. RFID와 NFC에는 PN532나 MFRC522가 필요하며, 적외선·BLE·USB 키보드 에뮬레이션마다 별도의 도구가 필요하다. Flipper Zero가 이 분산을 일부 해결했지만, 고정된 하드웨어 스펙과 높은 가격이 제약이 됐다.

Bruce는 다른 전제에서 출발했다. ESP32 생태계는 이미 멀티 프로토콜 보안 툴을 구성하기에 충분한 처리 능력·무선 인터페이스·모듈식 주변장치 지원을 갖추고 있다. 핵심 질문은 하나였다: 하나의 펌웨어가 ESP32 장치 시장의 하드웨어 다양성 — 다양한 MCU 변형, 디스플레이 컨트롤러, 입력 방식, 스토리지 구성 — 을 추상화하면서도 지원하는 모든 보드에 일관된 기능을 제공할 수 있는가?

해답은 PlatformIO 기반 펌웨어 아키텍처다. 보드 수준의 하드웨어 추상화 계층과 프로토콜 수준의 기능 모듈을 분리한다. Cardputer, T-Embed, CYD, 베어 ESP32-S3 DevKit이 모두 같은 코드베이스를 실행한다. 각 보드의 디스플레이 드라이버, 버튼 매핑, SPI 버스 할당, 주변장치 가용성은 보드 구성 파일에 캡슐화된다. 그 위에서 기능 모듈 — Wi-Fi, BLE, RF, RFID, IR, USB, Ethernet, 스크립팅 — 은 한 번 작성되고 빌드 대상별로 다르게 조합된다.

결과물은 단일 애플리케이션이 아닌 펌웨어 플랫폼이다. 이 구분이 Bruce 자체뿐 아니라, 그 주변에서 성장한 포크와 하드웨어별 구현체들을 이해하는 데 핵심이 된다.

02 — 왜 플랫폼 아키텍처인가?

🔷 단일 프로토콜 ESP32 보안 툴의 한계

대부분의 ESP32 보안 프로젝트는 하나의 프로토콜이나 하나의 공격 클래스를 중심으로 만들어진다. 해당 용도에는 잘 작동하지만 범용성이 없다. Wi-Fi 패킷 캡처에서 RFID 태그 분석으로, Sub-GHz 재생으로 이동할 때마다 장치, 펌웨어, 사고방식을 바꿔야 한다.

Bruce의 모듈식 아키텍처는 이 맥락 전환을 없애기 위해 설계됐다. 메뉴 시스템이 모든 프로토콜 도메인을 통합 인터페이스로 제공한다. 보드 추상화 계층 덕분에 같은 Wi-Fi 코드, 같은 RFID 읽기 경로, 같은 Ethernet 스캐너가 주머니 속 Cardputer부터 탁상용 CYD 패널까지 동일하게 실행된다.

🔷 설계의 핵심: 보드 추상화 계층

bruceConfigPins 구조체가 아키텍처의 핵심이다. W5500 Ethernet 컨트롤러를 포함한 모든 주변장치는 하드코딩된 GPIO 번호가 아니라 이 핀 구성 객체를 통해 접근된다. Theo의 T-Embed CC1101 구현이 W5500의 특정 SPI 핀(MOSI GPIO9, MISO GPIO10, SCK GPIO11, CS GPIO44, INT GPIO43)을 문서화할 수 있는 것은, 플랫폼이 W5500_bus라는 이름의 슬롯을 제공하고 어떤 보드든 다르게 채울 수 있기 때문이다.

이는 우연이 아니다. 핵심 모듈을 fork 없이 15개 이상의 지원 보드에서 실행하게 만드는 명시적 설계다.

🔷 확장성은 첫 번째 기능

Bruce는 JavaScript 인터프리터(mQuickJS)를 내장한다. 사용자는 펌웨어를 다시 컴파일하지 않고도 새로운 앱 로직을 작성하고 배포할 수 있다. 이 확장성은 Joseph의 HeavyButter 하드닝 포크의 토대가 됐다 — 기능을 추가하기 쉬운 모듈식 구조가 동시에 명시적인 보안 강화가 필요한 큰 런타임 공격 표면을 만들기 때문이다.

03 — 시스템 아키텍처

04 — 왜 WIZnet W5500인가? ⭐

🔷 Wi-Fi가 닿지 않는 영역을 채운다

ESP32는 설계상 Wi-Fi와 BLE 장치다. 대부분의 양산 보드에서 유선 Ethernet MAC과 PHY를 기본으로 제공하지 않는다. 결과적으로 외부 Ethernet 컨트롤러 없는 ESP32 기반 보안 툴은 유선 전용 네트워크 세그먼트 — 스위치, POS 단말, 산업용 컨트롤러, CCTV 백본, 출입 시스템 — 을 볼 수 없다.

W5500은 SPI 4선만으로 이 공백을 채운다. RMII, 외부 클럭, PHY 레이아웃 제약이 없다. I/O가 제한된 휴대용 보드에서 이 단순함이 결정적이다.

🔷 통합 방식: esp_eth 경유 SPI Ethernet 인터페이스

Bruce에서 W5500은 WIZnet ioLibrary 소켓 API가 아닌 ESP-IDF의 esp_eth와 esp_netif 계층을 통해 통합된다. EthernetHelper.cpp의 초기화 경로가 이를 명확히 보여준다:

mac_spi = esp_eth_mac_new_w5500(&w5500_config, &mac_config_spi); phy_spi = esp_eth_phy_new_w5500(&phy_config_spi);

W5500을 ESP32의 LwIP 네트워크 스택에 연결되는 외부 MAC·PHY로 사용하는 구조다. TCP/IP 처리는 ESP32 측에서 실행되고, W5500은 물리적 Ethernet 경로(프레임 송수신, 링크 상태, RJ45 연결)를 담당한다.

이는 MCU가 W5500 레지스터 맵에 직접 socket(), connect(), send()를 호출하는 전형적인 TOE 소켓 구조와 다르다. ARP 스캐너, DHCP 클라이언트, SSH 세션, Web UI가 동시에 동작하는 펌웨어 환경에 적합한 설계다.

🔷 플랫폼 수준의 Ethernet 지원

bruceConfigPins.W5500_bus 추상화 덕분에 어떤 기능 모듈도 SPI 핀을 하드코딩하지 않는다. ARPScanner.cpp는 LwIP ARP 테이블을 호출하고, DHCP 클라이언트는 네트워크 스택의 일부이며, Web UI는 활성화된 인터페이스(Wi-Fi 또는 Ethernet)에 자동으로 바인딩된다.

W5500 지원이 단독 Ethernet 스케치가 아니라 모든 Bruce 모듈이 투명하게 사용할 수 있는 네트워크 인터페이스로 동작하는 이유가 여기에 있다.

🔷 검증된 구현

• src/modules/ethernet/EthernetHelper.cpp — SPI 버스 초기화, W5500 MAC/PHY 드라이버 생성, esp_netif 연결, DHCP 시작
• src/core/menu_items/EthernetMenu.cpp — 전용 메뉴 진입점, 연결 오류 처리
• src/modules/ethernet/ARPScanner.cpp — etharp_request()를 통한 서브넷 스윕, ARP 테이블 읽기
• src/modules/gps/wardriving.cpp, gps_tracker.cpp — GPS UART 버스와의 W5500_bus 충돌 검사

05 — 핵심 구성요소

🌐 WIZnet W5500 — 유선 Ethernet 인터페이스 (SPI MAC+PHY 모드)

플랫폼을 Wi-Fi 전용 툴에서 유선 LAN 세그먼트까지 직접 접근할 수 있는 툴로 확장한다. SPI로 ESP32에 연결되며, esp_eth / esp_netif / LwIP를 통해 통합된다. 무선 채널 상태, AP 연결 상태, 신호 세기의 영향을 받지 않는 안정적인 물리 링크를 제공한다. 보드 구성의 W5500_bus 핀 할당으로 보드별로 활성화된다.

🧠 ESP32 / ESP32-S3 — 애플리케이션 코어

전체 소프트웨어 스택을 실행한다: UI 렌더링, 메뉴 시스템, Wi-Fi, BLE, TCP/IP(LwIP), 파일 시스템, JavaScript 인터프리터, USB HID, 모든 프로토콜 모듈 로직. ESP-IDF 5.x 기반 PlatformIO + Arduino 프레임워크. 보드별 구성은 bruceConfigPins에 격리되고 프로토콜 모듈은 보드 독립적이다.

📐 보드 추상화 계층 (bruceConfigPins)

하나의 코드베이스가 15개 이상의 장치에서 실행되게 하는 아키텍처 요소. W5500_bus, SDCARD_bus, NRF24_bus, CC1101_bus, gps_bus를 이름 있는 주변장치 버스로 정의하고, 보드마다 다르게 채운다. EthernetHelper.cpp의 SPI 버스 공유 로직이 런타임에 충돌을 해소한다.

📜 mQuickJS 스크립팅 엔진

펌웨어에 내장된 JavaScript 인터프리터. 리플래싱 없이 사용자 정의 앱, 자동화 스크립트, 프로토콜별 툴을 배포하고 업데이트할 수 있다.

06 — 활용 시나리오

01. 멀티 프로토콜 보안 교육의 기준 플랫폼

Wi-Fi 동글, SDR 수신기, RFID 리더, USB 고무 오리를 각각 준비하는 대신, Bruce 하나로 같은 메뉴에서 모든 것을 시연한다. W5500 모듈이 ARP, DHCP, 스위치 수준의 유선 LAN 주제까지 커버한다.

02. 하드웨어별 포트의 출발점

Bruce 코드베이스는 특정 하드웨어 대상을 위해 포크하고 확장하도록 설계됐다. 보드 추상화, 핀 구성, 모듈 조합을 이해하는 것이 모든 하드웨어 포트의 전제조건이다. Theo의 T-Embed CC1101 구현(WIZnet Makers에 별도 문서화)이 직접적인 사례다.

03. 펌웨어 보안 강화 프로젝트의 베이스라인

Joseph의 HeavyButter 포크(WIZnet Makers에 별도 문서화)는 Bruce 런타임이 노출하는 보안 위험 — WebUI 인증, 스크립트 권한, 자격증명 기본값, 라디오 전원 동작 — 을 강화한다. 이 강화 작업은 기본 펌웨어가 무엇을 노출하는지 이해하는 맥락에서만 의미가 있다. Bruce 플랫폼 아키텍처가 HeavyButter가 측정하는 베이스라인이다.

04. ESP32 펌웨어 아키텍처 학습

임베디드 개발자에게 Bruce 코드베이스는 PlatformIO와 ESP-IDF 기반의 멀티 주변장치·멀티 프로토콜 펌웨어의 구체적인 사례다. 보드 추상화 패턴, 외부 Ethernet 컨트롤러를 위한 esp_eth 사용, LwIP의 애플리케이션 펌웨어 통합은 모두 다른 ESP32 프로젝트에 직접 적용 가능하다.

결론

Bruce는 단일 목적의 ESP32 공격 툴이 아니다. 멀티 프로토콜 ESP32 보안 장치가 어떤 모습이어야 하는지를 정의하는 오픈소스 플랫폼이며, 모든 포크·포트·강화 프로젝트가 구축되는 아키텍처 기반이다.

• ✅ PlatformIO + 보드 추상화 계층으로 하나의 코드베이스가 15개 이상의 ESP32 장치에서 실행
• ✅ Wi-Fi, BLE, Sub-GHz, RFID/NFC, IR, USB, 유선 Ethernet을 단일 펌웨어에 통합
• ✅ W5500을 esp_eth / esp_netif / LwIP를 통해 통합 — 유선 Ethernet이 플랫폼 수준의 인터페이스
• ✅ ARP 스캐너, DHCP 클라이언트, MAC 수준 모듈을 갖춘 전용 Ethernet 메뉴
• ✅ bruceConfigPins.W5500_bus 추상화로 Ethernet이 보드 독립적으로 동작
• ✅ 리플래싱 없이 사용자 정의 앱 배포를 위한 mQuickJS 스크립팅 엔진
• ✅ GitHub 6,100 스타, 2,000 포크, 99명 기여자, 36 릴리스 — 대규모로 활발히 유지보수
• ✅ T-Embed CC1101 하드웨어 포트(Theo)와 HeavyButter 강화 포크(Joseph)의 직접적 기반
• ✅ W5500이 단순 IoT 연결 모듈이 아닌 플랫폼 수준의 네트워크 확장으로 사용되는 사례

07 — WIZnet Makers 내 연관 프로젝트

WIZnet Makers 플랫폼에는 Bruce 펌웨어 플랫폼에서 직접 파생된 두 프로젝트가 있다. Bruce를 이해하는 것이 두 프로젝트를 이해하기 위한 전제조건이다.

T-EmbedCC1101 BruceUSB Firmware — Theo Lilygo T-Embed CC1101을 위한 하드웨어별 구현. 이 보드의 정확한 W5500 핀 매핑(MOSI GPIO9, MISO GPIO10, SCK GPIO11, CS GPIO44, INT GPIO43), SPI Mode 0 구성, W5500과 nRF24 주변장치 간의 GPIO 충돌 고려사항을 문서화한다. EthernetHelper.cpp와 ARPScanner.cpp의 코드 수준 구현 내용 포함. 기본 플랫폼 이해 후 읽을 것.

HeavyButter: A Hardened Bruce Firmware Fork — Joseph Bruce의 런타임 공격 표면을 강화하는 보안 포크. WebUI 인증, 스크립트 권한, 자격증명 기본값, 라디오 전원 상태를 다룬다. W5500과 Ethernet 기능은 명시적으로 생태계 맥락으로만 언급된다. 강화 작업은 이 문서가 설명하는 기본 플랫폼과 상대적으로만 의미가 있다.

세 프로젝트는 자연스러운 독서 순서를 형성한다: Bruce가 플랫폼을 정의하고 → T-Embed가 특정 하드웨어에 어떻게 구현되는지 보여주고 → HeavyButter가 같은 플랫폼 표면이 어떻게 안전하게 강화되는지 보여준다.

Q&A

Q. Bruce에서 W5500은 어떤 소켓 모드를 사용하는가?

ESP-IDF의 esp_eth_mac_new_w5500()과 esp_eth_phy_new_w5500()을 통해 ESP32의 LwIP 스택에 esp_netif로 연결되는 외부 MAC·PHY로 통합된다. 애플리케이션 코드(ARP 스캐너, DHCP 클라이언트, Web UI, SSH)는 WIZnet ioLibrary 소켓 레지스터가 아닌 표준 네트워크 API를 사용한다. 이는 SPI Ethernet 인터페이스 모드로, 전형적인 베어메탈 TOE 소켓 모드(Sn_MR_TCP, Sn_MR_UDP)와 다르다.

Q. W5500 모듈 없이도 Bruce가 동작하는가?

그렇다. W5500은 선택적 주변장치다. 보드 핀 구성에 W5500_bus가 없으면 Ethernet 초기화를 건너뛴다. 다른 모든 기능은 독립적으로 동작한다.

Q. 보드 추상화 계층이 W5500에서 왜 중요한가?

Theo의 T-Embed 구현이 특정 핀아웃으로 W5500을 사용하고, 다른 보드가 완전히 다른 핀으로 W5500을 사용하면서도 정확히 같은 ARPScanner.cpp와 EthernetMenu.cpp 코드를 실행할 수 있는 메커니즘이 바로 이 추상화이기 때문이다.

Q. Bruce의 WIZnet 사용이 일반 IoT 사용과 어떻게 다른가?

대부분의 WIZnet Makers 프로젝트는 W5500을 이용해 임베디드 장치를 인터넷에 연결한다 — 센서의 MQTT 발행, HTTP 서버, Modbus 게이트웨이. Bruce는 방향을 뒤집는다: 장치가 W5500을 통해 연결된 LAN을 관찰하고 분석한다. ARP 탐색, DHCP 검사, 포트 스캐닝은 네트워크에 합류하는 도구가 아니라 네트워크를 이해하는 도구다. W5500이 연결 인터페이스가 아닌 진단·평가 인터페이스로 사용되는 사례다.