PCI Express SDR Board version 2024-04-26*This document is based on the latest test release.
Features may not be present in your current installed software. You may check their availability in change history or in your release documentation.
If you require an up to date release, ask for it in a ticket.
Features may not be present in your current installed software. You may check their availability in change history or in your release documentation.
If you require an up to date release, ask for it in a ticket.
Table of Contents
1 Features
- 2x2 RF transceiver (AD9361) with integrated 12-bit DACs and ADCs
- RF coverage: 500 MHz to 6.0 GHz
- RF bandwidth: < 200 kHz to 56 MHz
- Supports TDD and FDD operation
- Integrated TX/RX switch for TDD operation
- PCIe 1x standard connector
- Integrated GPS for precise time and frequency synchronization
- Clock/PPS inputs and outputs for easy chaining
- Optional sample compression to reduce the PCI bandwidth
2 Installation with the Amarisoft software
2.1 Introduction
If you have bought the OTS (Off-The-Shelve) package, then you donât need to install anything. Everything has already been installed on your PC. Otherwise, please follow through the steps below.
Decompress the trx_sdr archive into a convenient directory specified by <trx_path>.
tar -xzf trx_sdr-linux-YYYY-MM-DD.tar.gz -C <trx_path>
You have two ways to install the TRX driver for the PCIe card:
- automatic
- manual
For both cases, the installation requires some specific packages to compile the kernel module. To do this, you need to be root. In Fedora and Cent OS, you need to install kernel-devel, make, gcc and elfutils-libelf-devel packages by running the following command:
dnf install kernel-devel-$(uname -r) make gcc elfutils-libelf-devel
For Ubuntu, use the following command:
apt-get install linux-headers-$(uname -r) build-essential
Note that you’ll need equivalent packages for other Linux distributions if you do not use Fedora, Ubuntu or Cent OS.
Once you have finished the installation, you need to initialize (See Driver initialization) and upgrade your driver (See Firmware upgrade). Please make sure to initialize the driver after each system boot if you have not activates an automatic lte service.
2.2 Automatic Installation
Automatic installation is only available on Fedora, Ubuntu and CentOS distributions. Use manual install for other distributions. To start your automatic install, use the following command where <path> is the path to the directory where you have already installed your LTE component (eNB or UE) and type should be set to enb or ue accordingly.
./install <path> <type>
Notes:
- the script would install some packages, so make sure you have root privileges when you run the script
- this install creates a symlink for the TRX driver so please do not remove this directory afterwards.
2.3 Manual Installation
To manually install the driver, let’s note <path> the directory where Amarisoft eNB or UE software is installed. Then:
- Compile kernel driver:
Go to the kernel/ directory under <trx_path> and start compilation:cd kernel make
- Place driver:
Just copy the compiled driver into <path> directorycd .. cp trx_sdr.so <path> cp libsdr.so <path> cp libc_wrapper_sdr.so <path>
- Config files:
Copy RF driver config file. Note that there are 2 separate config directories for eNB and UE called config.enb and config.ue under your <trx_path>. As a result, the <config_dir> should be set to config.enb or config.ue accordingly.cp -r <config_dir> <path>/config/sdr
Select frontend:
<path>/config/rf_select.sh sdr
2.4 Driver initialization
Each time you boot your system, you need to perform this initialization. Note that if you are using OTS install, this step is already done by the lte service.
cd kernel ./init.sh
2.5 Firmware upgrade
Perform the following command to upgrade your PCIe card:
./sdr_util upgrade
Notes:
- If you have several PCIe cards installed, this will upgrade all cards.
- If the firmware is already up to date, this command will end directly.
- When the upgrade is over, you need your system to be powered off for the changes to take effect (not only reset, real power off).
2.6 Multiple card installation
To make several cards work together, they must be time and frequency synchronized. For that purpose you need to plug the provided black cable between each card. Connect the internal OUT connector (J4 on Figure 6.2) on the first card to the IN connector on the second card (J3 on Figure 6.2, connectors are between RoHS compliant mark and Serial number sticker). Then do the same with OUT of second card and IN of third one, etc...
When you install several PCIe cards, the mapping between the PCI connectors and the Linux devices is not predictable (but it shouldn’t change after each boot). To identify the order please do the following:
./sdr_util -c 0 led 1
Then check inside PC on each board, one of them should have a led blinking. This is card 0 (/dev/sdr0).
Switch off the led:
./sdr_util -c 0 led 0
You can do the same for other cards:
./sdr_util -c <n> led 1
Where <n>
is the index of the card.
To use all the cards, update eNB config file (1chan.cfg) using args parameter:
args: "dev0=/dev/sdrA,dev1=/dev/sdrB,..."
Note: this allow to change the order of the cards. For instance, if your card are from left to right have following indexes:
<1> <2> <0>
And you want first cell to be on left, second cell to be on middle and third on right, use the following:
args: "dev0=/dev/sdr1,dev1=/dev/sdr2,dev2=/dev/sdr0"
2.7 TRX driver configuration options
The default TRX configuration used by your component is called 1chan.cfg. It could be found under the directory config/sdr/ of your component (eNB or UE).
The following JSON properties are available:
argsrf_driver.args
String. Set the system device names for the boards. Example:
args: "dev0=/dev/sdr1,dev1=/dev/sdr2,dev2=/dev/sdr0"
sample_hw_fmtrf_driver.sample_hw_fmt
Optional enumeration (auto, ci16, cf8) (default = auto). Set the sample format used on the PCI bus.
auto
selects the best format depending on the available PCI bandwidth.ci16
selects 16 bit complex integers.cf8
selects 8 bit complex floats giving a 2:1 compression ratio while retaining the full 12 bit amplitude of the ADCs and DACs.rx_antennarf_driver.rx_antenna
Optional enumeration (auto, tx_rx, rx) (default = auto). Select the connector on which the RX antenna is connected. By default it is connected on the RX connector for FDD and on the TX/RX connector for TDD. This parameter is useful to force the use of the RX connector in TDD.
fifo_tx_timerf_driver.fifo_tx_time
Optional number. Set the DMA TX buffer size in us.
Decreasing this value will improve latency but may lead to signal samples loss if the PCIe chain on the motherboard is not fast enough. This can be detected with therf_info
monitor command of yourlteenb
orlteue
software. If such situation happens, the percentage ofTX buffer Usage
will be 100% which means the transmission path has encountered underflows.fifo_rx_timerf_driver.fifo_rx_time
Optional number. Set the DMA RX buffer size in us.
Same asfifo_tx_time
for RX chain but reducing it won’t improve latency.syncrf_driver.sync
Optional enumeration: none, internal, gps, external (default = none). Set the time synchronization source.
none
andinternal
uses the internal PPS generated from the clock.internal
synchronizes the RX timestamps on the internal PPS.none
does not synchronize the RX timestamps on the internal PPS for a faster startup.gps
uses the internal GPS.external
uses the PPS from the IN connector (J3 on Figure 6.2) if clock source is selected asexternal
or from the PPS MCX connector (PR10) if clock source is selected asinternal
.
When several cards are selected (with the
args
property),sync
only sets the time synchronization source of the first card. The other cards are implicitly set toexternal
synchronization, assuming the previous card is used as source.clockrf_driver.clock
Optional enumeration: internal, external (default = internal). Set the clock source.
internal
uses the internal clock (VCTCXO). If an external PPS sync source is used, the internal clock frequency is adjusted by the PPS signal.external
uses the clock from the IN connector (J3 on Figure 6.2).When several cards are selected (with the
args
property),clock
only sets the clock source of the first card. The other cards are implicitly set toexternal
clock, assuming the previous card is used as source.gpio0rf_driver.gpio0
Optional enumeration. Selects the signal ouput on test point TP3. See below for possible values. Default = rf_dts1.
gpio1rf_driver.gpio1
Optional enumeration. Selects the signal ouput on test point TP4. See below for possible values. Default = rf_dts2.
gpio values:
Value Description zero output a constant low level signal (OV) one output a constant high level signal (3.3V) rf_dts1 in TDD mode, output a high level when the TX is active on channel 1. Polarity can be inverted by setting dts_polarity
: lowrf_dts2 in TDD mode, output a high level when the TX is active on channel 2 Polarity can be inverted by setting dts_polarity
: lowpps_selected output a positive going Pulse per Second from the currently selected sync pps_ext output a positive going Pulse per Second from the EXT PPS MCX onboard connector pps_prev output a positive going Pulse per Second from the IN 5 pin inter board connector pps_gps output a positive going Pulse per Second from the onboard GPS module pps_vcxo output a positive going Pulse per Second from the onboard generator dma_tx output a positive front on each TX DMA packet (synced on current selected PPS) dma_rx output a positive front on each RX DMA packet dma_tx_100Hz output a 100 Hz signal synced with dma_tx dma_rx_100Hz output a 100 Hz signal synced with dma_rx dts_polarityrf_driver.dts_polarity
Optional enumeration: high (default), low. Selects the polarity for both rf_dts1 and rf_dts2 signals.
pps_extra_delayrf_driver.pps_extra_delay
Optional float value in microseconds, range: [-10000.0 .. +10000.0] (-10ms to +10ms) Adds a delay between GPS pulse and start of DL frame. If the pps_extra_delay value is negative, the actual delay will be (10ms + pps_extra_delay). For instance, if you want to compensate for 250ns delay caused by cable length, you will set pps_extra_delay: -0.25, the software will add (10ms - 250ns) to the GPS pulse.
tdd_tx_modrf_driver.tdd_tx_mod
Optional number value: 0 (default) or 1. If set to 1, the TX amplifiers will be switched on and off according to the TDD state.
The range for the transmit gain (tx_gain
parameter in
eNodeB/UE) is from 0 to 89.75 dB. The range for the receive gain
(rx_gain
parameter in eNodeB/UE) depends on the frequency:
Frequency | Gain |
---|---|
70-4000 MHz | 3 to 71 dB |
4001-6000 MHz | 0 to 62 dB |
The maximum sample rate is 61.44 MHz.
2.8 TDD support
The board integrates a TX/RX switch for TDD operation. When TDD operation is configured, the transmit and receive are done on a single RF port (the TX SMA connector). So you only need to connect antennas on the TX1 and TX2 SMA connectors for TDD operation.
2.9 GPS usage
You can check the GPS operation when the eNodeB/UE is stopped with
./sdr_util gps_state
The GPS takes a few minutes to lock if the GPS antenna is
connected. Any active GPS antenna accepting a 3.3V DC supply can be
used, for example: http://www.mouser.fr/Search/ProductDetail.aspx?R=ANT-GPS-SH-SMAvirtualkey59000000virtualkey712-ANT-GPS-SH-SMA
To ensure the PLL is correctly locked when launching the lte software, it is recommended to set the synchro to GPS beforehand with the command
./sdr_util sync_gps
2.10 Oscillator frequency fine tuning
If you don’t have a GPS, it is still possible to manually fine tune the VCTCXO (Voltage Controlled, Temperature Controlled Crystal Oscillator) frequency provided you have a way to know the offset:
./sdr_util clock_tune n
where n is the offset in PPM (parts-per-million) from the nominal TCXO frequency. Note: the PPM offset n to voltage law is only approximative, so you should adjust it by successive approximation.
3 Troubleshooting
Below are a few tips on how to handle different errors.
- The eNodeB does not start and the output of
dmesg
linux command resembles the following error message:
sdr: version magic '4.12.9-200.fc25.x86_64 SMP mod_unload' should be '4.12.11-200.fc25.x86_64 SMP mod_unload'
To resolve it, you need to recompile the SDR driver on the PC (See Manual Installation).
4 Miscellaneous utilities
4.1 sdr_util
usage: sdr_util [options] cmd [args...] Options: -h help -c device_num select the device (default = all) Available commands: version dump the FPGA version sync_state dump the synchro and clock state gps_state dump the GPS state sync_gps select GPS as sync source, wait for stable state gps_cal [-s] uses the GPS sync to tune VCXO, optionnaly stores the value in flash temp dump the temperature of the board components led [0|1] enable/disable led blinking clock_tune n tune TCXO frequency offset to n ppm upgrade [options] upgrade the FPGA firmware upgrade options are: -force force upgrade even if identical or previous version
4.2 sdr_spectrum
sdr_spectrum
is a real time spectrum analyzer, sample viewer
and I/Q file recorder. It handles several channels at the same
time. It can be invoked without arguments. The following options are
available:
-h
help
-args str
set the device arguments (default="dev0=/dev/sdr0")
-rx_freq freq
set the RX frequency in Hz (default=2400000000)
-rate rate
set the sample rate to ’rate’ Hz (default=30720000)
-rx_gain gain
set the RX gain in dB (default=60)
-channels c
set the number of RX channels to ’c’ (default=1)
-rx_bw
set the analog receive bandwidth in Hz (default=same as sample rate)
-sync source
set the sync source to ’source’ (none, internal, gps, external) (default=none)
-clock source
set the clock source to ’source’ (internal, external) (default=internal)
-save_path path
set the directory where the recorded samples are saved (default=/tmp)
-duration d
set the recorded sample file duration in seconds when saving (default=1.0)
-save
starts recording samples automatically from program start.
-save-and-exit
same as
-save
but program will quit at end of recording.
When saving the recorded samples, one file is generated per channel. The filename contains the UTC date, the frequency and the channel number. The I/Q samples are saved as little endian 32 bit float values, in I/Q order. The sample values are between -1 and 1.
Invocation example:
./sdr_spectrum -channels 2 -rx_gain 50 -rx_freq 2680e6 -rate 30.72e6
Resulting output:
sdr_spectrum
is interactive and allow actions during runtime:
keys
available keys are indicated in the left side text area.
left mouse button
select a range and the X-Y values are displayed on the bottom of the graph.
right mouse button
in spectrum mode, highlight a range and get a measure of the power inside the range.
4.3 sdr_play
sdr_play
is an I/Q file player. Several channels can be played
at the same time and they can be time synchronized on an external
clock. One file must be provided per channel. The following options
are available:
-h
help
-args str
set the device arguments (default="dev0=/dev/sdr0")
-tx_freq freq
set the TX frequency in Hz (default=2400000000)
-rate rate
set the sample rate to ’rate’ Hz (default=23040000)
-tx_gain gain
set the TX gain in dB (default=70)
-channels c
set the number of channels to ’c’ (default=1)
-tx_bw bw
set the analog transmit bandwidth in Hz (default=same as sample rate)
-loop
play the file in loop
-sync source
set the sync source to ’source’ (none, internal, gps, external) (default=none)
-clock source
set the clock source to ’source’ (internal, external) (default=internal)
-time_offset n
offset the output by n samples (default=0)
The sample files should contain the I/Q values as little endian 32 bit floats, in I/Q order. The sample values should be between -1 and 1.
4.4 sdr_test
sdr_test
is a general diagnostic tool for SDR boards.
usage: sdr_test [options] cmd [args...]
-h
help
-c device_num
select the SDR device number (default=0)
-d channel
select the device channel (default = 0). useful for CPRI boards.
dma_loopback_test [n][sec]
test DMA loopback on 1 or n devices for sec seconds (def: 10)
rfic_tx_test sample_rate freq tx_gain waveform [tone_freq/ofdm_bw]
test RFIC TX (freq in Hz, tx_gain in dB from 0 to 90)
waveform can be:zero for no signal prbs for PRBS simulation, tone for CW at specified offset from center freq (default = 7.68e6) ofdm for OFDM simulation on specified bw (default = auto)
flash_check
verify checksum of code in onboard FPGA.
flash_reload
reload FPGA code from onboard flash
gps_read
GPS read test (best with GPS antenna)
led
blinks onboard led during 5 seconds for identification
synchro_set [src]
Set the source for PPS synchronisation
0=internal 1=GPS 2=slave 3=ext PPS 4=CPRI 5=ext CLK
synchro_state
Show current status of clock and synchro source for SDR device
Example: sync_source = 0 (internal) pps_locked = 1 clock_source = 0 (internal) clock_pll_locked = 1
version
Show SDR device Hardware and firmware information
Example: Board ID: 0x4b01 Board master: 0x0 Board revision: 0x0 FPGA revision: 2022-06-07 16:29:58 FPGA status: operational Software version: 2022-02-25
dump_info
dump fpga and RF chip information (similar to sdr_util version)
Example: PCIe SDR TRX driver 2022-02-25 PCIe RFIC /dev/sdr0@0: Hardware ID: 0x4b01 DNA: [0x107149909461141596] Serial: '' FPGA revision: 2023-06-27 15:31:17 FPGA vccint: 1.00 V FPGA vccaux: 1.79 V FPGA vccbram: 1.00 V FPGA temperature: 42.6 °C AD9361 temperature: 18 °C AGC: Off Sync: internal (locked) Clock: internal (locked) Clock tune: -0.7 ppm NUMA: 0 DMA: 1 ch, 64 bits, SMem index: On DMA0 TX_Underflows: 65535 RX_Overflows: 65535 PCIe bus: bus=0xb4 FPGA PCI gen2 x1 (4.0Gb/s) OK
gpio 0|1 [value]
Get or set the signal available on GPIO points on the board
Seegpio0
andgpio1
in chapterTRX driver configuration options
;
5 C API
The PCIe SDR board can be used in other projects with its C API. The C
API allows to send and receive I/Q samples and to change the various
parameters (frequency, sample rate, bandwidth, gains, ...). The
Amarisoft TRX driver, sdr_play
and sdr_spectrum
are
built using this API.
The C API is described in libsdr.h. The corresponding Linux x86_64 dynamic library is libsdr.so.
Amarisoft does not provide any support for this API and can modify it without notice.
6 Physical specifications
6.1 Summary
- RF power output < 10 dBm
- Max RF input power: ~ -10 dBm RMS (+2dBm peak)
- 4 SMA female (TX1, TX2, RX1, RX2), AC coupled
- 1 SMA female (GPS antenna with 3.3V DC power supply)
- 2 internal 5-pin connectors for inter-card time synchronization
- 1 internal MCX connector for external PPS input
- PCIe gen2 x1, full height, short length
- Uses single 12V power supply from PCI connector
- ADC/DAC Sample Rate: maximum 61.44 MS/s
- ADC/DAC Resolution: 12 bits
- Frequency Accuracy: 2 ppm
- LTE 20MHz 64QAM EVM < 2 %rms (f < 2.6 GHz)
- LTE 20MHz 64QAM EVM < 4 %rms (f < 3.5 GHz)
- Full size (L x W x H): 128mm x 115mm x 20mm
- Weight: 0.100 kg
- Power (PCIe 12V): 210mA idle => 2.5W, 460mA maximum (2x2 max tx_gain) => 5.5W
6.2 Connectors
The following figure depicts the location and functionality of each connector in the PCIe board.
6.2.1 SMA connectors
See Figure 6.1 for the location.
On Figure 6.2, the connector names are:
PR7
TX2 (and RX2 for TDD)
PR9
RX2 (for FDD)
PR8
RX1 (for FDD)
PR6
TX1 (and RX1 for TDD)
PR5
GPS
6.2.2 PPS/Clock connectors
OUT connector (J4):
1
PPS_OUT
2
REFCLK_OUT_N
3
REFCLK_OUT_P
4,5
GND
PPS_OUT is a LVCMOS 3.3V output.
REFCLK_OUT is a standard LVDS signal with AC coupling.
IN connector (J3):
1
PPS_IN
2
REFCLK_IN_N
3
REFCLK_IN_P
4,5
GND
PPS_IN is a LVCMOS 3.3V input (> 3.3V input is not accepted).
REFCLK_IN is a standard LVDS signal with 100 ohm impedance and AC coupling.
This reference clock is 38.4 MHz when used to synchonize between SDR boards.
It can also accept a 10.0 MHz reference clock (auto detect).
5 or 4 pin USB2 motherboard PC cables can be plugged in J3 and J4.
When using a 4 pin connector, pin 5 can be left unconnected.
6.2.3 PPS MCX connector
- PR10
MCX input connector for external PPS source
- Imped.
50 ohms.
- Level
CMOS, positive pulse.
6.2.4 JTAG connector (J1)
JTAG connector:
1,3,5,7,9,11,13
GND
2
VCC (3.3V)
4
JTAG_TMS
6
JTAG_TCK
8
JTAG_TDO
10
JTAG_TDI
12,14
NC
6.2.5 Test Pins for TDD mode
See Figure 6.2 for the location. These pins are 3V3 CMOS output, they are driven high when RF port is in TX mode. They can be used to signal external RF circuitry in TDD mode.
TP3
see
gpio0
option in chapterTRX driver configuration options
; default value = rf_dts1 (TDD switch for TX1 port)TP4
see
gpio1
option in chapterTRX driver configuration options
; default value = rf_dts2 (TDD switch for TX2 port)
6.3 TX power
Maximum TX Power versus RF frequency, measured on OFDM BW = 20MHz.
RF Frequency | dBm/MHz | dBm |
---|---|---|
500 | -10.0 | 3.0 |
1000 | -11.0 | 2.0 |
1500 | -14.0 | -1.0 |
2000 | -15.0 | -2.0 |
2500 | -17.0 | -4.0 |
3000 | -21.0 | -8.0 |
3500 | -19.0 | -6.0 |
4000 | -20.0 | -7.0 |
4500 | -23.0 | -10.0 |
5000 | -25.0 | -12.0 |
5500 | -32.0 | -19.0 |
6000 | -34.0 | -21.0 |
7 Change history
7.1 Version 2023-09-08
- Added NUMA support
7.2 Version 2023-06-10
- Added tdd_tx_mod configuration parameter
- New FPGA firmmware version 2023-05-24
8 License
trx_sdr
is copyright (C) 2012-2024 Amarisoft. Its redistribution
without authorization is prohibited.
trx_sdr
is available without any express or implied warranty. In
no event will Amarisoft be held liable for any damages arising from
the use of this software.
For more information on licensing, please refer to license terms.