1How to use this handbook

This is a reference document, entered at the section that answers the question in hand rather than read 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.

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 carries no data claim. Illustration, used on the cover, is a scene that sets a context and is never evidence. The tags are printed so that a reader checking a claim can weight each figure accordingly.

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 a file's sample rate is not its bandwidth.
• 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.

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.

Instrument makers had a reason to be cautious about it, and the reason is worth understanding. 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 question is what happens to that chain. For most of the open ecosystem 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 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.

4Where the conversion happens: receiver architectures

Figure 1 drew the down-conversion stage as a mixer, a local oscillator and an IF filter. That is one way to build it, and not the only one. How a receiver gets from RF to samples is the first decision its designer makes, and it fixes most of what the rest of the chain can achieve. Four architectures cover almost every receiver built today, and most of the rest combine them. Table 3 sets them side by side.

A superheterodyne receiver filters and converts the signal in two or more stages and digitizes it at an intermediate frequency. A bank of filters ahead of the first mixer, the preselector, rejects the image and the strong out-of-band signals that would otherwise mix into the band of interest. That is what makes the architecture the reference for crowded spectrum. It is also what makes it large: every stage is a physical component with its own size, power and cost.

A block converter performs one conversion, shifting a whole band to a range where another receiver can take it. It is usually a way to extend frequency coverage rather than a complete receiver.

A direct-sampling receiver has no mixer at all. The converter digitizes the RF input directly, and everything after it is arithmetic. That gives the widest instantaneous span and the fewest analog parts, and it hands the whole dynamic-range budget to the converter. A strong signal anywhere in the converter's input band arrives in the data, wanted or not. It is the architecture section 2 describes when it says converters became fast enough to digitize a useful span directly.

A zero-IF receiver converts straight to baseband I and Q, usually inside one integrated transceiver chip. It is the smallest and lowest-power option. Its characteristic errors are a DC offset at the center of the band, local-oscillator leakage and an image produced by I/Q imbalance. They are corrected by algorithms rather than removed by filters.

Combinations are common. A typical one puts a block converter ahead of one of the other three to reach higher frequencies.

The lines between these architectures blur in practice. A receiver can switch between them by frequency band, and many modern instruments digitize an IF and finish the conversion in an FPGA, so the last analog stage is a design choice rather than a fixed boundary. The four are still the right starting question, because each one tells a reader which published figure to check first.

5What 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 the 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 a large, recurring job, and it has to be budgeted from the start.

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.

6Real-time analysis, and what gap-free 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 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 4 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.

7SoapySDR 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 8 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 3 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 per device
sdr = SoapySDR.Device('driver=<name>,serial=01AB')

Always read back what you set

This is the most important habit in the interface. 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

These are two controls, and conflating them 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. Usable bandwidth is typically about 0.8 of the sample rate, 100 MHz of 125 MSPS on this instrument, which is why a file's sample rate is not its bandwidth.

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 5 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 6 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, module path
SoapySDRUtil --find    # every device any module sees
SoapySDRUtil --probe="driver=<name>"   # one device

8What 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 7 states each one with the section it comes from.

9The 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 8 is the published family. The frequency column is what the model number encodes, and the last column divides the family into two signal chains: the ICX-045, 060 and 090 ship with 50 MHz of analysis bandwidth and a 16 ns sample interval, taking 100 MHz and 8 ns with option 50, and every other model holds 100 MHz at 8 ns as standard. Every current model is orderable with the -SDR option, which appends -SDR to the part number and ships the SoapySDR driver, the unit's calibration files and the example flowgraphs of Part III.

Figure 4 is the 40 GHz IP68 tablet. The range across the family is wider than one render shows: the published module weights are under 420 g for the USB module and under 665 g for the LAN module, 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 IP68 tablet and module datasheets; the handheld publishes 0 to 50 °C operating and nothing wider.

Physical, power and environmental

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

10The front end and the published performance

The handheld datasheet describes the ICX-045, 060 and 090 as having a superheterodyne front end with up to 14 preselector filter bands, the first architecture in Table 3, with IF and image rejection above 95 dBc typical. For the other models, the datasheets publish the figures Table 3 says to check. On the ICX-400 with spur rejection on, image rejection is better than 90 dB typical to 33 GHz and better than 58 dB from 33 to 40 GHz, and IF rejection is better than 90 dB typical, except better than 68 dB from 8.2 to 21.75 GHz. Every model also brings the final IF out to an analog IF output (MMCX, 50 Ω, −25 dBm maximum): 312.5 MHz ± 50 MHz on the ICX-045, 060 and 090, and 307.2 MHz ± 50 MHz on every other model. An external recorder or processor can take the band there, alongside the digital stream.

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 10 is the published radio-frequency performance. It is longer than a summary needs to be because a value without its condition cannot be compared with another.

Spurious-free dynamic range

Spurious-free dynamic range is the figure much software-defined radio hardware quotes, and a reader arriving from that world will look for it first. It is the ratio between the strongest signal a receiver can handle and the largest unwanted response the receiver itself adds, and it compresses several mechanisms into one number. Table 10 publishes those mechanisms separately: the intercept points for intermodulation, image and IF rejection for the responses a superheterodyne creates, and the displayed average noise level for the floor. For the common two-tone case, a reader can estimate the figure from two of them:

Both terms have to be taken at the same reference level, because reference level sets the attenuation and gain distribution that move both of them. The datasheets publish IIP3 at reference levels of +20, 0 and −20 dBm, and DANL at −20 dBm and at −50 dBm (−70 dBm on the ICX-045, 060 and 090), so −20 dBm is the condition at which the estimate can be made from published figures. For the ICX-400 at 1 GHz, IIP3 is +8.7 dBm and DANL is −154.1 dBm/Hz. In a 1 kHz resolution bandwidth N is −124.1 dBm, and the SFDR is about (2/3) × 132.8, or 89 dB. The ICX-095 under the same conditions, with IIP3 +10.5 dBm and DANL −146.0 dBm/Hz, gives about (2/3) × 126.5, or 84 dB.

The estimate holds only at that condition. On the ICX-400 at 1 GHz, IIP3 is +40.3 dBm at a +20 dBm reference level and +8.7 dBm at −20 dBm, a 31.6 dB swing from one setting. An SFDR quoted without its reference level and resolution bandwidth cannot be compared with another, which is why this handbook gives it as an estimate with its conditions, alongside the published figures, and not as a headline number.

11From IF to samples: conversion and digital processing

The front end ends at a fixed intermediate frequency, with the band of interest centered on it. The datasheets publish that IF because every model brings it out to a connector: 312.5 MHz ± 50 MHz on the ICX-045, 060 and 090, and 307.2 MHz ± 50 MHz on every other model. An analog-to-digital converter digitizes that band, and digital down-conversion finishes the job in arithmetic. A numerically controlled oscillator and a complex mixer shift the band to zero frequency, a low-pass filter removes everything outside it, and the stream is decimated to complex I and Q samples. Figure 5 shows the chain.

The I/Q rate is not the converter rate. The datasheets publish the maximum rate of the complex I/Q stream: 125 MSPS, or 62.5 MSPS on the ICX-045, 060 and 090 without option 50. That is a different quantity from the converter's rate. A complex stream at a rate f_s represents f_s of bandwidth, because I and Q together carry both sides of zero frequency, while a single real converter needs more than twice the bandwidth it digitizes; the quick reference in section 28 states both rules. This handbook therefore quotes 125 MSPS as the maximum I/Q rate and never as the converter rate.

The available rates. Every rate the instrument delivers comes from one relation:

Each step down halves the sample rate and the data the host has to absorb. At full rate the datasheets publish the bandwidth that goes with it: 100 MHz at 125 MSPS, and 50 MHz at 62.5 MSPS on the ICX-045, 060 and 090. At 16-bit components, which section 13 notes is a conventional format, 125 MSPS is 500 Mbyte per second, and decimating by four brings it to 125 Mbyte per second.

The right rate is the smallest one that still holds the signal, and it is rarely the rate a demodulator wants. The AM chain in Part III shows the pattern: it takes the stream at 976.5625 kSPS (D = 128) and resamples by 768/15,625 to reach exactly 48 kSPS of audio. Every chain in Part III makes the same move, which is why section 21 insists the rate arithmetic closes.

What a factor of four buys. Section 13 shows that the 128 Mbyte buffer holds about 0.26 seconds at full rate. Decimate by four and the stream drops to 125 Mbyte per second, so the same buffer holds about 1.0 second: four times the duration at a quarter of the sample rate. The trade is exact, because buffer duration is memory divided by data rate, and data rate is proportional to 1/D.

Burst and continuous. Table 11 publishes burst and continuous recording as two separate figures: 100 MHz burst and 25 MHz continuous on the ICX-095, 200 and 400 and on the IP68 tablet and module, and 50 MHz burst (100 MHz with option 50) and 12.5 MHz continuous on the ICX-045, 060 and 090. Burst fills the 128 Mbyte buffer; continuous is what can be carried to a host without a gap. A system that records to disk has to be sized on the continuous figure.

12The real-time engine

This is the instrument's answer to R3, and it is the part of the specification a reader can do the most with, because the governing relations are published rather than only the results. Equations (1) and (2) in section 6 are the datasheet's own, which is what lets a reader price a configuration the datasheet never mentions.

Figure 6 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.

Figure 7 is also the answer to a fair objection, and it carries a second check that 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. 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.

13IQ 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 larger one alone.

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

Figure 8 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.

14The 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 on the IP68 tablet and module, with 05 on the ICX-045, 060 and 090; 20 auxiliary input and output board; 34 and 35 antennas; 40 and 41 temperature classes on the IP68 tablet and module; 50 (100 MHz bandwidth), 60 to 62 (tracking generator) and 74 (CISPR 16-1-1 pre-compliance) on the ICX-045, 060 and 090; 71 basic digital demodulation; 72 pulse detection; and -SDR, the open sample path of Part III, on every model.

Figure 9 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 10 is worth reading beside Figure 9 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 12 is the evidence for it. This is the list the flowgraph path in Part III stands alongside rather than replaces.

15Reference and timing

The frequency reference is accurate to better than 1 ppm with the standard temperature-compensated oscillator and with the oven-controlled option 01 alike; what the OCXO adds is stability, better than 0.15 ppm over temperature and better than 1 ppm per year of aging. Global-navigation timing is available with a 1PPS accuracy of ±100 ns as standard and ±75 ns or ±50 ns with options on the IP68 tablet and module. Those 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 that 42.4 m: at a dilution of precision of 1.5, which is a good layout, it is 63.6 m of position error, and at a marginal 3 it is 127 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.

Synchronization across units

The timing arithmetic above treats each unit as an independent clock and asks how far apart two of them can be. A system of several receivers needs a different question answered first: what do the units share? Two levels are published for this family, and each enables a different class of application. Table 13 sets them out.

Frequency lock is the easiest level to reach and the easiest to overestimate. Two units on one reference agree on frequency, but each unit's synthesizer settles at an arbitrary phase every time it tunes, so their phase relationship is unknown and changes with every retune. That is enough for a common frequency axis.

Time synchronization is what the arithmetic earlier in this section prices. It is enough for time-difference-of-arrival geolocation, whose error budget BNC-AN-110 works through, and so for locating an emitter such as the drone controller in BNC-AN-103. In the fixed-frequency modes (IQS, DET and RTA), the trigger source can be set to GNSS1PPS, DevSyncByExt or DevSyncBy1PPS.

Source: the ICX-FieldHawk, ICX-FieldHawk-R and ICX-Series USB/LAN datasheets (reference clock input and output, GNSS 1PPS accuracy, trigger input and output); the instrument manual, sections 5.9.2 and 16.1.2 (trigger sources).

The seven requirements, scored

Table 14 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.

16Where this instrument is not the answer

Every requirement in section 8 that this family answers only in part is named here, together with the ones it does not answer at all. A reference document has to name its limits as well as its capabilities.

• 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.
• Two signal chains, not one. The ICX-045, 060 and 090 publish a 16 ns sample interval, a transform list that reaches 4,096 points, 50 MHz of analysis bandwidth as standard, 62.5 MSPS and 12.5 MHz of continuous recording, and option 50 brings them to the 8 ns, 100 MHz, 125 MSPS and 25 MHz of the other models. The numbers in this handbook are quoted for the 9.5, 20 and 40 GHz chain unless a row names the other.
• Out of scope. Vector network analysis and signal generation are different instruments; direction finding as a product capability is not published for this family; CISPR 16-1-1 pre-compliance (option 74) is published for the ICX-045, 060 and 090 only; 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 22 is about living with that split.

17How a flowgraph 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 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 moves tags. 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.

Added processor speed rarely cures it. The cure 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.

18The 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 15 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.

19Getting the environment right

An integration can fail before any signal processing runs, in three places that are cheap to check first. This section is short because the procedure is short.

Table 16 is the documented environment.

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

uname -a               # architecture and kernel
SoapySDRUtil --info    # the module directory you used?
SoapySDRUtil --find    # does the receiver appear?
SoapySDRUtil --probe   # what does it say it can do?

20Six chains, drawn and explained

These six chains were demonstrated on a 6 GHz-class USB module that is no longer in the product line; the current modules are the ICX-200U and ICX-400U, and the -SDR option is orderable on every current model. The interface, the driver mechanism and the way calibration installs do not change with the model, 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 11 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 12 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 13 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 an FM chain set from the output rate rather than the signal bandwidth runs and produces distorted audio.

QPSK: the order of recovery is the lesson

Figure 14 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 15 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 16 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. The capture's controls read a 0 dBm reference level, and the published noise floor nearest that condition is the −20 dBm reference-level row: −146.0 dBm/Hz on the ICX-095 family and −154.1 dBm/Hz on the ICX-400 family in the 90 MHz to 3 GHz band. In the 1 MHz processing bandwidth this chain uses that is −86.0 and −94.1 dBm, so −80 dBm is about 6 dB clear of the floor on one and 14 dB on the other, at a −20 dBm reference level. No noise-floor row is published at 0 dBm, and the floor rises with reference level, so the margin the capture ran at is smaller than those figures and is not established here. Read the demonstration as a working chain at a low level rather than as a sensitivity measurement; the sensitivity question is settled by the procedure in section 27 at the reference level you will use.

Figure 17 also answers a question the picture raises. 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 27: 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 18 and Figure 19 were demonstrated at 2.412 GHz and −40 dBm, and the chain ends in a file rather than a picture, with Figure 19 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. 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 20 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 21 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

The diagrams above describe six chains; Table 17 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 18 is the guidance a reader actually wants after seeing six diagrams: not another picture, but which parameter on each block decides whether it works.

21The arithmetic that has to close

GNU Radio does not know your sample rate. 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 (6) 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 19 applies equation (6) to all six chains of section 20.

22Making 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 27 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.

23Ten 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 derived, with the arithmetic and the 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 29.

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 (stated): 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 on the ICX-095, 200 and 400. Carrying 25 MHz takes a complex rate of at least 25 MSPS, so at 16-bit components the stream is at least 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.

Three properties of the capture decide whether a model trained on it will hold up in the field, and all three are set before the model sees a sample.

Completeness. A classifier learns the population it is shown. A swept receiver shows it the emitters that happened to be on air when it looked, which favors long and repeating signals and under-represents the short ones the arithmetic above says it mostly misses. A gap-free capture shows the training set and the field the same population, so a model's error rate in testing is a fair forecast of its error rate on the mast.

Calibrated amplitude. A model trained on uncorrected samples learns the receiver's gain table along with the signals. Move it to another unit, another gain state or another band and its inputs shift by an amount it was never shown. Samples corrected to dBm before they leave the instrument are the same at every gain state and on every unit within the published bound, so a model trained on one unit can be deployed on another.

Context carried with the samples. Center frequency, sample rate, gain and absolute time have to travel with every training example, or a labeled dataset cannot be reproduced or audited later. Section 17 shows how stream tags carry that context through a flowgraph. Treat it the way this handbook treats its figures: every example labeled with what it is and the conditions it was taken under.

Classification itself runs in the integrator's software, above the IQ line. The receiver's job is to make the training data and the field data comparable.

From the field (stated): 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 (stated): siting dominates. A mast placed well for the aircraft is a poor 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 maintained for years, and the deliverable is not the visit but the dated record the visit produces. An interference question arrives months later, and the commissioning archive is the timestamped, instrument-traceable record of the station's performance at acceptance, against which a later measurement is compared. 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 reference whose phase noise is acceptable at 10 MHz can limit the modulation order at 14 GHz.

From the field (stated): 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 (stated): 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 (stated): 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 (stated): 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 (stated): 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 a confirmation 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 a one-second sweep is the search rather than the confirmation. A confirmation scan run at search speed gives an optimistic result. The limit: CISPR 16-1-1 detectors, bandwidths and limit lines are published as option 74 for the ICX-045, 060 and 090 only; on the other models the scan is built from general-purpose functions.

From the field (stated): nothing in the note rests on option 74. Every scan in it is built from general-purpose analyzer functions that are published on every model, and no deployment outcome has been reported back yet.

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

Radio-frequency performance decides less of this argument than time transfer and geometry do. 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 (stated): 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.

24Conclusion

This handbook rests on one principle: calibration belongs to the signal path, not to the processing that follows it. A correction applied after a decision has been made on uncorrected data cannot change that decision. Whether an open flowgraph produces a defensible measurement therefore depends less on the flowgraph itself than on whether the samples reaching it have already been corrected.

Part I set out seven requirements that follow from this principle, and Part II assessed the ICX-FieldHawk against each one. Published specifications meet six of them:

• Amplitude accuracy is specified as a bound after a 10-minute warm-up at 25 °C ambient: ±2.0 dB from 9 kHz to 9.5 GHz and ±3.0 dB above 9.5 GHz on the ICX-095, 200 and 400 and the IP68 tablet models, and ±1.5 dB across the full temperature range on the ICX-045, 060 and 090.
• Acquisition is gap-free, and the intercept relations behind it are published, so the performance of any configuration can be calculated before it is used.
• Sample rate and usable bandwidth are published as separate figures.
• The native interface remains available through SCPI and the published language bindings.
• The module, handheld and IP68 tablet share one interface.
• The -SDR option supplies a driver module for the abstraction layer with the unit's calibration files staged for it.

The remaining requirement, correction applied before the abstraction boundary, is documented but not specified. It can be verified on the bench with the procedure in section 27: inject a known level, read it through the flowgraph, and confirm that the two values agree within the published bound.

System designs should also account for the following limits:

• Continuous recording bandwidth is 25 MHz, or 12.5 MHz on the ICX-045, 060 and 090. The 100 MHz figure applies to burst capture only.
• Vector signal generation requires a separate instrument.
• On the ICX-095, 200 and 400, the accuracy bound widens above 9.5 GHz. Uncertainty budgets based on the ±2.0 dB figure must be recalculated for measurements in that range.
• The abstraction layer provides access to the samples, not to the instrument's built-in measurement modes. Most systems will use both: SCPI for calibrated measurements, and a flowgraph for custom processing.

Recommended first steps on the bench:

1. Confirm the environment against Table 16, section 19, before opening a flowgraph.
2. Verify the amplitude path using the procedure in section 27.
3. Open a capture log from the reproducibility checklist and maintain it for the duration of the measurement campaign.

For the -SDR option, a datasheet, or the application notes listed in section 29, contact Berkeley Nucleonics at info@berkeleynucleonics.com or 800-234-7858.

25Measurement 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 can run 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 must be kept apart.

26Troubleshooting

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

27Proving the amplitude path

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, look first for 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
from SoapySDR import SOAPY_SDR_OVERFLOW
RX = SOAPY_SDR_RX

sdr = SoapySDR.Device('driver=<name>,serial=01AB')

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

# read back; never trust the request
state = {
    'rate': sdr.getSampleRate(RX, 0),
    'bw':   sdr.getBandwidth(RX, 0),
    'freq': sdr.getFrequency(RX, 0),
    'gain': sdr.getGain(RX, 0),
    'fmt':  sdr.getNativeStreamFormat(RX, 0),
}

rx = sdr.setupStream(RX, SOAPY_SDR_CF32, [0])
sdr.activateStream(rx)
mtu = sdr.getStreamMTU(rx)
buf = numpy.empty(mtu, 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:
        # record where, not only how many;
        # new file: never average across a gap
        overflows.append(written)
        out.close(); seg += 1
        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  # offsets
state['segments'] = seg + 1
json.dump(state, open('capture.json', 'w'),
          indent=1)   # the sidecar

28Quick reference

Table 21 is the page to photocopy.

Published values, collected

Table 22 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.

Conversions worth having on one page

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

Selection

Figure 22 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 24 runs the decisions in the order they are made.

29Definitions, 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 16 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 27 here.
• BNC-AN-108, analyzing 5G, Wi-Fi and Bluetooth in one instrument. The carrier-width argument behind the Wi-Fi chain in section 20.
• 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 20.
• 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 25.
• 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 15.
• IEEE Std 488.2 and the SCPI standard, for the instrument command language named in section 14 as a first-class path alongside the abstraction layer.
• The ICX -SDR option datasheet, for the driver module, the calibration files and the example flowgraphs that ship with the option.
• 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 20. 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 20.