Skip to content

Setting up Yate and YateBTS with the bladeRF

Jump to bottom
Robert Ghilduta edited this page Dec 22, 2020 · 24 revisions

Table of Contents

Overview

This guide is a quick and unofficial guide on creating a test setup of Null Team's Yate and YateBTS with the bladeRF. The goals of this guide are to:

  • Install Yate and YateBTS for use as non-root user in a yate group in /usr/local/
  • Verify basic "Network-in-a-Box" functionality by placing a call or sending an SMS message between two devices.
This guide is not intended to be comprehensive nor a replacement for any of the official Yate documentation; it is only intended to test a small fraction of the plethora of features provided by Yate.

While the Nuand team and bladeRF community are generally willing to help answer Yate & YateBTS questions, please note that the official resources listed below will likely better expedite any troubleshooting you need to do.

Disclaimer

As with all SDR development, you are responsible for ensuring that you operate only within bands for which you are licensed. When performing laboratory experiments, an RF test enclosure is highly recommended to ensure a system under test does not yield out-of-band emissions that might interfere with licensed network operators.

Prerequisites

USB 3

A USB 3.0 connection is preferred.

If you are on a USB 2.0 port and encounter errors (as evidenced by varying timestamp "jumps"), it may be the case that the system is not keeping up with the sample rate. Be sure to review the Transceiver Scheduling Priority section below, if you plan on using USB 2.0.

SIM card & Handset

A simple and inexpensive test setup can be achieved using a blank SIM card, a SIM card writer, and low-cost cellular device.

This "16 in 1 Super SIM" has been verified to work properly (alternative source on ebay). These all appear to come preprogrammed with the IMSI 001010123456789. To configure the sim card, please see this page about PySIM.

Plenty of quad-band GSM devices are available online. One such device that has been tested with the above SIM card is the BLU Q170T.

Build tools

To build Yate and YateBTS, basic knowledge of how to use GNU Autotools and GCC is required. Please refer to your Linux distribution's documentation for information on how to install these. If you plan to check out the latest source code, Subversion is required.

Setting up a yate group

This guide assumes one wants to run Yate as a non-root user, and uses a yate group to allow a non-root user to edit the various configuration files that will be manipulated at runtime.

First create a yate group: 

sudo addgroup yate

Add your user to this group. Change myuser to your user name. 

sudo usermod -a -G yate myuser

udev rule

A udev rule is required to ensure a user can access the bladeRF hardware.

If you have previously installed and used libbladeRF and/or the bladeRF-cli, you may skip this. These provide an 88-nuand.rules udev rule.

Otherwise, create an /etc/udev/rules.d/90-yate.rules file, containing: 

# nuand bladeRF
ATTR{idVendor}=="1d50", ATTR{idProduct}=="6066", MODE="660", GROUP="yate"

After creating this file, run the following command: 

sudo udevadm control --reload-rules

If the device is plugged in prior to this, ensure it is unplugged and re-connected at this time.

After logging out and back in, you should see yate listed when you run the groups command.

Install bladeRF

Fetch the bladeRF library and tools source from commit 3a411c87c2416dc68030d5823d73ebf3f797a145 by cloning the Nuand git repository and going to commit 3a411c87c2416dc68030d5823d73ebf3f797a145 via: 

$ git clone https://github.com/Nuand/bladeRF.git ./bladeRF
$ cd ./bladeRF
$ git reset --hard 3a411c87c2416dc68030d5823d73ebf3f797a145
$ ls

Once fetched, continue following the rest of the building from source instructions, continuing at the Configure the build step

Fetching Yate and Yate-BTS

Download the libbladeRF 2.0 based Yate and YateBTS source tarball

The following tarball includes YateBTS, Yate, and the latest RBFs. 

mkdir ~/software/bts/
cd ~/software/bts/
wget https://nuand.com/downloads/yate-rc-2.tar.gz
tar xfz yate-rc-2.tar.gz

A yate and yatebts directory should contain Yate and YateBTS, respectively. Remember to select and load the device and size appropriate v0.11.1 FPGA RBF included in the tarball. This step is recommended for using libbladeRF 2.0 (commit 3a411c8) with YateBTS and the bladeRF 2.0 micro.

Download pages (Alternative)

You can download the latest releases here:

Yate and YateBTS SVN (Alternative)

The below commands may be used to check out the Yate and YateBTS repositories into a ~/software/bts directory: 

mkdir ~/software/bts
cd ~/software/bts
svn checkout http://yate.null.ro/svn/yate/trunk yate
svn checkout http://voip.null.ro/svn/yatebts/trunk yatebts

If you already have the repositories checked out from a previous build, you can simply update them: 

cd ~/software/bts/yate
svn update

cd ~/software/bts/yatebts
svn update

Building and Installing Yate & YateBTS

Yate

First, configure the build to install into /usr/local: 

cd ~/software/bts/yate
./autogen.sh
./configure --prefix=/usr/local

Next, build Yate: 

make

If all went well, install it: 

sudo make install
sudo ldconfig

YateBTS

This procedure should look quite similar. 

cd ~/software/bts/yatebts
./autogen.sh
./configure --prefix=/usr/local

Build: 

make

Install: 

sudo make install
sudo ldconfig

Configuring Yate & YateBTS

To configure Yate & YateBTS to run as a non-root user, we need to change a few permissions and configuration options.

Group Write Permissions

First, we'll create a few files that Yate will fill in with defaults: 

sudo touch /usr/local/etc/yate/snmp_data.conf /usr/local/etc/yate/tmsidata.conf

Next, allow users of the yate group to modify configuration files: 

sudo chown root:yate /usr/local/etc/yate/*.conf
sudo chmod g+w /usr/local/etc/yate/*.conf

Required Configuration Items

While a majority of the configuration items will fall back to default values, there are a few items that the BTS operator is responsible for configuring correctly in /usr/local/etc/yate/ybts.conf

  • Radio.Band
  • Radio.C0
  • Identity.MCC
See the comments above each of these items for valid values. If not already clear, these are required to configure for the BTS to operate in the correct band, ARFCN, and country code.

Scheduling Priority

On some slower machines or when using USB 2.0 ports, you may see reports of "timestamp jumps" resulting from RX overruns. If this is the case, first ensure your CPU Governor is set to "performance" and that power settings are not limiting your CPU frequency. If problems persist, note that YateBTS provides the ability to increase the scheduling priority of the transceiver tasks.

Increasing the priority (i.e., decreasing its niceness) of a process generally requires additional privileges. We can edit the /etc/security/limits.conf file to grant users of the yate this ability by adding the following lines: 

@yate hard nice -20
@yate hard rtprio 99

Note that you may need to adjust these values per your situation, preferences, or policies. The below graphic, from ATAD #21, illustrates the meaning of the priority values: 

HIGH PRIORITY – – – – – > – – – – – > – – – – – > – – – – – > – – – – LEAST PRIORITY
| real time priority (static priority) |       nice value (dynamic priority)       |
|   99 ............ 50 ............ 1  | -20 ..... -10 ..... 0 ...... 10 ...... 19 |

The transceiver scheduling priority can be set in the [transceiver] of the /usr/local/etc/yate/ybts.conf file: 

radio_read_priority=highest
radio_send_priority=high

SNMP Port Numbers

Non-privileged users cannot bind sockets on ports lower than 1024. Therefore, we must change the SNMP ports. (Note that clients will need to be aware of this, if you plan to use SNMP.)

To do this, edit /usr/local/etc/yate/ysnmpagent.conf and look for the following lines: 

;port=161
;remote_port=162

Uncomment these by removing the preceding ; character, and set these to available ports greater than or equal to 1024. For example: 

port=20161
remote_port=20162

Running Yate

Startup

At this point, you should be able to plug in a bladeRF and run yate. When doing so, you should see LEDs on the bladeRF begin to blink. This indicates that the device's FPGA has been loaded and is in use.

Note that you use -v, -vv, -vvv, and so on to enable increasing degrees of verbosity.

Registering Devices

One simple way to allow a device to register is by placing its IMSI in the regexp field in /usr/local/etc/yate/subscribers.conf. As noted by the comments in this file, using a regular expression for IMSIs prevents one from utilizing 2G/3G authentication features; thus, this is suitable only for initial testing.

If you previously programmed your SIM, you should already know the IMSI such that you can place it in the regexp field.

If you are unsure or find that your device is not registering, you can use the NIB telnet interface to list rejected devices, as shown below.

With yate running: 

telnet localhost 5038

Once connected, one can list registered devices. 

nib list registered

Rejected devices can also be listed. If your device is not registering and is in this list, it implies that it is not properly entered in subscribers.conf 

nib list rejected

For example, suppose your devices have IMSIs ranging from 001010123456780 to 001010123456789. You could use the following regexp: 

regexp=^00101012345678[0-9]$

While Yate is running, this change can be applied via the telnet interface, using the following command: 

nib reload

Within a few minutes of registering the device should receive a text message noting its assigned phone number.

Testing Devices

The Yate NIB setup includes an ELIZA chat bot that you can communicate with by sending SMS messages to 35492. This is a good way to test use of a single device.

After registering a second device, you should be able to send SMS messages and connect a call between two devices.

Clone this wiki locally