{"@attributes":{"version":"2.0"},"channel":{"title":"K3XEC","link":"https:\/\/k3xec.com\/","description":"Recent content on K3XEC","generator":"Hugo -- gohugo.io","language":"en-us","lastBuildDate":"Tue, 19 May 2026 11:00:00 -0500","item":[{"title":"designing arf, an sdr iq encoding format \ud83d\udc36","link":"https:\/\/k3xec.com\/arf\/","pubDate":"Wed, 15 Apr 2026 11:43:00 -0400","guid":"https:\/\/k3xec.com\/arf\/","description":"
\nInterested in future updates? Follow me on mastodon at\n@paul@soylent.green<\/a>. Posts about\nhz.tools<\/code> will be tagged\n#hztools<\/a>.
\n
\n\ud83d\udc36 Want to jump right to the draft? I'll be maintaining ARF going forward at\n\/draft-tagliamonte-arf-00.txt<\/a>.\n<\/div>\n

It’s true – processing data from software defined radios can be a bit\ncomplex<\/a>\n\ud83d\udc48\ud83d\ude0f\ud83d\udc48 – which tends to keep all but the most grizzled experts and bravest\nsouls from playing with it. While I wouldn’t describe myself as either, I will\nsay that I’ve stuck with it for longer than most would have expected of me.\nOne of the biggest takeaways I have from my adventures with software defined\nradio is that there’s a lot of cool crossover opportunity between RF and\nnearly every other field of engineering.<\/p>\n

Fairly early on, I decided on a very light metadata scheme to track SDR\ncaptures, called rfcap<\/a>. rfcap has withstood my test\nof time, and I can go back to even my earliest captures and still make sense of\nwhat they are – IQ format, capture frequencies, sample rates, etc. A huge\npart of this was the simplicity of the scheme (fixed-lengh header, byte-aligned\nto supported capture formats), which made it roughly as easy to work with as a\nraw file of IQ samples.<\/p>\n

However, rfcap has a number of downsides. It’s only a single, fixed-length\nheader. If the frequency of operation changed during the capture, that change\nis not represented in the capture information. It’s not possible to easily\nrepresent mulit-channel coherent IQ streams, and additional metadata is\ncondemned to adjacent text files.<\/p>\n

ARF (Archive of RF)<\/h1>\n

A few years ago, I needed to finally solve some of these shortcomings and tried\nto see if a new format would stick. I sat down and wrote out my design goals\nbefore I started figuring out what it looked like.<\/p>\n

First, whatever I come up with must be capable of being streamed and processed\nwhile being streamed. This includes streaming across the network or merely\nwritten to disk as it’s being created. No post-processing required. This is\nmostly an artifact of how I’ve built all my tools and how I intereact with my\nSDRs. I use them extensively over the network (both locally, as well\nas remotely by friends across my wider<\/a>\nlan<\/a>). This decision sometimes even\nprompts me to do some crazy things<\/a> from time\nto time.<\/p>\n

I need actual, real support for multiple IQ channels from my multi-channel SDRs\n(Ettus, Kerberos\/Kracken SDR, etc) for playing with things like\nbeamforming<\/a>.\nMy new format must be capable of storing\nmultiple streams in a single capture file, rather than a pile of files in\na directory (and hope they’re aligned).<\/p>\n

Finally, metadata must be capable of being stored in-band. The initial set of\nmetadata I needed to formalize in-stream were Frequency Changes<\/code> and\nDiscontinuities<\/code>. Since then, ARF has grown a few more.<\/p>\n

After getting all that down, I opted to start at what I thought the simplest\ncontainer would look like,\nTLV<\/a>\n(tag-length-value) encoded packets. This is a fairly well trodden path,\nand used by a bunch of existing protocols\nwe<\/a>\nall<\/a>\nknow<\/a>\nand\nlove<\/a>.\nEach ARF file (or stream) was a set of\nencoded “packets” (sometimes called data units in other specs). This means that\nunknown packet types may be skipped (since the length is included) and\nadditional data can be added after the existing fields without breaking\nexisting decoders.<\/p>\n

\n
\ntag<\/a>\n<\/div>\n
\nflags<\/a>\n<\/div>\n
\nlength\n<\/div>\n
\nvalue\n<\/div>\n<\/div>\n
\nHeads up!<\/b>\nOnce this is posted, I'm not super likely to update this page. Once this\ngoes out, the latest stable copy of the ARF spec is maintained at\ndraft-tagliamonte-arf-00.txt<\/a>.\nThis page may quickly become out of date, so if you're actually interested in\nimplementing this, I've put a lot of effort into making the draft\ncomprehensive, and I plan to maintain it as I edit the format.\n<\/div>\n

Unlike a “traditional” TLV structure, I opted to add “flags” to the top-level\npacket. This gives me a bit of wiggle room down the line, and gives me a\nfeature that I like from ASN.1 – a “critical” bit. The critical bit indicates\nthat the packet must be understood fully by implementers, which allows future\nbackward incompatible changes by marking a new packet type as critical. This\nwould only really be done if something meaningfully changed the interpretation\nof the backwards compatible data to follow.<\/p>\n\n\n\n\n
Flag<\/td>\nDescription<\/td>\n<\/tr>\n<\/thead>\n
0x01<\/td>Critical (tag must be understood)<\/td><\/tr>\n<\/tbody>\n<\/table>\n

Within each Packet is a tag<\/code> field. This tag indicates how the contents of the\nvalue<\/code> field should be interpreted.<\/p>\n\n\n\n\n
Tag ID<\/td>\nDescription<\/td>\n<\/tr>\n<\/thead>\n
0x01<\/td>Header<\/a><\/td><\/tr>\n
0x02<\/td>Stream Header<\/a><\/td><\/tr>\n
0x03<\/td>Samples<\/a><\/td><\/tr>\n
0x04<\/td>Frequency Change<\/a><\/td><\/tr>\n
0x05<\/td>Timing<\/td><\/tr>\n
0x06<\/td>Discontinuity<\/a><\/td><\/tr>\n
0x07<\/td>Location<\/a><\/td><\/tr>\n
0xFE<\/td>Vendor Extension<\/a><\/td><\/tr>\n<\/tbody>\n<\/table>\n

In order to help with checking the basic parsing and encoding of this format,\nthe following is an example packet which should parse without error.<\/p>\n

 00, \/\/ tag (0; no subpacket is 0 yet)\n<\/span><\/span> 00, \/\/ flags (0; no flags)\n<\/span><\/span> 00, 00 \/\/ length (0; no data)\n<\/span><\/span> \/\/ data would go here, but there is none\n<\/span><\/span><\/code><\/pre><\/div>
Additionally, throughout the rest of the subpackets, there are a few unique and\nshared datatypes. I document them all more clearly in the draft, but to quickly\nrun through them here too:<\/p>\n
UUID<\/h3>\n
This field represents a globally unique idenfifer, as defined by RFC 9562, as\n16 raw bytes.<\/p>\n
Frequency<\/h3>\n
Data encoded in a Frequency field is stored as microhz (1 Hz is stored as\n1000000, 2 Hz is stored as 2000000) as an unsigned 64 bit integer. This has a\nminimum value of 0 Hz, and a maximum value of 18446744073709551615 uHz, or just\nabove 18.4 THz. This is a bit of a tradeoff, but it’s a set of issues that I\nwould gladly contend with rather than deal with the related issues with storing\nfrequency data as a floating point value downstream. Not a huge factor, but as\nan aside, this is also how my current generation SDR processing code (sparky<\/code>)\nstores Frequency data internally, which makes conversion between the two\nnatural.<\/p>\n
IQ samples<\/h3>\n
ARF supports IQ samples in a number of different formats. Part of the idea here\nis I want it to be easy for capturing programs to encode ARF for a specific\nradio without mandating a single iq format representation. For IQ types with\na scalar value which takes more than a single byte, this is always paired\nwith a Byte Order field, to indicate if the IQ scalar values are little or\nbig endian.<\/p>\n\n\n\n\n
ID<\/td>\nName<\/td>\nDescription<\/td>\n<\/tr>\n<\/thead>\n
0x01<\/td>f32<\/td>interleaved 32 bit floating point scalar values<\/td><\/tr>\n
0x02<\/td>i8<\/td> interleaved 8 bit signed integer scalar values<\/td><\/tr>\n
0x03<\/td>i16<\/td>interleaved 16 bit signed integer scalar values<\/td><\/tr>\n
0x04<\/td>u8<\/td> interleaved 8 bit unsigned integer scalar values<\/td><\/tr>\n
0x05<\/td>f64<\/td>interleaved 64 bit floating point scalar values<\/td><\/tr>\n
0x06<\/td>f16<\/td>interleaved 16 bit floating point scalar values<\/td><\/tr>\n<\/tbody>\n<\/table>\n
Header<\/h2>\n
Each ARF file must start with a specific Header packet. The header contains\ninformation about the ARF stream writ large to follow. Header packets are\nalways marked as “critical”.<\/p>\n
\n
\nmagic\n<\/div>\n
\nflags\n<\/div>\n
\nstart\n<\/div>\n
\nguid\n<\/div>\n
\nsite guid\n<\/div>\n
\n#st\n<\/div>\n<\/div>\n
In order to help with checking the basic parsing and encoding of this format,\nthe following is an example header subpacket (when encoded or decoded this\nwill be found inside an ARF packet as described above) which should parse\nwithout error, with known values.<\/p>\n
00, 00, 00, fa, de, dc, ab, 1e, \/\/ magic\n<\/span><\/span>00, 00, 00, 00, 00, 00, 00, 00, \/\/ flags\n<\/span><\/span>18, 27, a6, c0, b5, 3b, 06, 07, \/\/ start time (1740543127)\n<\/span><\/span>\n<\/span><\/span>\/\/ guid (fb47f2f0-957f-4545-94b3-75bc4018dd4b)\n<\/span><\/span>fb, 47, f2, f0, 95, 7f, 45, 45,\n<\/span><\/span>94, b3, 75, bc, 40, 18, dd, 4b,\n<\/span><\/span>\n<\/span><\/span>\/\/ site_id (ba07c5ce-352b-4b20-a8ac-782628e805ca)\n<\/span><\/span>ba, 07, c5, ce, 35, 2b, 4b, 20,\n<\/span><\/span>a8, ac, 78, 26, 28, e8, 05, ca\n<\/span><\/span><\/code><\/pre><\/div>
Stream Header<\/h2>\n
Immediately after the arf Header<\/a>, some number of Stream Headers\nfollow. There must be exactly the same number of Stream Header packets as are\nindicated by the num streams<\/code> field of the Header. This has the nice effect of\nenabling clients to read all the stream headers without requiring buffering of\n“unread” packets from the stream.<\/p>\n
\n
\nid\n<\/div>\n
\nflags\n<\/div>\n
\nfmt\n<\/div>\n
\nbo\n<\/div>\n
\nrate\n<\/div>\n
\nfreq\n<\/div>\n
\nguid\n<\/div>\n
\nsite\n<\/div>\n<\/div>\n
In order to help with checking the basic parsing and encoding of this format,\nthe following is an example stream header subpacket (when encoded or decoded\nthis will be found inside an ARF packet as described above) which should parse\nwithout error, with known values.<\/p>\n
00, 01, \/\/ id (1)\n<\/span><\/span>00, 00, 00, 00, 00, 00, 00, 00, \/\/ flags\n<\/span><\/span>01, \/\/ format (float32)\n<\/span><\/span>01, \/\/ byte order (Little Endian)\n<\/span><\/span>00, 00, 01, d1, a9, 4a, 20, 00, \/\/ rate (2 MHz)\n<\/span><\/span>00, 00, 5a, f3, 10, 7a, 40, 00, \/\/ frequency (100 MHz)\n<\/span><\/span>\n<\/span><\/span>\/\/ guid (7b98019d-694e-417a-8f18-167e2052be4d)\n<\/span><\/span>7b, 98, 01, 9d, 69, 4e, 41, 7a,\n<\/span><\/span>8f, 18, 16, 7e, 20, 52, be, 4d,\n<\/span><\/span>\n<\/span><\/span>\/\/ site_id (98c98dc7-c3c6-47fe-bc05-05fb37b2e0db)\n<\/span><\/span>98, c9, 8d, c7, c3, c6, 47, fe,\n<\/span><\/span>bc, 05, 05, fb, 37, b2, e0, db,\n<\/span><\/span><\/code><\/pre><\/div>
Samples<\/h2>\n
Block of IQ samples in the format indicated by this stream’s format<\/code> and\nbyte_order<\/code> field sent in the related Stream Header<\/a>.<\/p>\n
\n
\nid\n<\/div>\n
\niq samples\n<\/div>\n<\/div>\n
In order to help with checking the basic parsing and encoding of this format,\nthe following is an samples subpacket (when encoded or decoded\nthis will be found inside an ARF packet as described above). The IQ values\nhere are notional (and are either 2 8 bit samples, or 1 16 bit sample,\ndepending on what the related Stream Header<\/a> was).<\/p>\n
01, \/\/ id\n<\/span><\/span>ab, cd, ab, cd, \/\/ iq samples\n<\/span><\/span><\/code><\/pre><\/div>
Frequency Change<\/h2>\n
The center frequency of the IQ stream has changed since the\nStream Header<\/a> or last Frequency Change<\/a>\nhas been sent. This is useful to capture IQ streams that are jumping\naround in frequency during the duration of the capture, rather than\nstarting and stopping them.<\/p>\n
\n
\nid\n<\/div>\n
\nfrequency\n<\/div>\n<\/div>\n
In order to help with checking the basic parsing and encoding of this format,\nthe following is a frequency change subpacket (when encoded or decoded\nthis will be found inside an ARF packet as described above).<\/p>\n
01, \/\/ id\n<\/span><\/span>00, 00, b5, e6, 20, f4, 80, 00 \/\/ frequency (200 MHz)\n<\/span><\/span><\/code><\/pre><\/div>
Discontinuity<\/h2>\n
Since the last Samples packet for this stream, samples have been dropped\nor not encoded to this stream. This can be used for a stream that has\ndropped samples for some reason, a large gap (radio was needed for something\nelse), or communicating “iq snippits”.<\/p>\n
\n
\nid\n<\/div>\n<\/div>\n
In order to help with checking the basic parsing and encoding of this format,\nthe following is a discontinuity subpacket (when encoded or decoded this will\nbe found inside an ARF packet as described above).<\/p>\n
01, \/\/ id\n<\/span><\/span><\/code><\/pre><\/div>
Location<\/h2>\n
Up-to-date location as of this moment of the IQ stream, usually from a GPS.\nThis allows for in-band geospatial information to be marked in the IQ stream.\nThis can be used for all sorts of things (detected IQ packet snippits aligned\nwith a time and location or a survey of rf noise in an area)<\/p>\n
\n
\nflags\n<\/div>\n
\nsys<\/a>\n<\/div>\n
\nlat\n<\/div>\n
\nlong\n<\/div>\n
\nel\n<\/div>\n
\naccuracy\n<\/div>\n<\/div>\n
The sys<\/code> field indicates the Geodetic system to be used for the provided\nlatitude<\/code>, longitude<\/code> and elevation<\/code> fields. The full list of supported\ngeodetic systems is currently just WGS84, but in case something meaningfully\nchanges in the future, it’d be nice to migrate forward.<\/p>\n
Unfortunately, being a bit of a coward here, the accuracy field is a bit of a\ncop-out. I’d really rather it be what we see out of kinematic state estimation\ntools like a kalman filter, or at minimum, some sort of ellipsoid. This is\nneither of those - it’s a perfect sphere of error where we pick the largest\nerror in any direction and use that. Truthfully, I can’t be bothered to model\nthis accurately, and I don’t want to contort myself into half-assing something\nI know I will half-ass just because I know better.<\/p>\n\n\n\n\n
System<\/td>\nDescription<\/td>\n<\/tr>\n<\/thead>\n
0x01<\/td>\nWGS84 - World Geodetic System 1984<\/a>\n<\/td><\/tr>\n<\/tbody>\n<\/table>\n
In order to help with checking the basic parsing and encoding of this format,\nthe following is a location subpacket (when encoded or decoded this will be\nfound inside an ARF packet as described above).<\/p>\n
00, 00, 00, 00, 00, 00, 00, 00, \/\/ flags\n<\/span><\/span>01, \/\/ system (wgs84)\n<\/span><\/span>3f, f3, be, 76, c8, b4, 39, 58, \/\/ latitude (1.234)\n<\/span><\/span>40, 02, c2, 8f, 5c, 28, f5, c3, \/\/ longitude (2.345)\n<\/span><\/span>40, 59, 00, 00, 00, 00, 00, 00, \/\/ elevation (100)\n<\/span><\/span>40, 24, 00, 00, 00, 00, 00, 00 \/\/ accuracy (10)\n<\/span><\/span><\/code><\/pre><\/div>
Vendor Extension<\/h2>\n
In addition to the fields I put in the spec, I expect that I may need custom\npacket types I can’t think of now. There’s all sorts of useful data that could\nbe encoded into the stream, so I’d rather there be an officially sanctioned\nmechanism that allows future work on the spec without constraining myself.<\/p>\n
Just an example, I’ve used a custom subpacket to create test vectors, the data\nis encoded into a Vendor Extension, followed by the IQ for the modulated\npacket. If the demodulated data and in-band original data don’t match, we’ve\nregressed. You could imagine in-band speech-to-text, antenna rotator azimuth\ninformation, or demodulated digital sideband data (like FM HDR data) too. Or\neven things I can’t even think of!<\/p>\n
\n
\nid\n<\/div>\n
\ndata\n<\/div>\n<\/div>\n
In order to help with checking the basic parsing and encoding of this format,\nthe following is a vendor extension subpacket (when encoded or decoded this\nwill be found inside an ARF packet as described above).<\/p>\n
\/\/ extension id (b24305f6-ff73-4b7a-ae99-7a6b37a5d5cd)\n<\/span><\/span>b2, 43, 05, f6, ff, 73, 4b, 7a,\n<\/span><\/span>ae, 99, 7a, 6b, 37, a5, d5, cd,\n<\/span><\/span>\n<\/span><\/span>\/\/ data (0x01, 0x02, 0x03, 0x04, 0x05)\n<\/span><\/span>01, 02, 03, 04, 05\n<\/span><\/span><\/code><\/pre><\/div>
Tradeoffs<\/h1>\n
The biggest tradeoff that I’m not entirely<\/em> happy with is limiting the length\nof a packet to u16<\/code> – 65535 bytes. Given the u8 sample header, this limits us\nto 8191 32 bit sample pairs at a time. I wound up believing that the overhead in\nterms of additional packet framing is worth it – because always encoding 4\nbyte lengths felt like overkill, and a dynamic length scheme ballooned\ncodepaths in the decoder that I was trying to keep as easy to change as\npossible as I worked with the format.<\/p>"},{"title":"librtlsdr.so for fun and profit","link":"https:\/\/k3xec.com\/sparky-rtlsdr\/","pubDate":"Fri, 27 Mar 2026 13:30:00 -0400","guid":"https:\/\/k3xec.com\/sparky-rtlsdr\/","description":"
\nInterested in future updates? Follow me on mastodon at\n@paul@soylent.green<\/a>. Posts about\nhz.tools<\/code> will be tagged\n#hztools<\/a>.
\n<\/div>\n
It’s well known and universally agreed that radios are cool. Among the\ncontested field of coolest radios, Software Defined Radios (SDRs) are\ndefinitely the most interesting to me. Out of all of my (entirely too many)\nSDRs I own, the rtlsdr<\/code> is still my #1. It’s just good<\/em>. It’s a great price,\nextremely capable, reliable, well-supported, and compact. Why bother with\nanything else? Sure, it can’t transmit, uses a (fairly weird) 8 bit unsigned\ninteger IQ representation<\/a>,\nlimited sampling rate, limited frequency range – but even with all that, it’s\nstill the radio I will pack first. Don’t get me wrong, I love my Ettus radios,\nPlutoSDRs, HackRFs, my AirspyHF+ - they’re great! I just always find myself\nfalling back to an rtl-sdr<\/code>, every time.<\/p>\n
Perhaps the best reason to use an rtlsdr<\/code> is the absolutely mind-boggling\namount of cool stuff people have written for it. The rtlsdr<\/code> API is super easy\nto use, widely supported if you’re building on top of existing radio processing\nframeworks – it’s still a shock<\/em> to me when something omits rtlsdr<\/code> support.<\/p>\n
sparky<\/h1>\n
Over the last 7 years, I’ve been learning about radios – I got my ham radio\nlicense (de K3XEC<\/code>), hacked<\/a>\non<\/a> some<\/a>\ncool<\/a> stuff<\/a> where I’ve\nlearned how radios work by “doing”, and even was lucky enough to give my first\nrf-centric talk at districtcon<\/a>.\nEmbarrassingly, I still haven’t gotten around to learning how the fancy stuff\nlike GNU Radio<\/a> works. I’m sure I’m going to love\nit when I do.<\/p>\n
As part of this, I’ve also cooked up some very unprofessional formats and\nprotocols I use for convenience. Locally, all my on-disk captures are stored in\nrfcap<\/a> or more recently arf<\/a>,\nwhile direct SDR access at my house is almost entirely a mix of\nthe widely used rtl-tcp<\/a> protocol, and my\n“riq<\/code>” protocol (post on this coming soon). Both rtl-tcp<\/code> and riq<\/code> operate\nover the network, so I don’t have to bother with plugging things into USB ports,\nand I can share my radios with my friends<\/a>.<\/p>\n
All of that work sits in my current generation of radio processing code,\n“sparky” (a reference to\nspark-gap transmitters<\/a>),\nwhich is a heap of Rust, supporting everything from no_std<\/code> for embedded\nexperiments, conditional support for interfacing with all the radios I\nown, and tokio<\/code>-based async support in addition to blocking i\/o\nfor highly concurrent daemons. This quickly advanced beyond my old Go-based\ncode (hz.tools\/go-sdr<\/a>), which I archived\nso I can focus on learning. I still think Go is a great language to write RF\ncode in – but I can’t focus on that tech tree anymore.<\/p>\n
Of course, this now poses a new problem – no one supports my format(s) or\nradio protocol(s), since, well, I’m the only one using them. I’ve committed a\nfair amount of my hardware to this setup, and yanking it from the rack to try\nsomething out does pose a bit of a pickle. This isn’t a huge deal for learning,\nbut it does make it tedious to try out something from the internets.<\/p>\n
librtlsdr.so<\/h1>\n
Thankfully, Rust has robust support for\nwrap[ping itself] in a grotesque simulacra of C\u2019s skin and mak[ing its] flesh undulate<\/a>,\nwhich is an attractive nuisance if i’ve ever seen one. Naturally, my ability\nto restrain myself from engaging in ill-advised rf adventures is basically\nzero, so it’s time to do the thing any similarly situated person would do –\nreimplement the API and ABI of librtlsdr.so<\/code>, backed with sparky<\/code> instead.<\/p>\n
Since enumeration of devices is going to be annoying (specifically, they’re\nover the network), I decided early-on to rely on an explicit list of\ndevices via a configuration file. I’d rather only load that once so programs\ndon’t get confused, so I opted to use a\nCTOR<\/a>\nto run a stub when the ELF is linked at runtime.<\/p>\n
\/\/ lightly edited for clarity\n<\/span><\/span><\/span><\/span>\n<\/span><\/span>#[used]<\/span>\n<\/span><\/span>#[expect(unused)]<\/span>\n<\/span><\/span>#[unsafe(link_section = <\/span>".init_array"<\/span>)]<\/span>\n<\/span><\/span>pub<\/span> static<\/span> INITIALIZE<\/span>: extern<\/span> "C"<\/span> fn<\/span>() =<\/span> sparky_rtlsdr_ctor;\n<\/span><\/span>\n<\/span><\/span>#[unsafe(no_mangle)]<\/span>\n<\/span><\/span>pub<\/span> extern<\/span> "C"<\/span> fn<\/span> sparky_rtlsdr_ctor<\/span>() {\n<\/span><\/span> let<\/span> config: Config<\/span> =<\/span> {\n<\/span><\/span> if<\/span> let<\/span> Ok(config_bytes) =<\/span> std::fs::read("\/etc\/sparky-rtlsdr.toml"<\/span>) {\n<\/span><\/span> toml::from_slice(&<\/span>config_bytes).unwrap()\n<\/span><\/span> } else<\/span> {\n<\/span><\/span> Config { device: vec<\/span>!<\/span>[] }\n<\/span><\/span> }\n<\/span><\/span> };\n<\/span><\/span> CONFIG<\/span>.set(config);\n<\/span><\/span>}\n<\/span><\/span><\/code><\/pre><\/div>
Next, it’s time to start with the basics. Opening and closing a handle using\nrtlsdr_open<\/code> and rtlsdr_close<\/code>. Given we don’t control the runtime, and the\nrtl-sdr<\/code> device handle is opaque (for good reason!), I opted to smuggle a rust\nBox<Device><\/code> non-FFI safe heap-allocated struct through the device handle\npointer, and let C take ownership of the Box<\/code>. No one should be looking in\nthere anyway.<\/p>\n
\/\/ lightly edited for clarity\n<\/span><\/span><\/span><\/span>\n<\/span><\/span>#[unsafe(no_mangle)]<\/span>\n<\/span><\/span>pub<\/span> unsafe<\/span> extern<\/span> "C"<\/span> fn<\/span> rtlsdr_open<\/span>(dev: *<\/span>mut<\/span> *<\/span>mut<\/span> Handle, index: u32<\/span>) -> int<\/span> {\n<\/span><\/span> let<\/span> config =<\/span> &<\/span>CONFIG<\/span>.device[index as<\/span> usize<\/span>];\n<\/span><\/span> let<\/span> sdr =<\/span> match<\/span> config.load() {\n<\/span><\/span> Ok(v) =><\/span> v,\n<\/span><\/span> Err(err) =><\/span> {\n<\/span><\/span> return<\/span> -<\/span>1<\/span>;\n<\/span><\/span> }\n<\/span><\/span> };\n<\/span><\/span> let<\/span> handle =<\/span> Box::new(Handle { config, sdr });\n<\/span><\/span> unsafe<\/span> { *<\/span>dev =<\/span> Box::into_raw(handle) };\n<\/span><\/span> 0<\/span>\n<\/span><\/span>}\n<\/span><\/span>\n<\/span><\/span>#[unsafe(no_mangle)]<\/span>\n<\/span><\/span>pub<\/span> unsafe<\/span> extern<\/span> "C"<\/span> fn<\/span> rtlsdr_close<\/span>(dev: *<\/span>mut<\/span> Handle) -> int<\/span> {\n<\/span><\/span> let<\/span> dev =<\/span> unsafe<\/span> { Box::from_raw(dev) };\n<\/span><\/span> drop(dev);\n<\/span><\/span> 0<\/span>\n<\/span><\/span>}\n<\/span><\/span><\/code><\/pre><\/div>
With that in place, we can chip away at the API surface, translating calls\nas best as we can. I won’t bother listing it all, since it’s not very\ninteresting – but here’s an example implementation of rtlsdr_set_sample_rate<\/code>\nand rtlsdr_get_sample_rate<\/code>. These calls are translating from an rtl-sdr\nfrequency (which is a u32<\/code> containing the value as Hz) into a sparky Frequency\ntype, and invoking get_sample_rate<\/code> or set_sample_rate<\/code> on the device’s\nrust handle. Since each device implements the sparky Sdr<\/code> trait, the actual\nunderlying device doesn’t matter much here.<\/p>\n
#[unsafe(no_mangle)]<\/span>\n<\/span><\/span>pub<\/span> unsafe<\/span> extern<\/span> "C"<\/span> fn<\/span> rtlsdr_set_sample_rate<\/span>(dev: *<\/span>mut<\/span> Handle, rate: u32<\/span>) -> int<\/span> {\n<\/span><\/span> let<\/span> dev =<\/span> unsafe<\/span> { &<\/span>mut<\/span> *<\/span>dev };\n<\/span><\/span> let<\/span> rate =<\/span> Frequency::from_hz(rate as<\/span> i64<\/span>);\n<\/span><\/span> if<\/span> let<\/span> Err(err) =<\/span> dev.sdr.set_sample_rate(dev.channel, rate) {\n<\/span><\/span> return<\/span> -<\/span>1<\/span>;\n<\/span><\/span> }\n<\/span><\/span> 0<\/span>\n<\/span><\/span>}\n<\/span><\/span>\n<\/span><\/span>#[unsafe(no_mangle)]<\/span>\n<\/span><\/span>pub<\/span> unsafe<\/span> extern<\/span> "C"<\/span> fn<\/span> rtlsdr_get_sample_rate<\/span>(dev: *<\/span>mut<\/span> Handle) -> u32<\/span> {\n<\/span><\/span> let<\/span> dev =<\/span> unsafe<\/span> { &<\/span>mut<\/span> *<\/span>dev };\n<\/span><\/span> let<\/span> freq =<\/span> match<\/span> dev.sdr.get_sample_rate(dev.channel) {\n<\/span><\/span> Ok(freq) =><\/span> freq,\n<\/span><\/span> Err(err) =><\/span> {\n<\/span><\/span> return<\/span> 0<\/span>;\n<\/span><\/span> }\n<\/span><\/span> };\n<\/span><\/span> freq.as_hz() as<\/span> u32<\/span>\n<\/span><\/span>}\n<\/span><\/span><\/code><\/pre><\/div>
After repeating this process for the rest of the stubs I could (and otherwise\nsetting error conditions if the functionality is not supported), I was ready to\ntry it out. Within sparky, I patched my “MockSDR” (basically a Sdr<\/code> traited\nMock type) to implement the same testmode IQ protocol that the RTL-SDR has, and\ndecided to see if rtl_test<\/code> from apt<\/code> without any changes could be fooled.<\/p>\n
$ rtl_test\n<\/span><\/span>No supported devices found.\n<\/span><\/span><\/code><\/pre><\/div>
Great, cool. No devices plugged in. Looks great. Let’s try it with my\nlibrtlsdr.so<\/code> LD_PRELOAD<\/code>-ed into the binary first:<\/p>\n
$ LD_PRELOAD=target\/release\/librtlsdr.so rtl_test\n<\/span><\/span>Found 1 device(s):\n<\/span><\/span> 0: hz.tools, mock sdr, SN: totally legit no tricks\n<\/span><\/span>\n<\/span><\/span>Using device 0: sparky mock sdr\n<\/span><\/span>Supported gain values (0):\n<\/span><\/span>Sampling at 2048000 S\/s.\n<\/span><\/span>\n<\/span><\/span>Info: This tool will continuously read from the device, and report if\n<\/span><\/span>samples get lost. If you observe no further output, everything is fine.\n<\/span><\/span>\n<\/span><\/span>Reading samples in async mode...\n<\/span><\/span>^CSignal caught, exiting!\n<\/span><\/span>\n<\/span><\/span>User cancel, exiting...\n<\/span><\/span>Samples per million lost (minimum): 0\n<\/span><\/span>$\n<\/span><\/span><\/code><\/pre><\/div>
Outstanding. Even more outstandingly, if I change my testmode implementation to\nskip samples, rtl_test<\/code> correctly reports the errors – I think it’s showing\npromise! On to try the real endgame here – let’s have our new librtlsdr.so<\/code>\nconnect to an rtl-tcp<\/code> endpoint and see if rtl_fm<\/code> works:<\/p>\n
LD_PRELOAD=target\/release\/librtlsdr.so \\\n<\/span><\/span> rtl_fm -d 1 -s 120k -E deemp -M fm -f 90.9M | \\\n<\/span><\/span> ffplay -f s16le -ar 120k -i -\n<\/span><\/span>Found 2 device(s):\n<\/span><\/span> 0: hz.tools, mock sdr, SN: totally legit no tricks\n<\/span><\/span> 1: hz.tools, rtl-tcp, SN: node2.rf.lan:1202\n<\/span><\/span>\n<\/span><\/span>Using device 1: sparky rtltcp node2\n<\/span><\/span>Tuner gain set to automatic.\n<\/span><\/span>Tuned to 91170000 Hz.\n<\/span><\/span>Oversampling input by: 9x.\n<\/span><\/span>Oversampling output by: 1x.\n<\/span><\/span>Buffer size: 7.59ms\n<\/span><\/span>Sampling at 1080000 S\/s.\n<\/span><\/span>Output at 120000 Hz.\n<\/span><\/span><\/code><\/pre><\/div>
And there it was! Not the best audio quality (mostly due to my inability to\ncorrectly read the rtl_fm<\/code> manpage to tune the filter and\ndownsample\/oversampling rates to audio), but it’s definitely<\/em> passable.\nI figured I’d try something that was a bit more interesting next – gqrx<\/code>,\nsince it’s super handy, I use it a ton, and will definitely amuse me to no\nend. To my surprise and delight, LD_PRELOAD=target\/release\/librtlsdr.so gqrx<\/code>\nwound up running, and I saw my devices pop right up in the setting menu:<\/p>\n\"\"\n
Huge. Huge. Amazing. It did crash as soon as I tried to actually use<\/em> the\nradio, but after fixing a few dangling bugs in the API surface (and some\nassumptions I think some underlying gnuradio driver may be making that I need\nto double check in the code), I was able to get a super solid stream of\nbroadcast fm radio, with gqrx being none the wiser. It thought it was\n“just” talking to the device it knows as rtl=1<\/code>.<\/p>\n\"\"\n
Nice. I can’t wait to try this with the rest of the rtl-sdr based tools I like\nhaving around using my riq<\/code> protocol next. I don’t think that’ll be worth a\npost, but hopefully I’ll get around to publishing details on that stack next.<\/p>\n
epilogue<\/h1>\n
Well. That’s it. End of story. A bit anti-climatic, sure. While this new shim\nwill provide me endless minutes of mild amusement, I could see using this to\nexpose my sparky testing utilities via librtlsdr.so<\/code> – my “mock sdr” driver\nallows for replaying captures off disk, which could be interesting to make sure\nthat signals are still properly decoded after changes, or instrument\nperformance changes (via SNR, BER, packets observed, etc) on reference samples\nI have on my NAS. Maybe that’ll come in handy one day!<\/p>\n
Truth be told, I’m not sure I actually want to encourage anyone to do this for\nreal (although I think I’ll definitely be using it on my LAN to see what\nhappens). I also don’t have a repo to share – I don’t particularly feel with\ndealing with the secondary effects of publishing sparky<\/code> (and sparky-rtlsdr<\/code>)\nyet, since i’m still getting my feet under me on the radio aspect of all this.<\/p>\n
I’ll be sure to post updates if anything changes with this here (tagged\nsparky<\/a>) and at\n@paul@soylent.green<\/a>.\nI can’t wait to post more about some of the odd sidequests (like this one!)\ni’ve completed over the last few years – I’ve been waiting to feel\nconfident that my work has matured and was withstood the new problems i’ve\nthrown at it, and it largely has.<\/p>\n
It’s my hope that these projects (and this project in particular) has provided\na glimpse into the world of software defined radio for my systems friends, and\na bit about systems for my radio friends. It’s not all<\/em> magic, and I hope\nsomeone out there feels inclined to have some fun with radios themselves!<\/p>"},{"title":"Paging all Radio Curious Hackers","link":"https:\/\/k3xec.com\/paging-all-radio-curious-hackers\/","pubDate":"Mon, 02 Feb 2026 09:50:00 -0500","guid":"https:\/\/k3xec.com\/paging-all-radio-curious-hackers\/","description":"
After years of thinking about and learning about how radios work, I figured it\nwas high-time to start to more aggressively share the things i’ve been\nlearning. I had a ton of fun at DistrictCon<\/a>\nyear 0, so it was a pretty natural place to pitch an RF-focused introductory\ntalk.<\/p>\n
I was selected for Year 1, and able to give my first ever RF related talk about\nhow to set off restaurant pagers (including one on stage!) by reading and\nwriting IQ directly using a little bit of stdlib only Python.<\/p>\n
This talk is based around the work I’ve written about previously\n(here<\/a>, here<\/a> and\nhere<\/a>), but the “all-in-one” form factor was\nsomething I was hoping would help encourage folks out there to take a look\nunder the hood of some of the gear around them.<\/p>\n