iqengine / iqengine

A web-based SDR toolkit for analyzing, processing, and sharing RF recordings

A web-based SDR toolkit for analyzing, processing, and sharing RF recordings

🔎Try it out at iqengine.org🔎

IQEngine is a web application that powers iqengine.org but can also be deployed as a private instance to share recordings within a company/organization. The public instance, iqengine.org, is used by thousands each month to browse RF recordings shared by the community, although you can also use the site to visualize your own local files (processing is done client-side). It includes a spectrogram-based visualization and editor tool, built on top of the SigMF standard. Use IQEngine to expand your knowledge of wireless signals and how to analyze/process them, while learning more about FFTs, filtering, and other RF DSP. IQEngine's goal is to bring the open-source RF community together.

IQEngine is rapidly evolving, so check out our LinkedIn for updates, including new features, demos, and more! There is also an IQEngine Discord chat channel if you want to get involved in the development or have questions.

Link to the live docs which can also be found in the source code at client/src/pages/docs/***.mdx

List of Major Features:

• Spectrogram + time + freq + IQ plots with zooming and adjustable scales
• Table of all RF recordings available in a directory or blob storage account, with spectrogram thumbnails
• FIR filtering and arbitrary Python snippets prior to FFT, all client-side
• Time and frequency domain selection cursors to choose what gets sent to plots/plugins/downloads
• Configurable colormap
• Viewable/editable global params and annotations, including adding a new annotation graphically or through text
• Jump to annotation when you click it from the table
• Plugins, allowing DSP to run on the backend (currently supports Python and GNU Radio)
• Ability to search/query over millions of recordings by parsing metadata into database
• User/admin system for controlling access to certain recordings
• The IQEngine team created a new web library for performing FFTs and related functions, called WebFFT, you can play with it using the demo here

IQEngine is Supported By:

iqengine's Issues

"Edit me" links at the top of each docs page that links to the source

We're using MDX so each source file is really just markdown https://github.com/IQEngine/IQEngine/tree/main/client/src/pages/docs

Feature Request- being able to link to a folder in a repo

GRCon CTF could have really used it

Issues on really old browsers

Loading WebFFT will cause the error "WebAssembly.Compile is disallowed on the main thread, if the buffer size is larger than 4KB" because several years back there was a limit to the webasm memory size.

It's likely because within WebFFT it's loading the wasm sync instead of async, I spent some time trying to convert it over using this guide but it just caused more errors
https://web.dev/articles/loading-wasm

Alternatively we could add a new feature flag which uses indutny instead of webfft, getting rid of all the webasm, for orgs who need super old browsers to work

Features-Ideas-Improvements Master Thread

Features

• After setting selection cursors, right click (or some other way) to save the samples to a new file you can download
• Wavelet transforms! Including Readme/tutorial about why wavelets are useful, inspired by https://www.mathworks.com/help/wavelet/ug/time-frequency-analysis-and-continuous-wavelet-transform.html
• Server-side spectrogram calc to reduce data transfer when zoomed out in time or zoomed in in freq
• Ability to tune-filter-decimate a section after choosing the region of freq of interest (and time-domain selection), and then you can download the resulting samples
• Ability to click on an annotation label/rectangle and see the rest of its metadata somehow, especially comments
• Loading bar while detector is running, or some indication you clicked it and its running
• A toggle for turning off display of annotation rectangles/labels, both for the main spectrogram and within the minimap
• Rename scrollbar to minimap throughout code
• Developer docs that uses mdx, see react hot toast for an example
• Showing annotations in time and freq plot
• Colored annotations, one color for each label, e.g. auto-assigned (bonus points for being able to adjust the colors)
• Detect if the annotation rectangle text/label intersects with another one, and if so, put one at the bottom of the rectangle instead of top
• Ability to use a polyphase filterbank channelizer in place of FFT for better time resolution anaylsis
• Ability to convert non-sigmf files (e.g. pcap of difi) to SigMF, both locally and as an Azure Function
• Basic cyclostationary processing, e.g. brute force SCF
• Ability to link someone to a specific repo + recording, and even a specific sample_start would be cool
• An e2e test that measures how long page load times take, with a conservative threshold so that if someone changes code that leads to super long load times, we'll catch it early.

Misc Cleanups or Bugs

• If a filename has a 2nd period in it, the datafile isnt found
• Annotation label editing popup window needs a close button, enter doesnt always work
• Q/A section somewhere, can explain that it's not a Microsoft product, and other things
• Swap from google analytics to something nicer and open source like plausible.io
• Currently we redownload the samples when the taps change, or anything that impacts the iq_data, need to add a 3rd data structure to act as a buffer between downloading iq_data and producing fft_data

Provide Visual Feedback for Running Plugins

Is your feature request related to a problem? Please describe.
Currently, when a plugin is initiated, there's no visual cue to indicate that it's running.

Describe the solution you'd like
It would be very helpful to have some form of visual feedback, such as a loading spinner or progress bar, when a plugin is running. This is especially important for plugins that take a long time to execute.

Describe alternatives you've considered
A simple text notification saying "Plugin is running" could work, but a visual indicator would be more engaging.

Additional context
Providing this feedback would greatly improve the user experience, especially for plugins that take some time to complete.

Add Admin Space

Add admin space wherte you would configure data sources that woul would have to browse.

Make sure this admin space would also allow you to setyup auth and other configurations for the app

Typesense for search

https://typesense.org/

Cache requests to IQ Store that fails

Is your feature request related to a problem? Please describe.
IQEngine UI is making many times the same requests that fails when used against my own Azure Blob Storage:

• base file request, ie one without the .sigmf-meta or .sigmf-data file extension
• thumbnail

Describe the solution you'd like
I would like the request to occurs only once while it happens several time when using the spectogram.

refreshing page on spectrogram makes minimap offscreen

Frequency shift as a slider on spectrogram page

Frequency shifts are so common and the python snippet and plugins way of doing them isn't totally smooth yet so we're best off just having it similar to the current FIR Filter where its just done in javascript before the FFT

Support URL of a SigMF Collection as repository browsing entry point

So as to be less Azure Dependant and be more Web oriented, it would be nice if we could start browsing by just giving the URL of a SigMF Collection file. It would ease other people to share more of their IQ files.

I would like a new entry card on the home-page where I can provide the url of a SigMF collection that IQEngine could use to list IQ files available.

Care might be taken to handle access token to be forwarded on records retrieval

Describe alternatives you've considered
Other alternatives involved specific requests support for every different storage backend like very command S3. It would requires all plugin server support to every of those too.

Show Loading Indicators for API Data Sources on Main Screen

Is your feature request related to a problem? Please describe.
When opening the main screen, it initially appears empty while data is being fetched from API sources in the background.

Describe the solution you'd like
It would be great to see skeleton placeholders or a loading spinner to indicate that data is being fetched.

Describe alternatives you've considered
A text message saying "Loading data" could serve the purpose, but skeleton placeholders would offer a more visually pleasing experience.

Additional context
This feature would help users understand that data is being loaded and they need to wait, thereby improving the overall user experience.

Detector config weirdness

@Nepomuceno I missed this before it was committed but we refer to detectorEndpoint multiple times in this file so we probably need it to live in 1 place so its cleaner to reference, currently the 2nd time we refer to it its undefined and errors out when you try to run the detector.

IQEngine/client/src/Components/Spectrogram/DetectorPane.jsx

Line 23 in bb1f2a8

detectorEndpoint = config.data.detectorEndpoint;

You can reproduce this yourself by adding the following to the .env

DETECTOR_ENDPOINT=http://localhost:8000/detectors
VITE_DETECTOR_ENDPOINT=http://localhost:8000/detectors

and then in detectors/README.md it has the command for running the detector locally, e.g. in another tab.

IQEngine Spectrogram Page Crashes with Large Datasets

Issue Description:

When attempting to visualize large datasets, such as those around ~4.5GB or containing approximately 589.832192 million samples, the Spectrogram page crashes. The issue may be related to the minimap functionality.

The dataset in question is the SIGENCE Pulse Gallery from the Airbus SIGENCE Repository.

Steps to Reproduce:

1. Load the SIGENCE Pulse Gallery dataset from the Airbus SIGENCE Repository.
2. Attempt to view the dataset, specifically one with the aforementioned size (e.g., ~4.5GB or 589.832192 million samples).
3. Observe the page crash.

Expected Behavior:

The Spectrogram page should handle large datasets without crashing.

Additional Information:

• Dataset: SIGENCE Pulse Gallery from the Airbus SIGENCE Repository.
• Size of problematic dataset: ~4.5GB or 589.832192 million samples.
• Suspected cause: Potential issues with the minimap functionality.

Add greyscale colormap

Bug: "numbers" recording in CTF thumbnail looks weird

Improve Plugin Interactivity with Recordings Through New Options

Is your feature request related to a problem? Please describe.
At the moment, the only way to send an entire recording to a plugin is by manually extending the time cursor to encompass the whole record.

Describe the solution you'd like
It would be highly beneficial to have an option that allows users to automatically send the entire recording to a plugin without having to adjust the time cursor. Additionally, another default option could be added to send only the content currently displayed on the screen to the plugin for processing.

Describe alternatives you've considered
An alternative could be to keep using the time cursor for this purpose, but having these options would simplify the user experience and make the process more intuitive.

Additional context
These features would provide users with more flexibility and control over what data is sent to plugins, thereby enhancing the overall user experience.

Feature flag issue on staging

This only shows up on staging, not when running locally. the staging FEATURE_FLAGS is set to
{"useIQEngineOutReach": false, "useAPIDatasources": true, "displayIQEngineGitHub": true}

EDIT- since it's friday night im just going to disable the feature for now =)

Feature- get thumbnails working for opening a local directory

Long load times

Especially for folks not near the US East datacenter, the latency of accessing blob storage leads to long load time when you open the GNU Radio tile, because it's fetching each file's metadata individually and there's like 100's of ms of latency associated with each fetch, it needs to be batched.

Feature Request - support for real valued recordings

Everything is represented under the hood as complex float 32, but it's not a super quick addition because there's some code involved in fetching bytes from a file that may need *2 removed for real-valued signals.

Also every datatype needs a "c" or "r" so have the parser spit out an error if it finds a recording without either, and remove ones like i8 and u8 from list

From SigMF:

dataset-format = (real / complex) ((type endianness) / byte)

real = "r"
complex = "c"

type = floating-point / signed-integer / unsigned-integer
floating-point = "f32" / "f64"
signed-integer = "i32" / "i16"
unsigned-integer = "u32" / "u16"

endianness = little-endian / big-endian
little-endian = "_le"
big-endian = "_be"

byte = "i8" / "u8"

So, for example, the string "cf32_le" specifies "complex 32-bit floating-point samples stored in little-endian", the string "ru16_be" specifies "real unsigned 16-bit samples stored in big-endian", and the string "cu8" specifies "complex unsigned byte".

Docker File

There is no docker file to standup IQEngine.

python snippet broken

once its working, it should also only process whats on the screen, because otherwise it could take forever if its processing everything thats been downloaded

fftsize bug

if you change fftsize and hit the button, it doesn't actually go in effect until you move to a new spot in the recording

Bug: Data when loaded from env var is duplicated

Both the datasources and recordings are being super duplicated, 2x and 3x in a lot of cases. Only solution now is to manually add each datasource one by one.

Support Authentication and Authorization as Anonymous Access

IT shoudl have options to allow you sto specify auth but aso allow anonymous caccess to the engine.

Backend service that streams IQ to endpoint

It would be cool to have a way to stream either an entire recording or a piece of a recording over UDP, ZMQ, DIFI/VITA49, etc, to an endpoint, could be a GNU Radio flowgraph. Option for whether to loop or just playback once.

Env file should be simple key value pairs

It is a common patter to use simple key values for envitonment parameters instead of complex objects or json.

Bug: Lots of "Unclosed client session" and "Unclosed connector" in backend logs

Eg run the backend locally and even at the end of the sync process you'll see it, but also happens when client uses the backend

Bypass landing page also makes the about page just not load at all

so leaving it off for now

Page Blobs

Would page blobs be faster than block? E.g. for when you zoom out with decimation and grab N bytes every M bytes.

Configure Google Analytics within the environment file, off by default

It should not be used as a single one Google analytics and if you do not fill up environment variable it should not be present.

Bug: If core:frequency is missing it should assume 0 Hz

Technically its an optional SigMF field

incorrect vertical ruler calculations

The vertical ruler measurement changes as the bottom bar of the time cursor is dragged down.

To Reproduce
Steps to reproduce the behavior:

1. Open any recording in the recording-view page
2. Click the toggle for time cursor
3. Note the ruler measurement next to the bottom bar of the time cursor
4. drag the bottom bar down
5. mousewheel down to expose more of the spectrogram
6. drag the bottom bar of the time cursor down.
7. note that the measure on the ruler is changing as you go

Expected behavior
As you mousewheel down, the ruler measurement should not change. As you drag the bottom bar of the time cursor down, the ruler measurement should not change.

Move the code to typescript.

Typescript would give you many different advantages but the main one would be type safety and to guartantee that we do not sneak up in some unknown bugs because something that was not expeced was not treated.

An example of that it si the fact thart for example id on File.js in Components/RecordBroser if the item it is undefined the app just crash completly and should be comming back as empty or just not having the row.

Moving the app to typescript would alert to cases like that not being covered.

Idea to use filebrowser.org plus caddyserver.com to provide a web-based file browser/editor alongside IQEngine

files would be served via http to IQEngine but then you could use file-browser to manage them or even embed file-browser in iqengine. the http file server would need to be able to provide little bits of the file rapidly, that's how we are getting the current performance we have with azure blob storage.

Failure of calling a local plugin server with CloudStorage usage

Describe the bug
From a spectogram of an sigmf file from my own Azure Blob Storage,
with Time cursor activated and selection ready,
when calling a local plugin server with the "use Cloud Storage" option activated,
the plugin is not called and the console display: Uncaught TypeError: R.data is undefined

To Reproduce
Steps to reproduce the behavior:

1. Browse a personal Azure Blob Storage
2. Select an IQ file
3. Toggle Time Cursors
4. Select a local plugin
5. Toggle use Cloud Storage
6. Click 'Run plugin'

Expected behavior
The plugin shall be called but there is an error display in the console.
NB: If not using Cloud Storage, it works as expected.

Additional Context
The bug does not occur when the file comes from one of the "pre-registered" IQ repository.

Remove hardcoded references to non public sources

In the main page there are hardcoded references to sample files that do require you to access non public sources.

Enhance User Experience by Persisting Color Scheme Across Application Context

Is your feature request related to a problem? Please describe.
I notice that the color scheme applied on the spectrogram page resets when navigating to other parts of the application.

Describe the solution you'd like
It would be wonderful to have the color scheme stored in the application context, allowing it to persist across different records and even enable other features like dynamically changing the color scheme of the logo based on the spectrogram page.

Describe alternatives you've considered
An alternative could be to store the color scheme in local storage or cookies, but storing it in the application context would offer more dynamic capabilities.

Additional context
This feature would enhance the user experience by providing a more cohesive and personalized interface.

Add new API endpoints for IQEngine project

This proposal suggests adding several new API endpoints to the IQEngine project to enhance communication between the frontend and the backend. These endpoints will provide functionalities related to data sources and their associated metadata.

Some background and context:

• IQEngine has a list of datasources meaning the list of places where you can get data from.
• Datasources curently are containers into a blob storage account or a local file/directory
• The decision to use the storage accoutn name and container as datasouce id was done because it does allow you to work with datasource without the need to save them to a database and keeps compatibility with the current way of work of IQEngine while at the same time being able to unique identify a data source.
• The pagination fiels and how paginationn will be done have not been decided yet.
• All the parameters are going to be urlencoded to avoid problems with / and other url incompatible fileds

The proposed endpoints are as follows:

1. GET - api/datasources/?{pagination_fields}
   • Description: Returns a list of data source objects.
   • Parameters: None
   • Response: List of data source objects
     • ex:

[ 
   { "type": "server_blob", "name": "Cool RF recordings", "storage_account":"mystorage", "container":"mycontainer" },
   { "type": "client_blob", "name": "Private RF recordings", "storage_account":"mystorage", "container":"mycontainer", "key":"mySASkey" }
]

2. GET - api/datasources/{id}/meta?{pagination_fields}

   • Description: Returns the list of the latest version of all metadata files for the specified data source.
   • Parameters:
     • id: The identifier of the data source in the format blob_{azure_blob_storage_account_name}_{container_name}.
   • Response: List of the latest version of all metadata json that this datasource has

3. GET - api/datasources/{datasource_id}/{file_path}/meta?version={version}

   • Description: Returns the json of metadata file for the specified data source and file path.
   • Parameters:
     • datasource_id: The identifier of the data source in the format blob_{azure_blob_storage_account_name}_{container_name}.
     • file_path: The name of the file in the blob storage without the extension.
     • version: optional p[atameter to fetch one specific version
   • Response: The metadata file json

4. GET - api/datasources/{datasource_id}/{file_path}/meta/versions?{pagination_fields}

   • Description: Returns the list of versions for the specified metadata file of a data source.
   • Parameters:
     • datasource_id: The identifier of the data source in the format blob_{azure_blob_storage_account_name}_{container_name}.
     • file_path: The name of the file in the blob storage without the extension.
   • Response: List of versions of the metadata file

5. GET - api/datasources/{datasource_id}/{file_path}/data?{data_fetching_params}

   • Description: Returns the IQ data file for the specified data source and file path.
   • Parameters:
     • datasource_id: The identifier of the data source in the format blob_{azure_blob_storage_account_name}_{container_name}.
     • file_path: The name of the file in the blob storage without the extension.
     • data_fetching_params: have not yet being specified
   • Response: The IQ data file

6. GET - api/datasources/{datasource_id}/{file_path}/minimap

   • Description: Returns the JPEG minimap file for the specified data source and file path.
   • Parameters:
     • datasource_id: The identifier of the data source in the format blob_{azure_blob_storage_account_name}_{container_name}.
     • file_path: The name of the file in the blob storage without the extension.
   • Response: The JPEG minimap file

7. PUT - api/datasources/{datasource_id}/{file_path}/meta

   • Description: Updates the metadata file for the specified data source and file path.
   • Parameters:
     • datasource_id: The identifier of the data source in the format blob_{azure_blob_storage_account_name}_{container_name}.
     • file_path: The name of the file in the blob storage without the extension.
   • Request Body: Updated metadata file
   • Response: Success message or error if any

These new endpoints will provide efficient access to data source information, metadata, IQ data files, and minimap files, allowing for better integration and functionality within the IQEngine project.

Use recordings from url

The Dwingeloo telescopes hosts SigMF-files at https://data.camras.nl/satellites/raw/ and various other places at the starting url.

Also, we have data sets at zenodo, e.g. here.

We would like to load these SigMF files into IQEngine without downloading them to a local computer first.

It would be cool to be able to provide a link from data.camras.nl to iqengine with the url part of the address, so that it opens the recording straight away.

Within SigMF validator, have a toggle option to set additionalProperties: false within the JSON schema

in order to catch typos and such

Running backend without connection configured throws an error

Running FastAPI on port 5000...
INFO:     Started server process [12793]
INFO:     Waiting for application startup.
Starting from MongoDB 4.0.23 there isn't a generic Linux version of MongoDB
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:5000 (Press CTRL+C to quit)
Task exception was never retrieved
future: <Task finished name='Task-3' coro=<sync() done, defined at /home/sam/IQEngine/api/database/datasource_repo.py:60> exception=ClientAuthenticationError('Server failed to authenticate the request. Make sure the value of Authorization header is formed correctly including the signature.\nRequestId:05ecb159-b01e-007d-3002-c83a24000000\nTime:2023-08-06T01:05:09.5187348Z\nErrorCode:AuthenticationFailed\nauthenticationerrordetail:Signature fields not well formed.')>
Traceback (most recent call last):
  File "/home/sam/IQEngine/api/database/datasource_repo.py", line 68, in sync
    async for metadata in metadatas:
  File "/home/sam/IQEngine/api/blob/azure_client.py", line 96, in get_metadata_files
    async for blob in container_client.list_blobs():
  File "/home/sam/.local/lib/python3.10/site-packages/azure/core/async_paging.py", line 142, in __anext__
    return await self.__anext__()
  File "/home/sam/.local/lib/python3.10/site-packages/azure/core/async_paging.py", line 145, in __anext__
    self._page = await self._page_iterator.__anext__()
  File "/home/sam/.local/lib/python3.10/site-packages/azure/core/async_paging.py", line 94, in __anext__
    self._response = await self._get_next(self.continuation_token)
  File "/home/sam/.local/lib/python3.10/site-packages/azure/storage/blob/aio/_list_blobs_helper.py", line 90, in _get_next_cb
    process_storage_error(error)
  File "/home/sam/.local/lib/python3.10/site-packages/azure/storage/blob/_shared/response_handlers.py", line 189, in process_storage_error
    exec("raise error from None")   # pylint: disable=exec-used # nosec
  File "<string>", line 1, in <module>
azure.core.exceptions.ClientAuthenticationError: Server failed to authenticate the request. Make sure the value of Authorization header is formed correctly including the signature.
RequestId:05ecb159-b01e-007d-3002-c83a24000000
Time:2023-08-06T01:05:09.5187348Z
ErrorCode:AuthenticationFailed
authenticationerrordetail:Signature fields not well formed.
Content: <?xml version="1.0" encoding="utf-8"?><Error><Code>AuthenticationFailed</Code><Message>Server failed to authenticate the request. Make sure the value of Authorization header is formed correctly including the signature.
RequestId:05ecb159-b01e-007d-3002-c83a24000000
Time:2023-08-06T01:05:09.5187348Z</Message><AuthenticationErrorDetail>Signature fields not well formed.</AuthenticationErrorDetail></Error>

Linking directly to a url like https://staging.iqengine.org/siggen doesnt work

I can get to the siggen through the site but if I go to https://staging.iqengine.org/siggen I just get "{"detail":"Not Found"}", same with the other URLs, for both the current staging and prod

Unable to login to iqengine.org

Describe the bug

I'm interested in test driving the tool, but when I try to login to https://iqengine.org, I get the following error:

Selected user account does not exist in tenant 'Default Directory' and cannot access the application 'REDACTED_APPLICATION_NUMBER' in that tenant. The account needs to be added as an external user in the tenant first. Please use a different account.

This may not be the correct place to post this, but I could not find any contact info on the website.

To Reproduce
Steps to reproduce the behavior:

1. Go to https://iqengine.org
2. Click on login
3. See error

Expected behavior
See above

Screenshots

Additional context
None

Bug: FFTs above 1024 are buggy

Haven't figured out exactly whats going on but even size 2048 its not like it's just taking 2x the time to download/display, it's often not displaying anything for me, in Chrome

Ability to download samples within an annotation

Enhance Plugin Security Through Customizable Headers During Registration

Is your feature request related to a problem? Please describe.
Currently, when registering a plugin, there is no built-in mechanism for adding security controls like API keys.

Describe the solution you'd like
It would be fantastic to have an option during plugin registration to specify custom headers that should be sent along with the plugin's request. This would allow users to add API keys or other security measures, thereby enhancing the security and control over plugin usage.

Describe alternatives you've considered
An alternative could be to hard-code these security measures within each plugin, but having a centralized place for adding these headers would make management easier and more consistent.

Additional context
This feature would not only improve security but also help in managing the utilization of plugins, preventing spamming and overuse.

"how to look at a spectrogram" tutorial, for people totally new to RF

Lat/lon editable field for geolocation filter

Also the freq search needs an editable field, and stretch goal - potential dropdown for Hz/kHz/MHz/GHz, would default to Hz, make as reusable component