Awesome. Thank you. So my name is Mark and I'm here to show off the IQ Engine open source
project. I'll talk about where it's headed in the future as well. Also here we have Roman
who's involved in IQ Engine as well as SIGMF. And this talk is aimed primarily at two groups.
One is folks who are newish to SDR and RF signal processing, students, hobbyists, anyone
who wants to learn more about all this software that you're seeing. And then second is folks
who run or maintain an open source project that involves RF signal processing in some
way. And hopefully even if you're not in those groups you'll still find some interest here.
So IQ Engine currently it's a web app that is all about RF recordings. It lets you preview
recordings, manage them, analyze them, some light processing, and then most importantly
is sharing and all in your browser. So entirely web based. And I'll show a quick little demo
of what the current tool looks like. So IQ Engine is, it's available at IQEngine.org.
The project runs a public instance of the tool. But in this case I've got one running
locally because I wasn't sure about Wi-Fi. So the main screen here is essentially a list
of these RF recordings. They're all stored in the SIGMF format if you're familiar with
SIGMF. We have some good ones from Jean-Michel and Aang23. A lot of folks who are here today.
You can also open a recording that's local to your machine and then all the processing
is done client side. So like I can open a local directory full of recordings. Here, recordings
and it'll list out them all, generate the thumbnails. So actually it's the same directory
that I had served from the server. You can also open just one local file pair. So sort
of, anyway, so back to the list here. If you click on one of them, you're brought to a
spectrogram style interface where it loads the samples that you're looking at at any
given time. So that way you can have enormous files. And then the mini map on the right
represents the entire recording. So you can jump to any part of it and the little gray
area is the part you're looking at. We have time, frequency and IQ like you'd expect.
That's FM. And then some other features here are, so there's time and frequency cursors
if you want to measure stuff, adjustable dynamic range for the color, windowing, FFT size,
you can add an FIR filter taps and all of that is run client side. The FFTs are done
client side, the FIR filter is. But the one part that's not client side is our plug-in
system. So if you select a portion of the recording that you want to send to the plug-in
server, you can select it there and then, let me zoom in here, choose a plug-in. So this
was an FM recording. So I'm going to run an FM receiver that's implemented in Guinea
Radio. And it sends the samples to the server that runs Guinea Radio. And then in this case,
it's actually returning a WAV file with the audio of that signal. But there's other types
of outputs like you could run a block or a plug-in that gives you IQ as the output. So
if I do a low pass filter, it's just going to output IQ. Let me give it a proper cutoff
frequency there. And then currently we're just displaying the IQ in a pop-up. But in
the future, we're trying to figure out the best way to replace kind of the signal that's
already on the screen with this new one so that you can chain plug-ins together. So that's
sort of the gist of the tool. Now back to the slides here. So everything's, IQ engine's
built on top of SIGMF in many ways. If you're not familiar, SIGMF is an open standard for
saving your RF recordings to a file. It's as simple as it gets. You have a binary IQ
file which is sort of the native way to store a recording and then a JSON file. And the
SIGMF specifications mainly tell you how to write that JSON file. So there's stuff like
how you specify sample rate, center frequency, data type. And then I'll show you annotations
in a second here. And by using SIGMF, you have software interoperability. And then you
can also avoid data bit rot where like in five years you forget what sample rate stuff was
taken at. If you want to learn more about SIGMF, there's a link at the top of IQengine.org
and it also links out to the SIGMF GitHub page. So SIGMF, the standard is managed by
GNU Radio. It's kind of a sub-project sort of. Now as far as the IQ engine code itself,
it's web-based, front-end uses React, Tailwind, some big dependencies that we get a lot of
use out of our code mirror for all of the code editing. PyOdide lets us run Python in
the browser. I didn't demo that but there's some videos online about how that gets used.
And then Plotly for those time frequency and IQ plots. WebAssembly for FFTs. And then for
our documentation, we use the MDX system which lets us write it in markdown and then have
it rendered as part of this page here. So this was written in markdown and then it lets us
render it as React components. Kind of nice. Now, so that was kind of the introduction
but I wanted to start off where I left at GNU Radio conference last year. So what have
we done since then? Well now it's possible to run a local instance of IQengine like if
you want to run it within an organization or whatever to share things privately. You
can run an instance and you can put the recordings on the same server. So easy enough. Or something
that's mounted to the file system as long as Python open can see it and then it can serve
the recording. And the other option is to use Cloud Storage which is what we do for
IQengine.org. And as far as how to do that, so the general idea is you pick a directory
on your server and then you can run IQengine with the Docker images. So if you go to the
install with Docker page, you really, all you have to do is change the directory that's
mounted into the container. So pretty much this part here of the command. And then the
rest of this command will pull the latest IQengine Docker image and it will run it. And you should
be able to see your recordings. They'll look like this because they'll be local to the
back end. Versus IQengine.org which has a few different data sources that pop up here.
So and that's, yeah, fairly new. If you end up using this and notice some quality of life
issues, definitely reach out on Discord or GitHub. So next up, I'm going to dive into the plug-in
system that you saw me run with the FM receiver. So the idea is any RF signal processing that you
want to run on a back end server but triggered from the browser. So what we have within our
project is this rest-based API and it allows for someone to write the plug-in server in any
language they want. We have an example in Python and then Loic wrote one for Rust. The Python
one can run Gini radio flow graphs. It just pretty much runs the Python flow graph and
then uses ZMQ to get samples in and out of it. But in the future, there'll be more languages
and by using this rest API, it doesn't matter. It could be, really you can deploy it and implement
it however you want to as long as it supports this interface. I'm going to show a little
demo later running SatDump which is kind of an example of a whole separate project, not
a Gini radio flow graph or anything, but a piece of open-source software that you can
trigger from IQ Engine. And then Aang will be presenting more about SatDump in like an
hour or so. So as far as how the plug-ins look, the Python based ones, we tried to make
it as easy as possible to create a new one. This isn't the actual rest API, this is just
how you would make a new Python plug-in and then you would use an existing server code
that we already have. So you can see you have to specify your custom parameters and then
there's a run function where you're given the samples and you have to return several
different data types. As far as Gini radio, you specify the flow graph, but the only catch
is you have to substitute your file source and GUIs with the ZMQ source and ZMQ sync.
That's how we get samples in and out. Not the most performant thing, but it gets the
job done. So you can see these first couple blocks are the ZMQ ones and then the rest
represents the flow graph. So we have a Python flow graph that implements an FM receiver
in this case and that was the plug-in that I ran earlier. So the kind of the motivation
here is if you are an author of an out of tree module for Gini radio, you probably already
shared the code somewhere like GitHub and created some examples, some example flow graphs,
but the next step would be making it more accessible and easy for folks to find and play
with and I think this could be an option there by exposing it as a plug-in. Now, let
me go back to the plug-ins. So I'll go ahead and run the SAT dump one. So I've got a recording
of NOAA APT right here contributed by Aang. So I can click that, I can browse around
the signal. I'll notice so it's actually offset, but I believe this is the APT signal. You
could jump to different parts of the file there and then as far as running it through
SAT dump, I want to run the entire file because it needs a decent amount of samples. So I'm
going to select the whole file and then under plug-ins, we've got the fresh new SAT dump
plug-in already preloaded with the pipeline for APT, but you can put whatever pipeline
you want. So right now it ran SAT dump under the hood. So here's one of the images that
comes out. I think IQ Engine still has some work to do as far as if you have a bunch of
different outputs, how do you present them all to the user? There's a lot of web design
that can go on there. So either it pops open something or it saves a file and it supports
all the different MIME types. If you're familiar with web, it sort of just uses MIME type and
then we added some custom MIME types for IQ, like the different data types for SIGMF.
As far as other plug-ins, I think, yeah, pretty much, we have a detector as well. So let
me go to a recording that I give my students when we study signal detection and classification.
This is kind of like a toy example meant for testing a detector where you have a few different
signals here. IQ Engine's not about implementing RFML, it's about sharing it and making it
more accessible. So we made a very simple detector just to have an example. It's written
in Python, you're welcome to check it out in the source. It's called Simple Detector.
We also have Marco's detector, he was someone else who was working on it. Simple Detector
was pretty quick for that number of samples and it did a decent job. There's one extra
little detected emission there. Now the results are in the form of SIGMF annotations which
are bounding boxes in time and frequency and that's how the results are shared from the
plug-in. So if you wanted to download the raw metadata file, the SIGMF file, you can
go to the bottom here and here are the annotations that the plug-in created. So we sort of copied
the SIGMF format for the return data type. And if you wanted to perform classification
you would simply fill out the label and they would show up. Within IQ Engine you can also
edit the annotations and edit the labels. So if you wanted to manually tweak stuff like
you were making an RFML data set, sort of like a golden meta file, you could do that
here. What I find most useful is simply to have a quick glance at how well something
worked. If you had tons of files to run through you wouldn't want to do all this clicking,
you would just make a script and you could certainly run the plug-ins from a Python script.
It would just need to call the REST API. Back to the slides. Alright, so I want to take
just a really quick tangent to mention, remind people about what Gini Radio provides and then
how it relates to this plan that the project has. So Gini Radio, it's a way to implement
your RF, DSP and C++ or Python. It gives us a standard framework for doing that implementation
and it's easy to get annoyed at the boilerplate and how to install everything. But in the
end if you use that framework it means that other people who are familiar with Gini Radio
can then install your Aditree module. They sort of know the standard usage of your blocks,
where to look for the example flow graphs, how to connect your application with their
SDR sitting on their desk. And that's an enormous value, that's in my opinion one of the main
values of Gini Radio. And then the GUIs are nice as well, it's not always easy to program
GUIs. So if you're curious about learning about different Aditree modules, C-Gran.org
is where we point people. And I mention this because C-Gran represents a centralized location
for Gini Radio applications and libraries, what we call out of tree modules. But kind
of zooming out one more layer going beyond just Gini Radio is what I'm going to talk
about here in a sec. So let's say that you're a developer of open source software that involves
RF processing in some way, like you wrote SAT dump and you're doing satellite signal processing.
You build something, you want to share it, you want to keep it easy to demonstrate and
show off to people, easy to use. Those are sort of the main steps you might take. Now
on the other side of things, you have users out there, whoever they are, individual students,
organizations, who first they need to discover that this software exists. That's like the
very first step. And then how do you install it, how do you run it properly, how can I
evaluate how well it's working and use it with my SDR or my recordings. So kind of a
duality here. On the developer side, you might post your code to GitHub, you might share
it as part of a Faw STEM talk. That's kind of like the current method that we use. On
the user side of things, you might Google the topic you're interested in, like specific
satellite, Wi-Fi, whatever. You'll probably come across what's out there. But it's not
the best way to do it, right? Just by Googling. So installation can be an enormous barrier.
When I teach CS students, it depends who you are, but some students and some folks are
better at getting this software installed than others. Obviously having a lot of Linux
experience helps folks who are new to Linux but want to dive into signal processing, they
can struggle here and there. So it can definitely be a barrier. Now how do you actually run
it? If it's a new radio flow graph, you probably know how, but not everything's easy to use.
There's RF libraries out there that are not clear how exactly do you use it, but you know
it's powerful. And then lastly, evaluating the software. Maybe you're going to use it
as a dependency or use it as part of a project. So this idea to sort of evolve IQ engines,
so instead of just being a way to share and evaluate RF recordings, it can also be used
for just RF open source software in general. Sort of like a central hub, community driven
for devs to share stuff for users to find and discover software. And then by exposing
the software as a plugin, they can try it out on recordings that are already on the
site or their own. And then one side benefit is university isn't anyone else who wants
to show off their expertise and creates open source software. They can use this central
hub as a way to do that. Now this is all in the browser primarily for accessibility
sake. It's not the most performant way to do something like this, but it's extremely
convenient. Really, it removes a lot of barriers. So users would be able to play around with
a certain function using a variety of recordings. And it's more than just using recordings.
They can try in the future, maybe there's a way to lower the SNR, like add noise and
see if it still works or what not. Add a frequency shift, see if the RF function still works.
And then on the author side of things, all you really would need to do is add this REST
based interface or at least make it easy to call with CLI and then retrieve the results.
So like Sat dump, I'm not using a REST interface. I'm just running the CLI in a way that's
easy. Anyway, now one design decision that was made was to allow multiple plugin servers
to connect to a single IQ Engine instance like at IQEngine.org. That way, like a university
could run their own plugin server, have total control over it, but they could share their
expertise, everything they want to show off. And this is really just a concept. So right
now I showed you how IQ Engine lets you preview RF recordings and RF data sets. Well, I think
in the future with these building blocks that I showed through the plugin system and this
REST interface that we're designing, you could have a tool that would be used for previewing
what I'm calling Functions App Software, really anything that involves RF signal processing.
Now there are limitations, so a lot of RF apps can't simply be run on a recording. So
SRS ran excellent LTE and 5G radio stack. Because of LTE and 5G's strict latency requirements,
you can't easily just play it back. It's not straightforward, simply running it on a recording.
You sort of want to simulate that closed loop system. So not all RF functions and apps are
going to be shareable this way, but I think a vast majority of them are definitely GNU
radio apps and those kind of processing applications. The other thing that you wouldn't show off
is like an SDR interface, like a GUI, that wouldn't make any sense. Now if you're interested
in contributing, it's a community led project, so we can always use more web devs. It turns
out that the kind of folks in these RF circles tend to know C++, Python, but less so on the
website. And I know I've had to learn a lot of web development to get this project moving
more. So even if you're not a web developer, there's plenty of other ways to contribute.
We're always looking for more interesting RF recordings to share. If you have an entire
data set, we can add like a whole category here on the left. So we have Daniel Estevez's
awesome satellite recordings as an example, where we can link off to your website. And
so if you want to get involved in any way, there's a Discord link at the top of IQengine.org.
We have a little community that's slowly building. And with that, I will take questions.
Yep?
So yeah, the question was related to geolocation data, like running it as a plugin, I assume.
Yeah, yeah, while I explain that, so there actually is already a maps-based interface
for, anyway, when we designed the API mentioned, we made sure to allow multiple channels of
RF. So those channels could be time synchronized recordings from different sensors. That way
at least you could run it from a, the backend perspective. And then, yeah, I guess we would
need to have a maps interface to the spectrogram page to make that fully happen. So yeah, I
would need to make that fully happen. But good, good, great suggestion. Yep?
Well, so Guinea Radio has some Azure credit that they got, and that's what we've been
using for a lot of these recordings. So, and we can use that for other folks' recordings
if they want to share it publicly. Yeah, you can reach out and we can transfer it over.
Yeah, I think it would fall. No, no, no, like I could like upload it for you. So the Guinea
Radio has a blob storage account, so I could, I could give you a SAS token for you to upload
it yourself or I could upload it for you. Yep, I think there was one more. Yes, there
is something that's a work in progress, but I guess I'll share it. So there's an upload
page. Oh yeah, yeah, so, so IQengine.org slash upload should allow you to upload a recording.
The Wi-Fi's not great, but yeah, that would be the first place to go. I think we're out
of time. Any last question? Yep? So how well does it actually handle everybody's
thoughts? So, I mean, it was designed to deal with terabyte files from the start, which
is why we have that minimap, and when you open the spectrogram page, it's only loading
what you're looking at at any given time. So it's sending the IQ samples to your client,
to the browser. The browser's doing the FFTs. So it's sending maybe a few million samples
to get a spectrogram like this, but if it's a mini terabyte recording, you'll just have
a smaller, like, gray window here, because it'll represent a smaller part of the whole
recording. Yeah, I mean, you have to store the recording, but it's not all, we have
no part of the code that sends the entire recording to either the client or the backend,
because we know it's not going to fly for huge stuff. All right. Yep? Yeah. Yeah.
Actually, SIGMF has a lot of, there's even an extension for more details about the hardware
involved. Definitely check out SIGMF, the specs. So if you want a five minute introduction
to SIGMF, that's what we have here on IQ Engine, but I would, yeah, go ahead and go
to the specs and dive in, and you'll know a lot of the parameters that you mentioned.
All right, thank you very much.
Wow. Thank you very much.
Thank you very much.
Thank you.