diff --git a/host/utilities/bladeRF-fsk/README.md b/host/utilities/bladeRF-fsk/README.md index 8e153f54..580e2b6d 100644 --- a/host/utilities/bladeRF-fsk/README.md +++ b/host/utilities/bladeRF-fsk/README.md @@ -2,31 +2,31 @@ ## Project Overview ## -The bladeRF-fsk project is a simple frequency shift keying (FSK) based software modem -impemented 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 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 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 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. +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. +This project is meant to be an experimental example and should not be treated as a +rigorous modem. ## Dependencies ## @@ -36,22 +36,22 @@ rigorous modem. ## Build Instructions ## -The program builds as part of the bladeRF host side code. Follow the build instructions +The program builds as part of the bladeRF host side code. Follow the build instructions listed in [bladeRF/host/README.md]. [bladeRF/host/README.md]: ../../README.md -_NOTE_: Release builds are recommended for this program. -More info: The receiver thread inside phy.c eats up a lot of CPU resources with DSP. -Debug builds do not contain compiler optimization, so running the a debug build may -cause RX overruns (i.e. received samples get dropped) which can cause the modem to fail. -If you want to check the %CPU that this thread uses, you can run bladeRF-fsk_test_suite -which contains a function phy_receive_test() that simply runs the receiver thread for -some time. Monitor the CPU usage of the threads using the linux command: +_NOTE_: Release builds are recommended for this program. +More info: The receiver thread inside phy.c eats up a lot of CPU resources with DSP. +Debug builds do not contain compiler optimization, so running a debug build may +cause RX overruns (i.e. received samples get dropped) which can cause the modem to fail. +If you want to check the %CPU that this thread uses, you can run bladeRF-fsk_test_suite +which contains a function phy_receive_test() that simply runs the receiver thread for +some time. Monitor the CPU usage of the threads using the linux command: ``` top -H -p $(pidof [path to build/output executables]/bladeRF-fsk_test_suite) ``` -When bladeRF-fsk_test_suite gets to phy_receive_test(), be sure to watch the CPU usage. +When bladeRF-fsk_test_suite gets to phy_receive_test(), be sure to watch the CPU usage. ### Build Variables ### @@ -71,9 +71,9 @@ Below is a list of project-specific CMake options. | -DBLADERF-FSK_ENABLE_DEBUG_FSK=\ | Print debug messages from fsk.c. Default: OFF | | -DBLADERF-FSK_ENABLE_DEBUG_BLADERF=\ | Print bladeRF debug messages. Default: OFF | -Setting -DBLADERF-FSK_ENABLE_NOTES_LINK=ON will show you when a frame is received with -CRC errors. Setting -DBLADERF-FSK_ENABLE_NOTES_PHY=ON will show you when RX overruns -occur, meaning the PHY receiver thread could not process a set of samples fast enough +Setting -DBLADERF-FSK_ENABLE_NOTES_LINK=ON will show you when a frame is received with +CRC errors. Setting -DBLADERF-FSK_ENABLE_NOTES_PHY=ON will show you when RX overruns +occur, meaning the PHY receiver thread could not process a set of samples fast enough and samples had to be dropped. ## How to Run ## @@ -85,57 +85,55 @@ To see a list of configuration options and how to set them, type: ``` bladeRF-fsk -h ``` -_NOTE_: On Windows, if you are running two instances of the program on the same PC, you -must specify the bladeRF serial number with the '-b' option, due to a bug. Example: +_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 -b *:serial=4e +bladeRF-fsk -d *:serial=4e ``` -Failure to do so will result in libusb error messages; data transfer will not work. - -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. +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: +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 ``` - _NOTE_: On Windows, if both bladeRFs are plugged into the same PC, you must also - specify the device serial number with the '-b' option when calling bladeRF-fsk. See - note in the "How to Run" section. - -3) Run bladeRF-fsk on the other device (sender), with opposite frequencies and the input - TX file specified: + _NOTE_: On Windows 10, if both bladeRFs are plugged into the same PC, you must also + specify the device serial number with the '-d' option when calling bladeRF-fsk. See + note in the "How to Run" section. + +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] +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. +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. +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. +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. diff --git a/host/utilities/bladeRF-fsk/c/src/rx_ch_filter.h b/host/utilities/bladeRF-fsk/c/src/rx_ch_filter.h index 6a29d7bd..1cfe2687 100644 --- a/host/utilities/bladeRF-fsk/c/src/rx_ch_filter.h +++ b/host/utilities/bladeRF-fsk/c/src/rx_ch_filter.h @@ -33,6 +33,8 @@ * * MATLAB command: * taps = firpm(31, [0 1/8 1/3 1], [1 1 0 0]); + * OR + * taps = remez(31, [0 1/8 1/3 1], [1 1 0 0]); * * For FSK implementation with mod_index=pi/2, SPS=8, this filter was designed to: * - Pass the signal's main lobe