How to Install RuView: A Step-by-Step WiFi Radar Setup Guide

Hardware Checklist & Board Comparison

Before we get our hands dirty with flashing firmware and writing terminal commands, we must establish a rock-solid foundation by gathering the correct hardware. At its core, RuView works on a bi-directional wireless telemetry network, which means you need at least two physical devices: a transmitter (Tx) node and a receiver (Rx) node.

The transmitter is placed on one side of the monitoring area and acts as a beacon, constantly firing standard IEEE 802.11 WiFi packets into the ether at a steady, high-frequency rate (we recommend 100 Hz). The receiver is placed on the opposite side of the room. It sniffs the air, captures these incoming packets, extracts the raw Orthogonal Frequency-Division Multiplexing (OFDM) channel responses (which are mapped as Channel State Information matrices), and streams them over a USB serial connection to your local AI engine.

For high-fidelity spatial intelligence, choosing the right chip matters immensely. Many beginners mistakenly buy cheap, generic clones that suffer from poor antenna layout or insufficient memory, leading to terrible Signal-to-Noise Ratios (SNR) that completely mask subtle chest motions or slow walking speeds. We strongly advise using the ESP32-S3 DevKitC series. The ESP32-S3 has dual-core Xtensa LX7 processors with built-in vector instruction extensions. These extensions provide hardware-level acceleration for matrix and floating-point computations, making the ESP32-S3 uniquely equipped to capture high-bandwidth CSI telemetry with virtually zero packet loss.

Here is a comprehensive comparative breakdown of the most common microcontrollers available in the market today:

Figure 1: High-fidelity conceptual render analyzing How to Install RuView: A Step-by-Step WiFi Radar Setup Guide.

Compiling and Flashing the ESP32 Firmware

Once you have your transmitter and receiver microcontrollers sitting on your desk, the next step is flashing the custom RuView CSI logging firmware. The firmware configures the transmitter board to act as a beacon and the receiver board to operate in 'promiscuous' sniffing mode, logging the packet preamble of every incoming IEEE 802.11 frames.

To compile and upload the firmware, you will need the official Espressif IoT Development Framework (ESP-IDF) installed on your system. We strongly recommend using ESP-IDF version 5.1 or later, as it fully supports the advanced vector processing instructions of the ESP32-S3 series. Before running the compiler, ensure you have connected the microcontroller to your computer using a high-quality USB data cable. Note: Avoid cheap charging-only USB cables, as they lack the critical D+ and D- data wires, causing esptool to throw connection timeout errors.

Let's open up a shell and execute the compilation and flashing sequence:

# Step 1: Open terminal and clone the RuView repository
git clone https://github.com/ruvnet/RuView.git
cd RuView/firmware

# Step 2: Set the board target to the high-performance ESP32-S3
idf.py set-target esp32s3

# Step 3: Open the configuration utility to verify parameters
# (Here you can set the WiFi Channel to 6, and Baud Rate to 921600)
idf.py menuconfig

# Step 4: Compile the firmware binaries
idf.py build

# Step 5: Flash the binaries to your board (Replace COM4 with your physical port)
idf.py -p COM4 flash monitor

Setting Up the Python AI Edge Pipeline

Having a raw stream of Base64 numbers scrolling through your terminal is exciting, but it is completely useless without the AI processing brain. The RuView Python pipeline is the edge engine that ingests the raw serial data, cleans it, isolates spatial rhythms, and runs active neural network predictions.

The processing bridge utilizes a multi-stage digital signal processing (DSP) pipeline. First, it reads the incoming serial buffer and decodes the Base64 subcarrier array. Second, it runs a Hampel filter to remove high-amplitude outliers caused by clock synchronization errors. Third, it executes Principal Component Analysis (PCA) to reduce the 114 subcarriers into three dominant covariance channels, stripping away background environmental noise. Fourth, it applies a Butterworth bandpass filter. For vital sign tracking, the filter is tuned strictly to 0.15 Hz - 0.35 Hz (human breathing spectrum). Finally, the clean spectrogram arrays are fed into local neural networks (a hybrid 2D CNN-LSTM architecture) for action recognition.

Let's install this processing brain on your local machine:

# Step 1: Navigate to the core Python folder
cd ../core

# Step 2: Initialize a clean virtual environment
python -m venv venv

# Step 3: Activate the virtual environment
# Windows:
venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

# Step 4: Install the heavy AI libraries (PyTorch is fine on CPU for basic setups)
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
pip install numpy scipy pyserial websockets

# Step 5: Start the local AI processing daemon
python main.py --port COM4 --baud 921600 --websocket-port 8765

Configuring and Launching the 3D Web Dashboard

To appreciate the magic of WiFi radar, you need a visual medium. The RuView Web Dashboard is a beautiful, cyberpunk-themed interface that renders scrolling wireless wave graphs, a live 3D waterfall spectrogram, and real-time AI classification cards.

The front-end is built using standard React, styled with high-performance vanilla CSS, and bundled using Vite for instantaneous hot-reloading. The dashboard connects to the Python edge daemon via WebSockets, creating a seamless, low-latency display loop. Follow these commands to launch the user interface:

# Step 1: Navigate to the dashboard directory
cd ../dashboard

# Step 2: Install the required packages via Node Package Manager
npm install

# Step 3: Run the local development server
npm run dev

Real-World Calibration and Node Placement

Now that you have successfully installed RuView, achieving flawless tracking accuracy comes down to hardware placement and environmental calibration. Radio waves behave differently than light waves; they don't just travel in straight lines—they bounce, diffract, and scatter off every surface in your room, a physical phenomenon known as Multipath Propagation.

To set up a perfect sensing area, implement these expert calibration guidelines:

1. Optimal Height: Always position both your transmitter (Tx) and receiver (Rx) nodes at a height of 1.2 to 1.5 meters (chest level). This ensures that the main electromagnetic wave path directly intersects the human thorax, yielding high-amplitude breathing waveforms.
2. Avoid Metal Barriers: Metallic objects (like computer towers, refrigerators, or steel shelves) act as perfect Faraday mirrors. They will bounce the signals away and create massive dead zones. Drywall, glass, and wood doors are perfectly fine, as they exhibit low dielectric attenuation.
3. Device Spacing: Maintain a distance of at least 3 meters and no more than 12 meters between the Tx and Rx nodes. Placed too close, the direct wave will saturate the receiver's receiver-amplifier, rendering it blind to reflections. Placed too far, the signal-to-noise ratio will degrade.

+-------------------------------------------------------------+
|                                                             |
|                    [Ceiling / Wall]                         |
|             /--- Indirect Static reflection ---\            |
|            /                                    \           |
|     [Tx Node] ========> [DIRECT PATH] ========> [Rx Node]   |
|            \                                    /           |
|             \--- Dynamic Human Obstacle -------/            |
|                     (Dielectric Perturbation                |
|                      causing subcarrier                     | 
|                      phase shifts)                          |
|                                                             |
+-------------------------------------------------------------+

Troubleshooting Common Installation Errors

Even the most polished installations can experience hitches. Physical hardware pipelines involve many moving parts—from USB drivers and baud rates to environment physics. If your waves flatline or Python throws traceback logs, use our comprehensive troubleshooting matrix to quickly self-diagnose and resolve the issue:

Selecting and Configuring ESP32 Microcontrollers

Implementing a spatial WiFi radar does not require industrial SDR (Software Defined Radio) equipment. The RuView project operates entirely on standard, inexpensive microcontrollers. For high-fidelity telemetry, we highly recommend the ESP32-S3 DevKit. The S3 series features dual XTensa LX7 cores with custom vector instruction extensions that provide hardware acceleration for raw signal matrices.

A typical DIY radar setup consists of a transmitter (Tx) emitting beacon packets and a receiver (Rx) listening on the same WiFi channel. During selection, look for boards featuring an external IPEX antenna connector instead of a standard PCB trace antenna, as high-gain external antennas heavily minimize noise. For a full list of certified microcontrollers and specific command line flashing commands, read our extensive ESP32 WiFi Radar Guide.

Electromagnetic Wave Propagation & CSI Physics

To fully grasp how wireless sensing works, we must investigate the mathematical principles of modern radio frequency (RF) propagation. Traditional signals like RSSI only provide the average overall power of a received wireless packet. Conversely, Channel State Information (CSI) extracts complex vectors mapping individual Orthogonal Frequency-Division Multiplexing (OFDM) subcarrier channels. In a standard 20 MHz or 40 MHz WiFi spectrum, the signal is split into 56 to 114 separate subcarrier channels. For each subcarrier, the CSI packet header records the exact Amplitude (signal attenuation) and Phase (fractional cycle shift).

Human bodies are comprised of more than 60% water, making them highly conductive dielectric objects in the path of 2.4 GHz and 5.8 GHz frequencies. As waves travel between the transmitter and receiver, they bounce off walls, obstacles, and humans in a phenomenon known as Multipath Propagation. The physical displacement of a human body perturbs this multipath beam network, creating constructive and destructive interference waves. For a comprehensive overview of how these physical shifts are visualized in real-time, try our Interactive 3D WiFi Radar Demo.

Figure 2: Technological block diagram demonstrating Electromagnetic Wave Propagation & CSI Physics.

Digital Signal Processing & CSI Denoising Pipelines

Raw CSI data streamed from low-cost IoT chips is inherently messy. Thermal drift, clock phase offsets, and ambient environmental interference introduce massive high-frequency noise. The first step in our digital signal processing (DSP) pipeline is running the Base64 stream through a Hampel outlier filter.

We then apply Principal Component Analysis (PCA). PCA analyzes the covariance matrix across all 56 subcarriers and extracts the top three dominant variance components, effectively discarding redundant channels. To monitor rhythmic body signals such as respiration, the clean PCA streams are passed through a Butterworth bandpass filter tuned between 0.15 Hz and 0.35 Hz. For a detailed guide on how we isolate chest-wall displacements using these filters, proceed to Breathing & Vital Signs Detection.