Fabric School

Before any code

Start here even if it feels too basic. Half the confusion later comes from fuzzy ideas about what is actually travelling down the cable.

A radio signal is a wave — an electrical voltage that swings up and down very fast. How fast is its frequency, measured in hertz (Hz), cycles per second. A million cycles per second is a megahertz (MHz); a billion is a gigahertz (GHz). This board works between 70 MHz and 6 GHz.

To send information you have to modulate that wave: change something about it in a pattern the other end can read. You can vary its height (amplitude), its timing (phase), or its frequency. That is all radio is.

The traditional way, and the software way

A conventional radio does all of this with dedicated circuits. An FM radio has physical parts whose job is specifically to demodulate FM; it cannot become a Wi-Fi receiver, because its behaviour is soldered in.

A software-defined radio (SDR) moves the boundary. It keeps only the parts that must be analogue — an antenna connection, amplifiers, filters, and converters — and then turns the signal into numbers as early as possible. From that point on, what the radio is depends on what you do with the numbers. Same hardware, different software, completely different radio.

So the shape of every SDR is the same: antenna → analogue bits → ADC → numbers → something that processes numbers → and back out the other way. This course is about that "something", and specifically about making it be your design.

The single mental shift that makes everything else make sense.

A processor — the CPU in your laptop — is a fixed piece of circuitry that reads instructions one after another and does what each one says. It is fast because it does each step very quickly, but it is fundamentally doing one thing at a time.

An FPGA — Field-Programmable Gate Array — is not like that. It is a large field of tiny, blank logic elements plus a switching network between them. "Programming" it does not mean giving it instructions to follow. It means configuring what circuit it physically becomes.

The consequence: everything happens at once

If you describe ten filters, you get ten filters, all running simultaneously, all the time. Not ten filters taking turns. Adding an eleventh does not slow the other ten down — it uses more of the chip. You trade area instead of time.

This is why FPGAs suit radio. A signal arriving at 61 million samples per second does not wait. An FPGA can have a permanent, physical arrangement of hardware that handles every sample as it goes past, with completely predictable timing.

The price you pay

• It is slower per operation. Fabric typically runs at tens to a few hundred MHz, far below a CPU's gigahertz. It wins by doing thousands of things at once, not by being quick.
• The build is slow. Turning your description into a configuration means synthesis, placement and routing — twenty minutes to an hour on this board. You cannot iterate the way you do with software, which is why simulation matters so much (lesson 10).
• Resources are finite and visible. You will run out of DSP slices or fail timing, and you will have to make real engineering trade-offs.

Two computers, one radio chip, and the connection between them.

The main chip is a Xilinx XC7Z020-CLG400, a Zynq. A Zynq is unusual: it puts a processor and an FPGA on the same die.

The radio chip is an Analog Devices AD9361: a complete transceiver covering 70 MHz to 6 GHz, with two receivers and two transmitters. It contains the amplifiers, the mixers, the filters, and the ADCs and DACs. It is connected to the FPGA fabric by a fast digital interface, and configured by the Linux driver over SPI, a simple serial control bus.

The parts that matter, and what each is for

Nine chips do the work. Every one of these is read off the vendor schematic in the repository, with the sheet number, and cross-checked against what a running board reports — see docs/hardware.md for the full table with datasheet links.

What the radio will actually do

Not from a datasheet — these are the limits the board itself reports, which is the number that governs you. Read them back from any board with iio_attr.

Clocks, and the one that is the radio's accuracy

Six oscillators, but only one matters for radio work: the 40 MHz reference feeding the AD9361. Every frequency the radio produces or receives is derived from it, so its error is the radio's error — tune to 900 MHz with a reference 10 ppm high and you are 9 kHz off.

Two ways out, both brought to connectors. The oscillator's tuning voltage XTAL_VTC is on JP5 pin 15, so it can be disciplined from outside — by a GPS-locked reference, for instance. And EXT_CLK on a U.FL connector replaces the on-board oscillator entirely. Both TX_LO and RX_LO are also brought out on U.FL, which is what you would use to run two boards coherently.

What one of these measures like

From the repository's own bench measurements on a single unit, so treat them as indicative rather than a specification — but if yours is wildly different, something is wrong.

Six programs with confusing names, one of them optional. Here is which one does what.

The commands you will actually type

# run from: the repo root
./devkit doctor     # can this machine build? answers in a second, not at minute 40
./devkit setup      # fetch upstream source and apply this repo's patches
./devkit sim        # simulate the custom HDL          (~1 second)
./devkit build      # everything                       (45-90 min)
./devkit build --hdl-only   # just the FPGA part       (~20 min)
./devkit verify     # is the build sane? checks timing, compression, files
./devkit flash      # copy onto the running board over the network

The other target: --target modern

Everything above builds the factory firmware: the vendor's 5.15 kernel and a root filesystem held in RAM. This repo has a second, newer target — Linux 6.12 and a full Debian system — and the same commands build it when you add --target modern. Leave the flag off and nothing changes.

# run from: the repo root
./devkit setup --target modern     # about 0.6 GB, not 6.8: no vendor kernel, no Buildroot
./devkit container build --target modern --xsa "$(./firmware-modern/fetch-pinned-xsa.sh)"
./devkit verify --target modern    # reads BOOT.bin's parts back out and checks them
./devkit build --target modern --rootfs-only   # the Debian system, on the host (~10 min)

Three words in there need defining.

• An XSA is the FPGA design packed into one file: the bitstream plus the description of the hardware around it. The modern target never runs Vivado, so it cannot make a bitstream — it has to be handed one, and --xsa is required. Where from? A factory build writes one, and factory releases attach one. But a release's XSA is that release's design, so the tool will not guess on your behalf. The command above names one on purpose: fetch-pinned-xsa.sh downloads the XSA of the factory release written in firmware-modern/factory-xsa.pin (v1.7 today) and refuses it unless its fingerprint — a sha256 hash — matches the one written there. That is the same XSA a modern release is built from.
• BOOT.bin is the first file the chip reads at power-on, and it is three things glued together: the FSBL (a tiny program that sets up the memory), the bitstream, and U-Boot (the program that then loads Linux). The modern target builds the FSBL and U-Boot from the same sources as the factory target and takes the bitstream out of the XSA you give it, so given the same XSA its BOOT.bin is the factory one rebuilt — checked, not assumed: the FSBL and the bitstream came out byte-for-byte identical.
• A cross-compiler runs on your PC but produces code for the board's ARM chip. Either ARM Linux one works here: gcc-arm-linux-gnueabi or gcc-arm-linux-gnueabihf. If your desktop has neither, that is what container is for: it runs the build inside a packaged Linux that has one. The Debian system is the exception. It is built in a container of its own, so run that step on your PC, not inside container.

Why a wrapper, and not just the commands

Nothing ./devkit does is magic; every step is a script you can read. What it buys you is order and refusal. The build has seven stages that must happen in sequence, each with arguments that are easy to get subtly wrong, and several of the mistakes are silent — they do not fail, they produce a working-looking file that is wrong. A wrapper that refuses is worth more than one that is merely convenient.

The loop you will actually live in

Almost all of your time is one short cycle. The long commands are for the first day and for releases.

Which build, and which flash

Both commands take options that say how much to redo. Picking the smallest one that covers your change is the difference between a twenty-minute loop and an hour one — and, when flashing, between rewriting one file and rewriting the one that can stop the board booting.

Vivado in a container, and why you might want it

Vivado 2022.2 supports Ubuntu 18.04, 20.04 and 22.04 and nothing newer. That is not a suggestion you can ignore: on a newer distribution it fails to start, and so does its own installer, which is the same application underneath. Meanwhile the version is pinned here on purpose — a different Vivado produces a different bitstream, and this repository makes claims about the bitstream it produces.

A container resolves the standoff. It is a packaged Linux userspace — the libraries and programs an application expects — that runs on your own kernel. The build gets the 22.04 it wants; your laptop stays whatever it is.

# run from: the repo root
./devkit container build-image      # once, ~3 min
./devkit container install ~/Downloads/Xilinx_Unified_2022.2_*.bin
./devkit container doctor
./devkit container setup
./devkit container build            # the same build, in the container

Vivado is not inside the image. The image carries the userspace; your installation of Vivado is handed to it at run time as a bind mount — a directory on your machine made visible inside the container. That keeps the image about a gigabyte instead of forty-five, and means the toolchain you test is the one you already have.

The board answers on 192.168.2.1 over USB and asks your router for an address over Ethernet. How you change either depends on which rootfs you are running — and on both of them, the file that looks like it should do it is not the file that does.

# run on the board
grep ^ID= /etc/os-release   # ID=debian  -> firmware-modern
                            # no such file -> Buildroot (firmware/)

On Debian: the file is the configuration

There is no generator and no indirection. /etc/network/interfaces is read by ifupdown at boot and that is the whole story, so editing it is not a mistake here — it is the method:

# run on the board
$EDITOR /etc/network/interfaces
#   iface eth0 inet static
#       address 192.168.1.50
#       netmask 255.255.255.0
#       gateway 192.168.1.1        <- you get to include this, unlike Buildroot
systemctl restart networking      # no reboot needed

hostnamectl set-hostname lab-sdr  # avahi picks it up immediately

Three differences worth knowing before you rely on it:

• You can set a gateway and DNS, which the Buildroot static branch below cannot. So "static means no internet" is a Buildroot property, not a board one.
• It does not survive a fresh card. The file lives on the rootfs, so write-card.sh gives you the default back. Put the change in firmware-modern/debian/overlay/etc/network/interfaces if you want it in every card you build.
• The MAC still comes from U-Boot. The shipped file has a pre-up ip link set dev $IFACE address "$(fw_printenv -n ethaddr)" line, for exactly the reasons in "Two different names" below. Keep it when you edit around it, or the random-MAC problem comes back.

The USB side differs too. On Debian usb0 is brought up at 192.168.2.1 by fishball-usb-bind, which hard-codes that address rather than reading ipaddr — and there is no DHCP server on the board's USB link, so nothing hands your PC an address. Give your host end one yourself:

# run on your HOST, once - replace enx… with the interface the board created
sudo ip addr add 192.168.2.10/24 dev enx001122334455
sudo ip link set enx001122334455 up
ssh root@192.168.2.1

Stop typing the password

The board ships with a published root password, and you are about to type it several hundred times. One command replaces it with a key:

# run from: the repo root
./devkit ssh-key
ssh fishball

It makes a key used for this board and nothing else, installs the public half, and adds an ssh fishball shorthand to your SSH config. Then it logs in with BatchMode, which cannot fall back to a password — so a pass means the key really did the work, rather than ssh quietly asking and you not noticing.

On Buildroot: where the addresses actually live

Not on the SD card. They live in the U-Boot environment, a 128 KB block in the board's QSPI flash chip. At every boot a startup script called S40network reads that block and generates the Linux network configuration from it.

# run on the board
cat /etc/fw_env.config
#   /dev/mtd1    0x0000    0x20000    0x20000
cat /proc/mtd | grep mtd1
#   mtd1: 00020000 00010000 "qspi-uboot-env"

Two things follow from "generated at every boot", and they are the two mistakes people make. The first is editing /etc/network/interfaces: it works beautifully until you reboot, at which point the script writes over it. (This is the one that catches people moving from Debian, where that same file is the right place to edit and nothing overwrites it.) The second is subtler — the variables have defaults compiled into the script, stored nowhere, so fw_printenv ipaddr answering "ipaddr" not defined does not mean the board has no USB address. It means the script fell back to 192.168.2.1.

One happy consequence: because the environment is in QSPI and not on the card, your address settings survive reflashing the SD card, including ./devkit flash --all and a complete rewrite with a card reader. This is a genuine advantage over Debian's file-on-the-rootfs approach, and the reason ./devkit net exists at all.

The switch that chooses DHCP or static

There is no "mode" setting. There is one variable, ipaddr_eth, and the script branches on whether it has a value at all:

if [ -n "$ETH_IPADDR" ]; then
        echo "iface eth0 inet static"   >> $IFAC
        echo "\taddress $ETH_IPADDR"    >> $IFAC
        echo "\tnetmask $ETH_NETMASK"   >> $IFAC
else
        echo "iface eth0 inet dhcp"     >> $IFAC
fi

So "go back to DHCP" means deleting the variable, which is what fw_setenv with no value does:

# run on the board
fw_setenv ipaddr_eth 192.168.1.50    # a fixed address on your router's network
fw_setenv netmask_eth 255.255.255.0
fw_printenv ipaddr_eth netmask_eth   # read it back BEFORE rebooting
reboot

fw_setenv ipaddr_eth                 # no value = delete = back to DHCP
fw_setenv netmask_eth
reboot

The other variables the same script reads: ipaddr (the board's own address over the USB cable, default 192.168.2.1), ipaddr_host (the single address the board's own DHCP server hands your PC over USB, default 192.168.2.10), netmask, hostname — which is also the mDNS name — and ssid_wlan/pwd_wlan if you fit a USB Wi-Fi dongle.

The file that looks like it works

The SD card contains uEnv.txt. It is plain text, it is right there, and it already contains the exact lines you want to change — ipaddr=192.168.2.1 among them. Editing them changes nothing about the running Linux system.

U-Boot reads uEnv.txt with env import, which loads it into the environment U-Boot holds in RAM. There is no saveenv anywhere in the SD boot path, so nothing is written to flash. Those values live for as long as U-Boot runs, get used for U-Boot's own networking, and are gone before Linux starts. Linux's fw_printenv reads /dev/mtd1, which env import never touched.

The route that needs no shell: config.txt

Plugged into a PC, the board also appears as a small USB flash drive holding config.txt. Edit it, set reset = 1 under [ACTIONS], save, and eject the drive — the eject is what the board watches for. A daemon compares the file's md5 against a stored copy, parses it, and writes every value in one batch through the same fw_setenv. It leaves a file called SUCCESS_ENV_UPDATE on the drive if the write worked, or FAILED_INVALID_UBOOT_ENV if it did not.

What static mode leaves out

Look again at the static branch above: it writes an address and a netmask, and there is no gateway line. Nothing writes /etc/resolv.conf either. So a statically addressed board has no default route and no DNS. Measured on a board set to 192.168.129.200:

# run on the board
ip route
#   192.168.2.0/24     dev usb0 scope link  src 192.168.2.1
#   192.168.128.0/23   dev eth0 scope link  src 192.168.129.200
cat /etc/resolv.conf     # No such file or directory
ping -c1 8.8.8.8         # fails: no route

Two link-scope routes and no default via anything. The board can reach its own subnet and nothing else. For radio work that is usually irrelevant — libiio talks to it directly and your PC is on the same subnet — but ntpd, git, wget and anything that resolves a name will fail, for a reason nothing tells you.

DHCP does not have this problem: udhcpc's script sets both the default route and the nameserver. So if you want a fixed address and working internet, the clean answer is a DHCP reservation on your router — leave ipaddr_eth unset and let the router always hand out the same address. You get a predictable address, a gateway, DNS, and nothing to undo on the board when you move it to another network. Failing that, add what static mode omits to /mnt/jffs2/autorun.sh, the board's one writable persistent partition, which runs at every boot on this rootfs. (Nothing runs it on Debian — a script there will sit and do nothing, which is its own trap once you have learnt the Buildroot habit.)

Two different names, and why the router shows neither

A router listing this board as 26:ae:c6:de:ce:e0 is showing you two separate faults, and the second is the interesting one.

The name a router displays comes from the DHCP request — option 12, the client's hostname. The stock firmware never sends it: udhcpc runs with no hostname argument, so the router has nothing to list the board as except its hardware address. That is a different name from the mDNS one, which was working the whole time; mDNS is answered by a daemon on the board and never enters the router's client list at all.

And the hardware address is not stable. The device tree carries no local-mac-address, so the Ethernet driver says so and improvises:

macb e000b000.ethernet: invalid hw address, using random

Both are fixed by two lines in the interface stanza that S40network already generates, because busybox's ifupdown knows what to do with them: hostname becomes udhcpc -x hostname:, and hwaddress becomes an ip link set addr issued before the interface comes up.

auto eth0
iface eth0 inet dhcp
        hostname fishball
        hwaddress ether 00:0a:35:00:01:22

The address used is the one U-Boot already holds in its own environment (ethaddr) and uses for its own networking, so the board keeps a single identity from bootloader to Linux instead of two. The devkit ships this as firmware/patches/0013, and the same patch makes the default hostname fishball, so the board answers to fishball.local.

Day to day none of this needs remembering, because the devkit wraps it — and it knows which rootfs it is talking to, so on Debian static and name refuse and print the equivalent rather than writing a variable nothing reads:

# run from: the repo root
./devkit net                 # what address did it get, and how?
./devkit net dhcp            # ask the router          (the default)
./devkit net static 192.168.1.50
./devkit net name lab-sdr    # answer to lab-sdr.local instead
./devkit net find            # locate it without knowing the address

Each of those writes the environment, reads it back before rebooting, and then goes and finds the board again — because switching to DHCP throws away the address you were connected on, and that is the moment you would otherwise discover you have no way back.

Finding the board again

If you switched to DHCP, you do not need to know the address. The board announces itself:

# run from: your HOST
iio_info -s
#   1: 192.168.129.200 (FISH Ball PlutoSDR Rev.A (Z7020-AD9361)),
#      serial=b8f4c99de8525565d3f4fe3c917ad834 [ip:pluto.local]

avahi-resolve -n pluto.local
#   pluto.local	192.168.129.200

iio_info -s is the single most useful command here: it gives you the address, the model, the serial, and proof that the radio service is up. Better still, use ip:pluto.local as the libiio URI everywhere and never hard-code an address at all. The mDNS name follows the hostname variable, so fw_setenv hostname fishball makes it fishball.local.

The full version of this lesson, including the temporary no-reboot commands and the five other ways to discover a board's address, is changing the board's IP address in the repository documentation.

Verilog from nothing

Verilog is a big language. You need about a fifth of it, and this lesson is most of that fifth.

A module is the unit of Verilog: a box with wires going in and out, and a description of what is inside. Everything is a module, all the way up.

// Everything after two slashes is a comment.
module counter (
  input  wire        clk,     // one bit, coming in
  input  wire        rst,     // one bit, coming in
  output reg  [31:0] count    // 32 bits, going out
);

  always @(posedge clk) begin
    if (rst)
      count <= 32'd0;
    else
      count <= count + 32'd1;
  end

endmodule

Reading it line by line

• module counter ( … ); — declares a box called counter and lists its wires. endmodule closes it.
• input / output — which way each wire points.
• [31:0] — this is not one wire but a bundle of 32, numbered 31 down to 0. Bit 0 is the least significant. Verilog calls a bundle a vector.
• always @(posedge clk) — "whenever clk goes from low to high, do the following". posedge is the rising edge.
• <= — an assignment. Lesson 6 explains why it is this arrow and not =.
• 32'd0 — a literal: 32 bits wide, d for decimal, value 0. You will also see 'h (hex) and 'b (binary).

Now read it as hardware rather than as instructions: there is a 32-bit register called count. Permanently wired to its input is an adder that computes count + 1, and a selector that picks either that or zero depending on rst. On every rising clock edge the register captures whatever the selector is presenting. About 32 flip-flops and a handful of LUTs, existing all at once.

Why digital hardware has a heartbeat, and what it is for.

A clock is a signal that alternates high, low, high, low, forever, at a fixed rate. It carries no data. Its only job is to say now.

Logic gates take time to settle — a signal rippling through an adder arrives at different bits at slightly different moments, and for a few nanoseconds the output is meaningless. The clock solves this by dividing time into slices. Within each slice the combinational logic settles; at the edge, every flip-flop captures the settled value at once.

Reset

At power-on, flip-flops hold arbitrary values. Reset is a signal that forces them to known values so the design starts from a defined state.

Reset only what needs it. Over-resetting costs fabric and can hurt timing, because the reset signal must reach every flip-flop that uses it within one clock period. A counter needs reset; a pipeline register that will be overwritten within two cycles anyway usually does not.

The clock on this board

The datapath clock is called l_clk, and it is recovered from the AD9361's own data clock. It is not a fixed frequency — it scales with the sample rate. Change the radio's sample rate from software and l_clk changes underneath your logic. Do not write anything that assumes a particular number of clock cycles per second.

The most common source of designs that simulate correctly and behave wrongly in hardware.

Why the rule exists

Consider a rank of flip-flops that should shift a value along: a into b, b into c. In real hardware all three capture simultaneously, so c gets the old b, not the new one.

always @(posedge clk) begin
  b <= a;
  c <= b;      // gets the OLD b - three separate flip-flops
end

always @(posedge clk) begin
  b = a;
  c = b;       // gets the NEW b - collapses to a single flip-flop
end

Non-blocking assignments all read their right-hand sides first, then update every left-hand side together. That is precisely what a rank of flip-flops does on an edge. Blocking assignments happen in written order, like software — correct for describing a chain of gates, wrong for describing registers.

Mix them and you get a design whose simulation and synthesis disagree. Your testbench passes and the board misbehaves — the most expensive bug class there is.

Logic with no memory: outputs follow inputs continuously.

// continuous assignment - permanent wiring
assign sum   = a + b;
assign isbig = (a > b);          // a comparator
assign pick  = sel ? a : b;      // a multiplexer ("mux")

// block form, for anything needing if/case
always @(*) begin
  case (sel)
    2'b00:   out = a;
    2'b01:   out = b;
    2'b10:   out = c;
    default: out = 16'd0;    // ALWAYS write a default
  endcase
end

@(*) means "re-evaluate whenever any input changes" — which is what a lump of gates does naturally.

Radio samples are signed and awkwardly sized. Verilog will silently do the wrong thing if you let it.

Width is not checked

Assign a 16-bit expression to a 12-bit target and Verilog quietly discards the top four bits. No error, no warning by default. On this board you move constantly between 12-bit converter samples and 16-bit bus words, so be explicit about widths everywhere.

Signed means saying so

IQ samples are two's complement signed numbers: the top bit means negative. A plain reg [15:0] is unsigned as far as Verilog is concerned, so a > b gives wrong answers whenever negatives are involved — and half your samples are negative.

wire signed [11:0] adc;        // 12 bits from the converter
wire signed [15:0] wide;

// widening a signed number means REPLICATING the sign bit,
// not padding with zeros
assign wide = {{4{adc[11]}}, adc};

// {a, b}   concatenates
// {4{x}}   repeats x four times

Overflow, and what to do about it

Add two 16-bit signed numbers and the result needs 17 bits. Multiply two 16-bit numbers and you need 32. If you keep the result in 16 bits, a large sum wraps around — a big positive becomes a big negative, which in a radio sounds like a violent click and looks like broad spectral splatter.

Two honest choices: grow the width to fit, or saturate — clamp to the maximum instead of wrapping. Saturation is usually right for signal paths, because a clipped peak is far less damaging than an inverted one.

There is no floating point in the fabric. Every DSP block you write manipulates integers pretending to be fractions, and getting that pretence right is most of the craft.

What "fixed point" means

A floating-point number carries its own scale — the exponent moves so the same format handles 0.0001 and 10000. That flexibility costs hardware you do not have. So the fabric uses plain integers, and you remember where the decimal point is. It never moves, hence fixed point.

The usual notation is Qm.n: m integer bits, n fractional bits, plus a sign bit. A signed 16-bit word holding values between −1 and +1 is Q0.15: one sign bit and fifteen fractional bits.

The board's own numbers are fixed point already. Receive samples are 12-bit signed values sign-extended into 16 bits — full scale ±2047. Transmit takes the top 12 bits of a 16-bit word, so it is effectively Q0.15 with the bottom four bits discarded.

The number that governs everything: 6.02N + 1.76

An ideal N-bit converter has a best possible signal-to-noise ratio of

SNR = 6.02 × N + 1.76   dB

Each extra bit buys about 6 dB. For the AD9361's 12-bit converters that is 74 dB — the ceiling, before anything else in the system degrades it.

Scaling: the mistake that costs 40 dB

Fixed point has no automatic gain. If you use only a small part of the available range, you get only a small part of the available dynamic range — permanently.

Growth, and the two honest responses

Arithmetic makes numbers bigger. Adding two 16-bit values needs 17 bits; multiplying two needs 32; a 129-tap filter accumulating products needs more still.

• Grow the width to fit, then deliberately round back down at the end. Correct, and costs fabric.
• Saturate — clamp at the maximum rather than letting the value wrap. Wrapping turns a large positive into a large negative, which in a radio is a violent discontinuity and broad spectral splatter. A clipped peak is far less damaging than an inverted one.

What you must never do is let it wrap silently, which is exactly what Verilog does by default.

wire signed [16:0] sum = a + b;          // 17 bits: cannot overflow
wire signed [15:0] out =
  (sum >  17'sd32767) ?  16'sd32767 :      // clamp high
  (sum < -17'sd32768) ? -16'sd32768 :      // clamp low
                        sum[15:0];

Rounding versus truncation

When you discard low bits, truncating (just dropping them) always biases downwards. Over a long filter that accumulates into a measurable DC offset. Rounding — add half a least-significant bit before shifting — costs one adder and removes the bias.

One second against twenty minutes. This lesson decides whether learning this board is pleasant or miserable.

A testbench is a Verilog module with no inputs or outputs whose job is to wiggle the inputs of your design, watch its outputs, and complain if they are wrong. It is never synthesised — it exists only inside the simulator, so it may use conveniences real hardware cannot.

module tb;
  reg clk = 0, rst = 1;
  wire [31:0] count;

  counter dut (.clk(clk), .rst(rst), .count(count));   // dut = design under test

  always #5 clk = ~clk;      // flip every 5 time units -> a clock

  initial begin
    $dumpfile("tb.vcd"); $dumpvars(0, tb);   // record every signal

    repeat (2) @(posedge clk);
    rst = 0;
    repeat (10) @(posedge clk);

    if (count !== 32'd10) begin
      $display("FAIL: count=%0d, expected 10", count);
      $fatal;
    end
    $display("PASS");
    $finish;
  end
endmodule

iverilog -o tb.out tb_counter.v counter.v && vvp tb.out
gtkwave tb.vcd        # when the numbers alone do not explain it

The mutation check

A test that always passes is worse than no test, because it buys false confidence. This repo guards against that:

./devkit sim --mutate   # deliberately corrupt the design; the test MUST now fail

If your test still passes with a broken design, your test is not testing. Write the testbench before the module, describing what you want to be true; then the first run means something and you have a golden reference to check the hardware against later.

The radio's datapath

Every number flowing through this board comes in pairs. Here is why one number would not be enough.

Suppose you sample a radio wave and get the value 0.5. Is the wave rising or falling? You cannot tell. One number gives you amplitude at an instant and nothing about where in its cycle the wave is — and phase is where much of the information lives.

So SDRs take two measurements at each instant, from the same signal, using reference oscillators a quarter-cycle (90°) apart:

Together they pin down both amplitude and phase. If you think of the pair as a point on a plane — I across, Q up — then the distance from the origin is the signal's amplitude, and the angle is its phase. A steady tone traces a circle at constant speed; the speed of rotation is its frequency offset from the tuned centre.

How it is carried here

Each sample is two signed integers. On receive both are 12-bit values sign-extended into 16-bit containers; on transmit both are full 16-bit. The stream is interleaved — I, Q, I, Q — so one "sample" costs four bytes. That is why a 5 MSPS stream is 20 MB/s in each direction.

The one piece of theory you cannot skip, because violating it produces signals that are not there.

The sample rate is how many samples per second you take. This board goes from 2.083 to 61.44 million samples per second (MSPS).

The Nyquist theorem says: sampling at rate f can faithfully represent signals occupying a bandwidth of f. For complex I/Q sampling that bandwidth is centred on the tuned frequency and runs from −f/2 to +f/2. At 5 MSPS you see 5 MHz of spectrum, from 2.5 MHz below your tuned frequency to 2.5 MHz above.

Aliasing: why a signal can appear where it is not

Sampling does not watch the signal. It glances at it, at evenly spaced instants, and writes down what it saw. Everything between those glances is simply not recorded.

That creates an ambiguity you cannot argue your way out of. Two different sine waves can pass through exactly the same points at exactly those instants:

So when a signal arrives that is too fast for your sample rate, it does not go missing and it does not announce itself. It is recorded as a slower one, and from that moment it is indistinguishable from a genuine signal at that lower frequency. This is aliasing: the fast signal wears the alias of a slow one.

Where a given signal lands

The rule is simple: add or subtract whole multiples of the sample rate until the frequency falls inside the window. Wherever it lands is where it will appear.

At 5 MSPS the window runs from −2.5 to +2.5 MHz, so:

Note the third and fourth rows. A signal 7 MHz above where you tuned, and one 4 MHz below it, both land on top of perfectly ordinary places in your spectrum. Nothing about the captured data marks them as impostors.

The only real defence: filter before you sample

Once a signal has been sampled, the damage is permanent — the alias is the data. So the fix has to happen while the signal is still analogue, on the way in. That is what rf_bandwidth controls: a filter inside the AD9361, ahead of its converters, that attenuates anything far enough from centre to fold.

# run on your HOST - set the rate, then match the filter to it
iio_attr -u ip:192.168.2.1 -i -c ad9361-phy voltage0 sampling_frequency 5000000
iio_attr -u ip:192.168.2.1 -i -c ad9361-phy voltage0 rf_bandwidth        4000000

A sensible default is a filter slightly narrower than the sample rate. Common practice is 0.75 × the rate — that is gr-osmosdr's default for a HackRF — and the section below derives where that number comes from. Set it much wider and you are deliberately letting in signals that can only arrive as aliases. Set it much narrower and you are throwing away spectrum you paid to sample.

Decimation moves Nyquist, and things that were safe stop being safe

Everything above assumed one sample rate. The moment you decimate — keep one sample in every D and throw the rest away, which is what lesson 27 does for free dynamic range — there are suddenly two Nyquist limits, and the one that governs you is the smaller.

original rate   fs          window  +/- fs/2
decimate by D   fs / D      window  +/- fs / (2D)     <-- this one

a signal safely inside the first window can be well outside the second

This is the trap, because nothing warns you. The signal was legitimately inside the band when you sampled it. You then decimate to save CPU, and it folds — at which point it is a peak in your spectrum that was never on the air.

passband edge   fp                    what you keep
stopband edge   (fs / D) - fp         where rejection must already be reached
stopband depth  >= your dynamic range  so folded energy lands under the noise

Nyquist, fs/(2D), sits in the MIDDLE of that transition - not at its start.

What this costs you in practice

Higher sample rate means more bandwidth, and proportionally more data. At the top of this board's range, 61.44 MSPS, each direction is 245 MB/s.

Measured on this board, capture alone runs at the full 61.44 MSPS over gigabit Ethernet, with only a handful of dropped samples per two million. So getting the data off the board is not the wall. The walls are elsewhere: transmit and receive streaming simultaneously starve above about 5 MSPS, and a modest CPU cannot do much useful work on 245 MB/s in real time even once it has it.

Transmit is the fragile direction, and it is fragile earlier than you would guess. Feeding the DAC from the host at only 3.072 MSPS — 12 MB/s, a twentieth of what capture manages — took one starve mute inside ten seconds, with nothing else running. The same test with the client on the board, over loopback, took none. The variable that matters is not the data rate on its own but how much play-out time each buffer holds: 256 K samples at 3.072 MSPS is 85 ms, so any stall longer than that empties the DAC, and 250 ms of empty is a muted transmitter. Larger buffers buy you slack; a slow link spends it.

Which raises the obvious question — if you only care about a 200 kHz signal, why sample 56 MHz at all? That question has a good answer, and it is lesson 27.

You are not building a design. You are joining one that already works — so the useful knowledge is not "what does each block do" but "where can I cut in, and what will bite me".

It is a script, not a drawing

Vivado shows the block design as a diagram you can drag boxes around in. On this board that diagram is generated, every build, by firmware/src/hdl/projects/pluto/system_bd.tcl. Nothing is stored as a picture.

That has three consequences worth internalising:

• Your change is a diff. Someone can review it, CI can check it, and git can tell you what moved. A dragged wire in a GUI is none of those things.
• You cannot accidentally change it. Clicking in the diagram edits a project that will be regenerated and discarded.
• The project is a cache, and a treacherous one. The build reuses an existing project rather than re-running the script — which is exactly the trap in lesson 20.

How software reaches into the fabric at all

Before the table makes sense, one idea has to land: memory-mapped I/O.

The processor has a single enormous range of numbered addresses. Most of those numbers are ordinary memory — the DDR chips, where writing a value stores it and reading gets it back. But some of the numbers are not memory at all. They are wired to hardware.

Write to one of those addresses and nothing is stored; instead a register inside a block in the fabric changes, and the hardware behaves differently from that instant. Read from it and you are not retrieving something you saved; you are asking the hardware what it currently is.

This is why the processor and the fabric need no special "send command" mechanism. The processor already knows how to write to an address. The block design's job is to decide which addresses land on which blocks.

Reading the addresses

This board's map

Two rows there are worth pausing on. One physical block appears to Linux as two devices, because its receive registers start at the base and its transmit registers start 0x4000 bytes further in. That single fact is why this board has both cf-ad9361-lpc and cf-ad9361-dds-core-lpc — they are two windows onto one piece of hardware.

Notice also that the DMA engines have interrupts and the radio interface does not. The DMAs need to announce "a buffer is finished"; the radio interface only ever answers questions.

iio_attr -u ip:192.168.2.1 -D cf-ad9361-dds-core-lpc direct_reg_access 0xBC

Why the map is a contract, not a note

Nothing discovers any of this. There is no scan, no plug-and-play. Linux is told, by a file called the device tree — zynq-pluto-sdr-fishball.dts — which lists every block, its address, its interrupt and its settings.

So the same addresses are written down in two independent places: the block design, which decides where the hardware actually answers, and the device tree, which tells the driver where to look. Nothing checks that they agree.

Three things that are not where you would guess

.spi_clk_o (pl_spi_clk_o),   // -> ball L14
.spi_sdo_o (pl_spi_mosi),    // -> ball N16
.spi_sdi_i (pl_spi_miso),    // <- ball N15
.spi_csn_i (1'b1),           // tied inactive
.spi_csn_o (),               // <-- THE CHIP SELECT GOES NOWHERE

What not to touch, and why

Three facts about this specific board that will otherwise cost you a day each. Everything here is defined from scratch — none of it is assumed.

First: what a clock domain is

A clock domain is simply the set of flip-flops driven by one particular clock signal. Logic inside a single domain is easy to reason about: every register captures at the same instant, so signals move in lockstep.

Trouble starts when a signal crosses between domains, because two unrelated clocks have no fixed relationship — their edges drift past each other. This board has three domains, and lesson 20 is entirely about crossing safely between them. For now you only need to know they exist and which one your logic lives in.

Second: what a strobe is, and why a clock is not one

The word comes from stroboscope — the lamp that flashes for an instant to freeze a spinning object. A strobe in digital hardware is the same idea: a brief pulse that says "now".

That is worth separating from the other kind of signal you meet:

So why not just use the clock?

This is the question worth sitting with, because the clock also pulses, constantly and reliably. Why is it not enough?

Because the clock is always running, and the data is not always new. The clock ticks whether or not anything happened. It is the heartbeat of the circuit, not a statement about the wires beside it.

Data, meanwhile, arrives irregularly. On this board there are at least three reasons a given clock tick might carry nothing you want:

• The channels take turns. In 2R2T, half the ticks belong to the other channel (the next section).
• A filter is decimating. With the ÷8 filter on, seven ticks in eight produce no output at all — the filter is still accumulating.
• The data ran out. On transmit, if software could not keep up, the hardware is presenting substituted zeros rather than your samples.

Between real samples, the wires do not go blank. They keep showing the last value, because that is what a register does — it holds. So logic that acts on every clock edge will happily process the same sample eight times in a row and never know.

So the strobe carries the one piece of information the clock cannot: is the thing beside me worth looking at this time? It is the difference between "a moment passed" and "something happened".

always @(posedge clk) begin      // clk decides WHEN you may act
  if (valid_in)                  // the strobe decides WHETHER you should
    accumulator <= accumulator + sample_in;
end

Read those two lines as a pair, because that is the whole convention: the clock grants permission to act; the strobe supplies the reason. Every block in this design's datapath is built that way, which is why they can be chained together at all — each one only moves when the one before it says there is something to move.

Third: 2R2T, where clock edges stop meaning samples

This board runs the AD9361 with two receivers and two transmitters — "2R2T". But there is only one physical link between the radio chip and the fabric. Two channels, one set of wires.

So the two channels take turns on it. That is all time-multiplexed means: sharing one path by alternating who gets to use it. One clock period carries a channel-0 sample, the next carries a channel-1 sample, then channel 0 again, forever.

The consequence: a clock edge is not a sample. There are twice as many clock edges as there are samples of any one channel. At 30.72 MSPS, l_clk runs at 61.44 MHz.

if (valid_in) count <= count + 1'b1;   // counts SAMPLES
// count <= count + 1'b1;              // counts CLOCK EDGES - twice as fast

The strobes on this board

Two blocks sit between the radio and the memory system. One of them is wired lopsidedly, and that lopsidedness will quietly ruin your second receiver if nobody warns you.

Why anything sits there at all

Think of the radio as two people talking, and the memory system as a single notepad. The radio produces two separate streams of numbers, one per receiver, arriving whenever the converter feels like producing them. Memory wants one wide, tidy, regular stream.

Something has to sit in the middle and reconcile them. That is all the packers are.

The receive one is called cpack — short for "channel pack". The transmit one is tx_upack, "unpack", and does the reverse.

What "packing" actually does

Suppose you asked for one receiver. Each 64-bit word then holds four 16-bit samples of it, back to back. Now ask for two receivers: each word holds two samples of each, interleaved.

The packer rearranges this on the fly, because which channels are switched on is decided by software at the moment it opens a buffer. The result is that memory is always densely filled — no padding, no gaps, no bandwidth spent on a channel you did not ask for.

Then how does your program know which sample is which?

This is the obvious objection, and it has a satisfying answer: the layout is decided by something your program already set. The metadata is in the request, not in the data.

Before opening a buffer, an application enables the channels it wants. That enable mask completely determines what comes back — the hardware packs enabled channels in a fixed order, and that order is the channels' scan index, always ascending.

On this board's receive core the four scan indices are:

So the stream you get is a direct consequence of what you asked for:

Nothing in the buffer identifies a sample. Its identity is its position, and position is knowable because you chose the mask.

# receiver 1 only - 4 bytes per sample instant
iio_readdev -u ip:192.168.2.1 -b 65536 -s 1048576 cf-ad9361-lpc voltage0 voltage1

# both receivers - 8 bytes per sample instant
iio_readdev -u ip:192.168.2.1 -b 65536 -s 1048576 cf-ad9361-lpc voltage0 voltage1 voltage2 voltage3

The strobe that moves each word, and the lopsided bit

Each packer has one signal that says "move a word now". Where that signal comes from is the whole story of this lesson:

Every channel is captured on channel 0's timing. Remember that for two paragraphs — it is the hinge the whole lesson turns on.

On ADI's wiring, channel 1's own valid signal — adc_valid_i1 — is connected to nothing at all. (In a default build of this repo it does have somewhere to go: it drives valid_in_2 of the decimator. The single write strobe is unchanged either way, which is the point.)

The filter that, on ADI’s wiring, exists on one channel only

Between the radio interface and cpack, channel 0 passes through a block called rx_fir_decimator. Channel 1 does not — it goes straight past.

That block is a hierarchy containing:

• One filter per stream — so two here, one for I and one for Q, since they must be filtered identically. (Four once channel 1 is routed through it too.)
• A clock-domain crossing for the on/off signal (lesson 21's problem, already solved for you here).
• Bypass multiplexers, one per stream — the switch that decides whether samples go through the filters or straight past them. They all follow a single active bit, so the filter hardware is always present in the fabric and what actually moves at runtime is the bypass.

What is it for? The chip has a floor

A fair question, given the trouble it causes: why did ADI put a decimating filter in the fabric at all, when the AD9361 already has perfectly good filters of its own?

Because the AD9361 cannot go slow enough. Ask it:

iio_attr -u ip:192.168.2.1 -i -c ad9361-phy voltage0 sampling_frequency_available
#   [2083333 1 61440000]     <- minimum, step, maximum

2,083,333 samples per second is a hard floor in the silicon. The chip will not go below it. So without help, the narrowest slice of spectrum this radio can deliver is about 2.1 MHz wide — and an enormous number of interesting signals are far narrower than that:

For any of those you would be forced to capture 2.08 MSPS, ship it all to the host, and throw away 90% of it there — paying full bandwidth and full CPU for a sliver of signal.

The fabric decimator removes that floor. Measured on this board, with the converter set as slow as it will go:

260 kSPS is comfortably below anything the chip can reach alone, and it is exactly the region where FM, GSM and narrowband IoT live. That is what the block is for: it extends the radio's usable range downward, past a limit built into the silicon.

Why it is a filter and a ÷8, never just a ÷8

"Decimate by eight" sounds like it should be trivial: keep every eighth sample, throw the other seven away. Why drag a 129-tap filter and a coefficient file into it?

Because throwing samples away is undersampling, and you already know what undersampling does (lesson 12). Take 61.44 MSPS and keep one sample in eight and you now have a 7.68 MSPS stream — whose window is only ±3.84 MHz. Everything that was outside that window does not disappear. It folds in.

The FIR filter's job is to empty those seven slices out before the samples are discarded. It passes what is inside ±3.84 MHz and attenuates everything beyond it, so that when the folding happens there is almost nothing left to fold. That is why this kind of filter is called an anti-alias filter — it does not "improve" the signal, it removes what would otherwise arrive uninvited.

The order is not negotiable, and it is what the word means:

So what is in the .coe file?

Just numbers — one tap value per line, 129 of them. That list is the filter: it decides exactly where the passband ends, how steeply the response falls, and how far down the stopband sits.

That last figure is the one that matters here. If the stopband is 80 dB down, whatever folds in arrives 80 dB weaker than it was. If a sloppy design only reaches 40 dB, a strong neighbouring transmitter can still land on your signal at a level you will notice. The coefficients set how much aliasing survives, which is why they are a designed artefact and not an afterthought.

The one line of Tcl that builds it

The whole hierarchy comes from a single call in the block-design script:

ad_add_decimation_filter "rx_fir_decimator" 8 2 1 {61.44} {61.44} <coe>

Taken piece by piece, left to right:

How you switch it on

Each hierarchy has one pin called active. Low means "pass samples straight through"; high means "send them through the filters". That pin is driven from a single bit of a general-purpose register, pulled out by a small block called decim_slice.

You never set that bit by hand. You ask for the slower rate, and Linux engages the filter for you:

# run on your HOST. Ask what rates the receive path will give you:
iio_attr -u ip:192.168.2.1 -i -c cf-ad9361-lpc voltage0 sampling_frequency_available

# You get exactly TWO numbers, and they are not fixed - they follow
# whatever the AD9361 is currently converting at:
#   converter at 30.72 MSPS  ->  "30720000 3840000"
#   converter at 61.44 MSPS  ->  "61440000 7680000"
# In both cases: the full rate, and the full rate divided by eight.

# Asking for the lower one turns the filter on:
iio_attr -u ip:192.168.2.1 -i -c cf-ad9361-lpc voltage0 sampling_frequency 3840000

The AD9361 keeps running at its full rate; the fabric now hands you one eighth of it. Ask for the full rate again and the mux flips back. The filter is bypassed unless something asks for the slow rate.

iio_attr -u ip:192.168.2.1 -i -c ad9361-phy voltage0 sampling_frequency

Fixing it: both receivers, in lockstep

The helper already loops over its channel count, so the repair is to ask for four channels rather than two and feed the second pair through as well. Channel 1 then gets its own pair of filters, identical to channel 0's:

// 4 channels: ch0 I/Q and ch1 I/Q, rather than 2
ad_add_decimation_filter "rx_fir_decimator" 8 4 1 {61.44} {61.44} <coe>

// feed channel 1 in ...
ad_connect axi_ad9361/adc_data_i1  rx_fir_decimator/data_in_2
ad_connect axi_ad9361/adc_data_q1  rx_fir_decimator/data_in_3

// ... and take cpack's inputs from the filter, not from axi_ad9361
ad_connect cpack/fifo_wr_data_2  rx_fir_decimator/data_out_2
ad_connect cpack/fifo_wr_data_3  rx_fir_decimator/data_out_3

The word that matters is lockstep. Both channels now share one active bit, one coefficient set and therefore one group delay. They are not two filters that happen to be similar — they are the same filter instantiated twice, switching on together and delaying their signals by exactly the same amount. That is what keeps the two receivers sample-aligned, which is the whole point of having two.

cpack/fifo_wr_en still takes valid_out_0, and that is now correct rather than merely tolerable: all four paths produce output on the same schedule.

Two extra filter instances, about 11 DSP slices each, and over 70 dB of alias suppression on a channel that previously had none. Full write-up: docs/both-receive-channels.md in the repository.

The full journey in both directions: from the packer, through a DMA engine, across a dedicated port into the DDR chips, and up into your program's buffer. Every address and every setting here is this board's.

The problem being solved

At 61.44 MSPS each direction is 245 MB/s. A 666 MHz ARM core cannot copy that, byte by byte, and do anything else. It would not even come close.

So it does not. A separate piece of hardware moves the data while the processor gets on with its life, and only tells the processor when a whole buffer is done. That hardware is a DMA engine — Direct Memory Access.

The two engines on this board

Both are ADI's axi_dmac, one per direction, 64 bits wide on the fabric side — which is exactly the width cpack produces and tx_upack consumes. That is not a coincidence; the packers exist partly to make this width match.

Those addresses are mirrored in the device tree (zynq-pluto-sdr-fishball.dts). Move a block in the block design and the driver probes the wrong place; add one and it needs a device-tree node before Linux can see it at all.

Receive, step by step

1. The AD9361 sends samples over the LVDS link. axi_ad9361 recovers the clock, deserialises, sign-extends 12 bits to 16, applies DC-offset correction.
2. Channel 0 passes through rx_fir_decimator (lesson 15); channel 1 goes straight past it.
3. cpack interleaves the enabled channels into 64-bit words, one word per pulse of fifo_wr_en.
4. Those words land in the receive DMA's input FIFO — a small on-chip queue absorbing the difference between the steady sample rate and the bursty memory bus.
5. The engine bursts them across S_AXI_HP1 into DDR, at addresses software gave it in a descriptor.
6. When a buffer is full, the engine raises interrupt ps-13. The driver marks that buffer ready and hands the next one to the hardware.
7. Your program's read() — or iio_readdev, or pyadi-iio — returns the completed buffer. No sample was ever copied by the CPU.

SYNC_TRANSFER_START is why a capture begins on a clean packer boundary rather than halfway through an interleaved word. Without it, your first samples could be the tail of a word and the channel order would be shifted.

Transmit, step by step

1. Your program writes samples into a buffer. The driver hands the DMA a descriptor pointing at it in DDR.
2. The engine reads from DDR across S_AXI_HP2, filling an internal FIFO ahead of demand.
3. It presents 64-bit words to tx_upack as an AXI-Stream, one per pulse of fifo_rd_en.
4. tx_upack splits each word back into per-channel 16-bit samples.
5. axi_ad9361 takes bits [15:4] of each — the DAC is 12 bits — and sends them over the LVDS link. Bits [3:0] are discarded, which is exactly what the sample-locked GPIO feature reuses.
6. Interrupt ps-12 tells the driver a buffer has been consumed, so it can queue the next.

Buffer sizing, from Linux

Buffers are allocated by the kernel's IIO DMA layer, and there is a ceiling on how large one block may be. The Buildroot userspace sets it at boot, in the script below — note that a board running the Debian rootfs has no S21misc at all and does this from a systemd unit instead, so check which userspace you are on before looking for it:

MAX_BS=`fw_printenv -n iio_max_block_size 2> /dev/null || echo 67108864`
echo ${MAX_BS} > /sys/module/industrialio_buffer_dma/parameters/max_block_size

64 MB by default — about 16 million samples — overridable from the U-Boot environment with fw_setenv iio_max_block_size.

The trade is the usual one. Large buffers mean fewer interrupts and far more tolerance of a host that pauses, at the cost of latency: nothing is delivered until the whole buffer is full. Small buffers react quickly but demand that software keeps up, every time, or you underflow.

# run on your HOST - raise the sample rate until this starts complaining
iio_adi_xflow_check -u ip:192.168.2.1 cf-ad9361-lpc

Changing the fabric

A real module from this repo. Twenty lines of logic that teach four habits at once.

What it does. The AD9361's DAC is 12 bits, but you hand it 16-bit samples. It takes the top 12 and throws the bottom four away — literally, in ADI's HDL: dac_data_out <= dma_data[15:4]. Those four bits reach the fabric and stop there. This module catches them and puts them on four header pins, in lockstep with the sample that carried them. It costs nothing in signal quality, because the bits never reached the DAC.

module tx_gpio_bitmap (
  input  wire       clk,        // l_clk
  input  wire       rst,
  input  wire [3:0] sample_in,  // the discarded low nibble
  input  wire       valid_in,   // fifo_rd_valid | fifo_rd_underflow
  input  wire       flag,       // enable, from an AXI register
  input  wire [3:0] gpio_in,    // what the PS wants when disabled
  output wire [3:0] pin_o
);

  // (1) 'flag' is written in the AXI clock domain and read here in
  //     l_clk. Two flip-flops make that safe. See lesson 22.
  reg flag_meta, flag_sync;
  always @(posedge clk) begin
    flag_meta <= flag;
    flag_sync <= flag_meta;
  end

  // (2) capture on the VALID strobe, never on the clock: in 2R2T a
  //     sample arrives only every second l_clk edge.
  reg [3:0] held;
  always @(posedge clk) begin
    if (rst)            held <= 4'd0;
    else if (valid_in)  held <= sample_in;
  end

  // (3) our nibble, or the processor's GPIO
  assign pin_o = flag_sync ? held : gpio_in;

endmodule

The four habits

1. Synchronise anything arriving from another clock. flag is written by Linux. Sampling it directly risks metastability. Two flip-flops cost almost nothing.
2. Gate on valid, never on the clock. The 2R2T trap from lesson 14.
3. Reset only what needs it. held does; the synchroniser flops do not. Over-resetting wastes fabric and strains timing.
4. Keep the bypass clean. With flag clear the pins behave exactly as before. A feature you cannot fully switch off is one people will not switch on.

This board's block design is a script, not a drawing — which means your change is a reviewable diff rather than a mouse gesture nobody can check.

Tcl is the scripting language Vivado is driven by. You do not need to learn it as a language; you need four kinds of line, all in firmware/src/hdl/projects/pluto/system_bd.tcl.

# 1. make the source file part of the project
add_files -norecurse $ad_hdl_dir/projects/pluto/tx_gpio_bitmap.v

# 2. instantiate it as a cell in the block design
create_bd_cell -type module -reference tx_gpio_bitmap tx_bitmap

# 3. slice the bits you want out of a wide bus
ad_ip_instance xlslice nibble_slice [list \
  DIN_WIDTH 16 DIN_FROM 3 DIN_TO 0 DOUT_WIDTH 4]

# 4. connect things up
ad_connect axi_ad9361/l_clk            tx_bitmap/clk
ad_connect axi_ad9361/rst              tx_bitmap/rst
ad_connect tx_upack/fifo_rd_data_0     nibble_slice/Din
ad_connect nibble_slice/Dout           tx_bitmap/sample_in
ad_connect tx_upack/fifo_rd_valid      bitmap_valid_or/Op1
ad_connect tx_upack/fifo_rd_underflow  bitmap_valid_or/Op2
ad_connect bitmap_valid_or/Res         tx_bitmap/valid_in

The helper blocks you will reach for

Lesson 18 dropped a module into the block design in three lines. That is the right answer for a small change and the wrong one for anything you intend to keep. This lesson turns the same Verilog into a real Vivado IP — one that appears in the catalog, carries parameters and interfaces, and can be cut into the receive or transmit path the way ADI's own blocks are.

Module or IP? Decide once, up front

The honest rule: prototype as a module, package when it works. Packaging a design you are still changing is a tax you pay on every edit, because every change means re-running the packaging step before the project sees it.

Step 1 — write the RTL with the packager in mind

Vivado infers interfaces from signal names. Name your ports the way it expects and a 36-signal AXI4-Stream collapses into one bus you connect with a single line; name them creatively and you get 36 loose pins forever. Here is a receive-path block — a scaler, one multiply per sample — written for this board's conventions:

module util_rxscale #(
  parameter DATA_WIDTH = 16
) (
  input  wire                    clk,        // l_clk - the recovered clock
  input  wire                    resetn,

  // ---- the ADI datapath convention, in ----
  input  wire                    valid_in,   // one pulse per sample
  input  wire                    enable_in,  // channel is switched on (a level, not a strobe)
  input  wire [DATA_WIDTH-1:0] data_in,

  // ---- and out ----
  output reg                     valid_out,
  output wire                    enable_out,
  output reg  [DATA_WIDTH-1:0] data_out,

  input  wire [7:0]              shift       // runtime control, see step 6
);
  assign enable_out = enable_in;      // pass the level straight through

  wire signed [DATA_WIDTH-1:0] s = data_in;

  always @(posedge clk) begin
    if (!resetn) begin
      valid_out <= 1'b0;
      data_out  <= {DATA_WIDTH{1'b0}};
    end else begin
      valid_out <= valid_in;           // SAME latency as the data - one cycle
      data_out  <= s >>> shift;        // arithmetic shift: keeps the sign
    end
  end
endmodule

Step 2 — package it

The GUI route is Tools → Create and Package New IP → Package a specified directory, and it works. It is also a sequence of mouse clicks that nobody can review and you cannot repeat, so use it to explore and then write the script. This repository's library is entirely scripted, and your IP should match:

source ../../scripts/adi_env.tcl
source $ad_hdl_dir/library/scripts/adi_ip_xilinx.tcl

adi_ip_create util_rxscale                          # make the packaging project
adi_ip_files  util_rxscale [list "util_rxscale.v"]  # the sources it contains
adi_ip_properties_lite util_rxscale                 # name, vendor, taxonomy, clocks

ipx::save_core [ipx::current_core]

Build it the way every other IP here is built:

cp ../util_axis_fifo/Makefile .   # a library at the SAME depth as yours
# then edit it down to:
#   LIBRARY_NAME := util_rxscale
#   GENERIC_DEPS += util_rxscale.v
#   XILINX_DEPS  += util_rxscale_ip.tcl
#   include ../scripts/library.mk
make                             # runs vivado -mode batch on the _ip.tcl
ls component.xml                 # this file IS the IP

Step 3 — instantiate it

Once it is in the catalog it instantiates like any ADI block, from projects/pluto/system_bd.tcl:

ad_ip_instance util_rxscale rx_scale_i [list DATA_WIDTH 16]
ad_ip_instance util_rxscale rx_scale_q [list DATA_WIDTH 16]

Note what changed from lesson 18: no add_files, because the IP carries its own sources, and parameters are passed by name rather than hoped for.

Step 4 — cut it into the receive path

Insertion is always the same two moves: delete the existing connection, then make two new ones. On receive, the cut is between axi_ad9361 and whatever currently consumes its samples — rx_fir_decimator in this design, cpack in a design without the filter.

# 1. break what ADI wired
ad_disconnect axi_ad9361/adc_data_i0  rx_fir_decimator/data_in_0
ad_disconnect axi_ad9361/adc_valid_i0 rx_fir_decimator/valid_in_0

# 2. clock and reset your block from the same domain as the data
ad_connect axi_ad9361/l_clk  rx_scale_i/clk
ad_connect sys_rstgen/peripheral_aresetn rx_scale_i/resetn

# 3. route through it
ad_connect axi_ad9361/adc_data_i0   rx_scale_i/data_in
ad_connect axi_ad9361/adc_valid_i0  rx_scale_i/valid_in
ad_connect axi_ad9361/adc_enable_i0 rx_scale_i/enable_in

ad_connect rx_scale_i/data_out   rx_fir_decimator/data_in_0
ad_connect rx_scale_i/valid_out  rx_fir_decimator/valid_in_0
ad_connect rx_scale_i/enable_out rx_fir_decimator/enable_in_0

Repeat for _q0, and — this is the part people skip — for _i1 and _q1 as well.

Step 5 — and the transmit path, which is fussier

Transmit runs the other way: tx_upack produces samples, axi_ad9361 consumes them. The cut is symmetrical:

ad_disconnect tx_upack/fifo_rd_data_0 axi_ad9361/dac_data_i0

ad_connect tx_upack/fifo_rd_data_0  tx_scale_i/data_in
ad_connect tx_upack/fifo_rd_valid   tx_scale_i/valid_in
ad_connect axi_ad9361/dac_enable_i0 tx_scale_i/enable_in
ad_connect tx_scale_i/data_out      axi_ad9361/dac_data_i0

Step 6 — giving it a knob software can turn

The shift input has to come from somewhere. Two routes, in increasing order of effort:

Whichever you pick, the value crosses from sys_cpu_clk to l_clk, so it needs the treatment in lesson 22 — and a constraint, or Vivado will quietly drop the path.

Step 7 — build it, and the one step everybody forgets

# 1. package (only when the IP's own sources changed)
cd firmware/src/hdl/library/util_rxscale && make && cd -

# 2. DELETE THE PROJECT. build_hdl.tcl reuses an existing pluto.xpr and
#    will silently ignore your block-design change if you skip this.
rm -rf firmware/src/hdl/projects/pluto/pluto.{xpr,cache,gen,hw,ip_user_files,runs,sim,srcs,sdk}

# 3. build, check, flash
./devkit build --hdl-only
./devkit verify
./devkit flash --boot-only

Step 2 is the single most expensive mistake in this whole course. The build succeeds, the bitstream is valid, the board boots — and it is running your previous design. Delete the project.

A signal that reaches the edge of the fabric still has to be told which physical ball to leave by, and at what voltage.

Constraints live in an XDC file (Xilinx Design Constraints) — system_constr.xdc. One line per pin:

set_property -dict {PACKAGE_PIN V10 IOSTANDARD LVCMOS33 PULLTYPE PULLDOWN} \
  [get_ports sample_gpio[0]]

The four pins verified on this board

Bank 13 is supplied from the 3.3 V rail, which is why the standard is LVCMOS33. Declaring an IOSTANDARD that does not match the bank's supply is a build error at best.

You will barely click anything. But you must be able to read the report.

# run from: firmware/src
rm -rf hdl/projects/pluto/pluto.{xpr,cache,gen,hw,ip_user_files,runs,sim,srcs,sdk}

What the build actually does

Reading timing

The number that matters is WNS — Worst Negative Slack, in nanoseconds. Slack is spare time: how much earlier than its deadline the slowest signal arrived.

• WNS positive — timing met, with that much margin. Builds of this repository land near +0.2 ns on this board, on either wiring.
• WNS negative — some path is too slow. The bitstream still builds, and may even appear to work, but it is unreliable and temperature-dependent. Do not ship it.

Fixes, in the order worth trying: add a pipeline register to cut a long combinational path in two; narrow an arithmetic operation; move a multiply onto a DSP slice; and only then start adjusting constraints.

Your budget on this chip

Two-thirds of the multipliers and three-quarters of the logic are free. A 300-tap filter fits comfortably.

The richest source of bugs that pass simulation, pass timing, and then fail on hardware occasionally.

Your enable bit is written by Linux in the AXI clock domain. Your datapath runs on l_clk, whose frequency changes with the sample rate. These two clocks have no fixed relationship whatsoever.

A flip-flop needs its input to be stable for a short window either side of the clock edge. If the input changes exactly then, the flip-flop can enter metastability — an unstable in-between state, neither 0 nor 1, that resolves after an unpredictable delay. Anything downstream sees garbage, and worse, different downstream logic may resolve it differently.

reg meta, sync;
always @(posedge dest_clk) begin
  meta <= src_signal;   // this one may go metastable
  sync <= meta;         // by now it has had a full cycle to settle
end
// use 'sync' everywhere. Never use 'meta'.

Telling the tools it is deliberate

Synthesis does not know the crossing is intentional, so you say so in the XDC:

set_max_delay -datapath_only \
  -from [get_cells .../flag_reg] \
  -to   [get_cells .../flag_meta_reg] 4.000

Logic you cannot control from software is a demo. Here is where the two halves meet.

ADI's cores expose a block of AXI registers — memory addresses that, when written from Linux, change signals in the fabric. One of them, GP_CONTROL at offset 0xBC on the transmit core, is a general-purpose output whose bits you can slice and use. That is how the bit-map feature gets its enable without adding a whole new AXI device:

Because two independent features share one register, every write must be read-modify-write: read the current value, change only your bit, write it back. Assigning the whole register clears the other feature.

Poking it by hand

# run on your HOST
iio_attr -u ip:192.168.2.1 -D cf-ad9361-dds-core-lpc direct_reg_access 0xBC
iio_attr -u ip:192.168.2.1 -D cf-ad9361-dds-core-lpc direct_reg_access

Giving it a proper name

Raw register pokes are fine for bring-up and wrong for a shipped feature. Add a sysfs attribute in the Linux driver and your feature becomes a named file, readable and writable from anywhere including over the network:

static ssize_t axidds_tx_sample_gpio_store(struct device *dev,
    struct device_attribute *attr, const char *buf, size_t len)
{
    /* read-modify-write: bit 0 belongs to someone else */
    cf_axi_dds_lock(st);
    reg = dds_read(st, ADI_REG_DAC_GP_CONTROL);
    if (enable) reg |=  ADI_TX_SAMPLE_GPIO_EN;
    else        reg &= ~ADI_TX_SAMPLE_GPIO_EN;
    dds_write(st, ADI_REG_DAC_GP_CONTROL, reg);
    cf_axi_dds_unlock(st);
    return len;
}

# run on your HOST - no ssh needed, it is a device attribute
iio_attr -u ip:192.168.2.1 -d cf-ad9361-dds-core-lpc tx_sample_gpio_en 1

Signals, before the fabric

You have been reading spectra since lesson 12 without ever being told what one is. Here is the whole idea, and the three settings that decide whether the picture can be trusted.

One signal, two descriptions

A signal can be described by what it does over time — a list of samples, one after another — or by which frequencies it is made of. Neither description is more true than the other. They are two complete accounts of the same thing, and you can convert between them without losing anything at all.

The conversion is the Fourier transform. Its practical form on a computer is the DFT (Discrete Fourier Transform), and the clever algorithm everyone actually runs is the FFT (Fast Fourier Transform). When a tool says "4096-point FFT", 4096 is how many samples it swallowed in one go.

What the picture is actually showing

An FFT of N samples gives you N numbers back, called bins. Each bin is one narrow slice of frequency, and its value is how much energy landed in that slice. Plot the bins left to right, in decibels, and that is the spectrum you have been looking at.

Because this board samples I and Q (lesson 11), its bins run from −fs/2 to +fs/2 around the tuned frequency — negative offsets are real and mean "below the local oscillator".

The three settings that decide what you see

The trade you cannot escape

Resolution is fs / N. To see finer frequency detail you need a longer FFT, which means collecting samples for longer, which means less ability to see something that changes quickly. Frequency resolution and time resolution trade directly against one another. There is no setting that gives you both, and no amount of processing invents the difference.

At 61.44 MSPS a 4096-point FFT covers 66.7 µs of time and 15 kHz per bin. Drop to 2.083 MSPS and the same 4096 points cover 1.97 ms and 509 Hz per bin. Same transform, entirely different instrument.

Every measurement in this course is quoted in dB against a noise floor. Both halves of that sentence deserve explaining properly, because almost every wrong RF number traces back to one of them.

Decibels, once and for all

A decibel is a ratio written on a logarithmic scale. Radio needs it because one page has to hold both a transmitter and the thermal noise it is competing with, and those differ by a factor of a hundred billion.

power ratio      dB = 10 × log10(P1 / P2)
amplitude ratio  dB = 20 × log10(A1 / A2)

Two formulas, because power goes as amplitude squared — the 20 is not a different unit, it is the same formula with the square pulled out front. Worth memorising outright: 3 dB is double the power, 6 dB is double the amplitude, 10 dB is ten times the power, 20 dB is ten times the amplitude.

And because they are logarithms, they add. A +19 dBm transmitter through a 20 dB attenuator arrives at −1 dBm. No multiplication anywhere. That is the whole reason the unit survives.

Mixing these up is the most common unit error in radio. dBm is a power. dBFS only means something relative to one particular converter. dBc only means something relative to one particular signal. A density in dBm/Hz is not a power until you multiply it by a bandwidth.

Where noise actually comes from

Three sources stack up, and on this board they arrive in this order of importance:

1. Thermal noise. Charge carriers jiggle at any temperature above absolute zero, and that jiggle is a voltage. It sets an absolute floor no design can beat: −174 dBm per hertz at room temperature. Over 5 MHz of bandwidth that is −174 + 10·log₁₀(5×10⁶) = −107 dBm.
2. The receiver's own noise, quantified as noise figure (NF) — how many dB worse than that ideal floor the hardware actually is. Every amplifier and mixer adds some. The AD9361 is roughly 3–6 dB depending on gain setting and band.
3. Quantisation noise from the converter — the 6.02N + 1.76 dB limit from lesson 9. On this board it is usually the smallest of the three, which is the point of having 12 bits.

SNR is not one number — it is a number and a bandwidth

"The SNR is 30 dB" is an incomplete statement, in exactly the way "it is 20 degrees" is incomplete without saying Celsius. The honest form names the bandwidth it was measured in. A tone measured in a 15 kHz FFT bin and the same tone measured across 5 MHz of receiver differ by 10·log₁₀(5 000 000 / 15 000) = 25 dB, with nothing about the radio having changed.

Reading your own board

A measured example from this hardware — cable loopback at 900 MHz, 5 MSPS, TX2A through a 20 dB pad into RX2A:

DSP in the fabric

Almost everything you will build in the fabric is a filter or contains one. The idea is simpler than the notation suggests.

A filter passes some frequencies and rejects others. In the digital world you do that with arithmetic: each output sample is a weighted sum of the most recent input samples.

out[n] = c0*in[n] + c1*in[n-1] + c2*in[n-2] + c3*in[n-3];

That is a FIR filter — Finite Impulse Response, so called because if you feed it a single spike, the output stops after a finite number of samples (four, here). The weights c0..c3 are taps or coefficients, and they are the entire design: choosing them chooses which frequencies survive.

What it costs in fabric

A filter with N taps needs N multiplications per output. Multiplication is expensive in LUTs, which is why the chip has 220 dedicated DSP slices. A naive 100-tap filter would need 100 of them — nearly half your budget for one filter. The next lesson is about why that estimate is usually far too pessimistic.

The single most useful trick in fabric DSP, and the reason the channelizer in this repo is affordable.

Decimation means producing one output for every D inputs — lowering the sample rate by a factor of D. You must filter first, or the discarded bandwidth aliases back in (lesson 12). So decimation is always a filter plus a throw-away.

Here is the trick. If you only produce one output every D input samples, the hardware has D input-sample periods to compute each output. One multiplier can therefore be reused D times. A 128-tap filter decimating by 8 needs roughly 16 multipliers, not 128.

Why sample at 61 MSPS only to throw most of it away?

It looks wasteful. Capture 56 MHz of spectrum, decimate by 307, and keep a 200 kHz channel — you discarded 99.7% of what you collected. Why not just tell the AD9361 to sample at 200 kSPS in the first place? It can; its analogue filter goes down to 200 kHz.

Sometimes that is exactly the right answer. But there are four reasons the wide-then-decimate route wins, and the first one is worth real money.

1. You gain dynamic range — about four extra bits

The converter's own quantisation noise is roughly fixed in total power, and it is spread evenly across the whole sampled bandwidth. Filter down to a narrow slice and you keep all of your signal but only a fraction of that noise. The improvement is 10·log₁₀(D) decibels, where D is the decimation factor.

The AD9361's converter is 12 bits. Decimating by 307 gets you the effective dynamic range of a 16-bit converter in that channel, for free, in fabric you have already paid for. This is oversampling, and it is why high-end converters sample far faster than the signal needs.

2. A digital filter is far sharper than the analogue one

The AD9361's analogue filter is a handful of poles: a gentle slope, a corner that moves with temperature, and a response you cannot know exactly. A 321-tap FIR gives you 80 dB of stopband rejection, a transition band a few percent wide, and exactly linear phase — a response you designed and can verify. If a strong transmitter sits 300 kHz from the signal you want, only the digital filter will save you.

3. You can retune without touching the radio

Changing the AD9361's local oscillator takes time, disturbs its calibration, and breaks phase continuity. Changing the frequency of a digital mixer in the fabric (lesson 28) is a single register write, effective on the next sample, with the phase relationship preserved. Capture wide once, then move around inside that capture instantly and as often as you like.

For anything phase-sensitive — direction finding, coherent multi-channel work, interferometry — this is not a convenience, it is the only workable approach.

4. One capture, many channels

The local oscillator gives you one place at a time. A wide capture can be split into as many narrow channels as you have fabric for, all simultaneously, all phase-coherent with one another. That is what a channelizer is, and it cannot be done by tuning.

The worked example in this repo

It channelises wideband FM: filter and decimate in the fabric so the host receives a narrow, already-clean stream instead of the full firehose.

How to move a signal in frequency without touching the radio's tuning.

Multiplying a signal by a complex exponential shifts it in frequency. That is all a mixer is. Multiply your baseband by ej2πft and the whole spectrum slides up by f; use a negative f and it slides down.

To do that you need a source of sine and cosine at an arbitrary frequency — a numerically-controlled oscillator (NCO). The classic implementation is a phase accumulator: a counter that adds a fixed step every sample, so its value ramps and wraps, representing an angle. Feed that angle into a lookup table of sine values and you have an oscillator whose frequency is set by one number.

reg [31:0] phase;
always @(posedge clk)
  if (valid) phase <= phase + step;   // step sets the frequency

// frequency = step / 2^32 * sample_rate
// the accumulator wraps naturally, which is exactly what an angle does

A lookup table costs block RAM and its size grows with the precision you want. CORDIC is the alternative: an algorithm that computes sine, cosine and rotation using only shifts and adds, no multipliers and no table. It takes one iteration per bit of precision, which pipelines beautifully in fabric. For frequency shifting, rectangular-to-polar conversion, or computing magnitude and phase, CORDIC is usually the right answer on an FPGA.

Building a radio link

The lesson that decides your whole architecture: stream the information, not the samples.

To send data you map bits onto something measurable. The standard scheme is to choose, for each symbol period, one point from a fixed set — a constellation — and transmit a pulse of that amplitude and phase.

Between symbols you cannot simply jump — an abrupt step spreads energy across the whole spectrum. So each symbol is shaped by a pulse-shaping filter, usually a root-raised-cosine, which confines the signal to its allotted bandwidth while still letting the receiver recover each symbol cleanly.

The architecture question

So: should sophisticated modulation at high rates always live in the fabric? Not quite. The useful question is what you send down the wire to the board.

The three honest options

Note that "sophisticated" and "fast" are separate axes. A complex scheme at a modest rate streams perfectly well from a PC, where it is far easier to write and debug. A simple scheme at a very high rate belongs in fabric. The genuinely hard case is complex and fast — and there the answer is to split it: the clever, slow, irregular parts (coding, framing, adaptation) stay on the processor; the dumb, fast, regular parts (pulse shaping, interpolation, mixing) go in the fabric. That partition is what almost every real radio does.

A symbol is a number. A radio has to turn it into a shape. Which shape you pick decides how much spectrum you occupy and whether your symbols smear into each other — and the standard answer is strange enough to be worth deriving rather than copying.

The obvious idea, and why it fails

Say you want to send the QPSK symbols from lesson 29 at 1 Msym/s. The obvious thing is to hold each symbol steady for a microsecond and then jump to the next: a train of rectangles.

It fails for a reason you can see in lesson 24's terms. A rectangle in time is a sinc in frequency — skirts that fall off as 1/f and never truly end. Your 1 Msym/s signal, which ought to need about 1 MHz, is still radiating measurably 20 MHz away, into somebody else's band. Sharp edges in time are wide in frequency; there is no way around it.

Nyquist's trick: zero at the sampling instants

The insight is that a pulse does not have to be short. It only has to be zero at every other symbol's sampling instant. Between those instants it can do whatever it likes, because nobody looks there.

The family of pulses with that property is called Nyquist pulses, and the one everybody uses is the raised cosine. It has a single knob, the roll-off β, between 0 and 1:

So β buys timing tolerance with bandwidth. Occupied bandwidth = (1 + β) × symbol rate is the one formula to carry out of this lesson.

Why root raised cosine, and why it is split in half

Here is the part that confuses everyone the first time. The pulse that must satisfy the Nyquist condition is the one measured end to end — transmitter, channel and receiver combined. So you do not put a raised cosine in the transmitter. You put a root raised cosine (RRC) in the transmitter and an identical RRC in the receiver. Two square roots multiply back to the raised cosine you wanted, and you get it only after the receiver has done its half.

How you actually build one

Mechanically, pulse shaping is upsampling followed by an FIR filter — lesson 27's decimator run backwards:

1. Take one complex symbol per symbol period.
2. Insert sps−1 zeros after each one. This is the upsample step; sps is samples per symbol, and 4 is the usual choice.
3. Run the result through the RRC filter. Its taps fill in the zeros with the pulse shape, so what comes out is a smooth waveform at sps × the symbol rate.

The filter is defined over a span of symbols — how many symbol periods of tail you keep before truncating. Span 10 at 4 samples per symbol is 41 taps, which is what the test waveforms in this repository use.

up = np.zeros(nsym*sps, dtype=complex)
up[::sps] = syms                  # one symbol, then sps-1 zeros
h  = rrc(beta=0.35, sps=4, span=10)   # 41 taps
x  = np.convolve(up, h)           # the shaped waveform

Three lines. In the fabric it is the same three ideas — a strobe that fires once per symbol, a multiply-accumulate chain, and the polyphase decomposition of lesson 27 so the multipliers are not wasted on the zeros you just inserted.

A receiver does not get symbols. It gets a stream of numbers with the symbols hidden at unknown times, unknown phase and unknown orientation. Recovering them is a whole discipline — here is enough of it to avoid the classic traps.

Three unknowns, in order

Timing recovery

Matched-filter the incoming stream, then decide which sample within each symbol period is the right one. The classic detectors are Gardner and Müller & Mueller, both feedback loops that nudge the sampling instant until an error measure settles.

For an offline capture you can do something simpler and completely robust: try every candidate phase and pick the best by a quality measure. For a constant-envelope modulation like QPSK, the correct instant is the one where the recovered symbols have the least spread in magnitude:

# z is the matched-filtered stream, sps samples per symbol
best = None
for phase in range(sps * OVERSAMPLE):
    s = z[phase::sps * OVERSAMPLE]
    # 1/kurtosis: 1.0 means perfectly constant magnitude
    q = mean(abs(s)**2)**2 / mean(abs(s)**4)
    if q > best: best, best_phase = q, phase

That quality number is diagnostic in itself. A clean lock reads 1.000; a value near 0.5 means the symbols look Gaussian — which is what you get when the data is genuinely corrupted rather than merely mistimed. It is how the DMA-starvation problem on this board was first identified.

Phase ambiguity, and the bug it causes

QPSK's four points are symmetric under 90° rotation. So the standard way to remove an unknown phase is to raise the symbols to the fourth power — which cancels the data — take the angle, and divide by four.

It works, and it leaves you with a constellation that could still be rotated by any multiple of 90°, because the fourth power threw that information away. That residue is phase ambiguity, and real systems resolve it with a known preamble or by encoding data in phase changes rather than absolute phase.

Lesson 31 recovered timing and phase once you knew a signal was there. This is the step before it: deciding that something is there, and where it starts, in a stream of numbers that mostly is not. It is also the single operation this board's fabric is best at.

Correlation, in one sentence

Slide a known template along the received samples, and at each offset multiply the two together point by point and add up the result. Where the template lines up with a real copy of itself, every product is positive and the sum shoots up. Everywhere else the products are a random mix and the sum stays small.

That is all correlation is — and lesson 24's intuition for the Fourier transform was the same operation with a sine wave as the template. Detection, demodulation and spectrum analysis are three uses of one idea.

Where the gain comes from, and how much

Add up N samples of signal that are all lined up and the amplitudes add directly: N times bigger. Add up N samples of noise and they partly cancel, growing only as √N. The ratio improves by N / √N = √N in amplitude — which is 10·log₁₀(N) dB in power.

A 64-sample preamble therefore buys 18 dB. A 1024-sample one buys 30 dB. That is how a signal sitting below the noise floor is found at all: you do not see it, you accumulate it.

It is the same trade as every other one in this half of the book — longer look, narrower effective bandwidth, less noise. Lesson 24 called it FFT length, lesson 25 called it noise bandwidth, lesson 27 called it process gain. Here it is called correlation gain.

What makes a good preamble

The template you correlate against is usually a preamble — a known sequence sent at the front of every packet. It needs one property: it must look like itself at zero offset and like nothing at all at every other offset. That property is its autocorrelation, and the ideal shape is a single sharp spike, which is why engineers call it a thumbtack.

Why this belongs in the fabric

Lesson 29 argued for pushing work into the fabric when the input rate is huge and the output rate is tiny. Detection is the textbook case: 61.44 million samples per second go in, and a handful of "packet starts here" events come out. Better still, the coefficients never change, so the multipliers can be specialised:

So choosing a ±1 preamble is not a theoretical nicety. It is the difference between a correlator that fits in this XC7Z020 and one that does not.

Wi-Fi, LTE, 5G, DVB-T and DAB all use it, so it is worth understanding properly rather than as a black box. It is also the one waveform this board measurably struggles with — and the reason why is the most useful thing in this lesson.

The problem it solves

A signal arriving by two paths — direct, and bounced off a wall — arrives twice, slightly apart. That is multipath, and the delay between the first and last meaningful echo is the delay spread. Indoors it is tens to hundreds of nanoseconds; outdoors it can be microseconds.

Two echoes add, and at some frequencies they add in phase while at others they cancel. The channel is no longer a flat attenuation — it is a comb, with notches. Engineers call this a frequency-selective channel.

A single-carrier receiver fixes this with an equaliser long enough to span the delay spread. At 20 Msym/s and 1 µs of spread that is a 20-tap adaptive filter that must be continuously retrained, and the cost grows with the square of the bandwidth. It works, and it is horrible.

The FFT is the modulator

Here is the part that feels like a trick. You do not build 64 oscillators. You write your 64 symbols into the 64 bins of a frequency-domain array and take an inverse FFT. What comes out is the time-domain waveform with all 64 carriers already on it, correctly spaced and correctly summed. The receiver takes a forward FFT and reads the symbols straight out of the bins.

Lesson 24's transform, run backwards, is the transmitter. This is why OFDM became practical exactly when the FFT became cheap, and why it is a good fit for an FPGA.

X      = np.zeros(64, dtype=complex)
X[idx] = qpsk_symbols          # 52 used bins; DC and the edges left empty
x      = np.fft.ifft(X) * np.sqrt(64)
out    = np.r_[x[-16:], x]     # cyclic prefix: the last 16 copied to the front

Four lines, and the parameters are 802.11a's: a 64-point FFT, 52 subcarriers carrying data, a 16-sample cyclic prefix. The unused bins are not waste — the edge ones are a guard band so the signal does not splatter, and the DC bin is left empty because a direct-conversion receiver like this one has its own LO leakage sitting exactly there (lesson 11).

Orthogonality, and why the spacing is not negotiable

The subcarriers overlap. They do not interfere anyway, because each one fits a whole number of cycles into the symbol period, so when the receiver's FFT sums over that period every other subcarrier integrates to exactly zero. That is orthogonality, and it forces the spacing: Δf = 1 / T_symbol.

It is lesson 24's leakage argument in reverse. Leakage happens when a signal does not fit a whole number of cycles into the FFT window. OFDM arranges for every signal to fit exactly, and gets zero leakage as a result. Break the arrangement — a timing error, a frequency offset, a sampling-clock mismatch — and the subcarriers leak into each other. That failure has its own name, ICI (inter-carrier interference), and OFDM is notoriously more sensitive to frequency offset than single-carrier ever was.

The cyclic prefix: the bit that looks like waste

Copy the last 16 samples of the symbol to the front and send 80 samples instead of 64. You have just thrown away 20 % of your capacity. It buys two things, and both are essential:

1. Echoes land in the guard, not in the next symbol. As long as the delay spread is shorter than the prefix, the smeared tail of symbol n falls inside the prefix of symbol n+1, which the receiver discards. ISI between symbols disappears.
2. The channel becomes a multiply. Because the prefix makes the symbol look periodic, the channel's linear convolution behaves like a circular convolution over the FFT window — and a circular convolution in time is a plain multiplication in frequency. That is the theorem that makes the one-tap equaliser correct rather than approximate.

So the prefix length is a direct statement about the environment you expect: CP duration > delay spread, and anything longer is capacity you are giving away.

Equalisation, in the only place it is easy

Scatter a few pilot subcarriers of known value through the grid, or send one known symbol at the start of the packet. The receiver divides what it got by what it knows was sent, and that quotient is the channel at that subcarrier: H = Y / X. Interpolate across the pilots for the rest, then recover every data subcarrier with X̂ = Y / H.

One complex division per subcarrier per symbol. That is the whole equaliser — the thing that costs an adaptive filter and a training sequence in a single-carrier receiver. Lesson 34 is about what that single-carrier receiver has to do instead, and it is a great deal more work.

Measured on this board, and the honest explanation

At 61.44 MSPS over the 20 dB cable loopback, the seven test waveforms in docs/modulation-and-throughput.md give QPSK 2.17 % EVM, 16-QAM 2.24 % — and OFDM between 13 % and 51 %, run to run. That looks like a broken implementation. It is not, and the measurement that proves it is worth copying.

It gets monotonically worse as the signal weakens. That is the signature of a noise-limited link. Had it been clipping, backing off would have improved it. So the cause is not the transmitter compressing; it is that OFDM simply delivers less average power.

If you wanted to build it in the fabric

Xilinx ships an FFT core; a 64-point pipelined-streaming complex FFT runs comfortably at 61.44 MSPS and costs a handful of DSP48s and one BRAM. The transmit chain is: symbol mapper → write bins → IFFT → prepend prefix → the packer of lesson 15. The receive chain is that reversed, plus the synchroniser.

And that synchroniser is where the work actually is. The standard trick is Schmidl & Cox: send a symbol whose two halves are identical, and have the receiver correlate the incoming stream against a delayed copy of itself. The correlation peaks when the two halves line up, giving both the symbol boundary and — from the phase of the correlation — the frequency offset. It needs no template at all, which makes it exactly lesson 32's machinery pointed at the signal's own structure.

OFDM sidestepped the problem by making every subcarrier narrow enough that the channel is one number. A single-carrier receiver cannot do that, and has to undo the channel directly. This is the filter that does it — and, unusually, it designs itself.

What a channel does to your signal

Multipath (lesson 33) means the receiver gets several delayed copies added together. Written as samples, that is a convolution — the same operation as the FIR filter of lesson 26, except that nobody chose the coefficients:

y[n] = x[n]*h[0] + x[n-1]*h[1] + x[n-2]*h[2] + ... + noise
       |                |
       what you sent    the echo, half as strong, one sample late

The channel is an unwanted FIR filter sitting in your signal path. So the fix is another FIR filter that undoes it. The whole subject is that sentence plus the three complications that follow from it.

Complication one: you cannot simply invert it

The obvious equaliser is 1/H — divide by the channel and everything cancels. It is called the zero-forcing equaliser, and it works beautifully on paper.

The trouble is the notches. Where two echoes cancel, H is nearly zero, and 1/H is enormous. Your equaliser faithfully removes the ISI there and multiplies the noise by a hundred while doing it. Zero-forcing has zero residual ISI and can have appalling signal-to-noise.

The standard answer is MMSE — minimum mean-square error — which minimises total error instead, and so deliberately leaves a little ISI in the deep notches rather than amplifying the noise there. Every practical equaliser is an MMSE equaliser.

Complication two: you do not know the channel, and it changes

So the filter has to find its own coefficients while running. The workhorse is LMS — least mean squares — and it is three lines:

y = dot(w, x)          # filter: w is the taps, x the last N samples
e = d - y              # error: d is what the symbol should have been
w = w + mu * e * conj(x)   # nudge every tap toward reducing that error

Each tap is pushed in whichever direction would have reduced this sample's error, by an amount proportional to the error. Run it for a few hundred symbols and the taps settle into the MMSE solution on their own. Nobody solved anything; the filter descended a hill.

Complication three: where does d come from?

The error needs to know what the symbol should have been. Three answers, used in this order:

Where it goes on this board

This is the architecture point, and it is the same one lesson 29 made. An adaptive equaliser costs two complex multiply-accumulate chains per tap — one to filter the samples, one to update the taps — so a modest 11-tap complex equaliser is 88 real multiplies per input sample. Where you put it decides what that costs:

Both fit. But one of them spends a third of the device's arithmetic on a filter that did not need to run that fast, and leaves nothing for the rest of your design. Equalisation belongs after the decimation and the timing recovery, at one or two samples per symbol — at which point it is two DSP slices, or a comfortable software job on the ARM cores. Put the wideband work in the fabric and the clever, low-rate, iterative work behind it.

Lesson 33 said coding is worth 4 to 6 dB and lesson 41 spends them. This is where they come from, why they are real, and what they cost — because a decibel bought with arithmetic is a decibel you did not have to buy with a bigger amplifier.

The idea, and the exchange rate

Send more bits than the message needs, arranged so that the extra ones let the receiver work out which of the received bits are wrong and repair them. The ratio is the code rate R = k/n: rate 1/2 means every 1 message bit goes out as 2 transmitted bits.

What you get back is coding gain — the reduction in signal-to-noise needed for the same error rate. It is measured in decibels and it is entirely real: a rate-1/2, constraint-length-7 convolutional code with soft decisions buys about 5 dB. Against lesson 41's budget that is the difference between a link that works and one that does not, and it costs a few thousand LUTs rather than a bigger amplifier and a licence.

Soft decisions, and the free 2 dB most people throw away

Your demodulator produces a point on the constellation. Rounding it to the nearest symbol and handing the decoder a bit is a hard decision. Handing it the distance as well — "this is probably a 1, but only just" — is a soft decision, usually expressed as a log-likelihood ratio (LLR).

Soft decisions are worth about 2 dB over hard ones, for free, because the decoder can weigh a confident bit against an uncertain one instead of treating them alike. Two design consequences, both easy to get wrong:

• Your demodulator must output LLRs, not bits. A slicer in the middle of the chain throws the information away permanently.
• LLRs need the noise level to be scaled correctly, so a receiver that measures its own SNR (lesson 40) decodes better than one that does not.

The families, and which one to reach for

For a first link on this board the honest answer is convolutional, rate 1/2, K=7, soft Viterbi. It is the best gain-per-unit-effort in the table, it is what the textbooks work through, and Xilinx ships the decoder as IP.

In the fabric

The encoder is trivial — a shift register and two XOR trees, a handful of LUTs, no DSP slices at all. The decoder is where the work is.

And as always (lesson 29), put it at symbol rate behind the decimation, not at 61.44 MSPS in front of it.

Lesson 35 said these codes get within about a decibel of Shannon and left it there. The mechanism is a single idea — nodes exchanging opinions until they agree — and it is worth seeing, because the three ways people break it are all consequences of one rule.

The currency: log-likelihood ratios

Everything in this lesson trades in one number per bit:

L(x) = ln[ P(x = 0 | y) / P(x = 1 | y) ]

  sign      the decision        positive means 0
  magnitude the confidence      0 means "no idea"

For BPSK in Gaussian noise it is almost embarrassingly simple — L = 2y/σ², the received sample divided by the noise power. For Gray-mapped QPSK, I and Q are two independent BPSK channels and you do it twice, with no cross terms.

The reason LLRs and not probabilities: independent evidence multiplies as probability but adds as a log-ratio. Combining two opinions becomes an adder.

LDPC: opinions on a graph

Draw the parity-check matrix as a bipartite graph — a Tanner graph. One variable node per coded bit; one check node per parity equation; an edge wherever the matrix has a 1. Every edge carries a number in both directions, and the two node types have opposite jobs:

Run both, back and forth, and stop when the parity check passes — H·x̂ᵀ = 0 — or when you run out of patience.

Turbo: two decoders, one interleaver

A turbo encoder is two small convolutional encoders seeing the same data, the second through an interleaver. Each has a soft-in soft-out decoder, and they take turns — but what they hand over is not their answer. It is the part of their answer the other decoder did not already know:

L_in  = L_A + L_CH                 // what I was told, plus the channel
L_E   = L_out - L_in               // what I worked out that nobody told me
L(u)  = L_CH + L_E1 + deinterleave(L_E2)   // the final decision

L_E is interleaved and becomes the other decoder's prior. The interleaver is what makes this work: it guarantees the second decoder sees the errors in a completely different arrangement, so the information really is new. Same rule as LDPC, different clothes.

Polar: not iterative at all

Polar codes decode in one sweep. Bits are decided in a fixed order, and each decision is fed forward so that its effect is removed before the next — successive cancellation. The recursion needs exactly two operators, and if you have been paying attention they are familiar:

f(a, b) ~= sign(a) * sign(b) * min(|a|, |b|)    // a min-sum check node
g(a, b, s) = (-1)^s * a + b                     // a variable-node sum, sign-flipped
                                                // by the bits already decided

The weakness is obvious from the description: one bad early decision poisons everything after it. The fix is successive cancellation list decoding — carry L candidate paths and let a CRC at the end pick the survivor. That is why 5G's polar codes carry a CRC that is part of the code rather than a check bolted on top.

Sum-product, min-sum, and the one that matters in hardware

Min-sum replaces the exact expression with a bound that is always at least as large, so it systematically overstates how sure the check node is — which is exactly why scaling by α < 1 or subtracting an offset repairs it. Tuned well the gap nearly closes: one published 5G decoder in 28 nm reports an adjusted min-sum within 0.1 dB of floating-point sum-product.

You will see "min-sum costs 0.2 to 0.5 dB" repeated everywhere. That number is folklore as usually cited — the mechanism is solid, the figure is worth measuring for your own code rather than quoting.

How many iterations, and what stops you going further

Real numbers, from real systems: MathWorks' 5G NR LDPC hardware decoder defaults to 8 iterations with a maximum of 63 — 63 because the field is six bits wide — and stops early when the syndrome clears. Published high-throughput LDPC chips use as few as 3 to 5. DVB-S2X's performance tables assume 50, as do CCSDS's deep-space codes, which land about a decibel from Shannon.

More iterations stop helping at the error floor — the point where the curve flattens instead of continuing to fall. Three different causes, and conflating them is how people waste weeks:

What the standards actually use

What this costs on this board

Now the part that decides whether any of it is yours to build. The XC7Z020 has 53 200 LUTs, 220 DSP slices and 140 block RAMs:

Read that table carefully, because the obvious conclusion is slightly wrong. An LDPC decoder's area scales with its throughput, not with the block length — both LDPC rows are high-speed designs processing many graph edges per clock. A serial or lightly-layered decoder for the same N=1944 code running at a few megabits per second is a small fraction of those numbers and fits perfectly well. What does not fit on this part is a fast LDPC decoder.

And the hardware shortcut does not apply here: AMD's SD-FEC block, which decodes LDPC at gigabits per second, is a hardened block on selected Zynq UltraScale+ RFSoC devices — not every RFSoC part carries one, and no 7-series part does. Their soft-logic LDPC core does not list Zynq-7000 as a supported family either.

So the honest architecture advice for this board is the one lesson 35 gave: a soft-decision Viterbi decoder for a K=7 convolutional code is comfortable, useful, and worth about 5 dB. Reach for LDPC when you need the last decibel and can accept a slow decoder, or when you have moved to a bigger part. (802.11n keeps the convolutional code mandatory and LDPC optional — though that is as much about interoperating with 802.11a/g as about decoder area.)

From a link to a network

Every lesson so far has ended at "and now you have symbols". Nothing so far has said who the symbols are for, where they start, whether they arrived intact, or what to do when they did not. That is this lesson, and on this board one number in it decides your whole architecture.

The layers, named once

The boundary that matters here is the one between MAC and PHY, because it is also the boundary between "can live on the host" and "cannot".

What a frame is made of

[ preamble ][ sync word ][ header ][ payload ................ ][ CRC ]
     |            |           |            |                      |
  AGC settles  "packet     length,     the actual bytes,      did any of
  timing and    starts     type,       scrambled and           this arrive
  carrier       HERE"      address     coded                   intact?
  recovery

Scrambling: the step that looks pointless and is not

Payloads contain long runs of zeros. Sent literally, a run of identical symbols means a waveform with no transitions — and lesson 31's timing recovery feeds on transitions, so it drifts and loses lock in the middle of your own data. A constant symbol also puts a spike in the spectrum where you wanted a flat one, and a DC offset where this receiver already has LO leakage (lesson 11).

The fix is a scrambler: XOR the data with a pseudo-random sequence from a shift register (the same object as lesson 32's m-sequence) before transmitting, and XOR with the same sequence at the far end. Nothing is hidden — the sequence is public — but the transmitted stream now looks random whatever the payload was. Timing recovery gets its transitions, and the spectrum stays flat.

Whose turn is it? Media access on a shared medium

Retries, and what makes them possible

Lesson 37 ended with a frame that arrived intact. A network is what happens when there are more than two nodes, more than one hop, and something above you that expects an ordered byte stream. Almost all of it you can inherit rather than write — but only if you understand what you are handing it.

The layer model, honestly

The seven-layer OSI model is real (ITU-T X.200) and almost nobody implements it. What is actually deployed is the four layers of RFC 1122: application, transport, internet, link. Session and presentation have no deployed equivalent.

And even those four leak. RFC 3439's section titled "Layering Considered Harmful" puts it plainly: "multiplexing and segmentation both hide vital information that lower layers may need to optimize their performance." Keep the layers as a way to divide the work, not as a law of nature — this lesson is mostly about what happens when a layer's assumptions are wrong.

Addressing: who, and where

A MAC address says who. It is flat, permanent and unaggregatable — 48 bits, of which the top 24 are the manufacturer's OUI. A network address says where, and that is the whole point: RFC 4632 explains that prefixes are assigned "to roughly follow the underlying Internet topology so that aggregation can be used", which is what stops the global routing table from being one entry per device.

For a small radio network of your own, the cheapest credible design is the one 802.15.4 chose: a 16-bit short address plus a 16-bit network identifier. Two bytes each, 65 534 usable nodes once you reserve 0xFFFF for broadcast and 0xFFFE for "not assigned yet". Do not invent a 64-bit address you will never need; every byte of header is airtime, and airtime is the budget you are about to discover you do not have.

Frame length: the trap that looks like a broken radio

A frame survives only if every bit in it survives. RFC 3819 gives the arithmetic directly:

p = 1 - (1 - BER)^(FRAME_SIZE * 8)

and for BER * FRAME_SIZE * 8 << 1,   p ~= BER * FRAME_SIZE * 8

Which produces this — and the right-hand column is why a link that "works" can be useless:

Same radio, same noise, same everything — and a 1500-byte frame loses eleven percent where a 127-byte frame loses one. Frame length is a link-budget decision, and it is the one nobody puts in the link budget.

One caveat the same RFC insists on: this assumes bit errors are statistically independent, and on a fading radio link they are not — errors arrive in bursts. So every figure in that table is an upper bound on the loss, not a prediction of it. A bursty channel puts several errors inside one frame and leaves its neighbours clean, which is better than the table says — and is also exactly why interleaving (lesson 35) exists.

Pushing the other way: RFC 3819 points out that a 1500-byte frame on a 19.2 kb/s link is 625 ms of serialisation delay, which is hopeless for anything interactive. Short frames cost header overhead; long frames cost loss and latency. That is the trade, and it has no universal answer.

Routing, when the nodes move

For a small mesh of these boards, start with Babel. RPL is Standards Track too, and OLSRv2 as well — but RPL is built for collection toward a root, which a peer-to-peer mesh is not. Babel keeps little state, it is already in Linux distributions, and it uses ETX — a metric that counts delivery attempts rather than hop count, which is the difference between routing over a good three-hop path and routing over one terrible one-hop path. Reach for RPL only if your topology really is one collector, and for OLSR or AODV only to interoperate with something that already speaks them.

TCP over a radio link, and why it disappoints

TCP's congestion control has essentially one input: loss. RFC 5681 says the algorithms work "in terms of using loss as the signal of congestion" — and a bit error on a radio link is indistinguishable from a congested queue. (Explicit congestion notification, RFC 3168, adds a second input, but only if every hop supports it.) So every corrupted frame makes TCP slow down, which is precisely the wrong response.

How much it costs is quantifiable. The Mathis formula — restated in RFC 3819 — gives steady-state throughput under random loss:

BW = C * MSS / (RTT * sqrt(p))

Note the square root: a hundredfold worse loss costs you only tenfold in throughput — but it starts from a low number. And note RTT in the denominator, which is where this board gets interesting.

Three stacks worth stealing from

Zigbee is the fourth one people cite, and one precision is worth keeping: its network layer does on-demand route request and reply discovery which is AODV-style, but the specification never uses the word AODV. Say what it does, not what it resembles.

Everything built so far transmits in clear, accepts any frame that passes a CRC, and cannot tell your transmitter from anyone else's. That is not an oversight in the course — it is the normal state of a physical layer, and this lesson is about what has to be added on top and, just as usefully, what does not count.

Four properties, and what each one's absence looks like

Those are the four you can buy with cryptography. There is a fifth — availability — that you largely cannot, and it is the one a radio is most exposed to. It gets its own section below.

AEAD: one key, one call, both jobs

The modern answer is not "encrypt, then also MAC". It is a single mode that does both, called AEAD — authenticated encryption with associated data. You hand it a key, a nonce, the payload to encrypt, and any header fields that must be authenticated but not hidden; it returns ciphertext plus an authentication tag.

Real parameters worth copying: 802.11's CCMP-128 uses AES-128 with an 8-byte authentication tag and a 48-bit packet number that is both the replay counter and the varying part of the nonce — the nonce itself also folds in the transmitter address. Header fields are authenticated as associated data: 22 or 28 bytes, and 24 or 30 for the QoS data frames every 802.11n-and-later device actually sends. 802.15.4 offers 4-, 8- or 16-byte tags. The 2003 edition made only AES-CCM with the 8-byte tag mandatory; from 2006 the named suites were replaced by CCM* with selectable security levels, so check which edition your stack implements before assuming what it guarantees.

Replay protection is a separate thing you must add

This surprises people, so it is worth being blunt: AEAD does not give you replay protection. NIST says so directly — GCM "does not inherently prevent an adversary from intercepting the output of an invocation of authenticated encryption and 'replaying' it". A replayed frame is a genuine frame with a genuine tag. Nothing about it is forged.

The fix is a counter, carried in the frame and authenticated:

Keys: the part that is actually hard

Two details from LoRaWAN that generalise. First, its activation by personalisation mode burns session keys in directly and skips the join entirely — and the LoRa Alliance's own guidance is that over-the-air activation "should be preferred… for end-devices in need of higher levels of security". Second, the join nonce started as a random number and became a counter, persistent across power cycles, for a reason worth reading twice: unless the network remembers every nonce the device has ever used, random nonces let join requests be replayed — and remembering all of them is not practical.

Jamming: the attack cryptography cannot answer

Encryption protects the content. Nothing protects the channel from someone transmitting into it. The standard taxonomy:

The classical defences are all forms of spreading, and each has a price:

Physical-layer security: what it claims, and whether to use it

There is a real academic field arguing that the channel itself can provide secrecy — Wyner's wiretap model gives a secrecy capacity when the eavesdropper's channel is worse than the legitimate one, and channel reciprocity lets two ends derive a shared key from fading they both observe and a third party does not, because fading decorrelates over about half a wavelength.

It is genuinely interesting and it is not a substitute for cryptography. The honest summary from inside the field and from measurement:

• Key generation needs the channel to change. In published indoor measurements with nothing moving, received signal strength varies by only a couple of decibels, and generating a 256-bit key takes minutes — the entropy is simply not there in a static room.
• Published active attacks on real hardware, assuming no technological advantage for the attacker, have recovered a large fraction of the key bits — enough that the authors questioned whether the schemes are worth having.
• The field's own critique notes the adversary model is the central problem — a collaborative adversary with a linear factor more observations can drive the secrecy rate to zero, and antenna gain is cheap.
• No standards body endorses it. 3GPP's 5G security specification mandates AES; NIST requires keys to come from an approved random bit generator; there is no RFC.

Treat it as a possible extra layer or a key-refresh aid, never as the thing standing between your data and an attacker.

Measuring, and getting on the air

Six numbers describe an RF system. Knowing which one answers your question — and how to get it honestly from this board — is what separates a measurement from a screenshot.

Which one answers which question

Measured on this board

Through a cable from TX2 to RX2 with a 20 dB attenuator, at 900 MHz:

Everything so far has run down a cable. The moment an antenna is involved there is one calculation that decides whether the link exists at all — and because every term is in decibels, it is a single column of addition.

The whole calculation

  received power   = TX power + TX antenna gain - cable loss
                     - path loss + RX antenna gain      [dBm]

  noise floor      = -174 + 10*log10(bandwidth_Hz) + noise figure   [dBm]

  SNR              = received power - noise floor       [dB]
  margin           = SNR - SNR the demodulator needs    [dB]

If the margin is positive the link works in the conditions you assumed. How positive it needs to be is the whole art, and we will get to it.

Path loss, and what it really is

In free space, a transmitted wave spreads over an ever-larger sphere, and a receiving antenna catches an ever-smaller share. Nothing is absorbed; the energy is simply somewhere else. That is free-space path loss:

FSPL = 32.44 + 20*log10(distance_km) + 20*log10(frequency_MHz)

Two consequences fall straight out of the two 20s. Double the distance and you lose 6 dB. Double the frequency and you lose another 6 dB. The second one surprises people — the air is not more absorbent at 2.4 GHz than at 900 MHz. A fixed-gain antenna is simply physically smaller at the higher frequency, so it catches less of the sphere.

How much SNR does the demodulator actually need?

Roughly, for an uncoded link at a bit error rate around 10⁻⁵, measured across the occupied bandwidth:

Read down that table and each extra bit per symbol costs about 3 dB, not 6. The 6 dB figure belongs to lesson 9's converter formula, and it is 6 dB per bit per dimension — a real-valued ADC has one dimension, while QAM spends each new bit across two, I and Q. So the constellation gets denser half as fast as your instinct says. Forward error correction (lesson 35) hands 4–6 dB back, which is why every real system uses it.

A worked example on this hardware

900 MHz, 100 m of clear line of sight, a 2 dBi whip at each end, 5 MHz of bandwidth, QPSK:

Forty decibels sounds like the question is settled. Put the same link inside a building with a path exponent of 3.5 and you lose 30 dB of it; add a body standing in the way and another 10; and the margin is gone. The budget tells you whether a link is plausible, not whether it works.

Lesson 41 stopped at "transmit power" and "antenna gain" as if they were settings. They are hardware, and on this board some of that hardware is missing on purpose. This is the part of the signal chain that no amount of Verilog can fix.

Fifty ohms, and why anything has an impedance at all

At low frequency a wire is a wire. Once the wavelength is comparable to the cable, a signal travelling down it meets the far end and asks what impedance it sees. If that does not match the cable's own characteristic impedance, part of the wave reflects and comes back.

Everything in radio is standardised on 50 Ω so that this does not happen: the amplifier, the connector, the cable, the antenna all present 50 Ω and the wave goes out and never comes back. Fifty is a compromise — around 77 Ω gives the lowest loss in coax and around 30 Ω the highest power handling — and the industry split the difference sixty years ago.

The antenna, in the three facts that matter

The front end, and what this board has

From the schematic's parts list in docs/hardware.md, each RF port's path is short:

receive    RX1A/RX2A  -->  balun (T1-T4)  -->  AD9361 differential RF input

transmit   AD9361  -->  balun  -->  PGA-102+ (U12/U13, ~15.7 dB)  -->  TX1A/TX2A

Note where the balun sits on transmit: before the amplifier, not after. The AD9361 drives it differentially, the balun makes that single-ended, and only then does the PGA-102+ amplify. So the balun handles milliwatts, not the amplifier's output — and the TX1A_I / TX1A_O nets either side of U12 in the schematic are exactly that boundary.

Baluns, a power amplifier per transmit channel, and the AD9361. No external band filter in either direction. The chip's own front end is deliberately wideband — it has to cover 70 MHz to 6 GHz — so what protects a narrowband receiver elsewhere simply is not here. Two consequences follow, and both are practical rather than theoretical.

Where the noise figure is decided

Cascade several stages and the noise figure of the whole chain is dominated by the first one. Friis's formula says why:

F_total = F1 + (F2 - 1)/G1 + (F3 - 1)/(G1*G2) + ...
                     |
              divided by the first stage's gain

Every later stage's noise is divided by everything in front of it, so a low-noise amplifier with 15 dB of gain at the very front makes the rest of the chain nearly irrelevant. It also explains the rule that looks like folklore: put the LNA at the antenna, not at the radio. Ten metres of coax at 1 dB of loss in front of the LNA costs you a whole decibel of noise figure; the same coax behind it costs almost nothing.

Lesson 42 gave you the concepts — 50 ohms, VSWR, mismatch loss, noise figure. This is the practice: the instrument you measure with, the chart you design on, the network you design, and the copper you build it on. It is also where this board's one real hardware gap gets proved rather than asserted.

S-parameters, and why RF uses them

At low frequency you describe a two-port with voltages and currents. At RF you cannot, and Hewlett Packard's 1972 application note still gives the three reasons better than anyone since:

• "Equipment is not readily available to measure total voltage and total current at the ports."
• "Short and open circuits are difficult to achieve over a broadband of frequencies."
• "Active devices… very often will not be short or open circuit stable."

So you measure waves instead. Call a the wave going into a port and b the wave coming out; the S-matrix relates them:

b1 = S11*a1 + S12*a2          S11 = b1/a1 with a2 = 0   input reflection
b2 = S21*a1 + S22*a2          S21 = b2/a1 with a2 = 0   forward gain / loss
                              S12 = reverse transmission (isolation)
                              S22 = output reflection

Gamma = (Za - Z0)/(Za + Z0)   VSWR = (1+|Gamma|)/(1-|Gamma|)
Return loss (dB) = -20*log10(|Gamma|)

The Smith chart, explained rather than memorised

It looks mystical and it is not. The Smith chart is the complex reflection-coefficient plane inside the unit circle, with an impedance grid drawn over it. That is all. Every point is a Γ; the curved lines just tell you which impedance produced it.

The grid lines are circles because the transformation z = (1+Γ)/(1−Γ) maps straight lines of constant resistance and constant reactance into circles. Constant-r circles are centred on the horizontal axis at r/(1+r) with radius 1/(1+r); the constant-x arcs come off the right-hand point.

The L network, and the bandwidth you do not get to choose

Two components, and the design is closed-form. Let R_small and R_large be the smaller and larger of source and load:

Q      = sqrt( R_large / R_small - 1 )

|X_series| = Q * R_small        // in series with the SMALLER resistance
|X_shunt|  = R_large / Q        // across the LARGER resistance

one of them is an inductor and the other a capacitor (opposite signs)
fractional 3 dB bandwidth = 1 / Q

Read that first line again, because it is the part people do not expect: Q is fixed by the resistance ratio alone. Once you know what you are matching to what, the bandwidth is decided. You have no free parameter. Matching 50 Ω to 10 Ω gives Q = 2 and about 50 % bandwidth whether you like it or not.

Gamma_avg  >=  exp( -pi / (Q_load * FBW) )
                            ^^^^^^
                            the Q of the LOAD, not of your matching network

Copper: when a trace becomes a transmission line

A 50 Ω microstrip is set by the ratio of trace width to the height above the ground plane, plus the dielectric constant. For FR-4 that ratio is about W/H = 1.9 to 2.0, which gives:

That table is the entire argument for putting ground on layer 2 rather than layer 4. As a real reference point, TI's own Wi-Fi module layout guide specifies 255 µm from signal to ground and a coplanar-waveguide-with-ground trace 0.457 mm wide with a 0.381 mm gap — and says explicitly that it is CPWG and not microstrip, chosen for "the best isolation between input and output due to reduced field fringing".

Two layout rules worth carrying. Stitch ground vias along RF traces — without them the two ground layers support a parallel-plate mode and energy travels where you did not route it; the only vendor-citable spacing rule is a maximum of a quarter wavelength, which at 12 GHz in FR-4 is 3 mm. And treat a trace as a transmission line based on rise time, not clock rate — Howard Johnson simulates anything longer than about one sixth of the rising edge. Published thresholds range from a half to a twentieth of the edge length, so treat it as a range and err short.

The VNA, and the mistake everyone makes with it

A vector network analyser measures magnitude and phase, which is what makes the Smith chart usable. Calibration is the whole game: "systematic errors are caused by imperfections in the test equipment and test setup… if these errors do not vary over time, they can be characterized through calibration and mathematically removed." A full two-port calibration solves for twelve error terms; a one-port reflection calibration removes three — directivity, source match and reflection tracking.

What a good antenna measurement looks like

The industry conventions, from a vendor note rather than folklore: VSWR 1.5 (return loss 14 dB) is a good match; VSWR 2.0 (return loss 9.5 dB) is the point at which the matching network should be reviewed, and is also the conventional threshold for quoting an antenna's bandwidth. At 2:1 the antenna radiates 88.9 % of the transmitter's power — which is to say the last decibel is rarely where the problem is.

Filters, and the gap in this board

Lesson 42 said this board has no external band filter. Here is the proof rather than the assertion, and it matters more than it sounds.

The AD9361's receive filtering is baseband only — two programmable analogue low-pass filters after the mixer, then the converter and the digital decimators. UG-570 describes no RF preselector anywhere, and the transimpedance amplifier's single pole sits at 2.5 times the baseband bandwidth. The overload detector that protects the front end sits before all of it. ADI even gives you the diagnostic:

So if you put this board on an antenna, a front-end filter is the first accessory. The options, with real datasheet numbers:

That last row is the lesson inside the lesson. A filter's catalogue rejection figure is for the frequencies far from the band. The thing actually desensitising you is usually the strong signal just outside, and that is where every filter is weakest.

Simulating it before you build it

You do not need a commercial licence to start. openEMS is a GPL FDTD solver with Python and Octave interfaces; scikit-rf is a BSD Python library that reads and writes Touchstone files and has calibration and de-embedding built in — including the TRL and fixture-removal maths this lesson keeps recommending; Qucs-S gives you a GUI over Ngspice with microstrip models and S-parameter analysis.

A capture is a pile of numbers with no units, no frequency and no date. Six months later that is not a measurement, it is a file you are afraid to delete. This lesson is about the five minutes of work that prevents it.

What is actually in the file

iio_readdev writes raw samples to stdout with no header of any kind. The layout is exactly the packer's output from lesson 15, little-endian 16-bit signed integers, interleaved:

I0 Q0  I1 Q1  I2 Q2  ...        # int16 LE, I then Q

I0 Q0 I1 Q1   I0 Q0 I1 Q1   ...
|-- instant 0 --|-- instant 1 --|      # ch0 I, ch0 Q, ch1 I, ch1 Q

There is no marker between channels and no marker between samples. If you enable channels in a different order, or forget that you enabled two, the file still opens and the numbers still look plausible — they are simply somebody else's signal. Nothing in the file will tell you.

How big is it going to be?

Four bytes per sample per channel, and no compression anywhere. At full rate that is a firehose.

What the file does not say, and needs to

Open a bare .bin a year later and every one of these is unrecoverable from the data itself:

SigMF: a sidecar file, and the end of the problem

SigMF — the Signal Metadata Format — is a convention, not a library. You rename the capture x.sigmf-data and write a small JSON file called x.sigmf-meta next to it. Nothing about the samples changes, so every tool that read the bare file still reads it, and now the file explains itself.

{
  "global": {
    "core:datatype":    "ci16_le",        # complex, int16, little-endian
    "core:sample_rate": 7680000,
    "core:version":     "1.0.0",
    "core:hw":          "Fishball7020 / PlutoSky, AD9361, RX2A",
    "core:description": "10 MHz DDS tone, fabric decimator engaged, 20 dB pad"
  },
  "captures": [
    { "core:sample_start": 0,
      "core:frequency":    900000000,
      "core:datetime":     "2026-09-23T04:20:00Z" }
  ],
  "annotations": [
    { "core:sample_start": 0, "core:sample_count": 262144,
      "core:freq_lower_edge": 2200000, "core:freq_upper_edge": 2450000,
      "core:label": "alias of the 10 MHz tone" }
  ]
}

import json, os, datetime

def sigmf(binpath, fs, lo, desc, hw="Fishball7020 / AD9361"):
    base = os.path.splitext(binpath)[0]
    os.rename(binpath, base + ".sigmf-data")
    meta = {
      "global": {"core:datatype": "ci16_le", "core:sample_rate": fs,
                 "core:version": "1.0.0", "core:hw": hw,
                 "core:description": desc},
      "captures": [{"core:sample_start": 0, "core:frequency": lo,
                     "core:datetime": datetime.datetime.now(
                         datetime.timezone.utc).isoformat()}],
      "annotations": []}
    with open(base + ".sigmf-meta", "w") as f:
        json.dump(meta, f, indent=2)

Fourteen lines, once, and no capture you take afterwards is ever ambiguous.

MATLAB will talk to this board, show you one of its two receivers, offer to destroy its firmware, and hand you absolute levels that are 24 dB wrong. All four are fixable and none announces itself. The last part of this lesson is the useful part: three checks that looked like verification and were not.

MATLAB sees one receiver. This board has two.

Ask the stock support package for the second receiver and it refuses:

ChannelMapping must be equal to 1

That is not a bug to work around; the package is written throughout for a 1R1T radio — one receiver, one transmitter. This board is 2R2T, and the second receiver is the interesting one, because both sit behind one local oscillator and one sample clock (lesson 45). So the repository ships its own blocks, which reach the hardware through iio_readdev and iio_writedev and have no opinion about how many channels your radio has:

rx = fishball.RxSource('ChannelMapping','RX1+RX2', ...
                       'CenterFrequency',868e6);
[iq, status] = rx();      # iq is N-by-2; status is [rssi1 rssi2 degC gain]
release(rx)

In Simulink you drop a MATLAB System block and point it at fishball.RxSource. There is a matching fishball.TxSink for transmit.

Three ways a radio program lies to you

Each of these passed a check that looked like verification. That is what makes them worth a lesson rather than a footnote — all three were found by measuring something else.

AGC target 1         mean power 2.013   amplitude 1.419x   EVM as plotted  42.3 %
AGC target 1/sps     mean power 1.068   amplitude 1.034x   EVM as plotted   6.8 %
                                        # rescaled-first EVM read 6.3 % in BOTH cases

The common thread: every one of those was verified by reading back the thing that had just been written, rather than by measuring the thing that was supposed to change. A register read confirms a register. Only the samples confirm the radio.

open_system('examples/matlab/06-simulink/fishball_qam16.slx')

Two receivers, and the chip that feeds them

The shared local oscillator looked like a limitation in lesson 14. It is also this board's most interesting capability.

Both receivers run from one synthesiser, sample on one clock, and are captured on one strobe. They are therefore coherent: the phase relationship between them is stable and meaningful, not accidental.

That is a much stronger property than "two receivers". Two independent radios tuned to the same frequency drift against each other and give you two recordings. Two coherent receivers give you one measurement with two viewpoints, and the difference between those viewpoints carries information.

There is a working flowgraph for this in the repository: examples/03-coherent-receivers. It shows the phase on a dial whose radius is the coherence, so you can tell a real measurement from noise at a glance — and it is arranged to avoid the trap described at the end of this lesson.

What the phase difference tells you

A wave arriving at an angle reaches one antenna slightly before the other. That delay appears as a phase difference between the channels — and from it you can compute the direction the signal came from.

# rx1, rx2: simultaneous captures from the two receivers
phase_diff = np.angle(np.mean(rx2 * np.conj(rx1)))
# d = antenna spacing, lam = wavelength
angle_of_arrival = np.arcsin(phase_diff * lam / (2 * np.pi * d))

With antennas half a wavelength apart this is unambiguous across a useful arc — the basis of direction finding, and the first step toward beamforming, where you deliberately add the two channels with a phase shift to steer sensitivity.

Lesson 45 showed that this board's two receivers share a local oscillator, and used the phase between them to find a direction. That is one of three quite different things people mean by "multiple antennas", and it is worth knowing which one you are asking for.

Three things, one name

Only the third one is "MIMO" in the strict sense. All three are available on this board in some form, and they want opposite things from your antenna spacing — which is the first practical thing to understand.

Diversity, and the thing that actually rescues links

A fade is deep and local: move half a wavelength and it is gone. So two receivers, separated, rarely fade at the same instant.

That second sentence is the point. In a link-budget sense diversity buys 3 dB; in a reliability sense it can be worth 10 to 20 dB of fade margin, which is normally the most expensive part of lesson 41's budget.

Beamforming, in the only maths you need

Two elements a distance d apart, a wave arriving at angle θ from broadside. The far element is d·sin θ further away, so its signal is late by that much — which, in phase, is:

receive (direction finding)   phase difference = 2*pi * d * sin(theta) / lambda

transmit (steering a beam)    apply that same phase difference deliberately,
                              and the two waves add in phase toward theta
                              and cancel elsewhere

At d = λ/2 that simplifies to φ = π·sin θ: broadside gives 0°, endfire gives 180°, and everything in between maps one-to-one. Measure φ, take the arcsine, and you have the direction. Impose φ, and you have a beam.

Two elements give a broad beam and one unavoidable ambiguity. Signals at +30° and −30° produce opposite phase differences and are easily told apart — but a signal 30° in front of the array and one 30° behind it produce the same phase difference, because sin θ is the same for both. A linear array of two isotropic elements simply cannot distinguish them. A third element, a directional element, or moving the array resolves it. Scanning φ across all angles and plotting the output is called a beamscan; the sharper estimators (MUSIC, ESPRIT) do better by exploiting the fact that noise and signal live in different subspaces, and PySDR chapters 19 to 21 work through them properly.

Spatial multiplexing, and why it is not free here

If the channel between two transmit and two receive antennas is a 2×2 matrix H that happens to be invertible, the receiver can solve for two independent streams sent simultaneously on the same frequency. Throughput doubles with no extra bandwidth and no extra power. That is 802.11n and everything after it.

The catch is that H must be well-conditioned, which means the two paths have to be genuinely different — lots of scattering, or antennas far apart with different views. In free space with two whips side by side the two rows of H are nearly identical, the matrix is close to singular, and inverting it amplifies noise enormously. Multipath, which every other lesson has treated as the enemy, is the resource that makes spatial multiplexing work at all.

Every sample your logic has ever seen came out of this chip, already filtered, already decimated, already gain-controlled by something you did not write. Eleven lessons have quietly depended on how it behaves. Time to open it.

The receive path, stage by stage

RF in -> LNA -> mixer -> baseband filters -> ADC -> HB3 -> HB2 -> HB1 -> FIR -> LVDS/CMOS
                  |            |             |       \________________/      |
              RX_LO, shared  analogue     very fast   fixed halving stages  programmable,
              by BOTH        anti-alias   sigma-delta  bringing the rate     up to 128 taps
              receivers                                down in powers of 2

Two things in that diagram explain most of this course. The mixer uses one RX_LO for both receivers, which is why lessons 45 and 46 work and why you cannot tune the two channels separately. And the converter runs far faster than your sample rate, with a chain of halving filters behind it — which is why sampling_frequency will not accept arbitrary values.

The rate chain, and why the driver says no

Ask for 5 MSPS and the driver does not set anything to 5 MSPS. It picks a converter rate, a path through HB3/HB2/HB1, and a set of FIR coefficients whose product lands on 5 MSPS. Ask for a rate it cannot reach that way and it gives you the nearest one it can.

Gain is not in decibels, whatever the units say

The receive gain attribute reads in dB and behaves like a number of dB — its slope is within 1.7 % of 1.000 dB/dB across 56 measured slopes on this board, which is excellent. But underneath, gain is a table index: each step switches a specific combination of LNA, mixer and baseband amplifier settings, chosen by ADI per frequency band.

Two consequences. There are discontinuities — places where one step changes noise figure or linearity much more than it changes gain, because the chip switched which amplifier is doing the work. And the table differs by band, so a calibration taken at 900 MHz does not transfer to 2.4 GHz. ad9361-gain-tables.md in this repository has the measured detail; the short version is to measure gain where you intend to use it.

The calibrations, and the loops that never stop

The DC and quadrature tracking loops then keep running while you receive, continuously nudging the corrections. It is tempting to switch them off for a clean measurement; lesson 33 records what happened when that was tried on the OFDM link — it got worse. Leave them on unless you have measured that they are hurting.

iio_attr -u ip:192.168.2.1 -D ad9361-phy bist_tone "2 7680000 0 0"   # on
# ... capture ...
iio_attr -u ip:192.168.2.1 -D ad9361-phy bist_tone "0 0 0 0"         # off

How it is configured, and by whom

Not by your fabric. The AD9361's control bus is the processor's own SPI0, routed out through EMIO (lesson 23's mechanism) — not the axi_spi block that also appears in the block design, which is there for other purposes. The Linux driver owns every register, and the IIO attributes you write are the driver's interpretation of what you asked for.

That is why lesson 13's map matters: your logic sits in the datapath, downstream of a chip whose configuration is somebody else's. Nothing you put in the fabric can change the gain, the bandwidth or the LO. You have to ask.

iio_attr -u ip:192.168.2.1 -d ad9361-phy            # every device attribute
iio_attr -u ip:192.168.2.1 -c ad9361-phy voltage0   # the receive channel's
iio_attr -u ip:192.168.2.1 -c ad9361-phy temp0 input   # die temperature, millidegrees

Lesson 47 gave you the chip as a system. This is the layer underneath: the actual SPI words, the actual addresses, and the handful of places where the driver does something to your radio that no IIO attribute admits to.

One SPI transaction

The whole protocol is four macros:

#define AD_READ    (0 << 15)
#define AD_WRITE   (1 << 15)
#define AD_CNT(x)  ((((x) - 1) & 0x7) << 12)
#define AD_ADDR(x) ((x) & 0x3FF)

A 16-bit header, MSB first, then the data bytes. So a single-register access is 24 bits on the wire:

 15   14 13 12   11 10   9 . . . . . . . . 0
  W   count-1    unused        address

  bit 15   1 = write, 0 = read
  14:12    bytes to transfer, minus one (1 to 8)
   9:0     10-bit address, 0x000 to 0x3FF

The map, in blocks

525 register definitions across the full 10-bit space. The grouping below is the header file's own ordering rather than a quotation from the manual, but it is enough to know roughly where you are:

The first register the driver ever reads is 0x037, the product ID. Probe refuses the part unless (value & 0xF8) == 0x08; the low three bits are the silicon revision, so a Rev 2 part reads 0x0A. If that read fails, nothing else in this lesson matters — you have a wiring problem, not a radio problem.

The enable state machine, concretely

Lesson 47 mentioned the ENSM. Here are the actual numbers. Read 0x017; bits 3:0 are the state:

Two ways to drive it. Either write 0x014 — FORCE_TX_ON (1<<5), FORCE_RX_ON (1<<6), FORCE_ALERT_STATE (1<<2) — or set ENABLE_ENSM_PIN_CTRL (1<<4) and drive the chip's ENABLE and TXNRX pins from the fabric instead. Pin control is how you get deterministic, sample-accurate switching; SPI control is how you get convenience.

Gain tables, as bytes

A gain table row is three bytes, written through a little access port rather than being memory-mapped. ADI's own comments name them:

Set the row index in 0x130, write the three bytes, pulse the write bit in 0x137. The driver holds 77 rows in full-table mode and 41 in split-table mode — pick between them with AGC_USE_FULL_GAIN_TABLE in 0x0FB — and it keeps three tables per mode, for 0–1300 MHz, 1300–4000 MHz and 4000–6000 MHz.

You can also supply a table as firmware. firmware/ad9361_std_gaintable in the kernel tree is a plain text file the driver parses:

<list>
<gaintable AD9361 type=FULL dest=3 start=0 end=1300000000>
-1, 0x00, 0x00, 0x20
 0, 0x00, 0x01, 0x00

The leading number is the absolute gain in dB; the three that follow are the row. That first column is what makes the trap below possible.

The 128-tap FIR, and its rules

Coefficients are signed 16-bit, written low byte then high byte through 0x061/0x062 on transmit and 0x0F1/0x0F2 on receive. The constraints are all in ad9361_load_fir_filter_coef, and they are not negotiable:

• Tap count must be a multiple of 16, and at most 128. The driver rejects anything else outright — ntaps > 128 || ntaps % 16.
• The FIR does its own rate change. Decimation and interpolation of 1, 2 or 4, and the encoding is not what you would guess: 4 is written as 3, and 0 means bypass, not ÷1.
• At interpolation 1, transmit is capped at 64 taps. The general rule is max_taps = (converter_rate / sample_rate) × 16 — run the FIR at full rate and there simply are not enough clock cycles per sample to sweep 128 coefficients.
• Gain is quantised. Receive offers −12, −6, 0 or +6 dB; transmit offers only 0 or −6 dB.

That last rule is where lesson 47's 2.083 MSPS threshold comes from, and the number is exact: libad9361 tests rate <= 25000000 / 12 — 2 083 333 Hz — and steps the chip through an intermediate 3 MSPS before toggling the FIR, because enabling 128 taps directly at the final low rate would violate the tap limit.

The filter file the filter_fir_config attribute accepts is equally plain:

# comment
TX 3 GAIN 0 INT 4          # channel mask, gain in dB, interpolation
RX 3 GAIN -6 DEC 4
RTX 983040000 245760000 122880000 61440000 30720000 30720000
RRX 983040000 245760000 122880000 61440000 30720000 30720000
BWTX 18000000
BWRX 18000000
-2,-2                      # one TX coefficient, one RX coefficient

A coefficient line with a single value sets both chains identically. The RTX/ RRX clock chains are optional — but if you give one you must give both, or the driver quietly marks the filter invalid and computes its own chain instead.

What the driver does that you did not ask for

Probe, in order: get the reference clock, register the tx-active LED trigger (lesson 47 and docs/user-led.md), parse the device tree, claim the reset GPIO, load the gain table, reset the chip, check the product ID, register the clocks, run ad9361_setup, then register the IIO device.

ad9361_setup is the calibration sequence, and the order is load-bearing: bandgap and bias → BBPLL → clock chain → synthesiser charge-pump calibration → set both RF PLLs → gain control → RX baseband filter, TX baseband filter, RX TIA, TX second filter → ADC setup → baseband DC offset, RF DC offset, TX quadrature → enable the tracking loops → set the ENSM mode and the transmit attenuation.

Afterwards, on a retune:

debugfs, and what it is really for

initialize   loopback   bist_prbs   bist_tone   gpo_set
bist_timing_analysis   gaininfo_rx1   gaininfo_rx2
multichip_sync   calibration_switch_control   digital_tune

Beside those, every adi,* device-tree property also appears as a debugfs file. That is more dangerous than it looks, and it is the source of the next trap.

cd /sys/kernel/debug/iio/iio:device1        # resolve by name, never assume the index
echo 0x37 > direct_reg_access
cat direct_reg_access                      # 0x8 or 0xA - product ID and revision

Onward

This course has been asserting things. The matched filter is optimal. Correlation gain is 10·log₁₀(N). MMSE beats zero-forcing. Capacity is B·log₂(1+S/N). Here is why each is true — and, more usefully, exactly where each one stops being true.

Detection is a hypothesis test

"Is there a packet here?" is a question statistics answered in the 1930s. Two hypotheses — H₀, only noise; H₁, signal plus noise — and a rule for choosing. Two ways to be wrong, and they are not symmetric:

The optimal rule is the likelihood ratio test: form Λ(x) = p₁(x)/p₀(x) and compare it to a threshold. The Neyman–Pearson lemma says this is not merely a good test but the best one: among all tests with a false-alarm rate at most α, the likelihood ratio test has the highest probability of detection. Nothing else can do better at that false-alarm rate.

Sweep the threshold and you trace the ROC curve — detection probability against false-alarm probability. For the standard problem of detecting a known signal in Gaussian noise it collapses to one number:

P_D = Q( Q^-1(P_FA) - d )      d = sqrt( N * A^2 / sigma^2 )

Everything about your data enters through d — and d grows as √N. That is lesson 32's correlation gain arriving from the statistics side rather than the arithmetic side.

Why the matched filter is optimal, in one inequality

Filter the received signal and sample at time T. Write the filter as a vector, the signal as a vector, and the output signal-to-noise ratio is a ratio of an inner product to a norm. Then apply the Cauchy–Schwarz inequality — |⟨g,s⟩|² ≤ ⟨g,g⟩·⟨s,s⟩, with equality if and only if g = c·s:

SNR(T)  <=  2E / N0            E = the signal's energy

equality iff  h(t) = c * conj( s(T - t) )  // time-reversed and conjugated: the matched filter

That is the whole proof, and it says something the arithmetic does not: the peak SNR depends only on the signal's energy, not on its shape. A rectangle, a raised cosine and a random waveform of the same energy all reach exactly 2E/N₀. Which is why lesson 30 was free to choose the pulse shape on bandwidth grounds — the matched filter gives back the same SNR whatever you picked.

The error probabilities, exactly

BPSK        Pb = Q( sqrt(2*Eb/N0) )
QPSK, Gray  Pb = Q( sqrt(2*Eb/N0) )        // the same curve, in Eb/N0

square M-QAM, Gray, standard approximation:
            Pb ~= (4/k)*(1 - 1/sqrt(M)) * Q( sqrt( 3*k/(M-1) * Eb/N0 ) )     k = log2(M)

Evaluate them at a bit error rate of 10⁻⁵ and you get the exact version of the table lesson 41 budgets against — that one is rounded to whole decibels, so it reads about half a decibel high for the larger constellations:

Estimation: how well can you possibly know a number?

Timing offset, carrier frequency, channel taps — lessons 31 and 34 estimate all of them. The Cramér–Rao lower bound says how well any unbiased estimator could do: the variance is at least the reciprocal of the Fisher information, which measures how sharply the likelihood peaks. A sharp peak means the data pins the parameter down; a flat one means it does not.

For the case this board actually cares about — estimating the frequency of a complex tone from N samples at signal-to-noise ratio ρ — the closed form below is exact at every N rather than a large-N approximation:

var(f_hat)  >=  6 / ( (2*pi)^2 * rho * N * (N^2 - 1) )

Look at the N³. Variance falls as the cube of the observation length, so the standard deviation falls as N^1.5 — doubling the preamble buys 9 dB of frequency accuracy, not 3. Averaging intuition gets this wrong, because a longer observation does not merely average more noise; it gives phase more time to rotate, which is what carries the frequency information.

At 61.44 MSPS and 10 dB of SNR, on this board:

Which sets up lesson 32's frequency-offset trap — though the two numbers meet less neatly than they first look. A 64-sample preamble cannot pin the frequency closer than about 15 kHz, but 15 kHz across those same 64 samples is only 5.6° of phase rotation, which costs nothing. It becomes a problem at around 1040 samples, where that residual offset has turned a quarter turn.

So these are two constraints that meet at a length, not one constraint wearing two hats: your estimate improves the longer you correlate, the offset you failed to estimate punishes you the longer you correlate, and the preamble you want is where the two curves cross.

Why MMSE beats zero-forcing, in one term

Lesson 34 asserted it. Here are the two equalisers side by side:

zero forcing   W  ~  1 / H
MMSE           W  ~  1 / ( H + 1/SNR_mfb )
                              ^^^^^^^^^^^

One additive term, and it is the whole argument. Where the channel has a null, H approaches zero and zero-forcing divides by it — amplifying noise without limit. The extra term keeps the denominator away from zero, which is what "well conditioned" means here. (It is the reciprocal of the matched-filter-bound SNR rather than of the link SNR; Cioffi's Stanford notes give the exact form.) The orthogonality principle — the MMSE error is uncorrelated with the data — is the formal statement behind it.

The consequence is that the unbiased MMSE equaliser performs at least as well as zero-forcing at every SNR. Two conditions hide in that sentence and both bite in practice: the MMSE output is biased, and the bias has to be removed before slicing or generating LLRs; and MMSE needs an SNR estimate that zero-forcing does not — the same dependence on a noise-variance estimate that lesson 36 flags for sum-product decoding, and it fails the same quiet way.

Information theory, and the number everybody quotes wrong

Entropy is uncertainty; mutual information is how much observing the output tells you about the input; capacity is the mutual information of the best possible input distribution. Shannon's theorem, in his own words, is an existence result:

Rearrange the second in terms of energy per bit and spectral efficiency η = R_b/B, and you get the condition every link must satisfy:

Eb/N0  >=  (2^eta - 1) / eta

as eta -> 0:   -> ln 2 = 0.693  ->  10*log10(0.693) = -1.59 dB

What none of this promises

• Capacity says nothing about latency or complexity. The coding theorem is an existence proof over an ensemble of random codes. Approaching capacity needs long blocks, and long blocks are delay, memory and decoder power — none of which the theorem bounds. Lesson 36's utilisation table is what that costs in practice.
• Asymptotic means asymptotic. Maximum-likelihood efficiency, the coding theorem and the capacity limit are all statements about N → ∞. At the short blocks a packet radio actually uses, the finite-length penalty is real and large.
• AWGN is an assumption, and real channels violate it. Multipath, phase noise, amplifier non-linearity, impulsive interference, other users — none are Gaussian, none are white. The matched filter, every BER curve above and B·log₂(1+S/N) all inherit that assumption.
• Neyman–Pearson optimality is for simple hypotheses, with both distributions fully known. Unknown amplitude, phase and timing — which is every real receiver — puts you in composite testing, where generally no uniformly best test exists at all.

Each one uses the board for something software cannot do as well.

Before building something new, it is worth running something that already works. The repository ships three graded GNU Radio showcases in examples/ — dynamic range and how to lose it, a QPSK link you can watch end to end, and the two coherent receivers of lesson 45. Every control on them is wired to a number, so you can break the measurement on purpose and see what it cost.

1. A sample-locked trigger. Divide the sample stream and pulse a header pin. You now have a scope trigger with a fixed, known relationship to the transmitted RF. Uses lessons 13–16.
2. A power meter. Accumulate I² + Q² over a window in the fabric and expose the total in a register. The processor reads one number instead of a megabyte of samples. Your first real use of a DSP slice.
3. A digital downconverter. NCO plus mixer plus decimating filter: tune to a signal within the captured band and deliver only that, at a low rate. Lessons 26–28 combined, and genuinely useful.
4. A matched filter / correlator. Detect a known preamble in hardware and raise a flag. The gateway to radar, ranging and packet detection — and the first design where latency, not throughput, is the point.
5. A modulator. The exercise from lesson 29.
6. Hardware timestamping. Count l_clk edges and tag each buffer. This is the missing piece that makes cellular-class stacks work on AD936x boards. Hard, and genuinely valuable.

Every one of these was learned the expensive way on this exact board.

• Delete the Vivado project before any HDL or coefficient change, or your change is silently ignored.
• Simulate before you synthesise. One second against twenty minutes.
• Gate on the valid strobe, never on l_clk alone — this board is 2R2T, so a sample arrives every second edge.
• Capture on fifo_rd_valid | fifo_rd_underflow, never on fifo_rd_en, which is the request and arrives a cycle early.
• Synchronise every control bit that crosses a clock domain, and constrain the crossing with an explicit -from.
• Verify before you flash, and ./devkit verify --board after — it is the only thing that proves the board runs what you built.
• Set TX attenuation after the buffer opens, then read it back. Writing it before a stream starts guarantees nothing.
• Never loop transmit back to receive without at least 20 dB of attenuation. The receive port survives about +2.5 dBm; the transmitter reaches about +19 dBm.
• A guarantee you cannot reproduce on the bench is not a guarantee. This firmware claimed for a long time that killing a transmitting program muted the radio, because the kernel runs a teardown hook on file close. Measured on the board, it did not: the buffer stayed enabled and the port sat 12.6 dB hotter than muted with the program gone. The fix was to stop keying off an event - closing, crashing, being killed - and key off a state instead: no data reaching the converter for 250 ms means mute. Events get missed; a state cannot.
• Zero is not a safe default for everything. The same firmware cached the transmit attenuation to restore when it unmutes, in a struct that a reset path wipes with memset. Zero millidecibels of attenuation is full output, so poking a debugfs initialize and then opening any transmit stream keyed the transmitter flat out, with nobody having asked. It was found by re-running the safety tests by hand after a kernel upgrade — not by the upgrade breaking anything. Two lessons: a field whose zero value is dangerous does not belong in memory that something else clears, and the third time you write that sentence about the same struct, write a test instead of a comment.
• When the radio misbehaves, check /mnt/jffs2 first. It is writable, it survives reflashing, and a script there can rewrite settings underneath your application.

Measured figures quoted throughout — DSP and LUT counts, timing slack, mute depth, interpolator behaviour — come from one physical board. Treat them as indicative rather than specification.

Appendix

Fifty-four lessons, and every measured figure in them came off one board or out of a primary source. This appendix says which, points at the books worth owning, and — still — names the ground this course does not cover.

The two books to have open

Neither has an FPGA chapter. That gap is why this course exists.

Lesson by lesson

What this course still does not teach

Shorter than it used to be, and every entry is a real boundary rather than an omission.

Two things the sources taught this course

• "Process gain" is the standard name for what lesson 27 calls the decimation bonus, and it comes from the same 6.02N + 1.76 formula as converter resolution — which is why lessons 24, 25, 27 and 32 keep turning out to be one fact seen from four directions.
• Choose an awkward test frequency. SDR4E shows spur-free dynamic range dropping 11.4 dB purely because the test tone was harmonically related to the sample clock. The full-rate sweep in this repository used a tone at exactly fs/8 — the worst case — so those SFDR figures are pessimistic rather than flattering.