diff --git a/README.md b/README.md index 776b27d..f4cb33d 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ libcsdr ======= -*libcsdr* is a set of simple DSP routines for Software Defined Radio. -It is mostly useful for AM/FM/SSB demodulation and spectrum display. -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]. +*libcsdr* is a set of simple DSP routines for Software Defined Radio. +It is mostly useful for AM/FM/SSB demodulation and spectrum display. +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. - 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. @@ -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 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. -- Sample rates look like this: + +Sample rates look like this: 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 ``, optional parameters are noted as `[parameter]`. 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. -##### `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. -##### `limit_ff [max_amplitude]` + limit_ff [max_amplitude] The input signal amplitude will not be let out of the `-max_amplitude ... max_amplitude` range. -##### `gain_ff ` + gain_ff It multiplies all samples by `gain`. -##### `clone` + clone It copies the input to the output. -##### `yes_f [buf_times]` + yes_f [buf_times] It outputs continously the `to_repeat` float number. 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. -##### `shift_math_cc ` + shift_math_cc It shifts the complex spectrum by `rate`. `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. -##### `shift_addition_cc ` + shift_addition_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.) -##### `shift_addition_cc_test` + shift_addition_cc_test This function was used to test the accuracy of the method above. -##### `dcblock_ff` + dcblock_ff 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. -##### `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. -##### `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. -##### `fmdemod_quadri_novect_cf` + fmdemod_quadri_novect_cf It has more easily understandable code than the previous one, but can't be auto-vectorized. -##### `deemphasis_wfm_ff ` + deemphasis_wfm_ff It does de-emphasis with the given RC time constant `tau`. 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`. -##### `deemphasis_nfm_ff ` + deemphasis_nfm_ff 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` -##### `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. -##### `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`. -##### `firdes_lowpass_f [window [--octave]]` + firdes_lowpass_f [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. `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. -##### `firdes_bandpass_c [window [--octave]]` + firdes_bandpass_c [window [--octave]] 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. Other parameters were explained above at `firdes_lowpass_f`. -##### `fir_decimate_cc [transition_bw [window]]` + fir_decimate_cc [transition_bw [window]] 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`. `transition_bw` and `window` are the parameters of the filter. -##### `rational_resampler_ff [transition_bw [window]]` + rational_resampler_ff [transition_bw [window]] It is a resampler that takes integer values of `interpolation` and `decimation`. The output sample rate will be `interpolation / decimation × input_sample_rate`. `transition_bw` and `window` are the parameters of the filter. -##### `fractional_decimator_ff [transition_bw [window]]` + fractional_decimator_ff [transition_bw [window]] It can decimate by a floating point ratio. `transition_bw` and `window` are the parameters of the filter. -#### `bandpass_fir_fft_cc [window]` + bandpass_fir_fft_cc [window] 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`. -##### `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. @@ -278,11 +279,11 @@ It is an automatic gain control function. 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`. -##### `fft_cc [window [--octave] [--benchmark]]` + fft_cc [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. @@ -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. -##### `fft_benchmark [--benchmark]` + fft_benchmark [--benchmark] It measures the time taken to process `fft_cycles` transforms of `fft_size`. 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. @@ -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. -##### `shift_addition_cc --fifo ` + shift_addition_cc --fifo 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. -##### `bandpass_fir_fft_cc --fifo [window]` + bandpass_fir_fft_cc --fifo [window] 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 --------- -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. -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.