SHIELD / ATLAS

Required Hardware

You don't need all of these to get started. The mic alone will work. Add more sensors as you get them.

Software Prerequisites

Install these on your Windows PC before doing anything else.

1. Install Python 3.10+
   Download from python.org/downloads
   
   IMPORTANT: During installation, CHECK THE BOX that says "Add Python to PATH". If you already installed without this, you can use py instead of python in all commands below.
2. Install the required Python libraries
   Open PowerShell (search "PowerShell" in the Start menu) and paste this command:
   PS> pip install pyrtlsdr numpy requests sounddevice
   If pip doesn't work: Try py -m pip install pyrtlsdr numpy requests sounddevice instead.
3. For SDR only — Install SDR drivers (REQUIRED for the dongle to work)
   Windows treats the SDR dongle as a TV tuner by default. You must switch it to a generic USB device using a free tool called Zadig so Python can talk to it directly.
   Without this step, the SDR dongle will NOT work. Python will fail with "No RTL-SDR device found" even if the dongle is plugged in.
   1. Make sure your SDR dongle is plugged into a USB port with the antenna screwed on
   2. Download Zadig (small .exe, no install needed) and run it
   3. In the menu bar, click Options > List All Devices
   4. In the dropdown, find "Bulk-In, Interface (Interface 0)" or "RTL2838" — that is your SDR dongle
   5. On the right side, make sure the driver box says WinUSB
   6. Click Replace Driver (or Install Driver)
   7. Wait for it to finish — it will say "Driver installed successfully"
   8. Unplug and replug the SDR dongle after the driver installs
   You only need to do this once. After the driver is installed, the dongle will work every time you plug it in.
   Skip this step if you're only using the microphone.

Sensor Bridge Setup (PC — Mic + SDR)

The sensor bridge runs on your PC and reads data from your USB mic and SDR dongle, then sends it to the SHIELD/ATLAS cloud dashboard.

1. Plug in your hardware
   Connect your Fifine K669B mic (and NooElec SDR if you have it) to USB ports on your PC. Wait a few seconds for Windows to recognize them.
2. Open PowerShell
   Search "PowerShell" in the Start menu and open it.
3. Navigate to your Downloads folder
   PS> cd ~\Downloads
4. Find the file name
   The browser may have saved it with a different name. Check:
   PS> dir *sensor*
   Look for the .py file and use that exact name in the next step.
5. Run the sensor bridge
   
   # With both mic and SDR:
   PS> py shield-atlas-sensor-bridge.py --server https://shield-atlas-production.up.railway.app --scan
   
   # Mic only (no SDR dongle):
   PS> py shield-atlas-sensor-bridge.py --server https://shield-atlas-production.up.railway.app --mic-only
   
   # SDR only (no mic):
   PS> py shield-atlas-sensor-bridge.py --server https://shield-atlas-production.up.railway.app --sdr-only
6. Verify it's working
   You should see lines scrolling like:
   
   [ACOUSTIC] MATCH: Unknown (confidence: 84%) peak=1184Hz rms=-49.4dB shape=BROADBAND
   That means your mic is detecting and classifying sounds. If the SDR is connected, you'll also see RF scan results.
7. View it on the dashboard
   Open shield-atlas-production.up.railway.app/cram in your browser. The Sensor Fusion Tracks panel will show detections from your hardware in real time.

ESP32 Acoustic Sensor Node

The ESP32 is a standalone sensor that runs independently from your PC. It connects to your WiFi and sends acoustic detections to the cloud on its own. Great for placing sensors around a perimeter.

1. Install Arduino IDE
   Download the free Arduino IDE from arduino.cc/en/software. Install it and open it.
2. Add ESP32 board support
   In Arduino IDE:
   
   • Go to File > Preferences
   • In "Additional Board Manager URLs", paste:
     https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
   • Click OK
   • Go to Tools > Board > Boards Manager
   • Search esp32 and click Install (by Espressif Systems)
3. Install required libraries
   In Arduino IDE, go to Tools > Manage Libraries and install these two:
   • ArduinoJson by Benoit Blanchon
   • arduinoFFT by kosme
4. Open the downloaded file
   Go to File > Open and select the esp32-sensor.ino file from your Downloads folder. It will open in a new Arduino window.
5. Edit your WiFi and server settings
   Near the top of the file, find these three lines and change them:
   // ---- CHANGE THESE THREE LINES ----
   const char* WIFI_SSID = "your-wifi-name";
   const char* WIFI_PASSWORD = "your-wifi-password";
   const char* SERVER_URL = "https://shield-atlas-production.up.railway.app";
   Use your actual WiFi name and password. The ESP32 needs WiFi to send data to the cloud. The server URL should be https://shield-atlas-production.up.railway.app unless you're running locally.
6. Wire the microphone
   Connect the microphone module to the ESP32:

   Mic Pin	ESP32 Pin
   VCC	3.3V
   GND	GND
   OUT	GPIO 34

7. Connect the ESP32 to your PC via USB
8. Configure Arduino IDE for ESP32
   
   • Go to Tools > Board and select ESP32 Dev Module
   • Go to Tools > Port and select the COM port that appeared when you plugged in the ESP32 (e.g., COM3, COM4)
   Don't see a COM port? You may need to install the CP210x USB driver (for most ESP32 boards) or the CH340 driver (for some clones).
9. Upload the firmware
   Click the Upload button (right arrow icon) in Arduino IDE. Wait for it to compile and upload. You'll see "Done uploading" when finished.
10. Monitor output
    Go to Tools > Serial Monitor, set baud rate to 115200. You should see:
    WiFi connected: 192.168.1.x
    [ACOUSTIC] Sending detection — peak: 2400Hz, rms: -38.2dB
    [ACOUSTIC] Server response: 200 OK

Verify Everything Works

Once your sensors are running, check the dashboard to confirm data is flowing.

1. Open the C-RAM Dashboard
   Go to shield-atlas-production.up.railway.app/cram
2. Check Sensor Fusion Tracks (bottom of dashboard)
   You should see rows appearing with detection data from your sensors.
3. Check RF Waterfall (if SDR is connected)
   The RF spectrum panel will show a live waterfall display of scanned frequencies.
4. Test with the drone
   The HS190 has two detectable signatures — each requires a different sensor:
   • Drone MOTORS (mic detects this): Spin up the propellers — the high-pitched motor whine creates a clear acoustic signature. Just turning on the remote is NOT enough for the mic — it needs the motors running.
   • Remote RADIO signal (SDR detects this): Just powering on the remote transmits a 2.4GHz control signal. The SDR dongle picks this up as an RF detection — no motors needed.
   • Both together = sensor fusion: When both sensors detect the drone simultaneously, the dashboard fuses the tracks and THREATCON may escalate from GREEN to AMBER.

Troubleshooting