diff --git a/doc/README.md b/doc/README.md index 022174a4e7..5f61489893 100644 --- a/doc/README.md +++ b/doc/README.md @@ -103,7 +103,7 @@ Some directories under `radio` contain READMEs: - [RFsimulator](../radio/rfsimulator/README.md) - [USRP](../radio/USRP/README.md) -- [BladeRF](../radio/BLADERF/README) +- [BladeRF](../radio/BLADERF/README.md) - [IQPlayer](../radio/iqplayer/DOC/iqrecordplayer_usage.md), and [general documentation](./iqrecordplayer_usage.md) - [fhi_72](../radio/fhi_72/README.md) - [vrtsim](../radio/vrtsim/README.md) diff --git a/radio/BLADERF/README b/radio/BLADERF/README deleted file mode 100644 index c93c938baf..0000000000 --- a/radio/BLADERF/README +++ /dev/null @@ -1,138 +0,0 @@ -BladeRF documentation -===================== - -As of 2018-11-06, the bladeRF support is not fully automatic and requires -some manual settings before use. This documentation is the ultimate source -of information. If something described in this file does not work or does -not correspond to the reality, then contact us so we can fix the problems -and update this documentation. - -1. Install bladeRF 2.0 libraries. - - As of now, it's better to install from source. - So, do not run: ./build_oai -I -w BLADERF - (That is: do not include '-w BLADERF'.) - - Instead, follow the instructions at: https://github.com/Nuand/bladeRF - - If you already had some bladeRF software installed using automatic - methods, first remove it by hand ('apt-get purge bladeRF' or something - similar, you can get the list of installed bladeRF packages by running - 'dpkg -l|grep -i blade', remove them all). - -2. Update the device. - - Download the latest FX3 firmware and FPGA images from Nuand's website. - As of writing, this is: - - https://github.com/Nuand/bladeRF/wiki - - That points to the following pages. - For FX3: - - http://www.nuand.com/fx3_images/ - - For FPGA: - - http://www.nuand.com/fpga_images/ - - Install FX3 firmware: - - sudo bladeRF-cli -f bladeRF_fw_latest.img - - Install FPGA image (this is for BladeRF x40): - - sudo bladeRF-cli -L hostedx40-latest.rbf - - Retrieve calibration information: - - sudo bladeRF-cli -i - info - - That outputs the serial number of your device. - - Go to: - - https://www.nuand.com/calibration - - And enter your serial number. - The website tells you to run something like: - - sudo bladeRF-cli -i - flash_init_cal 40 0x9271 - - Actual values depend on your device and serial number. - -3. Calibrate the bladeRF device. - - We will work with band 7 on 2.68GHz with a bandwidth of 5 MHz (25 RBs). - - Plug the bladeRF device, then run: - - sudo bladeRF-cli -i - set frequency tx 2680000000 - set frequency rx 2560000000 - set gain rx 60 - set gain tx 60 - set bandwidth 5000000 - set samplerate 7680000 - cal lms - cal lms - cal lms - cal dc rxtx - cal dc rxtx - cal dc rxtx - -4. Tune the RX gain using the enb tracer. - - Run the softmodem and the 'enb' tracer. For instructions, see: - - https://gitlab.eurecom.fr/oai/openairinterface5g/wikis/T/basic - - In the enb window, check the 'input signal'. You should see some blue - signal as seen at: - - https://gitlab.eurecom.fr/oai/openairinterface5g/wikis/T/enb - - (the 'Time signal power' plot). - - The level should be around 30. - - If it's not around 30 then edit your configuration file and modify - the value 'max_rxgain' in the section 'RUs'. - - The configuration file to use is: - - configuration/bladeRF/enb-band7-5mhz.conf - - In the configuration file, you also need to set the correct values for: - - - tracking_area_code - - plmn_list: mcc, mnc, mnc_length - - mme_ip_address: this is the IP address used by the computer running - the softmodem to connect to the EPC - - NETWORK_INTERFACES: all the ENB*ADDRESS* variables have to point - to the IP address of the EPC machine - -5. You're good to go. - - You can now connect a UE and pass some traffic. If everything is well - configured you can expect more than 16 Mb/s of throughput in the downlink - using iperf and more than 8 Mb/s in the uplink. Looking at the logs, you - should find lines containing 'PHR 40' and 'CQI 15'. If your values are - lower then your setup may need some adjustments. - -6. In case of problems. - - If the performance of the softmodem is very bad, you can stop it and - run the calibration again, without setting the parameters (frequencies, - gains, etc.). Just run: - - sudo bladeRF-cli -i - cal lms - cal dc rxtx - - That may help. - - Be sure to use proper radio equipment (duplexer, antennas, clean - environment without interferences). diff --git a/radio/BLADERF/README.md b/radio/BLADERF/README.md new file mode 100644 index 0000000000..d2ac6e1547 --- /dev/null +++ b/radio/BLADERF/README.md @@ -0,0 +1,148 @@ +# BladeRF 2.0 Micro Documentation + +[TOC] + +## Install BladeRF 2.0 Micro Libraries + +You can install the BladeRF library by using `build_oai -I -w BLADERF`, which +will install it from the package manager if the distribution supports it, or +falls back to a build from source otherwise. + +If you intentionally want to install BladeRF from source, you can follow +[Nuand's Getting Started +guide](https://github.com/Nuand/bladeRF/wiki/Getting-Started%3A-Linux#building-bladerf-libraries-and-tools-from-source) +to do so. + +## Configure the device + +### Image Flash + +Download the latest FX3 firmware and FPGA images from Nuand's website. There +are [fx3 images](http://www.nuand.com/fx3_images/) and [FPGA +images](http://www.nuand.com/fpga_images/). Download and save the corresponding +files to your computer, then install the FX3 firmware + + sudo bladeRF-cli -f bladeRF_fw_latest.img + +and install the FPGA image (this is x40): + + sudo bladeRF-cli -L hostedx40-latest.rbf + +### Use of the configuration file + +This configuration will help the bladeRF board to load the bitstream images +automatically, and can be used to set some options automatically that are not +configured by OAI. + +Create the bladeRF config file: + +```bash +$ cat ~/.config/Nuand/bladeRF/bladerf.conf +# Load the hostedx40.rbf FPGA image, set the trim DAC, and +# configure the frequency +fpga ~/.config/Nuand/bladeRF/image.rbf +# trimdac 592 +# frequency 2.4G +``` + +More information is available at [Nuand's +website](https://nuand.com/libbladeRF-doc/v2.5.0/configfile.html). + +### Useful commands for `bladerf-cli` + +`bladeRF-cli` can be used to query various device details. + +Show the version of bladeRF and device details + + bladeRF-cli --exec version + bladeRF-cli --exec info + +Probe for a specific device + + bladeRF-cli --probe + +Print some information on device capabilities and current configuration +(bandwidth, frequency, clocking and sample rate, various features) + + bladeRF-cli --exec print + +### Calibration + +Retrieve calibration serial number: + + bladerf-cli --exec info + +Go to the [Nuand calibration page](https://www.nuand.com/calibration) and enter +your serial number. The website tells you to run something like: + + sudo bladeRF-cli -i + flash_init_cal 40 0x9271 + +Actual values depend on your device and serial number. + +You can also rerun a calibration like so + + sudo bladeRF-cli -i + cal lms + cal dc rxtx + +## OAI + +### Build BladeRF driver + +You can use `build_oai` to build with BladeRF support, e.g., + + cd openairinterface5g/cmake_targets/ + ./build_oai --ninja --nrUE --gNB -w BLADERF + +or you can use cmake directly + + cd openairinterface5g/ + cmake -B build -G Ninja -DOAI_BLADERF=ON + cmake --build build -t oai_bladerfdevif # to build only the driver + cmake --build build # to build it all + +For more information about the build, please refer to [the build +documentation](../../doc/BUILD.md). + +### Adapt the OAI-gNB configuration file to your system + +You can start from a [sample BladeRF configuration +fiel](../../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band78.fr1.51PRB.bladerf20xa0.conf). + +The only BladeRF-specific configuration resides in `RUs.[0].sdr_addrs`. This +string is passed to +[`bladerf_open()`](https://www.nuand.com/libbladeRF-doc/v2.6.0/group___f_n___i_n_i_t.html#gab341ac98615f393da9158ea59cdb6a24) +and can be used to select a specific BladeRF device. For instance, to open a +specific device with serial 730f5a36545849d9aa71ca6cf50e8ca0 on USB, you would +add `libusb: serial=730f5a36545849d9aa71ca6cf50e8ca0`. + +The TX gain is automatically chosen to be the maximum, and can be reduced with +`att_tx`. The RX gain is taken from `RUs.[0].max_rxgain`, and can be attenuated +with `att_rx`. + +The rest of the paramaters (PLMN, frequencies, IP addresses) is the same as in +any other configuration. Refer to the [general +tutorials](../..//doc/NR_SA_Tutorial_OAI_CN5G.md) for more information. + +### Run the setup + +Assuming you built from source above: + + cd ~/openairinterface5g/build/ + sudo ./nr-softmodem -O ../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band78.fr1.51PRB.bladerf20xa0.conf -E + +### In case of problems + +Refer back to the calibration section above. If not done yet, consider +calibrating your device. + +You can get more logs from BladeRF. To do so, you have to edit the code and +modify this line inside [`bladerf_lib.c`](./bladerf_lib.c). + +```patch +- bladerf_log_set_verbosity(BLADERF_LOG_LEVEL_INFO); ++ bladerf_log_set_verbosity(BLADERF_LOG_LEVEL_VERBOSE); +``` + +in function `device_init()`.