bladeRF-fsk: Fixed misinformation in README.md
- Made changes to the readme which were meant to be part of the
initial bladeRF-fsk commit, but were not.
- Also added a comment to rx_ch_filter.h, regarding MATLAB
- Cleaned up trailing whitespace.
This commit is contained in:
parent
96a99c02cc
commit
fcd775f2b9
2 changed files with 75 additions and 75 deletions
|
|
@ -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=\<ON/OFF\> | Print debug messages from fsk.c. Default: OFF |
|
||||
| -DBLADERF-FSK_ENABLE_DEBUG_BLADERF=\<ON/OFF\> | 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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue