top of page

Using Raven

How to set up and install Raven

​

Version 1.0.0 Beta

Prerequisites

Before proceeding, ensure you have the following installed on your system.

- Python 3

- pip + virtualenv

- rtl-sdr package, including rtl_tcp and rtl_power

- hackrf_sweep for the HackRF


Installation and Setup

Before starting Raven, make sure that you have the backend tools like rtl_tcp, rtl_power, or hackrf_sweep installed and updated to the most current version. If you're on Windoze, make sure that you have these in your system PATH. Instuctions for all of this can be found with some quick Googleing.

1. Clone the Source Code

git clone https://github.com/fosatech/Raven.git

2. Navigate to the Project Directory

cd Raven/

3. Create a Python Virtual Environment:

python3 -m venv venv

4. Activate the Virtual Environment:

source venv/bin/activate

5. Install Dependencies:

python -m pip install -r requirements.txt

6. Run the Flask Application:

python raven.py

Note: this currently starts the Flask development server. Proper WSGI server support is coming soon.


Usage

After completing the setup, the Flask application will be running on your local server. You can access it via localhost:5000/rtl_data.

1. Open the settings window, enter the desired wideband scan range and bin size, and start the scan.

2. Start the `rtl_tcp` server with the desired port and IP, and connect to it with your SDR software.

3. Select your desired rtl-tcp server instance by clicking on the current frequency, then `ctrl + left click` on the wideband window and STK Sweep will automatically tune your SDR to it.


Settings and Configuration

Wideband Settings:

Enter the freqency range, gain, and bin size.

- Gain for the rtl-sdr should be between 0-50, or "automatic".

- Gain for the hackrf should be between 0-40.

- The bin size is in kHz, and sets the frequency range that each pixel covers. Lower bin size, more resolution.

- The reccomended bin size is 0.12% of your bandwidth. A simple way to calculate this is `<bw in MHz> * 0.12`. This will give you the optimal bin size in kHz.

- Note: the device ID does not currently correlate to any specific device. This will be fixed soon.



RTL TCP Settings:

This is for creating new instaces of the backend `rtl_tcp` server. `STK Sweep` has a TCP proxy on the backend in order to be able to update the center frequency of the 2nd RTL-SDR dongle.

- IP: The IP address your external SDR software will connect to.

- Port: The port your external SDR software will conenct to.

- Gain: Gain for the rtl-sdr. Can be set from 0 - 50.

- Client Port: The port that the backend proxy server and the rtl-tcp instance will use to talk to each other.

- Device: The device ID for rtl-tcp to use. Change this if you're using multiple rtl-sdr's.

- Color: Sets the display color.




Once you've created and configured your rtl-tcp instance, use the Start/Stop buttons to start and stop the server. To chage the center frequency that your device is tuned to, click on the frequency display for your desired instance, and you will see it selected. Then simply `ctrl + click` anywhere on the wideband to tune your rtl-tcp instance to that frequency. You will see an overlay pop up on the wideband waterfall that shows the current area your SDR is looking at.




Waterfall Display Settings:

This sets the color profile for each new row of the waterfall. Future versions will update the entire waterfall color scheme.

The `Activity Threshold` slider sets the threshold for the activity bar.



The Bottom Toolbar

This is where the magic happens. The toolbar has 4 separate views: these are for SIGINT, viewing your saved systems, editing database entries, and getting systems from the Olympus API. To get Raven set up with Olympus, see the section on Using Raven with Olympus.


SIGINT View

This allows you to see all saved systems, as well as the interface for the Olympus SIGID database. To query the database, simly ctrl+click on the desired frequency in the wideband, then click the query button.


This will query the SIGID database for signals that overlap with your selected frequency range. The database is currently referencing the entries at https://www.sigidwiki.com/, but more signal classification tools and references are coming soon. Go check out the Sigid Wiki page to contribute to their awesome project.


This view will also eventually incorporate an option to view live FFT data from a second SDR, or a zoomed-in version of the wideband scan:


System View

This just allows you to view all existing systems in the local database. There will soon be an option to have systems automatically highlighted if they're active on the wideband.


Database Edit

This is where you can edit the system and device entries in the local database.


The buttons function as follows:

  • Edit selected entry

  • Write entry to database

  • Delete entry

  • Clear entry fields


Simply type in the desired information for the system or device, then click the "Write entry" button. To edit the entry, load it into the editor with the "Edit entry" button. Once it's loaded, you can also delete it with the "Delete entry" button. If both a system and a device are loaded in the editor, Raven will delete the device. If only a system is loaded, then raven will delete the system and all associated devices.




Olympus Systems View

This allows you to call the Olympus systems API and get a list of systems that operate in the selected frequency range within 60km of the center point set in the Olympus settings. The "↯" button will get systems from the range of your entire scan, but the current API is limited to a maximum of 30 systems. In the future, this will be used with an updated API to get all of the systems in not only the scan range, but in a set frequency range. This functionality will be coming to Olympus users in Q1 of 2024.


The "↔" button will get all of the systems within the selected frequency range on the wideband. The "⇊" button will save all of the systems and devices to your local databse.


The Olympus systems API currently interfaces with the maprad.io API on the backend, but we will soon be adding integration to the Radio Reference database API as well, along with several other new internal and external systems.



Using Raven with Ølympus

Setup

To get started with Olympus, visit https://www.fosa-tech.com/olympus

Once you have a plan, you can go to your user page and generate an API key


Next, open Raven, and click on the "OLYMPUS" button on the sidebar. This will open a window for you to enter your API key, as well as lat-long coordanates. These will be used as a center point when making calls to the systems API to get radio systems for your local area.


Once you click "Submit," Raven will save this to VAR.conf in your Raven folder.


Support

For any issues or questions, please contact us here.


Contributing

Contributions to the SDR-STK project are welcome. Please read the `CONTRIBUTING.md` file for guidelines on how to contribute.


To-Do

Coming Soon:

  • Multiple concurrent widebands

  • Update info from backend when page refreshes

  • Type in center frequency for live SDR's

  • Proper mobile browser support

  • Zoom and scroll relative to page center/mouse cursor

  • Create custom frequency plans


Bug Fixes:

  • Large `bin` size breaks `drawRow()` in `rtlDataDisplay.js` in some browsers

  • Implement proper server like `gunicorn` without `rtl_tcp` proxy lagging

  • Detect when scan or tcp server is stoppen on backend

  • Wideband and tcp proxy instances don't always shut down properly


Aditional Features:

  • Convince entire population of earth to use Linux

  • Custom wideband backend

  • Update entire waterfall colors

  • Automatic gain on frontent

  • Add option to directly interface with software like SDR++



Thank you for participating in the Raven project development.

bottom of page