rpitx/csdr
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

fix formatting, etc.

Browse source
This commit is contained in:
ha7ilm 2014-11-28 17:26:39 +01:00
parent 07c6a7df3a
commit 4f95f267ce
1 changed files with 40 additions and 38 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

78
README.md
View file

@ -1,10 +1,10 @@
libcsdr libcsdr
======= =======
*libcsdr* is a set of simple DSP routines for Software Defined Radio. *libcsdr* is a set of simple DSP routines for Software Defined Radio.
It is mostly useful for AM/FM/SSB demodulation and spectrum display. It is mostly useful for AM/FM/SSB demodulation and spectrum display.
Feel free to use it in your projects. Feel free to use it in your projects.
Most of the code is available under the permissive BSD license, with some optional parts under GPL. For additional details, see [Licensing]. Most of the code is available under the permissive BSD license, with some optional parts under GPL. For additional details, see <a href="licensing">licensing</a>.
- The package comes with a command-line tool `csdr`, which lets you build DSP processing chains by shell pipes. - The package comes with a command-line tool `csdr`, which lets you build DSP processing chains by shell pipes.
- The code of *libcsdr* was intended to be easy to follow. - The code of *libcsdr* was intended to be easy to follow.
@ -48,7 +48,8 @@ Usage by example
- We want to listen to one radio station, but input signal contains multiple stations, and its bandwidth is too large for sending it directly to the FM demodulator. - We want to listen to one radio station, but input signal contains multiple stations, and its bandwidth is too large for sending it directly to the FM demodulator.
- We shift the signal to the center frequency of the station we want to receive: `-0.17*2400000*0.5 = -204000`, so basically we will listen to the radio station centered at 89504000 Hz. - We shift the signal to the center frequency of the station we want to receive: `-0.17*2400000*0.5 = -204000`, so basically we will listen to the radio station centered at 89504000 Hz.
- We decimate the signal by a factor of 10. The rolloff for the FIR filter used for decimation will be 10% of total bandwidth (as of parameter 0.05 is 10% of 0.5). Hamming window will be used for windowed FIR filter design. - We decimate the signal by a factor of 10. The rolloff for the FIR filter used for decimation will be 10% of total bandwidth (as of parameter 0.05 is 10% of 0.5). Hamming window will be used for windowed FIR filter design.
- Sample rates look like this:
Sample rates look like this:
2.4 Msps 240 ksps 48 ksps 2.4 Msps 240 ksps 48 ksps
@ -134,33 +135,33 @@ You can use these commands on complex streams, too, as they are only interleaved
Regarding `csdr`, the first command-line parameter is the name of a function, others are the parameters for the given function. Compulsory parameters are noted as `<parameter>`, optional parameters are noted as `[parameter]`. Regarding `csdr`, the first command-line parameter is the name of a function, others are the parameters for the given function. Compulsory parameters are noted as `<parameter>`, optional parameters are noted as `[parameter]`.
Optional parameters have safe defaults, for more info look at the code. Optional parameters have safe defaults, for more info look at the code.
##### `realpart_cf` realpart_cf
It takes the real part of the complex signal, and throws away the imaginary part. It takes the real part of the complex signal, and throws away the imaginary part.
##### `clipdetect_ff` clipdetect_ff
It clones the signal (the input and the output is the same), but it prints a warning on `stderr` if any sample value is out of the -1.0 ... 1.0 range. It clones the signal (the input and the output is the same), but it prints a warning on `stderr` if any sample value is out of the -1.0 ... 1.0 range.
##### `limit_ff [max_amplitude]` limit_ff [max_amplitude]
The input signal amplitude will not be let out of the `-max_amplitude ... max_amplitude` range. The input signal amplitude will not be let out of the `-max_amplitude ... max_amplitude` range.
##### `gain_ff <gain>` gain_ff <gain>
It multiplies all samples by `gain`. It multiplies all samples by `gain`.
##### `clone` clone
It copies the input to the output. It copies the input to the output.
##### `yes_f <to_repeat> [buf_times]` yes_f <to_repeat> [buf_times]
It outputs continously the `to_repeat` float number. It outputs continously the `to_repeat` float number.
If `buf_times` is not given, it never stops. If `buf_times` is not given, it never stops.
Else, after outputing `buf_times` number of buffers (the size of which is stated in the `BUFSIZE` macro), it exits. Else, after outputing `buf_times` number of buffers (the size of which is stated in the `BUFSIZE` macro), it exits.
##### `shift_math_cc <rate>` shift_math_cc <rate>
It shifts the complex spectrum by `rate`. It shifts the complex spectrum by `rate`.
`rate` is a floating point number between -0.5 and 0.5. `rate` is a floating point number between -0.5 and 0.5.
@ -168,56 +169,56 @@ It shifts the complex spectrum by `rate`.
Internally, a sine and cosine wave is generated to perform this function, and this function uses `math.h` for this purpose, which is quite accurate, but not always very fast. Internally, a sine and cosine wave is generated to perform this function, and this function uses `math.h` for this purpose, which is quite accurate, but not always very fast.
##### `shift_addition_cc <rate>` shift_addition_cc <rate>
Operation is the same as with `shift_math_cc`. Operation is the same as with `shift_math_cc`.
Internally, this function uses trigonometric addition formulas to generate sine and cosine, which is a bit faster. (About 4 times on the machine I have tested it on.) Internally, this function uses trigonometric addition formulas to generate sine and cosine, which is a bit faster. (About 4 times on the machine I have tested it on.)
##### `shift_addition_cc_test` shift_addition_cc_test
This function was used to test the accuracy of the method above. This function was used to test the accuracy of the method above.
##### `dcblock_ff` dcblock_ff
This is a DC blocking IIR filter. This is a DC blocking IIR filter.
##### `fastdcblock_ff` fastdcblock_ff
This is a DC blocker that works based on the average of the buffer. This is a DC blocker that works based on the average of the buffer.
##### `fmdemod_atan_cf` fmdemod_atan_cf
It is an FM demodulator that internally uses the `atan` function in `math.h`, so it is not so fast. It is an FM demodulator that internally uses the `atan` function in `math.h`, so it is not so fast.
##### `fmdemod_quadri_cf` fmdemod_quadri_cf
It is an FM demodulator that is based on the quadri-correlator method, and it can be effectively auto-vectorized, so it should be faster. It is an FM demodulator that is based on the quadri-correlator method, and it can be effectively auto-vectorized, so it should be faster.
##### `fmdemod_quadri_novect_cf` fmdemod_quadri_novect_cf
It has more easily understandable code than the previous one, but can't be auto-vectorized. It has more easily understandable code than the previous one, but can't be auto-vectorized.
##### `deemphasis_wfm_ff <sample_rate> <tau>` deemphasis_wfm_ff <sample_rate> <tau>
It does de-emphasis with the given RC time constant `tau`. It does de-emphasis with the given RC time constant `tau`.
Different parts of the world use different pre-emphasis filters for FM broadcasting. Different parts of the world use different pre-emphasis filters for FM broadcasting.
In Europe, `tau` should be chosen as `50e-6`, and in the USA, `tau` should be `75e-6`. In Europe, `tau` should be chosen as `50e-6`, and in the USA, `tau` should be `75e-6`.
##### `deemphasis_nfm_ff <one_of_the_predefined_sample_rates>` deemphasis_nfm_ff <one_of_the_predefined_sample_rates>
It does de-emphasis on narrow-band FM for communication equipment (e.g. two-way radios). It does de-emphasis on narrow-band FM for communication equipment (e.g. two-way radios).
It uses fixed filters so it works only on predefined sample rates, for the actual list of them run: `cat libcsdr.c | grep DNFMFF_ADD_ARRAY` It uses fixed filters so it works only on predefined sample rates, for the actual list of them run: `cat libcsdr.c | grep DNFMFF_ADD_ARRAY`
##### `amdemod_cf` amdemod_cf
It is an AM demodulator that uses `sqrt`. On some architectures `sqrt` can be directly calculated by dedicated CPU instructions, but on others it may be slower. It is an AM demodulator that uses `sqrt`. On some architectures `sqrt` can be directly calculated by dedicated CPU instructions, but on others it may be slower.
##### `amdemod_estimator_cf` amdemod_estimator_cf
It is an AM demodulator that uses an estimation method that is faster but less accurate than `amdemod_cf`. It is an AM demodulator that uses an estimation method that is faster but less accurate than `amdemod_cf`.
##### `firdes_lowpass_f <cutoff_rate> <length> [window [--octave]]` firdes_lowpass_f <cutoff_rate> <length> [window [--octave]]
Low-pass FIR filter design function to output real taps, with a `cutoff_rate` proportional to the sampling frequency, using the windowed sinc filter design method. Low-pass FIR filter design function to output real taps, with a `cutoff_rate` proportional to the sampling frequency, using the windowed sinc filter design method.
`cutoff_rate` can be between 0 and 0.5. `cutoff_rate` can be between 0 and 0.5.
@ -231,40 +232,40 @@ Some functions (below) require the `transition_bw` to be given instead of filter
The `--octave` parameter lets you directly view the filter response in `octave`. For more information, look at the [Usage by example] section. The `--octave` parameter lets you directly view the filter response in `octave`. For more information, look at the [Usage by example] section.
##### `firdes_bandpass_c <low_cut> <high_cut> <length> [window [--octave]]` firdes_bandpass_c <low_cut> <high_cut> <length> [window [--octave]]
Band-pass FIR filter design function to output complex taps. Band-pass FIR filter design function to output complex taps.
`low_cut` and ` high_cut` both may be between -0.5 and 0.5, and are also proportional to the sampling frequency. `low_cut` and ` high_cut` both may be between -0.5 and 0.5, and are also proportional to the sampling frequency.
Other parameters were explained above at `firdes_lowpass_f`. Other parameters were explained above at `firdes_lowpass_f`.
##### `fir_decimate_cc <decimation_factor> [transition_bw [window]]` fir_decimate_cc <decimation_factor> [transition_bw [window]]
It is a decimator that keeps one sample out of `decimation_factor` samples. It is a decimator that keeps one sample out of `decimation_factor` samples.
To avoid aliasing, it runs a filter on the signal and removes spectral components above `0.5 × nyquist_frequency × decimation_factor`. To avoid aliasing, it runs a filter on the signal and removes spectral components above `0.5 × nyquist_frequency × decimation_factor`.
`transition_bw` and `window` are the parameters of the filter. `transition_bw` and `window` are the parameters of the filter.
##### `rational_resampler_ff <interpolation> <decimation> [transition_bw [window]]` rational_resampler_ff <interpolation> <decimation> [transition_bw [window]]
It is a resampler that takes integer values of `interpolation` and `decimation`. It is a resampler that takes integer values of `interpolation` and `decimation`.
The output sample rate will be `interpolation / decimation × input_sample_rate`. The output sample rate will be `interpolation / decimation × input_sample_rate`.
`transition_bw` and `window` are the parameters of the filter. `transition_bw` and `window` are the parameters of the filter.
##### `fractional_decimator_ff <decimation_rate> [transition_bw [window]]` fractional_decimator_ff <decimation_rate> [transition_bw [window]]
It can decimate by a floating point ratio. It can decimate by a floating point ratio.
`transition_bw` and `window` are the parameters of the filter. `transition_bw` and `window` are the parameters of the filter.
#### `bandpass_fir_fft_cc <low_cut> <high_cut> <transition_bw> [window]` bandpass_fir_fft_cc <low_cut> <high_cut> <transition_bw> [window]
It performs a bandpass FIR filter on complex samples, using FFT and the overlap-add method. It performs a bandpass FIR filter on complex samples, using FFT and the overlap-add method.
Parameters are described under `firdes_bandpass_c` and `firdes_lowpass_f`. Parameters are described under `firdes_bandpass_c` and `firdes_lowpass_f`.
##### `agc_ff [hang_time [reference [attack_rate [decay_rate [max_gain [attack_wait [filter_alpha]]]]]]]` agc_ff [hang_time [reference [attack_rate [decay_rate [max_gain [attack_wait [filter_alpha]]]]]]]
It is an automatic gain control function. It is an automatic gain control function.
@ -278,11 +279,11 @@ It is an automatic gain control function.
Its default parameters work best for an audio signal sampled at 48000 Hz. Its default parameters work best for an audio signal sampled at 48000 Hz.
##### `fastagc_ff [block_size [reference]]` fastagc_ff [block_size [reference]]
It is a faster AGC that linearly changes the gain, taking the highest amplitude peak in the buffer into consideration. Its output will never exceed `-reference ... reference`. It is a faster AGC that linearly changes the gain, taking the highest amplitude peak in the buffer into consideration. Its output will never exceed `-reference ... reference`.
##### `fft_cc <fft_size> <out_of_every_n_samples> [window [--octave] [--benchmark]]` fft_cc <fft_size> <out_of_every_n_samples> [window [--octave] [--benchmark]]
It performs an FFT on the first `fft_size` samples out of `out_of_every_n_samples`, thus skipping `out_of_every_n_samples - fft_size` samples in the input. It performs an FFT on the first `fft_size` samples out of `out_of_every_n_samples`, thus skipping `out_of_every_n_samples - fft_size` samples in the input.
@ -290,12 +291,12 @@ It can draw the spectrum by using `--octave`, for more information, look at the
FFTW can be faster if we let it optimalize a while before starting the first transform, hence the `--benchmark` switch. FFTW can be faster if we let it optimalize a while before starting the first transform, hence the `--benchmark` switch.
##### `fft_benchmark <fft_size> <fft_cycles> [--benchmark]` fft_benchmark <fft_size> <fft_cycles> [--benchmark]
It measures the time taken to process `fft_cycles` transforms of `fft_size`. It measures the time taken to process `fft_cycles` transforms of `fft_size`.
It lets FFTW optimalize if used with the `--benchmark` switch. It lets FFTW optimalize if used with the `--benchmark` switch.
##### `lowpower_cf [add_db]` lowpower_cf [add_db]
Calculates `10*log10(i^2+q^2)+add_db` for the input complex samples. It is useful for drawing power spectrum graphs. Calculates `10*log10(i^2+q^2)+add_db` for the input complex samples. It is useful for drawing power spectrum graphs.
@ -303,7 +304,7 @@ Calculates `10*log10(i^2+q^2)+add_db` for the input complex samples. It is usefu
Some parameters can be changed while the `csdr` process is running. To achieve this, some `csdr` functions have special parameters. You have to supply a fifo previously created by the `mkfifo` command. Processing will only start after the first control command has been received by `csdr` over the FIFO. Some parameters can be changed while the `csdr` process is running. To achieve this, some `csdr` functions have special parameters. You have to supply a fifo previously created by the `mkfifo` command. Processing will only start after the first control command has been received by `csdr` over the FIFO.
##### `shift_addition_cc --fifo <fifo_path>` shift_addition_cc --fifo <fifo_path>
By writing to the given FIFO file with the syntax below, you can control the shift rate: By writing to the given FIFO file with the syntax below, you can control the shift rate:
@ -313,7 +314,7 @@ E.g. you can send `-0.3\n`
Processing will only start after the first control command has been received by `csdr` over the FIFO. Processing will only start after the first control command has been received by `csdr` over the FIFO.
##### `bandpass_fir_fft_cc --fifo <fifo_path> <transition_bw> [window]` bandpass_fir_fft_cc --fifo <fifo_path> <transition_bw> [window]
By writing to the given FIFO file with the syntax below, you can control the shift rate: By writing to the given FIFO file with the syntax below, you can control the shift rate:
@ -327,8 +328,9 @@ E.g. you can send `-0.05 0.02\n`
Licensing Licensing
--------- ---------
Before the implementation of some algoritms, GPL-licensed code from other applications have been reviewed. Most of the code for `libcsdr` is under BSD license.
[link](#licensing) However, before the implementation of some algoritms, GPL-licensed code from other applications have been reviewed.
In order to eliminate any licesing issues, these parts are placed under a different file. In order to eliminate any licesing issues, these parts are placed under a different file.
However, the library is still fully functional with BSD-only code, altough having only less-optimized versions of some algorithms. However, the library is still fully functional with BSD-only code, altough having only less-optimized versions of some algorithms.
It should also be noted that if you compile with `-DUSE_FFTW` and `-DLIBCSDR_GPL` (as default), the GPL license would apply on the whole result. It should also be noted that if you compile with `-DUSE_FFTW` and `-DLIBCSDR_GPL` (as default), the GPL license would apply on the whole result.