SDRs in the real-time spectrum analyzer field

1How to use this handbook

This is a reference document. Almost nobody reads one of these from front to back, so it is arranged in five parts that can be entered separately, and the sections that matter to each kind of reader are named here rather than left to be discovered.

Table 1 is the router. Find the row that matches why you opened this document, and start where it tells you to.

Conventions used throughout

Every figure in this handbook carries a tag saying what kind of evidence it is. Measured is a screenshot of a real instrument or a real host application showing real data. Derived is a chart computed from the relations in this document, with no measurement behind it. Schematic is a drawing made to explain something, and proves nothing on its own. A reader checking a claim should weight the three differently, which is why they are labeled rather than left to be guessed at.

Five terms are used precisely in this handbook and loosely almost everywhere else, so they are fixed here before anything depends on them.

• Instantaneous bandwidth is the span the receiver digitizes at one instant. Swept bandwidth is the span it can cover by tuning across it in sequence. A receiver that covers 40 GHz by sweeping and holds 100 MHz at once has both numbers, and only one of them decides what it can catch.
• Gap-free means every input sample reaches a transform, with no dead time for retune or processing. It is a statement about the acquisition, not about the display.
• Probability of intercept, written POI, is the observation length that guarantees an event is measured at its true amplitude rather than glimpsed. It is a guarantee boundary, not a probability that improves with waiting.
• Sample rate is not usable bandwidth. Anti-alias and decimation filters need a transition band, so the usable span is always narrower than the rate, and quoting a file's sample rate as its bandwidth is the commonest avoidable error in this field.
• Published, documented and stated are used deliberately. Published means it appears on a Berkeley Nucleonics datasheet. Documented means it is worked through with evidence in a technical document that is not a datasheet. Stated means somebody said it. The verification note at the end lists every value in this handbook that is not published.

2Why software-defined radio arrived in measurement

For most of the history of spectrum analysis the instrument was the measurement. A swept superheterodyne receiver moved a physical filter across a span, a detector reduced what passed through it to a trace, and the trace was the answer. The engineer chose the settings and read the result, and everything between those two acts was fixed at the factory.

Two things changed that. Converters became fast enough to digitize a useful span directly, which moved the boundary between fixed hardware and changeable processing toward the antenna. And general-purpose computers became fast enough to do the processing that used to need dedicated silicon. The result is that the interesting part of a modern receiver is software, and software can be replaced.

The measurement world took that badly at first, for a reason worth understanding rather than dismissing. An instrument's value is not that it computes a spectrum. It is that the number it reports is traceable to a standard, with a stated uncertainty, by an unbroken chain. Open the processing and the obvious question is what happens to that chain. For most of the open ecosystem the honest answer was that there was never a chain to break: the hardware reported a fraction of full scale and the user supplied the meaning.

That is the tension this handbook is about. It is not open against closed, or cheap against expensive. It is that the two families each solved half of the problem, and until recently a buyer had to pick which half to go without.

3Anatomy of a software-defined receiver

Every receiving instrument draws a line. On one side is hardware the user cannot change: the antenna port, the attenuator, the amplifiers, the mixers and filters, and the converter. On the other is processing that could in principle be rewritten. The history of the last thirty years is that line moving toward the antenna, and more of what falls behind it becoming the user's rather than the vendor's.

Figure 1 is worth holding in mind through the rest of Part I. Sections 3 and 5 are about what the left of that line has to deliver. Sections 6 and 7 are about how an application reaches across it.

Table 2 places the classes of hardware an engineer actually chooses between along that line. It is deliberately written about classes rather than named products, because the boundary moves with each generation and the classes do not.

4What separates a reading from a measurement

A number without a stated uncertainty and a traceable reference is a reading. A number with both is a measurement. The distinction is not pedantry, and it is the whole reason the two families of hardware in this handbook are not interchangeable.

An uncorrected receiver reports its converter's output. That output is a fraction of full scale, and turning it into an absolute power in dBm needs a table of corrections covering every gain state and every frequency in use, built by the user against a reference source, maintained as it drifts, and re-checked when anything in the chain changes. Nothing prevents an engineer from building that table. It is simply a large, dull, recurring job that most projects discover late.

This is why the amplitude accuracy figure matters more than it looks. A receiver quoting plus or minus 2.0 dB is making a claim about every reading it produces under stated conditions. A board quoting nothing is not making a weaker claim; it is making no claim, and the difference between those two positions is the difference between a result that can be published and one that cannot.

5Real-time analysis, and what gap-free actually guarantees

The second thing that separates instrument-grade acquisition from a development board is what happens to signals that are not on all the time. A swept receiver visits each frequency in turn, and anything that happens elsewhere while it is looking here is simply absent from the result. The absence is silent: the trace looks the same whether the band was quiet or the receiver was pointed the other way.

A real-time receiver holds a span continuously and transforms every sample. The published relations for a gap-free engine of this kind are short, and they let a reader price any configuration rather than only the ones on a datasheet:

The factor of two in equation (2) is not a safety margin. It is the worst case for a burst that straddles a frame boundary: a burst exactly one frame long, arriving halfway through a frame, puts half its energy in each of two frames and is measured at full amplitude in neither. Guarantee full amplitude and you must guarantee that at least one whole frame falls inside the burst, which needs two frames of observation.

Table 3 evaluates both relations at four settings, two of which are published operating points and two of which are not. The second pair is the argument for publishing a relation rather than a curve: a reader can price a configuration the vendor never considered.

The practical consequence is a number a system architect can put on a requirement. At 0.512 microseconds of guaranteed intercept, every event in the band lasting longer than about half a microsecond is measured at its true amplitude rather than glimpsed. A swept receiver at the same span offers no such boundary at all, and the arithmetic in BNC-AN-102 works through how far apart the two answers land.

6SoapySDR in depth

Every manufacturer of software-defined radio hardware ships a programming interface, and every one of them is defensible on its own terms. The trouble is not that any single one is badly designed. It is that they disagree with each other on exactly the points an application has to commit to in its first hundred lines.

How is a device found: by scanning a bus, by reading a serial number, by opening a named handle? Is the tuner one center frequency, or a local oscillator and a digital down-converter the caller has to place separately? Is gain a scalar or a chain of named stages whose order matters? Do samples arrive as interleaved 16-bit integers, as normalized floats, or packed twelve to a word? None of those questions has a natural answer, so each vendor answered differently, and application code inherits all of the answers.

SoapySDR removes that coupling. It is an open-source, vendor-neutral hardware abstraction layer for software-defined radio: one C++ interface with C and Python bindings that an application programs against, and a plug-in mechanism through which any manufacturer can make its hardware appear behind that interface. The application asks for a device, sets a frequency, sets a rate and reads complex samples. It does not know which radio answered.

Where it came from, and why this one

SoapySDR is not the only answer to the portability problem, and knowing what else exists is part of choosing it deliberately rather than by default.

• A vendor's own framework gives the deepest access to that vendor's hardware and the least portability. It is the right answer when a program has one supplier for its lifetime and the wrong answer the moment it does not.
• A device-specific library wrapped by the application is what most projects start with, and it is where the forty-line problem of the previous section comes from.
• An aggregating source block inside a signal-processing framework solves the problem for that framework and nothing else. It is a good answer if the framework is the whole system, and no answer at all for a laboratory application, a control script or a service.
• A hardware abstraction layer solves it once, outside any framework, which is what SoapySDR is. The cost is that the abstraction is only as good as its lowest common denominator, and section 7 is about exactly where that bites.

It is open source, vendor neutral and maintained as a community project rather than by any hardware manufacturer, which matters for the reason a second source usually matters: the interface an integrator writes against does not belong to the company selling the radio. Its license and its current release are worth checking before a product commits to it, along with those of the framework and any out-of-tree modules in the chain; four independent projects appear in Part III of this handbook and each carries its own terms.

The four layers

Figure 2 is worth reading as a boundary line rather than a stack. In a closed instrument the line falls high: the vendor's application owns acquisition, analysis and display, and you get what was exposed. In a bare development board it falls very low: you own everything above the converter, which is freedom and is also a great deal of unfinished work. SoapySDR does not move the line. It standardizes where the line is drawn, so the same application code meets the same boundary whatever is underneath.

Everything begins with a dictionary

One type carries most of the API. A dictionary of string key-value pairs, called Kwargs, describes a device that was found, requests a device to open, configures a stream and passes hints into a tuning call. It has a compact text form, which is why device arguments across the whole ecosystem look like a query string.

# enumerate, then open the specific unit by serial
found = SoapySDR.Device.enumerate()          # one dict per device
sdr   = SoapySDR.Device('driver=<name>,serial=0123ABCD')

Always read back what you set

This is the most important habit in the whole interface and the one most often skipped. A setter in SoapySDR is a request, not an assignment. The hardware has a synthesizer step size, a clock divider tree, filters with discrete corners and a gain table with real granularity. Ask for 2.000000 MHz of sample rate and you may get 2.000000, or 1.999999, or 1.920000, depending on what the master clock divides down to.

sdr.setSampleRate(SOAPY_SDR_RX, 0, 2e6)
fs = sdr.getSampleRate(SOAPY_SDR_RX, 0)   # use fs, not 2e6, from here on

The interface is built on interrogation rather than a table of what devices can do. Nearly every settable quantity has a matching query: getFrequencyRange, getSampleRateRange, getGainRange return a minimum, a maximum and a step, where a step of zero means continuous. The list calls report the names a particular device recognizes. The argument-info calls return records carrying a key, a default, a display name, a unit and a permitted range, which is how a capable receiver application builds a settings panel for hardware it has never heard of.

Tuning and gain: two levels, and one of them is not portable

Frequency has an overall call and a set of named tuning elements. A real receive chain rarely has one frequency-setting device in it: there is a local oscillator, and very often a digital shift after the converter that can move the band by a finer amount. Listing the elements returns them in signal order from the antenna inward, conventionally a radio-frequency element and a baseband element. Call the overall setter and the driver distributes across them, typically placing the oscillator as close as its step allows and making up the remainder digitally, so the result is exact even when the synthesizer is coarse. That is one of the better parts of the design.

Both forms accept a dictionary of hints. The commonest asks for a deliberate offset between the front-end oscillator and the requested center, so that oscillator leakage and the converter's own offset land outside the band of interest rather than in the middle of it. A hint a driver does not recognize is ignored rather than rejected.

Gain follows the same two-level pattern, and here the difference between the levels has consequences for a measurement. The overall call takes one number in decibels and lets the driver decide how to realize it. Named stages are listed in signal order and set individually.

Sample rate and bandwidth are two different controls

This pair is confused more often than any other in the interface, and the confusion produces measurements that are wrong in a way nothing downstream can detect. The sample rate sets how many complex samples per second cross the boundary. The bandwidth sets the analog or digital filter in front of the converter. They are related and they are not the same, and setting one does not set the other.

Set a rate of 20 MSPS and leave the filter at 56 MHz and everything outside the 20 MHz Nyquist window folds back into the data as an alias, indistinguishable from signal. Set a filter far narrower than the rate and the band edges are attenuated by a roll-off nobody recorded. A ratio around 0.8 of rate to usable bandwidth is typical, which is why quoting a file's sample rate as its bandwidth is a standard and avoidable error.

The streaming model

Streaming has five calls and a lifecycle. Set up a stream naming a direction, a sample format and the channels; activate it; read repeatedly into a buffer; deactivate and close. The read call returns the number of elements actually delivered, or a negative error code, along with flags and a timestamp.

rx = sdr.setupStream(SOAPY_SDR_RX, SOAPY_SDR_CF32, [0])
sdr.activateStream(rx)
buff = numpy.empty(8192, numpy.complex64)
sr = sdr.readStream(rx, [buff], len(buff))   # sr.ret, sr.flags, sr.timeNs
sdr.deactivateStream(rx); sdr.closeStream(rx)

Two formats matter in practice. Complex 16-bit integers are what most hardware produces and move half the bytes; complex 32-bit floats are what most processing wants and cost a conversion. Ask for the format the hardware natively produces and the driver hands it over; ask for anything else and somebody converts, either in the driver or in your code. At high rates that conversion is not free, and it is the first thing to remove when a chain cannot keep up.

The wider ecosystem

GNU Radio is the framework this handbook works through, and it is not the only application that speaks this interface. A receiver that appears as a standard device appears to all of them. Gqrx is a general-purpose receiver and spectrum display, useful as a first sanity check that hardware works before any flowgraph exists. SDRangel and CubicSDR are multi-channel receivers with device panels built from the interface's own capability queries. welle.io is a digital radio decoder. None of these needed to know anything about this instrument in advance, which is the whole return on a standard interface, and any of them is a faster way to answer “is the hardware working” than a flowgraph is.

The call surface, in one table

Table 4 is the working set. Everything an acquisition program needs is in it, grouped by what it controls, so a reader can write against the interface without leaving this page.

The flags and codes worth checking

Two of this handbook's operational arguments rest on what the stream reports back, so Table 5 names the values rather than leaving them as a category. Every one is a return code or a flag from the read call.

SoapySDRUtil, and what to run first

One command-line tool answers most installation questions, and running it before anything else saves a great deal of time spent debugging a flowgraph that was never going to work.

SoapySDRUtil --info      # library version and where modules were loaded from
SoapySDRUtil --find      # every device every loaded module can see
SoapySDRUtil --probe="driver=<name>"  # full capability dump for one device

7What the abstraction deliberately leaves out

SoapySDR standardizes control and transport. It does not standardize meaning. That sentence is the hinge of this handbook, so it is worth spelling out exactly what falls outside the contract.

• Absolute amplitude. Nothing in the interface says what a sample value means in dBm. A full-scale reading is a fraction of full scale, and converting it to power is the caller's problem unless somebody else has already solved it.
• Calibration. There is no standard call that returns a correction table, a calibration date, or an uncertainty. A device that is calibrated and a device that is not look identical through the interface.
• Timing discipline. Timestamps exist and their quality is entirely a device matter. The interface will not tell you whether the clock behind them is disciplined.
• Device-specific measurement modes. A real-time density display, a pulse-parameter table or a phase-noise routine has no representation in the interface. Reaching them means the native interface, not this one.

None of this is a defect. An abstraction that tried to standardize calibration across hardware that mostly has none would have failed to be adopted, and adoption is the whole value of an abstraction layer. But it does mean the question that decides whether an open flowgraph can produce a defensible number is a question the abstraction cannot answer, and the reader has to ask it of the hardware instead.

Derived requirements for the boundary

Sections 1 to 7 are an argument. Turned into requirements, they are what to put on a specification for a receiver that has to serve both an open flowgraph and a measurement file. Table 6 states each one with the section it comes from.

8The family: form factors and frequency tiers

The ICX-FieldHawk is a real-time spectrum analyzer family built around one analysis engine and one host interface, SpectraCore, in three physical forms. What changes between them is packaging, environmental class and how the instrument is carried to the signal. What does not change is the measurement, which is the property that matters for R7.

Table 7 is the published family. Read the last column against the third: every model holds 100 MHz at once except the entry-level module, and the frequency column is what the model number encodes.

Figure 3 is the 40 GHz rugged variant. The range across the family is wider than one photograph shows: published module weights start below 305 g for the 9.5 GHz USB variant and reach 665 g for the LAN version, against 1.5 kg for the handheld with its display and battery. The environmental classes are options rather than variants: the base class covers 0 to 50 °C, option 40 widens it to −20 to +65 °C and option 41 to −40 to +65 °C. Those classes are published on the rugged and module datasheets; the handheld publishes 0 to 50 °C operating and nothing wider, so do not assume the options extend to it without confirming.

Physical, power and environmental

A selection guide that names form factors has to say what they weigh and what they draw. Table 8 is the published physical data, with the rugged rows the datasheets leave unstated marked rather than guessed.

9The front end and the published performance

This section is the instrument's answer to R1. Every figure below carries its condition, because a specification without its condition is not a specification.

Table 9 is the published radio-frequency performance. It is longer than a summary needs to be because a reference document that omits the condition column is worse than no table at all.

10The real-time engine

This is the instrument's answer to R3, and it is the strongest technical asset in the line because the governing relations are published rather than the results. Equations (1) and (2) in section 5 are the datasheet's own, which is what lets a reader price a configuration the datasheet never mentions.

Figure 4 carries the trade that decides a monitoring architecture. A large transform buys frequency resolution and costs time resolution, and the two are locked together by a constant product. There is no setting that improves both, and a vendor who implies otherwise is describing a display rather than an acquisition.

Figure 5 is also the answer to a fair objection, and it carries a second check that is worth doing slowly because it looks at first like a contradiction. At 4,096 points and 125 MSPS the bin spacing is 30.518 kHz, yet the screen reports a resolution bandwidth of 60.3 kHz, twice as wide. Both are right. Resolution bandwidth is bin spacing multiplied by the window's equivalent noise bandwidth, and 60.3 divided by 30.518 is 1.976, which is the equivalent noise bandwidth of a Blackman-Nuttall window to four figures. A flat-top window would give about 3.77 instead. So the screen agrees with equation (2), with the bin spacing, and with the window it was configured to use, at a transform size no datasheet quotes. The datasheet's own Blackman-Nuttall endpoints imply a rounded 2.00 rather than the true 1.976, so a reader checking those instead has found the rounding, not an error. The published real-time resolution bandwidth range runs from 14.73 MHz down to 3.59 kHz with a flat-top window in thirteen grades, and real-time amplitude resolution is 0.75 dB.

11IQ capture, streaming and triggering

R2 and R4 are answered here, and the second of them is answered in a way worth noticing: the datasheet publishes burst and sustained capture as two separate numbers rather than quoting the flattering one twice.

Table 10 is the IQ path, and the pair of bandwidth rows at the top is the part worth pausing on.

Figure 6 is R2 on the instrument's own glass, before any host is involved. Part III is the same samples reached through an abstraction layer instead, and the question that part has to answer is whether anything is lost on the way across.

12The measurement set, and what it costs

A published function list is a weak argument on its own, because length is not merit. The argument worth making from this one is about what is not withheld.

• Included: channel power, occupied bandwidth, x dB bandwidth, adjacent-channel power ratio, third-order intermodulation, spectrum emission mask, AM and FM demodulation, antenna factor, amplitude offset, signal track, peak table, data record and playback, multiple-unit display, and amplitude correction.
• Modes: standard spectrum analysis, IQ streaming with multi-trigger acquisition and digital down-conversion, power detection at 8 ns time resolution with six detectors, real-time spectrum, phase noise measurement from 1 Hz to 10 MHz offsets with automatic carrier search, and harmonics analysis to ten harmonics with total harmonic distortion.
• Digital demodulation, option 71. The published format list is 2ASK, 2FSK, 4FSK, GMSK, BPSK, QPSK, 8PSK and 16, 64, 128 and 256 QAM. Read it against Part III, where QPSK and 16-QAM appear again: use the option when you want a modulation-quality measurement from an instrument calibrated to make it, and build the flowgraph when you want the samples, a format the option does not cover, or a decoder you intend to own.
• Options: 01 OCXO reference; 02 built-in signal generator, 100 kHz to 6.3 GHz, USB models only; 05, 06, 21, 22 and 23 GNSS variants; 20 auxiliary input and output board; 34 and 35 antennas; 40 and 41 temperature classes; 71 basic digital demodulation; 72 pulse detection.

Figure 7 also carries a detail worth noticing, because it is the kind of thing a measurement is for and a summary figure would hide. The harmonics do not decay monotonically: the second is 15 dB lower than the third and 25 dB lower than the fourth, so the fourth dominates the distortion total. A single total-distortion number would report the same 0.154 percent whichever harmonic carried it, and the corrective action is different in each case. This is the argument for a measurement that reports every harmonic separately rather than collapsing them.

Figure 8 is worth reading beside Figure 7 for what the two have in common. In both cases the instrument reports a derived quantity and also reports the raw numbers it derived it from, so the reader can check the derivation without trusting the instrument. That is a design choice rather than an accident, and it is the property to look for in any measurement function: a result you cannot recompute is a result you cannot defend.

The commercial argument is that a fleet assembled from these units is uniform: a routine written against one runs against all of them, because the measurement set is not licensed function by function. That argument is made here from the published list and never from a claim about anyone else's price list, which is a claim this handbook is not in a position to verify.

The published programming interfaces

R6 asks that the native interface stay reachable for the measurement modes the abstraction layer cannot express, and Table 11 is the evidence for it. This is the list the flowgraph path in Part III stands alongside rather than replaces.

13Reference and timing

The frequency reference is a temperature-compensated oscillator below 1 ppm as standard, with an oven-controlled option below 0.15 ppm. Global-navigation timing is available with a 1PPS accuracy of ±100 ns as standard and ±75 ns or ±50 ns with options. Those three timing numbers decide what a distributed system can do, and BNC-AN-110 works the arithmetic, and it is worth doing on the page. At 0.2998 m per nanosecond, ±100 ns is 30.0 m of range uncertainty before geometry, and one assumption travels with that number: it treats the bound as the uncertainty on the arrival-time difference. If each node carries ±100 ns independently, the difference carries a factor of root two more and 30.0 m becomes 42.4 m. Geometry then multiplies it: at a dilution of precision of 1.5, which is a good layout, that is 45 m of position error, and at a marginal 3 it is 90 m. The ±50 ns option halves both. Geometry is the term with no receiver parameter in it at all, which is why a site survey moves this number further than any receiver choice does.

The seven requirements, scored

Table 12 closes the spine this handbook opened. Part I derived seven requirements without naming a product; Part II has now reviewed one against them, and this is the scorecard. A reader specifying against a different receiver can use the same seven and fill the middle column differently.

14Where this instrument is not the answer

Every requirement in section 7 that this family answers only in part is named here, together with the ones it does not answer at all. A reference document that lists only capability is a brochure.

• Continuous wideband recording is 25 MHz, not 100 MHz. If an application genuinely needs minutes of unbroken 100 MHz capture, this is the wrong class of instrument and the right answer is a recorder with a storage array behind it.
• Vector signal generation is not an ICX capability. The only published generation feature is a built-in signal generator covering 100 kHz to 6.3 GHz, on USB models only, as option 02. A record-and-replay bench pairs an ICX capture with a separate vector signal generator, and BNC-AN-105 keeps the two halves apart throughout for exactly this reason.
• Amplitude accuracy loosens above 9.5 GHz, from ±2.0 dB to ±3.0 dB. Any measurement whose uncertainty budget assumed the tighter figure has to be re-derived at the higher frequency. The arithmetic is short: an amplitude bound is a rectangular contribution, so it enters a budget as its half-width squared over three, and widening the half-width from 2.0 to 3.0 dB multiplies that contribution by 2.25. BNC-AN-107 works a full budget of this kind.
• Only two frequency tiers carry published specification tables. Intermediate tiers appear in marketing material; they do not have specification tables behind them, and nothing in this handbook is written against one.
• Some things are simply out of scope. Vector network analysis and signal generation are different instruments; direction finding as a product capability and EMC measurement functions are not published capabilities of this family; and every chain in Part III is receive-only.
• The abstraction layer does not reach the measurement modes. Real-time density, pulse parameter tables and the phase-noise routine have no representation in SoapySDR, so R6 is answered by SpectraCore and the published native interfaces rather than by the flowgraph path. Section 20 is about living with that split.

15How a flowgraph actually works

A GNU Radio flowgraph is a directed graph of signal processing blocks. Blocks are connected by edges that carry a stream of fixed-size items, and the runtime arranges for each block to be handed pointers into buffers and asked to do some work. GNU Radio Companion is a graphical editor over that idea; what it produces is a Python file, and reading that file is often faster than reading the canvas.

Blocks, ports and item sizes

Every port has an item size in bytes, and the runtime enforces only that the sizes match. A complex float 32 item is eight bytes, a float is four, a byte is one. The runtime cannot tell a complex sample from a pair of floats, because both are eight bytes, which is why a type mismatch is the commonest beginner failure and why it produces plausible nonsense rather than an error.

Blocks come in a few kinds and the kind determines the rate arithmetic. A sync block produces one output item per input item. A decimator produces one per M. An interpolator produces L per one. A general block declares its own relation through a forecast call and consumes its input explicitly.

Streams, tags and messages

A flowgraph carries three kinds of traffic, and knowing which one a problem belongs to resolves most confusion about why a block will not connect to another.

• Streams are the continuous flow of fixed-size items. They have no notion of time and no notion of a boundary: a stream of complex samples is just samples, and nothing in it says where one burst ended and the next began.
• Stream tags are metadata attached to a specific sample index, traveling with the stream. This is how a source communicates a retune, a timestamp or a discontinuity to blocks downstream of it, and it is the mechanism by which an instrument's absolute time can reach a processing block at all. A block that ignores tags is not told about any of it.
• Messages, sometimes carried as protocol data units, are asynchronous and travel on separate ports drawn as dashed lines. A decoded frame, a detection report or a control command is a message rather than a stream, because it is an event rather than a rate.

Tags, in enough detail to use

A tag is not a comment. It is a small record attached to one absolute sample index, and it carries four things: the item number it belongs to, a key, a value, and the identity of the block that produced it. Key and value are typed rather than free text, which is why reading one takes a type-specific accessor rather than a string compare.

• The keys that matter here are the time tag a source emits to say what absolute instant a sample corresponds to, the rate tag that declares the sample rate the stream is now running at, and the frequency tag that records a retune. A source that does not emit them is not obliged to, and a block downstream cannot tell the difference between a source that never tags and one whose tags it is ignoring.
• Read them against the absolute item count, not against the buffer. The runtime tracks a monotonically increasing item number for every port, and a tag's position is expressed in that space, so a tag stays findable across as many work calls as it takes.
• Propagation is a policy, and the default will surprise you. A block declares whether tags pass through untouched, are scaled by its rate change, or are dropped for the block to re-emit itself. The scaling policy is the default for a reason: a timestamp on item 1,000 of a stream that is then decimated by ten belongs on item 100 afterwards, and the runtime will move it there without being asked. A block that changes the rate and does not think about tag policy silently moves every timestamp in the stream.

Writing a block, and the contract it signs

Most integrations need one block that does not exist yet. The contract is small enough to state in full, and knowing it is what separates using GNU Radio from being able to extend it.

class my_block(gr.sync_block):
    def __init__(self):
        gr.sync_block.__init__(self, name='my_block',
                               in_sig=[numpy.complex64],
                               out_sig=[numpy.float32])

    def work(self, input_items, output_items):
        out = output_items[0]
        out[:] = numpy.abs(input_items[0])
        return len(out)          # items produced

• A sync block returns the count it produced and the runtime consumes the same number of inputs automatically. Use it whenever the rate is one to one.
• A decimator or interpolator declares its ratio in the constructor and the runtime still does the bookkeeping.
• A general block implements general_work, declares its input needs through forecast, and must call consume itself. A general block that forgets to consume runs once and then waits forever on a full input buffer, which is one of the two classic stalls. The other is a forecast asking for more input than the buffer can hold, which the scheduler can never satisfy, so the work function is never called at all.
• set_history tells the runtime a block needs the previous samples present at the head of its input, which is how a filter's taps see the past without buffering it themselves. set_output_multiple forces the work size to a multiple, which is how a block that must see whole transforms or whole symbols gets them.

The scheduler, and back pressure

The default scheduler gives every block its own thread, and every thread runs the same loop for the life of the graph: see how many items are available on the inputs and how much space is free on the outputs, wait if there is not enough of either, ask the block how much input it needs to fill that output, call the block's work function, then advance the read and write pointers by what was actually consumed and produced.

Every output port gets one circular buffer, allocated when the graph starts and never resized, and every consumer reading that port reads from the same buffer with its own index. That is why a branch point costs nothing: fanning one output to three destinations copies no data. It is also what explains back pressure. If a block downstream cannot keep up, its input buffer fills, the block upstream finds no free output space, and it waits. The stall propagates upstream until it reaches the source, and this is where an instrument behaves differently from a file.

The cure is almost never a faster computer. It is to remove work from the critical path: reduce the sample rate at the source rather than resampling it down later, cut the update rate of graphical sinks, take per-sample work out of interpreted code, and decimate as early in the chain as the measurement allows.

16The source block, parameter by parameter

One block connects the instrument to everything else, and five of its fields decide whether the rest of the graph can work at all.

Table 13 lists them with the specific failure each one produces when it is wrong, which is more useful than a description of what each one does.

17Getting the environment right

Most of the time lost on an integration is lost before any signal processing runs, and almost all of it is lost in three places. This section is short because the procedure is short; it is here because skipping it is expensive.

Table 14 is the verified environment.

Verify in this order, and stop at the first step that fails, because every later step depends on the earlier ones:

uname -a                 # confirm architecture and kernel
SoapySDRUtil --info      # is the module directory the one you installed into?
SoapySDRUtil --find      # does the receiver appear at all?
SoapySDRUtil --probe     # what does it say it can do?

18Six chains, drawn and explained

These six chains were run on a 6.3 GHz-class unit, which is neither of the two tiers whose specification tables Part II quotes. The interface, the driver mechanism and the way calibration installs do not change with the tier, so the integration result transfers; the published amplitude bounds do not follow from these captures and nothing here should be read as measuring them.

Each of the six chains below has been demonstrated end to end against this receiver with a real signal and a captured result. The diagrams are redrawn rather than reproduced, and the display-only branches are collapsed where they carry no teaching, so that what remains on the page is the processing that decides whether the chain works.

Amplitude modulation: one acquisition, three outputs

Figure 9 was demonstrated with a 1 GHz carrier at −20 dBm, modulated by a 1 kHz tone at 50 percent depth. Frequency modulation is the same topology with a wider front end, and the next section works that pair through. The lesson worth taking from it is that the topology transfers between modulations and the acquisition settings do not, because bandwidth is a property of the signal rather than of the graph.

Figure 10 is worth one habit, and it earns it by failing the test. Before trusting any demodulator, find a feature whose frequency you already know and confirm it lands where the arithmetic says. Here it does not, and the discrepancy is small, systematic and entirely explainable, which is what a reference offset looks like. A chain that produces clean audio can still be four kilohertz off, and nothing downstream of the demodulator would have told you. Lock both instruments to one reference before any measurement that depends on absolute frequency, and note that this is a frequency error rather than an amplitude error: the calibration argument of Part I is untouched by it.

Frequency modulation: the acquisition has to move

The FM chain is the AM chain with the demodulator swapped, and it is worth a page of its own precisely because the swap is not the whole change. Frequency modulation at 75 kHz deviation occupies far more spectrum than an amplitude-modulated tone, so the source runs at 7.8125 MSPS rather than 976.5625 kSPS, an eight-fold increase, and the demodulator runs at 384 kSPS with an audio decimation of 8 to land on the same 48 kHz output.

Figure 11 makes a point worth carrying into any integration. Carson's rule puts the occupied bandwidth at roughly twice the sum of deviation and modulating frequency, so 2 × (75 + 3) kHz is about 156 kHz, against the roughly 200 kHz the trace shows, which is what the rule's own definition leads you to expect: it bounds the bandwidth holding about 98 percent of the power, and the sidebands beyond it are down but not absent on a display with this much dynamic range. The receiver has to be set from the signal's bandwidth rather than from the demodulator's output rate, and getting that backwards is the commonest reason an FM chain that runs produces distorted audio.

QPSK: the order of recovery is the lesson

Figure 12 was demonstrated at 1 GHz with root-raised-cosine pulse shaping at a roll-off of 0.35 and four samples per symbol. Two details in it are worth transferring to any chain you build. The Gardner timing error detector is chosen because it does not require carrier phase to be recovered first, which is what makes the ordering above possible at all. And the Costas loop is fourth order because the constellation has fourfold rotational symmetry, and the loop order has to match it; setting it wrongly locks the loop to the wrong phase and produces a constellation rotated by a multiple of ninety degrees, which looks correct until the bits are wrong.

Figure 13 is also the cheapest diagnostic in this part. If a QPSK constellation shows four clusters at one radius, the chain is working. If it shows a ring, symbol timing has not locked. If it shows four clusters rotating slowly, the carrier loop has not. If the clusters are present but the bit assignment is wrong, suspect the loop order against the constellation symmetry. The picture names most failures before any log is read.

16-QAM at minus 80 dBm: amplitude changes the architecture

Figure 14 recovers a clean constellation at −80 dBm, which is the number worth carrying away from this section, and it is worth pricing rather than admiring. In the 1 MHz processing bandwidth this chain uses, the noise floor is the published noise level plus 60 dB: −107.5 dBm on the 9.5 GHz tier and −99.9 dBm on the 40 GHz tier. So −80 dBm is about 27 dB clear of the floor on one and 20 dB clear on the other. The demonstration is not operating at the edge of sensitivity; it is showing that an ordinary open-source chain, handed corrected samples, works comfortably at a level where an uncorrected board would still be arguing about what full scale means.

Figure 15 also answers the question a skeptical reader should be asking by now. A constellation is a picture, and a picture proves that a chain ran rather than that it ran correctly. The check that turns it into evidence is section 24: inject a known level, read it through the graph, and confirm the two agree inside the published bound. Do that once and every constellation afterward inherits the result.

Wi-Fi OFDM: finding a packet before demodulating it

Figure 16 and Figure 17 were demonstrated at 2.412 GHz and −40 dBm, and the chain ends in a file rather than a picture, with Figure 17 carrying the decode. One number in that demonstration does not reconcile with the rest and is worth stating rather than smoothing over. The integration document records 12 Mb/s with rate 1/2 coding, which is a 20 MHz channel; this capture runs at 3.90625 MSPS and demodulates at 5 MSPS, which is a quarter of that and corresponds to the 5 MHz channel option, where the same modulation and coding carry 3 Mb/s. The published result window's spectrum is band-limited at about 2 MHz either side of center, which agrees with the capture rate and not with a 20 MHz channel. The rate figure is the integration document's stated condition rather than something this capture demonstrates, and the verification note records it as unresolved. The decoded frames leave as a packet capture that Wireshark opens, which means the analysis continues in a tool the network engineer already uses and the amplitude behind every frame remains traceable. The rate identity closes here too: 3,906,250 × 32 / 25 = 5,000,000 exactly, and 3.90625 MSPS is 125 MSPS divided by 32.

Figure 18 closes the loop the handbook opened. The constellation on that window was produced by open-source blocks that were never written for this instrument, running against a front end whose amplitude is bounded by a published specification. Neither half gave anything up to work with the other, and that is the whole claim of Part I stated as a screenshot.

ADS-B: when the receiver chain is barely a receiver

Figure 19 was demonstrated against live air traffic at 1090 MHz, decoding aircraft address, callsign, altitude, speed, heading and position. The decoded messages leave over a message socket rather than into a display block, which is the pattern to copy whenever the output of a chain is data rather than a picture: it lets the visualization be a separate process that can crash, be restarted or be replaced without disturbing the acquisition.

Every chain, parameter by parameter

Eight pages of diagrams describe six chains; Table 15 is what lets you rebuild them. Every value is read off the demonstration flowgraphs. A blank means the demonstration did not record that value, and a blank is more useful than a plausible number, because a reader who fills one in has made a decision rather than inherited one.

A reference for the blocks used above

Table 16 is the guidance a reader actually wants after seeing five diagrams: not another picture, but which parameter on each block will ruin the afternoon.

19The arithmetic that has to close

GNU Radio does not know your sample rate. That one sentence prevents more trouble than any other in this part. The stream carries items, not seconds, and a block that appears to know the rate knows only the number typed into its field. Get that number wrong and the block designs a filter for the wrong rate and applies it without complaint.

Write equation (4) out for any flowgraph you are handed. Every block either changes the rate by a declared factor or leaves it alone. If the product does not come out to a rate the sink can accept, the graph is wrong, and it is wrong in the worst way: it produces output rather than an error.

Table 17 applies equation (4) to all six chains of section 18.

20Making a flowgraph produce a defensible number

Everything so far makes a chain run. This section is about making its output survive somebody else's review, which is a different and higher bar.

• Turn automatic gain control off at the device. Not at the AGC block inside the graph, which is doing a different job: the device-level loop changes the scaling underneath your data, and no downstream correction recovers it. AGC inside the graph is fine for symbol recovery and must never be upstream of an amplitude reading.
• Record the state, not just the trace. Center frequency, sample rate read back from the device, bandwidth, gain and its distribution, reference level, decimation, transform size and an absolute timestamp. An IQ file without that sidecar is a pile of integers.
• Read back every setting and use the returned value. A resampler designed against the requested rate and fed the achieved rate produces a slow frequency error that survives every other check in the chain.
• Prove the amplitude path once, then trust it. Inject a known level from a calibrated source, read it in the flowgraph, and confirm the two agree inside the published bound. Section 24 gives the procedure. Doing it once at the start of a campaign is worth more than any amount of argument about whether calibration survives the boundary.
• Detect overflow rather than assuming it did not happen. Check the stream return code and log every event with its timestamp. A campaign that cannot say whether its data has gaps has to be repeated.
• Do not average across a discontinuity. If an overflow is logged, discard the acquisition that contains it rather than the samples around it, because the loop states downstream took time to reacquire and the reacquisition is not marked anywhere.

21Ten applications, reviewed

Each review below is one problem, the property that decides it, and the limit worth knowing before you commit. The document number at the head of each review is where that problem is actually derived, with the arithmetic and the honest limits; this handbook is the index rather than the replacement, and none of these reviews is a summary of its note. Full titles are in the cross-reference index in section 26.

Programming an analyzer as a platform: BNC-AN-101

The buyer wants to build a system, not operate an instrument. The decision usually gets argued on noise figure and ends up being about whether the samples are reachable and whether the calibration reaches them with it. Everything in Parts I and III of this handbook is the long form of that argument. The limit: the abstraction layer reaches the samples and not the measurement modes, so a system that needs real-time density or pulse parameter tables uses the native interfaces for those and the flowgraph for the rest.

From the field: the buyers are universities, research groups and experimenters, and what they report back is not throughput or block count. It is that the amplitude axis survives the boundary, so a plot produced by student code carries the same bound as one produced by the vendor's.

Wide-area monitoring with automated classification: BNC-AN-102

Modern monitoring systems hand identification to a trained model, which makes the receiver a sensor feeding a statistical estimator rather than a display feeding a human. The estimator inherits every property of the data it is given, and no model recovers what the front end discarded. The arithmetic is unforgiving. Take a swept receiver at 1 MHz resolution across a 40 GHz span with a 100 ms revisit: it dwells 2.5 microseconds in each resolution cell per pass, so counting the pulse width the window in which a 1 microsecond pulse can land is 3.5 microseconds per revisit, and for a 1 kHz emitter that is roughly one pulse in 28,000 arriving while the receiver is looking at that frequency. The repetition rate does not change that fraction; it sets how often you get a chance, so a 1 kHz emitter yields a catch about every 29 seconds. The limit is storage, and the right rate to quote is the sustained one: continuous capture is published at 25 MHz, which at 16-bit components is 100 Mbyte per second, or 360 Gbyte an hour. The 500 Mbyte per second figure belongs to the 125 MSPS burst case and the buffer behind it, not to anything written to disk. Either way, an architecture that does not decimate or trigger fills any disk you own.

From the field: systems integrators serving defense and national security customers have built exactly this architecture, buying the capture guarantee and the documented interface and writing every layer above the IQ line themselves.

Detecting unmanned aircraft and finding the operator: BNC-AN-103

The signal of interest is a frequency-hopping control link that is present for milliseconds at a time across a wide band, and the operator is found by direction-finding the uplink rather than the aircraft. Holding the control band whole is what makes the difference, because a hopping link is present in any one channel for only milliseconds at a time, so what a visiting receiver reports as empty is a function of when it happened to look. The limit, and it is a legal one: a lawful sensor detects, characterizes and direction-finds an emission. It does not demodulate the communication that emission carries.

From the field: siting dominates. A mast placed well for the aircraft is the worst place from which to hear a controller near the ground behind a building line, and installations that optimize for one lose the other.

Commissioning a satellite earth station: BNC-AN-104

Stations are built once and defended for years, and the deliverable is not the visit but the file the visit produces. An interference claim arrives months later as an assertion, and the commissioning archive is the only timestamped, instrument-traceable evidence of the station's compliant state. One number carries the section: a block upconverter locked to a 10 MHz reference multiplies it by 1,305 to reach a 13.05 GHz local oscillator, and phase noise rises by twenty times the log of that ratio, which is 62.3 dB. A mediocre reference that looks harmless at 10 MHz is fatal at 14 GHz.

From the field: instruments of this class get specified against the maintenance workload rather than the commissioning one, which inverts what a datasheet comparison usually optimizes for.

RF record and playback: BNC-AN-105

A receiver bug that appears once an hour at one intersection cannot be bisected against an environment that never recurs, so the environment becomes a file. The governing fact is that a replay can never be cleaner than its capture: the analyzer's noise, spurs, imbalance and phase noise are burned into the file and are indistinguishable from signal to the generator. The capture instrument sets the ceiling. The limit: this needs two instruments. Vector signal generation is not an ICX capability, and a record-and-replay bench pairs an ICX capture with a separate generator.

From the field: one requirement recurs often enough to name, which is two generators under a single control port rather than two separately addressable instruments. Two channels commanded separately are two instruments with two time bases.

UAV-borne antenna and airborne radio measurement: BNC-AN-106

Measuring an antenna pattern with an airborne probe replaces a range with a flight plan, and the two quantities that decide whether the result means anything are geometric. Far field begins near two aperture-squared over wavelength, and at exactly that distance the phase error across the aperture is one sixteenth of a wavelength. The limit: a pattern point is a statistic over a population of pulses, not a single reading, so the measurement wants pulse detection rather than a spectrum trace.

From the field: this configuration flies commercially, and the stated motivation is simpler than any argument in the note: engineers should not have to climb antenna structures.

EMF safety and RF exposure: BNC-AN-107

Exposure limits are written in field strength or power density, and a spectrum analyzer reports power at a connector, so the whole job is a conversion with an uncertainty budget behind it. The budget is where the engineering lives: rectangular contributions enter as the square of the half-width over three, and the worked example totals a variance of 2.196 for an expanded uncertainty of 2.96 dB. The limit: which quantity the limit is written in decides the antenna, and getting that wrong makes every number downstream wrong together.

From the field: the instrument a safety officer carries is increasingly an integrator's product with a general-purpose receiver inside it, which puts this arithmetic on the integrator rather than on the officer.

5G, Wi-Fi and Bluetooth in one instrument: BNC-AN-108

Coexistence problems are between-standard problems, so an instrument that measures one standard at a time cannot see them. Holding 100 MHz gap-free is exactly one FR1 carrier edge to edge under one amplitude reference, which means the interferer and the victim are measured in the same acquisition against the same axis. The limit: 100 MHz is one carrier. Aggregated carriers beyond that span need either a wider instrument or a stated, recorded decision about which carrier is being observed.

From the field: a wireless test vendor drew this boundary when they built a multi-radio analysis product on a receive module and wrote the protocol layer themselves, because from the customer's side a decode failure caused by a dropped sample carries the vendor's name.

EMC pre-compliance on your own bench: BNC-AN-109

Pre-compliance moves the expensive surprises earlier, and the arithmetic that decides whether a scan is honest is dwell time against the intercept relation. A compliant scan over bands C and D, stepped in 60 kHz increments at 100 ms a point, takes about 27 minutes, and the one-second sweeps people run are the search rather than the confirmation. Running the confirmation scan as a search is the commonest way a pre-compliance result turns out to be optimistic. The limit: no EMC measurement function is published in any specification table, so the scan is built from general-purpose functions rather than selected from a menu.

From the field: nothing here rests on the EMC software option, which appears in no published specification table. Every scan is built from general-purpose analyzer functions that are published, and no deployment outcome has been reported back yet.

Designing a receiver into your own product: BNC-AN-110

The argument is usually had on radio-frequency performance and is almost never decided by it. In a distributed radio-location node the receiver's own time-delay estimation contributes under one hundredth of one percent of the position-error variance, while time transfer, inter-channel matching, enclosure temperature and site geometry contribute all of it. One nanosecond is 0.2998 m, and geometry multiplies whatever timing error survives. The limit: the ten-year cost is dominated by the calibration fixture, the traceability chain and obsolescence engineering, none of which scale down to low volumes.

From the field: several independent system houses have built monitoring and direction-finding products on receive modules from this family, write their own software, and sell the result under their own name. None is in the receiver business.

22Measurement practice

None of the following depends on which analyzer you buy, and all of it decides whether the result is worth anything.

1. Let it warm up. The published accuracy figures assume ten minutes. Measurements from a cold start are covered by no specification on any datasheet.
2. Set the reference level deliberately. Amplitude accuracy, intermodulation performance and displayed noise floor all move with it, and an automatic reference level during a comparison invalidates the comparison.
3. Check the sample format before parsing an IQ file. Interleaving order, component width and scaling silently corrupt an otherwise perfect capture.
4. Choose the antenna before the analyzer. The antenna factor has to be entered before any field-strength number means anything at all.
5. Fix the cable and leave it fixed. Loss in flexible assemblies runs to several decibels per meter at 40 GHz and changes when the cable moves, so swapping one mid-campaign is an uncalibrated step in the middle of the record.
6. Record the resolution bandwidth with every noise figure. A displayed average noise level per hertz becomes a real floor only after ten times the log of the bandwidth is added, and the two get confused constantly.

23Troubleshooting

Table 18 is arranged by symptom, because a symptom is what a reader actually has when they open this page.

24Proving the amplitude path, and a reproducibility checklist

Calibration crossing an abstraction boundary is a claim, and a claim is worth one afternoon of proof at the start of a campaign. The procedure is short.

1. Lock the receiver and a calibrated source to a common reference.
2. Inject a continuous-wave tone at a known level, well inside the display range and at least 20 dB above the noise floor in the resolution bandwidth in use.
3. Read the level on the instrument's own display. Record it.
4. Read the same tone through the flowgraph, using a power measurement over a whole number of cycles, with device automatic gain control off and no scaling block in the path.
5. Compare. The two should agree inside the published amplitude accuracy bound for the band in use. If they do not, the fault is almost always a gain or reference-level setting that differs between the two paths, or a scaling constant left in the graph.
6. Repeat at three frequencies across the range in use and at two levels 20 dB apart, then record the six results as the campaign's amplitude evidence.

Reproducibility checklist

Copy this into a capture log and fill it in. A capture without these entries is not reproducible, whatever else is true of it.

1. Instrument model and serial number.
2. Calibration date.
3. Ambient temperature, and warm-up elapsed before the first reading.
4. Center frequency, span and bandwidth.
5. Sample rate as read back from the device, not as requested.
6. Decimation, transform size, window and detector.
7. Reference level, attenuation and preamplifier state.
8. Device gain, and confirmation that automatic gain control was off.
9. Antenna, its antenna factor, and the cable assembly used.
10. Software versions: the abstraction layer, the framework, and every out-of-tree module.
11. Overflow events with timestamps, or an explicit statement that none occurred.
12. The amplitude-path result from the procedure above, with the date it was taken.

One acquisition, written out

Everything in this section as a single program. It opens a named unit, reads back every setting it asked for, turns automatic gain off, queries the native format, handles overflow rather than ignoring it, and writes a sidecar so the capture can be defended later.

import json, numpy, SoapySDR
from SoapySDR import SOAPY_SDR_RX, SOAPY_SDR_CF32, SOAPY_SDR_OVERFLOW

sdr = SoapySDR.Device('driver=<name>,serial=0123ABCD')

if sdr.hasGainMode(SOAPY_SDR_RX, 0):
    sdr.setGainMode(SOAPY_SDR_RX, 0, False)      # never AGC for absolute amplitude
sdr.setSampleRate(SOAPY_SDR_RX, 0, 20e6)
sdr.setBandwidth (SOAPY_SDR_RX, 0, 16e6)        # not the same control as the rate
sdr.setFrequency (SOAPY_SDR_RX, 0, 2.412e9)

state = {                                        # read back, never trust the request
    'sample_rate': sdr.getSampleRate(SOAPY_SDR_RX, 0),
    'bandwidth':   sdr.getBandwidth (SOAPY_SDR_RX, 0),
    'frequency':   sdr.getFrequency (SOAPY_SDR_RX, 0),
    'gain':        sdr.getGain      (SOAPY_SDR_RX, 0),
    'native_fmt':  sdr.getNativeStreamFormat(SOAPY_SDR_RX, 0),
}

rx = sdr.setupStream(SOAPY_SDR_RX, SOAPY_SDR_CF32, [0])
sdr.activateStream(rx)
buf = numpy.empty(sdr.getStreamMTU(rx), numpy.complex64)
overflows, seg, written = [], 0, 0
out = open('capture-0.cf32', 'wb')
for _ in range(2000):
        sr = sdr.readStream(rx, [buf], len(buf))
        if sr.ret == SOAPY_SDR_OVERFLOW:
            overflows.append(written)            # record WHERE, not just how many
            out.close(); seg += 1                # start a new file: never average across
            out = open(f'capture-{seg}.cf32', 'wb'); written = 0
            continue
        if sr.ret > 0:
            out.write(buf[:sr.ret].tobytes()); written += sr.ret
out.close()
sdr.deactivateStream(rx); sdr.closeStream(rx); SoapySDR.Device.unmake(sdr)

state['overflow_at'] = overflows        # sample offsets, one per event
state['segments']    = seg + 1
json.dump(state, open('capture.json', 'w'), indent=1)   # the sidecar

25Quick reference

Table 19 is the page to photocopy.

Published values, collected

Table 20 is the specification side of the quick reference. It exists so the photocopied page is genuinely self-contained: a reader who keeps only these two tables should not have to open a datasheet for anything this handbook argues from.

Selection

Figure 20 and the table below say the same thing in two registers, which is deliberate: a specifying engineer reads the table and a reviewer reads the tree.

Table 21 runs the decisions in the order they are actually made.

Conversions worth having on one page

Table 22 collects every conversion this handbook uses, with a worked example on each row so the arithmetic can be checked rather than trusted.

26Definitions, symbols and further reading

Analysis bandwidth

The span digitized and processed at one instant. Distinct from the frequency range, which is covered by tuning.

Argument dictionary

The string key-value map used throughout SoapySDR to describe, open and configure a device. Its text form is what a device-string field accepts.

Back pressure

The propagation of a stall upstream through a flowgraph when a downstream block cannot consume as fast as its input arrives.

Displayed average noise level

The receiver's own noise floor, quoted per hertz. Add ten times the log of the resolution bandwidth to get the floor in a real measurement.

Flowgraph

A directed graph of signal processing blocks connected by buffered edges carrying fixed-size items.

Detector

The rule that reduces the samples in a display bin to one value. The published set is positive peak, negative peak, sample, average, RMS and maximum power. Peak detectors report the largest excursion and RMS reports the power, and a modulated signal reads several decibels apart between them.

Gap-free

Every input sample reaches a transform, with no dead time for retune or processing. A property of the acquisition, not of the display.

Hardware abstraction layer

A standard interface between applications and hardware, so that application code is independent of which device answers.

Rate identity

The requirement that source rate multiplied by all interpolation factors and divided by all decimation factors equals the rate every sink expects.

Overflow

Loss of samples at the driver because the application did not read fast enough. Leaves no gap in the delivered stream, only a discontinuity.

Probability of intercept

The observation length that guarantees an event is measured at true amplitude. A guarantee boundary, not a probability that improves with waiting.

Reference level

The top of the instrument's displayed amplitude range. It sets attenuation and gain distribution, so amplitude accuracy, intermodulation performance and displayed noise floor all move with it. Changing it mid-campaign invalidates a comparison.

Spur reject

A processing mode that suppresses internally generated spurious responses at the cost of sweep speed. The published accuracy figures assume it is on in its standard setting; the fastest sweep-speed figures assume it is bypassed.

Tuning element

A named frequency-setting stage inside a receiver, exposed individually by SoapySDR. Conventionally a radio-frequency and a baseband element.

Traceability

The unbroken chain from a reading to a national or international standard, with a stated uncertainty at each step. What separates a measurement from a reading.

Cross-reference index

The ten application notes in this series, each with what it derives that this handbook only states. Where a subject appears in both, the note is the authority.

• BNC-AN-101, the programmable spectrum analyzer. The calibration argument in full, the derived requirements, and the open-ecosystem evidence. The primary companion to Parts I and III of this handbook.
• BNC-AN-102, wide-area spectrum monitoring with automated classification. The intercept arithmetic, the storage arithmetic that forces a triggered architecture, and why no model recovers what the capture discarded.
• BNC-AN-103, detecting unmanned aircraft and finding the operator. Holding a control band whole, and the lawful-sensor design rule.
• BNC-AN-104, commissioning and maintaining a satellite earth station. The link budget, figure of merit, and why the archived baseline is the deliverable.
• BNC-AN-105, RF record and playback. Complex baseband, the fidelity budget, and the two-instrument split this handbook's section 14 refers to.
• BNC-AN-106, UAV-borne antenna and airborne radio measurement. Far-field geometry and pattern statistics.
• BNC-AN-107, EMF safety and RF exposure measurement. The uncertainty budget worked in full, which is the model for section 24 here.
• BNC-AN-108, analyzing 5G, Wi-Fi and Bluetooth in one instrument. The carrier-width argument behind the Wi-Fi chain in section 18.
• BNC-AN-109, EMC pre-compliance on your own bench. Dwell, antenna factor and the arithmetic of a compliant scan.
• BNC-AN-110, designing a spectrum analyzer into your own product. The error budget of a distributed system, and the build-against-buy crossover.

Standards and further reading

• IEEE 802.11-2020, Wireless LAN Medium Access Control and Physical Layer Specifications. The physical layer decoded in section 18.
• ICAO Annex 10, Volume IV, Surveillance and Collision Avoidance Systems. The 1090 MHz extended squitter format.
• CISPR 16-1-1, Radio disturbance and immunity measuring apparatus. The receiver requirements behind BNC-AN-109.
• JCGM 100:2008, Evaluation of measurement data: guide to the expression of uncertainty in measurement. The source of the rectangular-distribution treatment.
• IEC/CISPR 16-4-2, Uncertainty in EMC measurements. The uncertainty framework used in BNC-AN-107.
• 3GPP TS 38.104, NR base station radio transmission and reception. The FR1 carrier definitions behind BNC-AN-108.
• ITU-R SM.1794 and the ITU-R Handbook on Spectrum Monitoring, for the international framework behind the monitoring arithmetic in BNC-AN-102 and the measurement practice in section 22.
• IEEE Std 1139, Definitions of Physical Quantities for Fundamental Frequency and Time Metrology, for the vocabulary behind the reference, holdover and phase-noise material in section 13.
• IEEE Std 488.2 and the SCPI standard, for the instrument command language named in section 12 as a first-class path alongside the abstraction layer.
• The SoapySDR project documentation and the GNU Radio project documentation, for the interface and framework described in Parts I and III.
• gr-ieee802-11, the open-source IEEE 802.11 transceiver blocks used in the Wi-Fi chain of section 18. The packet detection, synchronization, equalizer and MAC decoder in that diagram are that project's work, not ours.
• gr-adsb, the open-source ADS-B framer, demodulator and decoder used in the 1090 MHz chain of section 18.