NAME

       bladeRF-fsk - command line fsk application

DESCRIPTION

       The  bladeRF-fsk  project  is  a  simple  frequency  shift  keying (FSK) based software modem implemented
       entirely on the host PC side in C code. The project uses libbladeRF to transmit/receive  samples  with  a
       bladeRF  device.  A  USB  3.0  port  is  not  required when using this modem. The project also contains a
       MATLAB/Octave simulation/implementation of the physical layer (PHY) portion of the modem.

       The top level bladeRF-fsk C program demonstrates the functionality of the modem in a  simple  bladeRF-to-
       bladeRF  data  transfer  program.  This  program can transmit/receive both text (like a chat program) and
       binary files (like a file transfer program) with a raw link rate of 250 kbps. To properly demonstrate the
       program, two instances of the program must be run with two separate  bladeRF  devices  (loopback  is  not
       supported).

       The  modem modulates with continuous-phase frequency shift keying (CPFSK). Baseband I/Q CPFSK samples are
       sent to the bladeRF device, inside which they converted from digital to analog, mixed with quadrature  RF
       carriers,  and  transmitted  through  the air.  Received signals are mixed with quadrature RF carriers to
       downconvert to baseband I/Q, sampled with an  ADC,  and  sent  to  the  host  PC  program  over  the  USB
       connection.

       The  physical  layer  code features an FIR low-pass filter, power normalization, preamble correlation for
       signal detection, CPFSK modulation/demodulation, and scrambling. The link layer  code  features  framing,
       error  detection  via  CRC32  checksums,  and  guaranteed  delivery  of  frames  via acknowledgements and
       retransmissions.

       This project is meant to be an experimental example and should not be treated as a rigorous modem.

EXAMPLES

       To run the top-level bladeRF-fsk program with defaults, type into a terminal:

              bladeRF-fsk

       To see a list of configuration options and how to set them, type:

              bladeRF-fsk -h

       _NOTE_: On Windows 10, if you are running two instances of the program on the same PC, you  must  specify
       the      bladeRF      serial      number      with     the     '-d'     option,     due     to     [Issue
       #484](https://github.com/Nuand/bladeRF/issues/484). Example:

              bladeRF-fsk -d *:serial=4e

       By default the program uses the first available bladeRF device, gets  TX  input  from  stdin,  writes  RX
       output  to stdout, and uses a default set of transmit/receive frequencies and gains. Gains may need to be
       tweaked for a good connection with another bladeRF running bladeRF-fsk. To transfer files, use  the  '-i'
       and '-o' options. If using stdin for tx data, the program will transmit data line-by-line.

       The program runs until it gets an EOF in its TX input.

       ###  Example:  Transferring  Files  ###  1)  Be sure two bladeRF devices are plugged into your PC (or two
       separate PCs) with
          TX and RX antennas attached.

       2) Run bladeRF-fsk on one of the devices (receiver), with the output RX file specified:

              bladeRF-fsk -r 904M -t 924M -o rx.jpg

       3) Run bladeRF-fsk on the other device (sender), with opposite frequencies and the input
          TX file specified:

              bladeRF-fsk -r 924M -t 904M -i puppy.jpg

       4) The file will begin transferring, and progress will be printed in the terminal for the
          sending device.

       5) Once the transmission is complete, press [CTRL-D] on Linux/OSX or [CTRL-Z then ENTER]
          on Windows to stop the program on the receiving end.

       If the sending device does not get any response from the receiving device, it will quit the program.  Try
       increasing the gains and run it again.

KNOWN LIMITATIONS

       1) The program does not currently support the use of an XB-200 transverter expansion
          board to transmit/receive at frequencies below 300MHz. In order to add XB-200 support,
          a new configuration option as well as functions from the "Expansion boards" section
          of the libbladeRF API would need to be added to the source code.

       2) The program is currently unable to perform two file transfers in both directions
          simultaneously. Reason #1: The program runs until is gets an EOF in its TX input,
          meaning whichever side finishes transmitting its file first will quit and stop
          receiving. An EOF bit would need to be added to the link layer packet format in order
          to stop this behavior. Reason #2: The program doesn't seem to perform well during
          these simultaneous file transfers, and usually loses connection. Further investigation
          is required to debug this.

See Also

       bladeRF-cli(1)

BLADERF                                              2017.07                                      bladeRF-fsk(1)