Commit dd33723

orion-rfdd33723

docs: add Rust toolchain setup, dual-build, and cleanup to README

Document the project-local layout (ESP-IDF in ./.embuild, LIBCLANG_PATH in
.cargo/config.toml instead of ~/export-esp.sh), the dual cargo/pio build
workflow, the cmake-file-api clean-rebuild fix, and tiered uninstall steps.

Author: krolyxon
Date: 2026-10-21 16:15 +0530
Parent: ab699e4
Commit: dd337234c0f2f4a515da8f03d146fcccc7f73a94

+158 −8

2 files changed

Browse files Patch

−Context 3+

M .cargo/config.toml +3 −0
M README.md +155 −8

M .cargo/config.toml View

M README.md View

		@@ -13,6 +13,9 @@ build-std = ["std", "panic_abort"]
13	13		MCU = "esp32s3"
14	14		ESP_IDF_VERSION = "v5.5.3"
15	15		ESP_IDF_TOOLS_INSTALL_DIR = "workspace"
	16	+	# Replaces ~/export-esp.sh — bindgen (esp-idf-sys) needs libclang from the esp toolchain.
	17	+	# Version-pinned: update the esp-20.1.1_* segment after an `espup update`.
	18	+	LIBCLANG_PATH = "/home/k/.local/share/rustup/toolchains/esp/xtensa-esp32-elf-clang/esp-20.1.1_20250829/esp-clang/lib"
16	19
17	20		# Uncomment this if you have moved the target dir by setting CARGO_TARGET_DIR or similar.
18	21		# Required for now due to embuild limitations.

		@@ -1,25 +1,54 @@
1	1		<div align="center">
2	2		<img src="assets/logo.png" width="250" alt="Orion RF Logo" />
3		−	<p>Portable RF & Wireless Toolkit for ESP32</p>
	3	+	<p>Portable RF & Wireless <b>Signal-Testing</b> Toolkit for ESP32 — Laboratory Use Only</p>
4	4		</div>
5	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.
6	30
7	31		## Features
8	32
	33	+	All features are intended for laboratory signal testing against owned/authorized equipment.
	34	+
9	35		### Wireless
10	36		- BLE scanning
11	37		- WiFi scanning
12		−	- WiFi analyzer
	38	+	- WiFi analyzer (spectrum/channel activity)
13	39		- RF capture (WIP)
14	40		- RF replay (planned)
15	41
16		−	### NRF24
	42	+	### NRF24 — Interference / Robustness Testing
17	43		- BLE interference testing
18	44		- Bluetooth interference testing
19	45		- WiFi interference testing
20	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	+
21	50		### HID
22		−	- BadUSB keyboard emulation
	51	+	- BadUSB keyboard emulation (HID input testing)
23	52		- BLE mouse emulation
24	53
25	54		### Utilities
		@@ -39,6 +68,10 @@
39	68
40	69		## Status
41	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	+
42	75		\| Feature \| Status \|
43	76		\|---\|---\|
44	77		\| BLE Scan \| Working \|
		@@ -46,9 +79,9 @@
46	79		\| WiFi Analyzer \| Working \|
47	80		\| BadUSB \| Working \|
48	81		\| BLE Mouse \| Working \|
49		−	\| BLE Jammer \| Working \|
50		−	\| Bluetooth Jammer \| Working \|
51		−	\| WiFi Jammer \| Working \|
	82	+	\| BLE Interference Test \| Working \|
	83	+	\| Bluetooth Interference Test \| Working \|
	84	+	\| WiFi Interference Test \| Working \|
52	85		\| RF Capture \| WIP \|
53	86		\| RF Replay \| WIP \|
54	87		\| SD Card Support \| Planned \|
		@@ -82,9 +115,123 @@ git clone https://github.com/krolyxon/orion-rf.git
82	115		cd orion-rf
83	116		```
84	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	+
85	165		#### Build & Upload Firmware
86	166
87	167		```bash
88		−	pio run -t upload
	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
89	185		```
90	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	+	```

orion-rf/dd33723

docs: add Rust toolchain setup, dual-build, and cleanup to README

orion-rfdd33723