openwebrx-clone/README.md

OpenWebRX
=========

OpenWebRX is a multi-user SDR receiver software with a web interface.

![OpenWebRX](/screenshot.png?raw=true)

It has the following features:

- <a href="https://github.com/simonyiszk/csdr">libcsdr</a> based demodulators (AM/FM/SSB),
- filter passband can be set from GUI,
- waterfall display can be shifted back in time,
- it extensively uses HTML5 features like WebSocket, Web Audio API, and &lt;canvas&gt;.
- it works in Google Chrome, Chromium (above version 37) and Mozilla Firefox (above version 28),
- currently only supports RTL-SDR, but other SDR hardware may be easily added.

**News (2015-08-18)**
- My BSc. thesis written on OpenWebRX is <a href="http://openwebrx.org/bsc-thesis.pdf">available here.</a>
- Several bugs were fixed to improve reliability and stability.
- OpenWebRX now supports compression of audio and waterfall stream, so the required network uplink bandwidth has been decreased from 2 Mbit/s to about 200 kbit/s per client! (Measured with the default settings. It is also dependent on `fft_size`.)
- OpenWebRX now uses <a href="https://github.com/simonyiszk/csdr#sdrjs">sdr.js</a> (*libcsdr* compiled to JavaScript) for some client-side DSP tasks. 
- Receivers can now be listed on <a href="http://sdr.hu/">sdr.hu</a>.
- License for OpenWebRX is now Affero GPL v3. 

**News (2015-02-14)**
- The DDC in *csdr* has been [manually optimized](https://github.com/simonyiszk/csdr/blob/2b54054a9f5de9a908ee075b488a5ee74f41ba18/libcsdr.c#L300) for ARM NEON, so it runs around 3 times faster on the Raspberry Pi 2 than before. 
- Also we use *ncat* instead of *rtl_mus*, and it is 3 times faster.
- OpenWebRX now supports URLs like: `http://localhost:8073/#freq=145555000,mod=usb`
- UI improvements were made, thanks to John Seamons and Gnoxter.

> When upgrading OpenWebRX, please make sure that you upgrade *csdr*, and install the new (optional) dependency *ncat*!

## OpenWebRX servers on sdr.hu

[sdr.hu](http://sdr.hu) is a site which lists the active, public OpenWebRX servers. Your receiver [can also be part of it](http://sdr.hu/openwebrx), if you want.

![sdr.hu](/screenshot-sdrhu.png?raw=true)

## Setup

OpenWebRX currently requires Linux and python 2.7 to run. 

First you will need to install the dependencies:

- <a href="https://github.com/simonyiszk/csdr">libcsdr</a>
- <a href="http://sdr.osmocom.org/trac/wiki/rtl-sdr">rtl-sdr</a>
- ncat (On Debian/Ubuntu, it is in the *nmap* package). 

> By the way, *nmap* is a tool commonly used for auditing network security, and it is not used by OpenWebRX in any way. We need to install it, because the *ncat* command is packaged with it.
>
> *ncat* is a better *netcat* alternative, which is used by OpenWebRX for internally distributing the I/Q data stream. It also solves the problem of having different versions of *netcat* on different Linux distributions, which are not compatible by their command-line arguments.

After cloning this repository and connecting an RTL-SDR dongle to your computer, you can run the server:

	python openwebrx.py

You can now open the GUI at <a href="http://localhost:8073">http://localhost:8073</a>.

Please note that the server is also listening on the following ports (on localhost only):

- port 4951 for the multi-user I/Q server.

Now the next step is to customize the parameters of your server in `config_webrx.py`.

Actually, if you do something cool with OpenWebRX (or just have a problem), please drop me a mail:  
*Andras Retzler, HA7ILM &lt;randras@sdr.hu&gt;*

## Usage tips

You can zoom the waterfall display by the mouse wheel. You can also drag the waterfall to pan across it.

The filter envelope can be dragged at its ends and moved around to set the passband.

However, if you hold down the shift key, you can drag the center line (BFO) or the whole passband (PBS).

## Configuration tips

Now we have a %[Wiki](https://github.com/simonyiszk/openwebrx/wiki) with some how-tos. However, some quick tips:

If you want to run OpenWebRX on a remote server instead of localhost, do not forget to set *server_hostname* in `config_webrx.py`.

DSP CPU usage can be fine-tuned in `plugins/dsp/csdr/plugin.py`: you can set transition bandwidths higher (thus degrade filter performance by decreasing the length of the kernel, but also decrease CPU usage), and also set `fft_size` lower.

If you want a chat-box to the top of the page, <a href="https://gist.github.com/ha7ilm/15c4c5e4c80cef9b3144">here is a snippet</a> for you to include in `config_webrx.py`.
initial commit 2014-11-29 00:07:10 +00:00			`OpenWebRX`
Initial commit 2014-11-28 20:55:31 +00:00			`=========`

initial commit 2014-11-29 00:07:10 +00:00			`OpenWebRX is a multi-user SDR receiver software with a web interface.`

screenshot fix, tnx hg2ecz 2014-11-29 17:47:50 +00:00			`![OpenWebRX](/screenshot.png?raw=true)`
initial commit 2014-11-29 00:07:10 +00:00
			`It has the following features:`

			`- <a href="https://github.com/simonyiszk/csdr">libcsdr</a> based demodulators (AM/FM/SSB),`
readme fixes 2014-11-29 00:10:36 +00:00			`- filter passband can be set from GUI,`
initial commit 2014-11-29 00:07:10 +00:00			`- waterfall display can be shifted back in time,`
readme fixes 2014-11-29 00:10:36 +00:00			`- it extensively uses HTML5 features like WebSocket, Web Audio API, and <canvas>.`
initial commit 2014-11-29 00:07:10 +00:00			`- it works in Google Chrome, Chromium (above version 37) and Mozilla Firefox (above version 28),`
			`- currently only supports RTL-SDR, but other SDR hardware may be easily added.`

Added some features. 2015-09-30 14:06:30 +00:00			`News (2015-08-18)`
many fixes and new features like IMA ADPCM compression 2015-08-17 18:32:58 +00:00			`- My BSc. thesis written on OpenWebRX is <a href="http://openwebrx.org/bsc-thesis.pdf">available here.</a>`
			`- Several bugs were fixed to improve reliability and stability.`
			- OpenWebRX now supports compression of audio and waterfall stream, so the required network uplink bandwidth has been decreased from 2 Mbit/s to about 200 kbit/s per client! (Measured with the default settings. It is also dependent on `fft_size`.)
fixed named anchor in readme 2015-08-17 18:53:48 +00:00			`- OpenWebRX now uses <a href="https://github.com/simonyiszk/csdr#sdrjs">sdr.js</a> (libcsdr compiled to JavaScript) for some client-side DSP tasks.`
fix comments & readme 2015-08-18 15:22:49 +00:00			`- Receivers can now be listed on <a href="http://sdr.hu/">sdr.hu</a>.`
many fixes and new features like IMA ADPCM compression 2015-08-17 18:32:58 +00:00			`- License for OpenWebRX is now Affero GPL v3.`

Fix things in the readme, added inactive.html for issue/22 2016-02-14 17:19:32 +00:00			`News (2015-02-14)`
Update README.md 2016-02-14 17:51:22 +00:00			`- The DDC in csdr has been [manually optimized](https://github.com/simonyiszk/csdr/blob/2b54054a9f5de9a908ee075b488a5ee74f41ba18/libcsdr.c#L300) for ARM NEON, so it runs around 3 times faster on the Raspberry Pi 2 than before.`
			`- Also we use ncat instead of rtl_mus, and it is 3 times faster.`
Update README.md again. 2016-02-14 17:53:06 +00:00			- OpenWebRX now supports URLs like: `http://localhost:8073/#freq=145555000,mod=usb`
Update README.md 2016-02-14 17:51:22 +00:00			`- UI improvements were made, thanks to John Seamons and Gnoxter.`
Added some features. 2015-09-30 14:06:30 +00:00
Fix things in the readme, added inactive.html for issue/22 2016-02-14 17:19:32 +00:00			`> When upgrading OpenWebRX, please make sure that you upgrade csdr, and install the new (optional) dependency ncat!`
Removed rtl_mus in favor of ncat. 2016-01-23 23:03:08 +00:00
Fix README 2016-02-14 17:23:34 +00:00			`## OpenWebRX servers on sdr.hu`

Fix README 2016-02-14 17:28:12 +00:00			`[sdr.hu](http://sdr.hu) is a site which lists the active, public OpenWebRX servers. Your receiver [can also be part of it](http://sdr.hu/openwebrx), if you want.`
Fix things in the readme, added inactive.html for issue/22 2016-02-14 17:19:32 +00:00
			`![sdr.hu](/screenshot-sdrhu.png?raw=true)`
Added some features. 2015-09-30 14:06:30 +00:00
initial commit 2014-11-29 00:07:10 +00:00			`## Setup`

insert shebang, fix readme 2014-11-29 17:50:25 +00:00			`OpenWebRX currently requires Linux and python 2.7 to run.`
initial commit 2014-11-29 00:07:10 +00:00
			`First you will need to install the dependencies:`
initial commit 2014-11-29 00:07:47 +00:00
initial commit 2014-11-29 00:07:10 +00:00			`- <a href="https://github.com/simonyiszk/csdr">libcsdr</a>`
			`- <a href="http://sdr.osmocom.org/trac/wiki/rtl-sdr">rtl-sdr</a>`
Removed rtl_mus in favor of ncat. 2016-01-23 23:03:08 +00:00			`- ncat (On Debian/Ubuntu, it is in the nmap package).`

Fix README 2016-02-14 17:26:00 +00:00			`> By the way, nmap is a tool commonly used for auditing network security, and it is not used by OpenWebRX in any way. We need to install it, because the ncat command is packaged with it.`
Removed rtl_mus in favor of ncat. 2016-01-23 23:03:08 +00:00			`>`
			`> ncat is a better netcat alternative, which is used by OpenWebRX for internally distributing the I/Q data stream. It also solves the problem of having different versions of netcat on different Linux distributions, which are not compatible by their command-line arguments.`
initial commit 2014-11-29 00:07:10 +00:00
			`After cloning this repository and connecting an RTL-SDR dongle to your computer, you can run the server:`

			`python openwebrx.py`

			`You can now open the GUI at <a href="http://localhost:8073">http://localhost:8073</a>.`

readme fixes 2014-11-29 00:12:17 +00:00			`Please note that the server is also listening on the following ports (on localhost only):`
initial commit 2014-11-29 00:07:47 +00:00
initial commit 2014-11-29 00:07:10 +00:00			`- port 4951 for the multi-user I/Q server.`

			Now the next step is to customize the parameters of your server in `config_webrx.py`.

readme fixes 2014-11-29 00:13:15 +00:00			`Actually, if you do something cool with OpenWebRX (or just have a problem), please drop me a mail:`
readme fixes 2014-11-29 00:13:38 +00:00			`Andras Retzler, HA7ILM <randras@sdr.hu>`
readme fixes 2014-11-29 00:13:15 +00:00
initial commit 2014-11-29 00:07:10 +00:00			`## Usage tips`

readme fixes 2014-11-29 13:09:03 +00:00			`You can zoom the waterfall display by the mouse wheel. You can also drag the waterfall to pan across it.`
readme tips fix 2014-11-29 13:05:39 +00:00
initial commit 2014-11-29 00:07:47 +00:00			`The filter envelope can be dragged at its ends and moved around to set the passband.`
initial commit 2014-11-29 00:07:10 +00:00
readme fixes 2014-11-29 13:09:03 +00:00			`However, if you hold down the shift key, you can drag the center line (BFO) or the whole passband (PBS).`
initial commit 2014-11-29 00:07:47 +00:00
added ddc_transition_bw() 2014-11-29 12:56:56 +00:00			`## Configuration tips`

Added some features. 2015-09-30 14:06:30 +00:00			`Now we have a %[Wiki](https://github.com/simonyiszk/openwebrx/wiki) with some how-tos. However, some quick tips:`
added ddc_transition_bw() 2014-11-29 12:56:56 +00:00
Added some features. 2015-09-30 14:06:30 +00:00			If you want to run OpenWebRX on a remote server instead of localhost, do not forget to set server_hostname in `config_webrx.py`.
readme fix 2014-11-30 17:00:53 +00:00
Added some features. 2015-09-30 14:06:30 +00:00			DSP CPU usage can be fine-tuned in `plugins/dsp/csdr/plugin.py`: you can set transition bandwidths higher (thus degrade filter performance by decreasing the length of the kernel, but also decrease CPU usage), and also set `fft_size` lower.
readme fix 2014-11-30 17:00:53 +00:00
readme fix 2014-11-30 18:22:21 +00:00			If you want a chat-box to the top of the page, <a href="https://gist.github.com/ha7ilm/15c4c5e4c80cef9b3144">here is a snippet</a> for you to include in `config_webrx.py`.