-
Notifications
You must be signed in to change notification settings - Fork 14
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1382 from anarkiwi/doc
Remove obsolete docs.
- Loading branch information
Showing
9 changed files
with
23 additions
and
1,058 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,66 +1,40 @@ | ||
| # gamutRF | ||
|
|
||
| An SDR orchestrated scanner and collector. | ||
| gamutRF is a gnuradio-based SDR-based scanner, I/Q signal collector and identifier (using a image or I/Q based pyTorch model). | ||
|
|
||
| gamutRF is a system enabling a compact network of one or more modest machines (such as Pi4s), each with their own USB SDR (such as an Ettus | ||
| B200mini or a BladeRF XA9), to operate collectively as a configurable wideband scanner and I/Q sample recorder. | ||
| While it can run on Pi4 and Pi5 machines (and its components can be distributed over a network), it is more typically deployed on a single x86_64 machine with an nvidia GPU (see [deployment instructions](https://github.com/IQTLabs/gamutrf-deploy)). | ||
|
|
||
| gamutRF's scanner container connects to a local SDR and sweeps over a configured frequency range or ranges collecting samples. When a configurable number of [valid I/Q samples](https://github.com/IQTLabs/gr-iqtlabs/blob/7990932fa871aa3f84e75771052500551f615638/lib/retune_pre_fft_impl.cc#L276) are received the SDR is retuned to a new interval (see [blocks in gr-iqtlabs](https://github.com/IQTLabs/gr-iqtlabs)). The samples are processed and sent to a waterfall container for display, and optionally to a [Torchserve](https://github.com/IQTLabs/torchserve) instance for identification. Recording, and basic parameters (such as the frequency range to scan) can be controlled from the waterfall container. | ||
|
|
||
| A gamutRF system comprises an "orchestrator" machine which typically runs at least one scanner service (typically scanning 0.1GHz to 6GHz in 30s) and the sigfinder service, which then | ||
| can command potentially many gamutRF "workers" to make I/Q sample recordings for later analysis. sigfinder can command multiple scanners which can be on the same machine or be connected | ||
| over a network. | ||
|
|
||
| gamutRF provides tools to work with I/Q sample recordings, and to also record GPS location/compass metadata for the system itself. gamutRF typically runs on networks of Raspberry Pi4s, but can also run on x86 machines, and is based on gnuradio. | ||
|
|
||
| See also [instructions on how to build a gamutRF system](docs/3-BUILD.md). | ||
|
|
||
| ## Scanner theory of operation | ||
|
|
||
| gamutRF's scanner container connects to a local SDR and sweeps over a configured frequency range or ranges collecting samples. The samples are sent an FFT block, and then to a [streaming retuning gnuradio block](https://github.com/iqtlabs/gr-iqtlabs), which aggregates and then serves the frequency-annotated FFT points as JSON objects over ZMQ to the "sigfinder" container (see below) and also commands the source SDR block to retune to a new frequency in the range when enough FFT points have been accumulated. | ||
|
|
||
| The sigfinder container consumes these FFT points over ZMQ (potentially from many scanners), does some noise processing (correcting FFT points to be in frequency order, computing mean power over 10kHz, and then a rolling mean over 1MHz) and then submits them to [scipy.signals.find_peaks](https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.find_peaks.html). | ||
|
|
||
| If workers have been provisioned, the sigfinder will then command the workers to make an approximately 10 second I/Q recording at approximately 20Msps of each signal. Each signal peak is assigned a 20MHz bin, which means that if a signal is repeatedly detected with some frequency variation, the assigned recording bin will be constant, and if multiple signals are detected within 20MHz they can be collected simultaneously. A worker by default records at a higher sample rate than the bin size, so that 20MHz signal margins can be recorded. | ||
|
|
||
| As there will almost certainly be more signals than workers available, sigfinder will prioritize signals that it least often observed over a configurable number of scanner cycles. It is possible to configure this to `off` so that the recording choice will be random. It is also possible to configure the workers to tell the sigfinder to exclude that worker from certain frequency ranges (if for example the worker SDR cannot handle some part of the frequency spectrum scanned). | ||
|
|
||
| ## Build and Operating gamutRF | ||
| ## License | ||
|
|
||
| See the [build doc](docs/3-BUILD.md) for instruction on setting up a GamutRF system. Next see the [operating instructions](docs/4-OPERATION.md) for instructions on operating GamutRF. | ||
| Distributed under the [Apache 2.0](./LICENSE). See [LICENSE](./LICENSE) for more information. | ||
|
|
||
| ## Documentation | ||
| ## Contact IQTLabs | ||
|
|
||
| [1 - Introduction](docs/1-INTRODUCTION.md) | ||
| [2 - System Overview](docs/2-SYSTEM_OVERVIEW.md) | ||
| [3 - Build](docs/3-BUILD.md) | ||
| [4 - Operation](docs/4-OPERATION.md) | ||
| [5 - ML Tooling](docs/5-ML_TOOLING.md) | ||
| [6 - Testing](docs/6-TESTING.md) | ||
| [7 - Troubleshooting](docs/7-TROUBLESHOOTING.md) | ||
| [AIRT Support](docs/README-airt.md) | ||
| - Twitter: [@iqtlabs](https://twitter.com/iqtlabs) | ||
| - Email: [email protected] | ||
|
|
||
| ## Contributing | ||
| See our other projects: [https://github.com/IQTLabs/](https://github.com/IQTLabs/) | ||
|
|
||
| 1. Fork the Project | ||
| 2. Create your Feature Branch (`git checkout -b dev`) | ||
| 3. Commit your Changes (`git commit -m 'adding some feature'`) | ||
| 4. Run (and make sure they pass): | ||
| ## AIR-T support | ||
|
|
||
| ``` | ||
| black --diff --check gamutrf | ||
| ``` | ||
| GamutRF has legacy support for the [Deepwave AIR-T](docs/README-airt.md) | ||
|
|
||
| 5. Push to the Branch (`git push origin dev`) | ||
| 6. Open a Pull Request | ||
| ## Development | ||
|
|
||
| See `CONTRIBUTING.md` for more information. | ||
| Development with GamutRF requires familiarity with gnuradio, an SDR, a x86_64 host running Ubuntu 24.04 with Docker installed (and ideally an nvidia GPU, though this is not required). | ||
|
|
||
| ## License | ||
| ### Local development | ||
|
|
||
| Distributed under the [Apache 2.0](./LICENSE). See [LICENSE](./LICENSE) for more information. | ||
| * Install [gnuradio](https://wiki.gnuradio.org/index.php/InstallingGR), 3.10 or later | ||
| * Install [gr-iqtlabs](https://github.com/IQTLabs/gr-iqtlabs) | ||
| * Make modifications, and install with ```poetry install``` | ||
| * Run tests with ```pytest``` | ||
|
|
||
| ## Contact IQTLabs | ||
| ### Docker development | ||
|
|
||
| - Twitter: [@iqtlabs](https://twitter.com/iqtlabs) | ||
| - Email: [email protected] | ||
| Follow above local development instructions, and then build containers (tests will be run inside the containers). | ||
|
|
||
| See our other projects: [https://github.com/IQTLabs/](https://github.com/IQTLabs/) | ||
| * ```docker build -f docker/Dockerfile.base docker -t iqtlabs/gamutrf-base:latest``` | ||
| * ```docker build -f Dockerfile . -t iqtlabs/gamutrf:latest``` |
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.