| 1 | <div align="center"> |
| 2 | <img src="assets/logo.png" width="250" alt="Orion RF Logo" /> |
| 3 | <p>Portable RF & Wireless <b>Signal-Testing</b> Toolkit for ESP32 — Laboratory Use Only</p> |
| 4 | </div> |
| 5 | |
| 6 | ## Purpose & Scope |
| 7 | |
| 8 | ORION-RF is a **bench/laboratory signal-testing instrument** for ESP32-S3. It is built for |
| 9 | **authorized RF and wireless engineering, education, and security research** in a controlled |
| 10 | environment — characterizing radios, measuring the spectrum, and testing the resilience of |
| 11 | *your own* devices on *your own* bench. |
| 12 | |
| 13 | It is **not** a consumer or field device. Every feature is intended to be exercised against |
| 14 | equipment you own or are explicitly authorized to test, inside an RF-controlled space |
| 15 | (e.g. a shielded enclosure / RF test bench), with transmit features kept off the air. |
| 16 | |
| 17 | ## Intended Use & Responsible Operation |
| 18 | |
| 19 | - ✅ **Authorized lab testing only** — on hardware you own or have written permission to test. |
| 20 | - ✅ **Controlled RF environment** — keep transmit/interference features inside a shielded |
| 21 | enclosure or on a wired/attenuated test link so no third-party or licensed spectrum is affected. |
| 22 | - ✅ **Education & research** — understanding wireless protocols, RF capture/replay, HID, NFC. |
| 23 | - ❌ **Not for use against devices, networks, or people you do not own or are not authorized |
| 24 | to test**, and not for operation on open/public airwaves. |
| 25 | |
| 26 | Operating radio transmitters may be **regulated in your jurisdiction** (e.g. FCC / CE / local |
| 27 | spectrum rules). The operator is solely responsible for lawful, authorized use. This project |
| 28 | is provided for legitimate testing and research under the terms of its [LICENSE](LICENSE); the |
| 29 | authors accept no liability for misuse. |
| 30 | |
| 31 | ## Features |
| 32 | |
| 33 | All features are intended for laboratory signal testing against owned/authorized equipment. |
| 34 | |
| 35 | ### Wireless |
| 36 | - BLE scanning |
| 37 | - WiFi scanning |
| 38 | - WiFi analyzer (spectrum/channel activity) |
| 39 | - RF capture (WIP) |
| 40 | - RF replay (planned) |
| 41 | |
| 42 | ### NRF24 — Interference / Robustness Testing |
| 43 | - BLE interference testing |
| 44 | - Bluetooth interference testing |
| 45 | - WiFi interference testing |
| 46 | |
| 47 | > These exercise a device-under-test's resilience to RF interference on the 2.4 GHz band and |
| 48 | > are meant for a shielded bench only. |
| 49 | |
| 50 | ### HID |
| 51 | - BadUSB keyboard emulation (HID input testing) |
| 52 | - BLE mouse emulation |
| 53 | |
| 54 | ### Utilities |
| 55 | - System information |
| 56 | - Hardware diagnostics |
| 57 | - Device restart |
| 58 | |
| 59 | ## Hardware |
| 60 | - ESP32-S3 N16R8 |
| 61 | - 2x NRF24L01 Module |
| 62 | - 2x CC1101 Module |
| 63 | - PN532 NFC Module |
| 64 | - MicroSD card Module |
| 65 | - TP4056 Charging Module |
| 66 | - OLED display |
| 67 | - Battery-powered portable setup |
| 68 | |
| 69 | ## Status |
| 70 | |
| 71 | > **Note:** the firmware is being rewritten from the Arduino/PlatformIO build to **Rust on |
| 72 | > `std` ESP-IDF**. The table below reflects the feature set (parity target for the rewrite). |
| 73 | > See `CLAUDE.md` for the rewrite architecture and phased plan. |
| 74 | |
| 75 | | Feature | Status | |
| 76 | |---|---| |
| 77 | | BLE Scan | Working | |
| 78 | | WiFi Scan | Working | |
| 79 | | WiFi Analyzer | Working | |
| 80 | | BadUSB | Working | |
| 81 | | BLE Mouse | Working | |
| 82 | | BLE Interference Test | Working | |
| 83 | | Bluetooth Interference Test | Working | |
| 84 | | WiFi Interference Test | Working | |
| 85 | | RF Capture | WIP | |
| 86 | | RF Replay | WIP | |
| 87 | | SD Card Support | Planned | |
| 88 | | Emulator | Planned | |
| 89 | | NFC | WIP | |
| 90 | |
| 91 | |
| 92 | ## Installation |
| 93 | |
| 94 | ### End User Installation |
| 95 | |
| 96 | The easiest way to install ORION-RF is through the web installer. |
| 97 | |
| 98 | 1. Connect your ESP32-S3 to your computer using a USB cable. |
| 99 | 2. Open the installer page: |
| 100 | * https://krolyxon.github.io/orion-rf/ |
| 101 | 3. Click **Connect** and select your device. |
| 102 | 4. Click **Install** and wait for the flashing process to complete. |
| 103 | 5. Reboot the device if required. |
| 104 | |
| 105 | > Google Chrome, Microsoft Edge, and other Chromium-based browsers are recommended. It may or may not work on Firefox based browsers. |
| 106 | |
| 107 | --- |
| 108 | |
| 109 | ### Development Build |
| 110 | |
| 111 | #### Clone the Repository |
| 112 | |
| 113 | ```bash |
| 114 | git clone https://github.com/krolyxon/orion-rf.git |
| 115 | cd orion-rf |
| 116 | ``` |
| 117 | |
| 118 | #### Toolchain Setup |
| 119 | |
| 120 | The Rust rewrite targets **`std` ESP-IDF on Xtensa** (`xtensa-esp32s3-espidf`), which needs the |
| 121 | Espressif Rust toolchain (`espup` + the `esp` rustup channel), the ESP-IDF v5.5.3 SDK, and |
| 122 | `espflash`/`ldproxy`. |
| 123 | |
| 124 | 1. **Prerequisites** — `rustup`, plus the host packages ESP-IDF needs to build. On Arch: |
| 125 | ```bash |
| 126 | sudo pacman -S --needed git wget flex bison gperf python \ |
| 127 | cmake ninja ccache dfu-util libusb libffi openssl pkgconf |
| 128 | ``` |
| 129 | (`pkgconf` + the `systemd` libudev library — part of a base Arch install — are what |
| 130 | `espflash` links against on Linux.) |
| 131 | |
| 132 | 2. **Install `espup`** and set up the `esp` toolchain: |
| 133 | ```bash |
| 134 | cargo install espup --locked |
| 135 | espup install |
| 136 | ``` |
| 137 | This installs the `esp` rustc toolchain into `RUSTUP_HOME` (shared across projects) and writes |
| 138 | a `~/export-esp.sh`. **You do not need that script for this repo** — `LIBCLANG_PATH` is already |
| 139 | set in `.cargo/config.toml`, so you can delete it (see Cleaning Up below). |
| 140 | |
| 141 | 3. **Install the flasher and linker shim:** |
| 142 | ```bash |
| 143 | cargo install espflash ldproxy --locked |
| 144 | ``` |
| 145 | |
| 146 | 4. **Build** from the repo root — the ESP-IDF SDK (~4.4 GB) downloads into `./.embuild/` on the |
| 147 | first build and is reused afterwards: |
| 148 | ```bash |
| 149 | cargo build --release |
| 150 | ``` |
| 151 | |
| 152 | This project is configured to stay **self-contained** — the heavy, project-specific pieces live |
| 153 | inside the repo instead of cluttering your home directory: |
| 154 | |
| 155 | - **ESP-IDF SDK + its tools (~4.4 GB)** install into `./.embuild/` (not `~/.espressif`), because |
| 156 | `.cargo/config.toml` sets `ESP_IDF_TOOLS_INSTALL_DIR = "workspace"`. Already gitignored. |
| 157 | - **`LIBCLANG_PATH`** (needed by `bindgen`) is set in `.cargo/config.toml`'s `[env]` block, so you |
| 158 | do **not** need to `source ~/export-esp.sh` — a plain `cargo build` picks it up. If you ran |
| 159 | `espup install` and it created `~/export-esp.sh`, you can delete it. The path is version-pinned; |
| 160 | after an `espup update`, bump the `esp-clang` version segment in `.cargo/config.toml`. |
| 161 | - The **`esp` rustc toolchain (~1.8 GB)** is a normal rustup toolchain and lives in `RUSTUP_HOME` |
| 162 | (e.g. `~/.local/share/rustup/toolchains/esp`). It is intentionally **shared** across all ESP |
| 163 | projects — `rust-toolchain.toml` (`channel = "esp"`) selects it automatically. |
| 164 | |
| 165 | #### Build & Upload Firmware |
| 166 | |
| 167 | ```bash |
| 168 | cargo run --release # builds and flashes + opens the serial monitor |
| 169 | cargo build --release # build only |
| 170 | ``` |
| 171 | |
| 172 | #### Repository Layout & Dual Build |
| 173 | |
| 174 | During the rewrite, the Rust and Arduino firmwares live side by side in one repo. The Rust tree |
| 175 | is primary (at the root, where most Rust projects put it); the Arduino tree is kept only as a |
| 176 | 1:1 parity reference and is removed once the rewrite is verified on hardware. |
| 177 | |
| 178 | ``` |
| 179 | orion-rf/ |
| 180 | ├── src/ # Rust firmware (active) — Cargo reads this |
| 181 | ├── src-arduino/ # original Arduino firmware (reference only) |
| 182 | ├── lib-arduino/ # Arduino libraries (renamed from lib/ to be explicit) |
| 183 | ├── Cargo.toml build.rs rust-toolchain.toml sdkconfig.defaults |
| 184 | └── platformio.ini # points PlatformIO at the -arduino/ trees |
| 185 | ``` |
| 186 | |
| 187 | The two build systems don't collide because each is told where to look: |
| 188 | |
| 189 | | Firmware | Command | Reads | |
| 190 | |---|---|---| |
| 191 | | **Rust (active)** | `cargo build` / `cargo run` | `src/`, `Cargo.toml` | |
| 192 | | **Arduino (reference)** | `pio run` / `pio run -t upload` | `src-arduino/`, `lib-arduino/` | |
| 193 | |
| 194 | PlatformIO is redirected to the renamed trees via the `[platformio]` section of |
| 195 | `platformio.ini`: |
| 196 | |
| 197 | ```ini |
| 198 | [platformio] |
| 199 | src_dir = src-arduino |
| 200 | lib_dir = lib-arduino |
| 201 | ``` |
| 202 | |
| 203 | > The Arduino build is retained only for parity reference and will be deleted in a final cleanup |
| 204 | > commit once the Rust firmware is verified on hardware. |
| 205 | |
| 206 | #### Troubleshooting |
| 207 | |
| 208 | - **`Error: Failed to list cmake-file-api reply directory` / `No such file or directory`** — |
| 209 | usually a stale ESP-IDF build dir after moving files or switching toolchains. Do a clean |
| 210 | rebuild: |
| 211 | ```bash |
| 212 | rm -rf target .embuild |
| 213 | cargo build --release |
| 214 | ``` |
| 215 | |
| 216 | #### Uninstalling / Cleaning Up |
| 217 | |
| 218 | To reclaim space, work from least to most destructive: |
| 219 | |
| 220 | ```bash |
| 221 | # 1. Project build artifacts (safe; regenerated on next build) |
| 222 | cargo clean # removes ./target |
| 223 | rm -rf .embuild # removes the project's ESP-IDF SDK + tools (~4.4 GB) |
| 224 | rm -rf .pio .cache # legacy PlatformIO + clangd caches |
| 225 | |
| 226 | # 2. Stray file espup may have dropped in your home dir (not used by this project) |
| 227 | rm -f ~/export-esp.sh |
| 228 | ``` |
| 229 | |
| 230 | Because everything project-specific lives under the repo, deleting the repo directory removes |
| 231 | the SDK and build output with it. The only things left outside are the shared, global installs: |
| 232 | |
| 233 | ```bash |
| 234 | # 3. Global toolchains — ONLY if you have no other ESP projects |
| 235 | espup uninstall # removes the `esp` rustup toolchain (~1.8 GB) |
| 236 | cargo uninstall espflash ldproxy # remove the flasher/linker helpers |
| 237 | ``` |