From d3bc3dc27ff0803b4343238edc5da17bee2c6c70 Mon Sep 17 00:00:00 2001 From: Jon Szymaniak Date: Tue, 17 May 2016 22:05:31 -0400 Subject: [PATCH] host: examples: bladeRF-cli: Added sync_trx example This example demonstrates how to use the bladeRF-cli to perform synchronized sampling using two devices and a trigger signal on J71-4. --- host/examples/bladeRF-cli/sync_trx/.gitignore | 2 + host/examples/bladeRF-cli/sync_trx/README.md | 142 ++++++++++++++++++ .../bladeRF-cli/sync_trx/create_samples.bat | 9 ++ .../bladeRF-cli/sync_trx/create_samples.sh | 29 ++++ host/examples/bladeRF-cli/sync_trx/master.txt | 32 ++++ .../bladeRF-cli/sync_trx/plot_samples.m | 25 +++ host/examples/bladeRF-cli/sync_trx/slave.txt | 30 ++++ 7 files changed, 269 insertions(+) create mode 100644 host/examples/bladeRF-cli/sync_trx/.gitignore create mode 100644 host/examples/bladeRF-cli/sync_trx/README.md create mode 100644 host/examples/bladeRF-cli/sync_trx/create_samples.bat create mode 100755 host/examples/bladeRF-cli/sync_trx/create_samples.sh create mode 100644 host/examples/bladeRF-cli/sync_trx/master.txt create mode 100644 host/examples/bladeRF-cli/sync_trx/plot_samples.m create mode 100644 host/examples/bladeRF-cli/sync_trx/slave.txt diff --git a/host/examples/bladeRF-cli/sync_trx/.gitignore b/host/examples/bladeRF-cli/sync_trx/.gitignore new file mode 100644 index 00000000..fbefff01 --- /dev/null +++ b/host/examples/bladeRF-cli/sync_trx/.gitignore @@ -0,0 +1,2 @@ +*.csv +*.bin diff --git a/host/examples/bladeRF-cli/sync_trx/README.md b/host/examples/bladeRF-cli/sync_trx/README.md new file mode 100644 index 00000000..0ca6acad --- /dev/null +++ b/host/examples/bladeRF-cli/sync_trx/README.md @@ -0,0 +1,142 @@ +# Synchronized TRX # + +This example illustrates how to synchronize RX and TX sampling on +multiple devices, using the bladeRF-cli and the trigger functionality +introduced in FPGA v0.6.0. + +This example assumes the use of an RF power splitter/combiner and two bladeRF +devices, connected as follows: + +1. The "master" bladeRF has both its TX and RX ports connected to + the combiner. + +2. The "slave" bladeRF has its RX port connected to the combiner. + +3. Pin 4 on J71 on both devices is connected together. This connects + the trigger signal on both devices. The "master" will output this + signal, and the "slave" will receive it. + +4. Pin 2 on J71 on both devices is connected. This provides a common ground. + +5. The J62 SMB clock connector of both devices are connected together. + The "master" bladeRF will output its 38.4 MHz reference clock, and the + "slave" bladeRF will utilize this reference instead of its own on-board + clock. This ensures that both devices are sampling using the same clock. + +When a trigger is "armed," the FPGA will gate both transmit and receive +samples; the flow of samples to/from the host is blocked. The assertion +("firing") of the trigger signal unblocks samples, causing all devices to +begin transmitting or receiving within +/- 1 sample clock period. + +In this example, the "master" will transmit a series of on-off pulses at a +1 MHz offset, and both the "master" and "slave" will receive these pulses. The +transmission and reception are synchronized using the J71-4 trigger signal. + +## Creating Samples ## + +Scripts are provided to create a samples.csv file containing a single pulse. +This files consists of 1,000 zeros, followed by 100 samples of a CW tone, +followed by 1,000 more zeros. + +In Linux and OSX, run `create_samples.sh`. In Windows, run `create_samples.bat`. +This script make take a few moments to complete. + +## Executing the Example Scripts ## + +Two bladeRF-cli scripts, `master.txt` and `slave.txt`, are provided for this +example. + +The `master.txt` script configures the "master" device to output its +reference clock on the SMB connector (J62), arm a TX "master" trigger, and +arm an RX "slave" trigger. + +Note that even though both the RX and TX paths are on the same device, one +of these must assume the "master" trigger role that will output the trigger signal. +Internally, the other path with receive this -- it is *very* important +that both not be configured as "master", as this would cause contention +over the trigger signal. + +In a multi-device configuration, especially for this master-slave setup, it is +recommended to run the bladeRF-cli in a manner that specifies the device +to open via serial number. + +Run `bladeRF-cli -p` to see a list of available devices. For example: + +``` +$ bladeRF-cli -p + +Backend: libusb +Serial: e93f190c76e987cd7f462026f965a1a1 +USB Bus: 1 +USB Address: 13 + +Backend: libusb +Serial: b74ed347390d35c29923e80f64c9d904 +USB Bus: 12 +USB Address: 8 + +``` + +For this example, the "master" is the device with serial number `b57...` +and the "slave" is the device with serial number `e93...`. + +In one terminal, run the `master.txt` script: + +``` +$ bladeRF -d '*:serial=b74' -s master.txt -i +``` + +In another terminal, run the `slave.txt` script: + +``` +$ bladeRF -d '*:serial=e93' -s slave.txt +``` + +At this point, both devices' sample streams are blocked and awaiting +a trigger. In the "master" console, fire the trigger via: + +``` +trigger j71-4 tx fire +``` + +Wait for the RX and TX operations complete via the commands: + +``` +rx wait; tx wait +``` + +It will most likely be the case that these operations have finished +before you can type these commands. They will return immediately if +this is true. + +## Viewing the Results ## + +The results may be viewed using [Octave] [1] or [MATLAB] [2]. + +Run one of these programs in this directory and execute the +`plot_samples` function provided in this directory. This script +will load and plot samples from the `master_tx.csv`, `master_rx.csv`, and +`slave_rx.csv` files located in the current working directory. + +Note that in the resulting plot, the first pulse transmitted by the "master" +will be red/orange. The signal received by the "master" device is blue. The +signal received by the "slave" device is green. + +Zoom in to see the first few pulses in detail. The reception of the pulse by +the "master" and "slave" devices should be synchronized within +/- 1 samples. + +Although the devices' sampling clocks are synchronized, they are not guaranteed +to be phase-aligned; the mixers in each device operate using independent +PLLs. However, the phase offset between the synchronized devices should remain +fixed. This allows for opportunities to determine and compensate for +phase offsets. + +Lastly, there is a fixed offset between the transmission of the signal +by the "master" device, and its reception. This length of this offset +is determined by the TX chain in the FPGA and LMS6002D, and should remain +a constant value. Thus, one can make a priori assumptions about this value +after quantifying it for a particular FPGA version. (Changes to the FPGA +code could alter this value.) + +[1]: https://www.gnu.org/software/octave/ "GNU Octave" +[2]: https://www.mathworks.com/products/matlab "MATLAB" diff --git a/host/examples/bladeRF-cli/sync_trx/create_samples.bat b/host/examples/bladeRF-cli/sync_trx/create_samples.bat new file mode 100644 index 00000000..6b133204 --- /dev/null +++ b/host/examples/bladeRF-cli/sync_trx/create_samples.bat @@ -0,0 +1,9 @@ +@echo off + +set OUTFILE=master_tx.csv +if exist %OUTFILE% del %OUTFILE% + +echo Creating %OUTFILE%. This window will close when this is done. +for /L %%G in (1, 1, 1000) do echo "0, 0" >> %OUTFILE% +for /L %%G in (1, 1, 100) do echo "1447, 1447" >> %OUTFILE% +for /L %%G in (1, 1, 1000) do echo "0, 0" >> %OUTFILE% diff --git a/host/examples/bladeRF-cli/sync_trx/create_samples.sh b/host/examples/bladeRF-cli/sync_trx/create_samples.sh new file mode 100755 index 00000000..7b5842a4 --- /dev/null +++ b/host/examples/bladeRF-cli/sync_trx/create_samples.sh @@ -0,0 +1,29 @@ +#!/bin/sh +# +# Creates a master_tx.csv file +################################################################################ + +OUTFILE=master_tx.csv + +rm -f ${OUTFILE} + +# Write zeros +i=0 +while [ $i -lt 1000 ]; do + echo "0, 0" >> ${OUTFILE} + i=$(expr $i + 1) +done + +# Write a pulse (i = q = sqrt(2)/2) +i=0 +while [ $i -lt 100 ]; do + echo "1447, 1447" >> ${OUTFILE} + i=$(expr $i + 1) +done + +# Write zeros +i=0 +while [ $i -lt 1000 ]; do + echo "0, 0" >> ${OUTFILE} + i=$(expr $i + 1) +done diff --git a/host/examples/bladeRF-cli/sync_trx/master.txt b/host/examples/bladeRF-cli/sync_trx/master.txt new file mode 100644 index 00000000..1b151814 --- /dev/null +++ b/host/examples/bladeRF-cli/sync_trx/master.txt @@ -0,0 +1,32 @@ +# Set up device parameters +set frequency rx 922M +set frequency tx 923M +set samplerate 6M +set bandwidth 3M +set txvga1 -15 +set txvga2 0 +set lnagain 6 +set rxvga1 10 +set rxvga2 0 + +# Configure TX & RX operations +tx config file=master_tx.csv format=csv repeat=25 timeout=60s +rx config file=master_rx.csv format=csv n=60000 timeout=60s + +# Output reference clock +set smb_mode output + +# Arm the triggers +trigger j71-4 tx master +trigger j71-4 rx slave + +# Start streaming sampling +rx start +tx start + +# Inform user how to fire trigger +echo " ---------------------------------------------------------------" +echo " Run the slave.txt script in another terminal." +echo " Then, run 'trigger j71-4 tx fire' to fire trigger." +echo " ---------------------------------------------------------------" +echo "" diff --git a/host/examples/bladeRF-cli/sync_trx/plot_samples.m b/host/examples/bladeRF-cli/sync_trx/plot_samples.m new file mode 100644 index 00000000..3c3f8cfa --- /dev/null +++ b/host/examples/bladeRF-cli/sync_trx/plot_samples.m @@ -0,0 +1,25 @@ +% This script assumes it is being run from: +% ${BLADERF}/host/examples/bladeRF-cli/sync_trx +% +% If this is not the case, change the following addpath() line to point to: +% ${BLADERF}/host/misc/matlab +% +% This directory contains the load_csv() function. +addpath('../../../misc/matlab') + +master_tx = load_csv('master_tx.csv'); +master_rx = load_csv('master_rx.csv'); +slave_rx = load_csv('slave_rx.csv'); + +master_tx_len = length(master_tx); +master_rx_len = length(master_rx); +slave_rx_len = length(slave_rx); + +% Scale the master_tx samples to the max RX'd amplitude +% just to make the plot a bit easier to read. +abs_master_tx = abs(master_tx) * max(abs(master_rx)); + +plot(1:master_tx_len, abs_master_tx, 'r', ... + 1:master_rx_len, abs(master_rx), 'g', ... + 1:slave_rx_len, abs(slave_rx), 'b'); + diff --git a/host/examples/bladeRF-cli/sync_trx/slave.txt b/host/examples/bladeRF-cli/sync_trx/slave.txt new file mode 100644 index 00000000..788272c9 --- /dev/null +++ b/host/examples/bladeRF-cli/sync_trx/slave.txt @@ -0,0 +1,30 @@ +# Set up device parameters +set frequency rx 922M +set frequency tx 922M +set samplerate 6M +set bandwidth 3M +set lnagain 6 +set rxvga1 10 +set rxvga2 0 + +# Configure RX & TX operations +rx config file=slave_rx.csv format=csv n=60000 timeout=60s + +# Use reference clock input from master. +# This assumes the master is already outputting this reference. +set smb_mode input + +# Arm the trigger +trigger j71-4 rx slave + +# Start streaming sampling +rx start + +# Inform user how to fire trigger +echo " ---------------------------------------------------------------" +echo " Ready. Fire the trigger on the master device." +echo " ---------------------------------------------------------------" + +# Wait for the RX to complete and then finish up. +rx wait +