FIXME **This page is not fully translated, yet. Please help completing the translation.**\\ //(remove this paragraph once the translation is finished)//

====== PySDR ======

PySDR is a software dedicated to display a live waterfall (spectrogram) from a data stream provided via a unix pipe or JACK audio system.
The tool is useful for tuning [[http://wiki.bolidozor.cz/doku.php?id=en:rmds|Bolidozor detection stations]]. Data visualisation for audience should be provided by [[en:freya|Freya]] tool.

===== Basic properties =====

  * OpenGL graphic acceleration
  * A possibility to connect Jacku
  * A possibility to run detection scripts
  * Dynamic scaling using a mouse 


{{youtube>UKHGVK75AGA?medium}}

{{:cs:pysdr:pysdr_detector.png?500|PySDR with a detection script.}}


You can see other screenshots on the following pictures.

{{gallery>:cs:pysdr?2&lightbox }}

==== Programme control ====

After downloading and installing the programme according to readme (found on Github) and launching jack (e.g. via qjackctl), the programme can be launched from a working directory using:

  ./pysdr-waterfall

A window opens, and if there is a data source connected, it will contain a spectrogram. The spectrogram can be moved using a left mouse button and zoomed using a right one.

=== Keyboard shortcuts ===

Applicable anytime when the PySDR is running

  * **~** activates Python console (in a Quake style)
  * **t** textureshot - saving a texture of a whole waterfall
  * **s** screenshot - saving a current image on display 

=== Command line parameters ===

Using: waterfall.py [-h] [-b BINS] [-j NAME] [-r RATE] [-o OVERLAP] [-d FILENAME]

Optional arguments:
  * **-h, --help **  shows help and ends
  * **-b BINS, --bins BINS**  setting the number of FFT bins (default: 4096)
  * **-H HEIGHT --height**  height of displayed spectrogram in seconds 
  * **-j NAME, --jack NAME**  naming the (?? přípojky) generated in JACK
  * **-r RATE, --raw RATE**   expects a signal from a standard input with a defined sampling speed
  * **-o OVERLAP, --overlap OVERLAP** ratio of FFT windows overlap (default: 0.75)
  * **-d FILENAME, --detector FILENAME**  file with a detection script


===== Installation =====

==== Ubuntu ====

Install the necessary dependencies:

  sudo apt-get install python-numpy python-opengl python-dev libjack-jackd2-dev

Download the source codes from [[https://github.com/MLAB-project/pysdr|Githubu]] 

  git clone https://github.com/MLAB-project/pysdr.git
  cd pysdr
  
Translate the computationally demanding parts written in C:

  python setup.py build_ext --inplace

Run the PySDR using:

  ./pysdr-waterfall

===== Audible output =====

In order to generate audio signal from RF signal received by a station we created a special programme **whistle** that processes audio input from jack and transforms it into an audible output. It is available at [[https://github.com/MLAB-project/pysdr/tree/sound|Github]], at the same repository as pySDR.

==== Using Whistle ====

Whistle is a configurable signal generator. Various operations can be stack one after another. It is like a very small GNURadio that runs inside the JACK’s callback. It is capable of Kaiser-Bessel [[https://en.wikipedia.org/wiki/Finite_impulse_response|FIR filter]] (entered as "kbfir, filter order, Fa, Fb, suppression in rejected bands (??) potlačení v nepropustném pásmu) in dB”), where Fa til Fb represent the frequency range of bandpass), frequency shift ("freqx, shift in Hz"), amplification ("amplify, amplification factor"), FM demodulation ("fmdemod"). The individual operations are merged using colon and passed to -p parameter.

An example:

  ./whistle -p freqx,-10000:kbfir,41,0,1000,100:freqx,1000:amplify,100

for listening to meteors. This sequence of operation is set as default if nothing is passed to -p.

  ./whistle -p freqx,-31800:kbfir,201,0,400,200:freqx,500:amplify,200
  
Before the FIR filter calculation, the signal is shifted down by 31.8 kHz. 

A FIR is calculated - 201 taps.

Bandpass from 0 Hz til 400 Hz. Attenuation 200 dB.

Filter output is shifted up by 500 Hz.

Output is increased 200x.

==== Principle of operation ====

The programme performs a frequency conversion by a complex multiplication of signal with a local number oscillator. This causes a frequency shift of the meteor reflection to lower frequencies which are audible. 

===== Playback from audio file =====

  sox SVAK1_1386323982726.wav -c 2 -t f32 -r 44100 - repeat 20 | jack-stdin pysdr:input_i pysdr:input_q -e float
  
==== Socket connection ====

PySDR can be connected to RMDS02D station directly using netcat, e.g.:

  nc radio-TEST.local 3701 | ./pysdr-waterfall -r 96000

where radio-TEST.local is the station’s network name. In case of running pysdr directly on a station, the name is localhost.