Setting Up The Nuand BladeRF On Mac OS X for Bluetooth Low Energy (BLE) Hacking

(Cross-posted to peerlyst.com)

This is a quick guide to getting the Nuand BladeRF software defined radio (SDR) up and running on Mac OS X. The end goal is to have an environment that can be used to perform basic Bluetooth Low Energy (BLE) hacking. The initial focus will be getting it set up to perform BLE scanning and advertising.

A note on formatting: I’ve bolded commands that should be entered in at the command prompt. Any other code formatted content is output from running the commands, shown for reference.

Here’s the steps needed:

1. Install the dependencies, clone the repo, compile the software:

brew install libusb pkgconfig cmake libtecla
git clone --recursive https://github.com/Nuand/bladeRF.git
cd bladeRF/host
mkdir build ; cd build
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/opt/local ..
make
sudo make install

2. Make sure the device is recognized by the system:

$ bladeRF-cli -p
  Description:    Nuand bladeRF
  Backend:        libusb
  Serial:         7ddf0461b8c6cb36ffe8358189bc5d1d
  USB Bus:        20
  USB Address:    6

3. Download the most recent FPGA image

  • Make sure you get the correct version for your FPGA size. 
  • You can get the size by running: `bladeRF-cli -e info`
  • Look for a line similar to: `FPGA size:                40 KLE`

4. Setup the FPGA auto-load up so you don’t have to do this manually every time you reconnect the SDR:

  • Create the Nuand directory: `mkdir -p $HOME/.Nuand/bladeRF/`
  • Move the FPGA image to the Nuand directory: `mv $HOME/Downloads/hostedx40-latest.rbf $HOME/.Nuand/bladeRF/hostedx40.rbf`

5. Run the CLI, and you will likely see a warning message, followed by the bladeRF command prompt:

$ bladeRF-cli

table not found. Manual gain control will be used instead.
[INFO @ /<redacted>/bladeRF/host/libraries/libbladeRF/src/board/bladerf1/bladerf1.c:1706] To enable AGC, see "Generating a DC offset table" at https://github.com/Nuand/bladeRF/wiki/DC-offset-and-IQ-Imbalance-Correction
bladeRF>

6. Setup the AGC. This can be done either manually each time, or a table can be created:

  1. To set the AGC Manually:

    1. Set the frequency you wish to use. Since BLE uses 2.4 GHz, we’ll want to use that. In the example below, we set the frequencies to BLE Frequency Channel 37, which is used for BLE advertising. Channel 37 is centered at 2402 MHz, so we can set transmit to 2401 MHz, and receive to 2402 MHz:

    bladeRF> set frequency tx 2401M

      TX1 Frequency: 2401000001 Hz (Range: [237500000, 3800000000])

    bladeRF> set frequency rx 2402M

      RX1 Frequency: 2401999999 Hz (Range: [237500000, 3800000000])

    2. Set the gain (we set it to 8 dB here. There’s nothing magic about that, I picked it on a whim):

    bladeRF> set rxvga2 8
      Note: This change will not be visible until the channel is enabled.
      Setting RX1 rxvga2 gain to 8 dB
        rxvga2:    6 dB (Range: [0, 30])

    3. Calibrate the LMS module:

    bladeRF> cal lms
      LPF tuning module: 23

      TX LPF I filter: 27
      TX LPF Q filter: 39

      RX LPF I filter: 30
      RX LPF Q filter: 30

      RX VGA2 DC reference module: 25
      RX VGA2 stage 1, I channel: 37
      RX VGA2 stage 1, Q channel: 45
      RX VGA2 stage 2, I channel: 30
      RX VGA2 stage 2, Q channel: 33

    4. Run the DC offset calibration routines (look for `Error` values to be near 0:

    bladeRF> cal dc rx

    RX DC I: Value =   352, Error =  0.456
    RX DC Q: Value =   640, Error =  0.265

    bladeRF> cal dc tx

    TX DC I: Value =  -208, Error =  0.347
    TX DC Q: Value =   160, Error =  0.349

  2. To generate a table:

    1. Run the cal command. This will take some time, and should be done after the bladeRF has been running a bit so it is properly warmed up:

    bladeRF> cal table dc rx
    Calibrated @  237500000 Hz: I= 384 (Error: 3.63), Q= 224 (Error: 0.95)      DC-LUT: Max (I=-46, Q=-38) Mid (I=  7, Q= 10) Min
    Calibrated @  247500000 Hz: I= 384 (Error: 2.44), Q= 224 (Error: 1.81)      DC-LUT: Max (I=-43, Q=-39) Mid (I=  7, Q= 10) Min
    Calibrated @  257500000 Hz: I= 384 (Error: 0.81), Q= 224 (Error: 0.30)      DC-LUT: Max (I=-41, Q=-39) Mid (I=  8, Q= 10) Min
    ...
    Done.

    2. Once complete, check the current directory on the file system. There should be a file named `<serial #>_dc_rx.tbl`.

  • For example: Using the device shown in the info command above, the file name would be `7ddf0461b8c6cb36ffe8358189bc5d1d_dc_rx.tbl`

    3. Move the file to the Nuand directory: mv 7ddf0461b8c6cb36ffe8358189bc5d1d_dc_rx.tbl $HOME/.Nuand/bladeRF

That’s all there is to it. Now when you run `bladeRF-cli`, the FPGA will be auto-loaded, and the AGC table will be loaded as well, leaving you ready to rock. In a future post, I’ll talk about where to go next to start listening to beaconing BLE devices near you.


Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.