This document is about OpenWebRX+, an improved and extended version of the original OpenWebRX web-based SDR radio. Since the original project is missing such necessary features as noise reduction, tuning steps, and support for many digital modes, I have decided to fork it and add the features considered necessary, interesting, or simply widely requested by the public.
Please note that the following document covers both the original OpenWebRX and the extended OpenWebRX+. Features specific to OpenWebRX+ are marked so.
Binary packages for the latest Ubuntu and Debian Linux can be installed from this package repository. Please, carefully read the instructions there before trying to install. The correct installation should completely and cleanly replace the original OpenWebRX packages, if they are installed on your system.
The source code is available from my Github account. Most development happens in the "master" branches of the relevant repos, such as csdr, pycsdr, owrx_connector, and openwebrx. Some packages are reused from the "master" branches of the original OpenWebRX repos without changes.
News and announcements are posted to a Telegram channel. The support and discussion occurs in a Telegram chat.
Since OpenWebRX is a server designed to share SDR resources among multiple users, its operation is somewhat different from regular SDR applications. This section explains the basics of OpenWebRX usage, including the main display and controls.
The scrolling waterfall shows the band activity in your currently selected SDR profile. The waterfall colors represent signal levels at each frequency, with brighter colors corresponding to stronger signals. Thus, a strong, healthy, ongoing signal will look like a bright vertical stripe at the waterfall. Different signal modulations produce differently shaped stripes. See Signal Identification Guide for examples.
The frequency scale shows the actual frequencies, as well as the currently tuned frequency, represented with the yellow caret. This is the frequency you are currently listening to. The numbers at the caret sides stand for the current filter bounds. You can change these bounds by dragging the caret sides.
The spectrum display, found in OpenWebRX+, shows the current signal level at each frequency, as opposed to the historic level shown by the waterfall. The spectrum display has a little bit of latency, to make sure that short signals still leave their mark on the spectrum.
The step-tuning buttons let you tune up and down the frequency scale by left-clicking them. With the "side-stepping" feature enabled, you can also right-click these buttons to step outside your currently selected profile.
The bookmarks let you quickly tune to previously bookmarked frequencies. There are three types of bookmarks in OpenWebRX:
The receiver information is shown by clicking the icon at the top-left page corner. This information is filled in by the administrator and includes receiver's name, location and the hardware description.
The Status button toggles the status bar shown at the bottom of the receiver web page.
The Chat button toggles the log and chat panel shown at the bottom of the receiver web page. If the administrator has chosen to disable chat functionality, this button will turn into Log, opening the non-interactive log panel instead.
The Receiver button toggles the main control panel for the receiver.
The Map button opens the map page showing radio stations, repeaters, other online receivers, and position reports from various sources, such as airplanes, ships, and HAM operators.
The Files button opens the file browser page with the most recently received SSTV images, faxes, and other data.
The Settings button opens the password protected settings page for configuring OpenWebRX. Normally, only server adminstrator needs to access the server settings.
The status bar at the bottom of receiver's page displays the current status of the server and its connection to your web browser. Various panels show network throughput, server CPU load and temperature, audio sampling rate, and so on.
This is the currently tuned frequency of the receiver. You can change it by clicking on the waterfall, the bookmarks, or by entering it directly into this field. The frequency can only be changed within the current profile bounds.
Click this button to bookmark your current frequency. The new bookmark will be stored locally in your browser and appear as a blue marker above the waterfall.
This is the current profile, including the SDR device name ("RSPdx"). OpenWebRX supports multiple SDR devices with multiple profiles for each device. When selecting a new profile, remember that it will change for all users of the same SDR device, so be considerate when you see somebody else using the server.
This is the list of all available audio modulation modes, with the current mode highlighted in yellow. Select a new mode by clicking corresponding button, but keep in mind that not all modes can be applicable. It helps to know what each modulation looks like on the waterfall. Consult the Signal Identification Guide if unsure.
This button will light up if a digital decoder is active. Click it to toggle digital decoding off.
This is the current digital decoding mode, if active. You can select a new digital decoding mode from the list here, but keep in mind that not all modes can be applicable. It helps to know what each digital mode looks like on the waterfall. Consult the Signal Identification Guide if unsure.
Use this slider to control audio volume. Click the speaker button to mute or unmute audio.
Use this slider to set the squelch threshold. Left-click the SQ button to toggle squelch on and off. When the squelch is on, any audio that is below the selected squelch threshold will be muted.
Right-clicking the SQ button toggles the frequency scanner, making SQ button glow green. The scanner will automatically check all bookmarked frequencies for signals that are above the squelch threshold and tune to them. Once a signal disappears, the scanner will continue checking bookmarks for more signals.
Use this slider to set the noise reduction threshold. Click the NR button to toggle noise reduction on and off. The noise reduction algorithm works on the spectral subtraction principle. It will remove any frequencies that are below the selected threshold from the audio, reducing the background noise. Remember that excessive use of noise reduction may distort or muffle the useful sounds though.
The tuning step selector lets you choose the frequency tuning granularity. For example, if 1kHz step is selected, the frequency will always tune in 1kHz increments. Different profiles may assume different default tuning steps, such as 5kHz for shortwave broadcasters or 500Hz for HAM operators using SSB modulation. Click the adjacent button to reset tuning step to its default value for the current profile.
This slider sets the signal level for the "hottest" waterfall color (usually red). Set it higher when looking at strong signals, lower when looking at weak signals.
Left-click the adjacent button to make a one-time automatic adjustment of the waterfall colors. Right-click the button to toggle continuous automatic adjustment of the waterfall colors.
This slider sets the signal level for the "coldest" waterfall color (usually blue). Set it higher when looking at strong signals, lower when looking at weak signals.
Left-click the adjacent button to reset waterfall colors to their default values.
This drop-down list lets you choose one of the user interface themes. Clicking the adjacent button resets user interface to the default theme.
This slider controls the user interface opacity, making panels more or less visible on top of the waterfall. Click the adjacent button to reset user interface to the full opacity.
The four zoom buttons let you zoom waterfall in and out. Zooming always happens around the currently tuned frequency, keeping it on display.
The clock at the bottom of the main panel shows the current Universal Coordinated Time (UTC). Most of the OpenWebRX user interface operates in UTC, so this clock is shown for easier reference.
Click the REC button to start recording audio at any moment. The button will glow red, indicating ongoing recording. Once you click the REC button again, it will stop recording and save the recorded audio to a file.
The bar at the bottom indicates the current signal level. It will change color based on what OpenWebRX considers signal overload. There is also a numeric readout, showing the exact value in decibels.
This button toggles the live spectrum display above the waterfall. When using it, keep in mind that the spectrum display may make your web browser use a lot of processor power.
OpenWebRX requires the use of the right mouse button. On devices with a single mouse button (such as Apple computers), the right mouse button is simulated by holding the CONTROL key with a mouse click.
On touch-based devices, such as smartphones and tablets, the right mouse button is simulated by holding the spot with your finger for a little bit longer than unusal.
The mouse scroll wheel operates in two modes: normal and modified (with the right mouse button, the wheel button, or the SHIFT key pressed):
In the waterfall:
Normal wheel spin tunes frequency, modified wheel spin changes zoom
factor. This behavior can be reversed with a checkbox found in the
receiver panel.
In the frequency scale:
Both normal and modified wheel spins tune frequency.
At the bandpass filter (yellow caret):
Normal wheel spin shifts filter left or right, modified wheel spin makes
filter wider or narrower.
OpenWebRX+ includes keyboard shortcuts for accessing the most common interface functions. To see the complete list of shortcuts, press the ? key, which opens the following panel:
The OpenWebRX+ includes a frequency scanner that can monitor currently shown bookmarks for activity. When the scanner detects a signal at one of the bookmarked frequencies, it will tune to that frequency. Once that frequency goes quiet, the scanner goes back to monitoring all shown bookmarks. In order to use the scanner, do the following:
Tune to an empty part of the waterfall and left-click the SQ button in order to set the squelch level.
Right-click the SQ button to start scanning. The SQ button will glow green indicating that the scanner is on. Mobile device users can simply hold the button down for a longer time to simulate the right-click.
Once done, right-click the SQ button again to disable the scanner.
Please, keep in mind that the scanner will not work on digital voice channels, since they tend to keep signal on even if there is no actual traffic on a channel.
OpenWebRX+ includes a simple chat that lets connected users talk to each other. The chat panel opens by pressing the Chat button at the top of the receiver web page.
When you send your first chat message by entering it at the bottom of the chat window, OpenWebRX+ will assign you a random nickname, shown to other users next to your messages. To change your name, enter your new nickname at the left of the message input.
The server administrator can disable chat functionality via the settings. When disabled, the Chat button turns into the Log button, with the log panel not accepting any input from users.
OpenWebRX has a map display showing the received data, such as ship and airplane locations, APRS reports, and digital HAM messages. You can reveal the map by clicking the Map button at the top of the browser window.
OpenWebRX+ offers two map types: Google Maps and a collection of free maps based on the Leaflet library. The very popular OpenStreetMap is a part of that collection. You can switch between map types by clicking the Map button at the top of the browser window.
The above image shows OpenWebRX+ Google Maps interface. Aside from the regular navigation controls, this interface presents a toolbox at the left side with toggle switches for different kinds of data. New switches will appear as OpenWebRX receives new kinds of data, such as ship or aircraft positions for example.
The large red marker indicates the receiver location. Colored "locator" squares represent origins of digital HAM transmissions, such as FT8, FT4, or WSPR reports, with each elemental color representing either frequency (when "By Band" selected) or mode (when "By Mode" selected). Individual colors can be clicked on and off in the toolbox.
By clicking on a colored locator square, you can see all the reports received from its location, as shown below. The information bubble also indicates locator's name (using Maidenhead System), its distance from the receiver, and the time last report has been received from this locator.
By clicking on a marker, you can see marker-specific information, such as APRS weather report shown below. The information bubble also indicates marker's name (e.g. HAM callsign), its distance from the receiver, and the last time information has been received about this marker. When relevant, OpenWebRX+ will also indicate the path infomation travelled, as seen at the bottom of the information bubble.
OpenWebRX+ will periodically query ReceiverBook, KiwiSDR, and WebSDR.org sites for other online SDR receivers. These receivers are indicated on the map with ◬ markers, as shown below. Red markers stand for KiwiSDR receivers, green markers correspond to OpenWebRX receivers, while blue markers designate the original WebSDR receivers. Clicking on a marker brings up the general information about the receiver, along with a link to receiver's web page.
Once a day, OpenWebRX+ queries the EiBi database for shortwave broadcast schedules. Currently broadcasting stations are indicated with ⍑ markers on the map, as shown above. Clicking on a station brings up its schedule, with frequencies and broadcast times. OpenWebRX+ will tune to clicked frequencies, as long as they are within the profile you are listening to.
Once a day, OpenWebRX+ queries RepeaterBook.com for the list of repeaters closest to the receiver location. These repeaters are indicated with ⋈ markers on the map, as shown below.
In this section, we will go over some common things you can use OpenWebRX for, such as listening to broadcast radio, HAM operators, and tracking ships and aircraft.
The FM broadcasts generally occur between 76MHz and 108MHz. Each broadcaster is allocated 100kHz of spectrum, unless they are in the US where 200kHz is allocated to each station. FM broadcasts may reach distances up to 100km, limited by the horizon line. If you live in the US, the closest FM stations can be found via the Radio Locator website.
In order to listen to FM broadcasts in OpenWebRX, select a profile containing above frequencies, press the WFM button at the receiver panel, and tune to one of the signals. Please note that OpenWebRX only plays mono sound, so there will not be any stereo.
OpenWebRX also allows to decode textual RDS information sent within FM broadcasts, such as station name, program name and type, and so on. If enabled, this information shows up in a box at the bottom of the waterfall.
Since RDS data is encoded slightly differently in the US, compared to Europe, you may want to go to "Settings | Demodulation and Decoding | Miscellaneous" and change the "Decode USA-specific RDS information from WFM broadcasts" option to reflect your receiver location.
Many American FM broadcasters are now using a form of digital radio known as HDRadio or NRSC5. The HDRadio signal, showing up as two thick "columns" around the traditional WFM signal, adds up to four digital channels to each analog FM broadcast.
HDRadio decoding requires a lot of CPU power and will not work on slower computers, or wide profiles. In order to listen to the HDRadio in OpenWebRX+, tune to the "enhanced" WFM signal and click on the HDR button. Once the decoder syncs with the signal, the station information and the channel selector should show up at the bottom of the waterfall.
Where American broadcasters use HDRadio, European FM broadcasters use a different digital standard known as DAB. Each DAB multiplex signal essentially occupies a single old analog TV channel and transmits many individual radio station signals at once.
DAB decoding requires a lot of CPU power and will not work on slower computers, or wide profiles. In order to listen to DAB in OpenWebRX, tune to the DAB signal and click on the DAB button. Once the decoder syncs with the signal, the station information and the station selector should show up at the bottom of the waterfall.
By "AM", people generally mean radio broadcasts occurring in the LW and MW bands, between 100kHz and 1800kHz. Each station is allocated 10kHz of the spectrum. During the day, AM broadcasts may reach up to 200km, but this distance greatly increases during the night. If you live in the US, the closest AM stations can be found via the Radio Locator website.
In order to listen to AM broadcasts in OpenWebRX, select a profile containing above frequencies, press the AM button at the receiver panel, and tune to one of the signals. If the signal you are interested in is obscured by adjacent signals, try using the SAM button instead. It has the same effect as AM, but uses a different algorithm more resistant to interference.
"Shortwave" describes multiple bands between 1800kHz and 30MHz used by radio broadcasters, amateurs, and professionals alike. The SWL activity generally refers to shortwave broadcast listening though, with brodcasters easily reaching across thousands of kilometers using AM modulation. Global shortwave broadcast schedules can be found at the Shortwave Info and Shortwave Schedule websites.
In order to listen to shortwave broadcasts in OpenWebRX, select a profile containing the shortwave band you are interested in, press the AM button at the receiver panel, and tune to one of the signals. If the signal is obscured by adjacent signals, try using the SAM button instead. It has the same effect as AM, but uses a different algorithm more resistant to interference.
Some shortwave broadcasters have started to use Digital Radio Mondiale (DRM) for their broadcasts. If you see a clearly digital signal at a shortwave band, try tuning to it, pressing the DRM button, and waiting 30-40 seconds for the decoder to sync. DRM broadcasts are somewhat rare at the moment though.
Once a day, OpenWebRX+ queries the EiBi database for shortwave broadcast schedules. Currently broadcasting stations are indicated with ⍑ markers on the map and with bookmarks in the main receiver window.
Citizens Band (CB) generally covers a swath of spectrum between 27MHz and 28MHz, where individuals can communicate without a license, as long as they adhere to a few rules. The exact boundaries of the CB band change from country to country. It sits adjacent to the 10m amateur band.
In most places, the CB band is divided into 40 channels (CB1 to CB40), spaced at 10kHz. OpenWebRX+ provides default bookmarks for these channels. While all analog voice modes (AM, FM, LSB, USB) were originally allowed on CB, the US users generally prefer AM at lower channels and LSB at upper channels. In the UK, where AM has been banned until recently, FM is the most common CB mode.
In order to listen to CB in OpenWebRX, select a profile containing the CB band and tune to one of the signals by clicking on the waterfall or a bookmark. You may then have to press AM, FM, LSB, or USB button at the receiver panel, depending on the modulation type used by the transmission you are listening to.
The amateur radio operators (HAMs) are found at 160m, 80m, 40m, 20m, and a few other shortwave bands. All kinds of activities happen at these bands, from Morse code, to voice, to digital transmissions.
Each amateur band is usually broken into three parts:
Right above the Morse code, there is a bunch of digital transmissions in different formats, such as RTTY, FT8, FT4, and so on. A lot of these formats operate at fixed frequencies, which are included into OpenWebRX band plan and thus show up as green bookmarks.
The rest of a band is allocated for the voice (or "telephone") transmissions using LSB or USB modulation, with some AM sprinkled in. The LSB modulation is used below 20m, while USB is used at 20m and above.
In order to listen to amateur radio operators in OpenWebRX, select a profile containing the HAM band you are interested in, press the LSB or USB button at the receiver panel and tune to one of the signals. While most amateur transmissions occur at 1kHz boundaries, you may have to tune more precisely to get cleaner sound.
Most Morse code (CW) transmissions occur at the lower end of amateur radio bands, such as 3500-3600kHz, 7000-7100kHz, 14000-14100kHz, and so on. To engage the CW mode in OpenWebRX, press the CW button at the receiver panel. In this mode, the bandpass filter shrinks to 700-900Hz range for better selectivity. Also, when in CW mode, OpenWebRX+ will tune 800Hz below clicked carrier frequency, to make sure that the carrier is always heard.
For those who do not understand Morse code, OpenWebRX+ offers automated CW decoding, enabled by selecting the "CW Decoder" digital mode. The CW decoder presents you with a zoomed secondary waterfall that may contain multiple CW signals. Once you click on a CW signal you are interested in, the decoded text will show up below the secondary waterfall, with unrecognized characters shown as underscores.
You can also make the CW decoder show the original dits and dahs it is decoding. To do that, go to "Settings | Demodulation and Decoding | Miscellaneous" and enable the "Show CW codes (dits / dahs) when decoding CW" option.
A teletype transmission consists of two carrier signals, where one signal designates "spaces" (or zeros), while the other signal designates "marks" (or ones). Five bits in a row make a character, encoded with Baudot code. Hence, there are three important parameters describing an RTTY transmission:
Bandwidth (Hz)
This is the distance, in hertz, between two carrier signals. Common
bandwidths are 85Hz, 170Hz, 450Hz, and 650Hz.
Bitrate (baud)
This is the transmission speed, determining how many bits per second are
being sent. Common bitrates are 45bd, 45.45bd, 50bd, 75bd, and 100bd.
Reverse
The "reverse" option, when applied, flips the meanings of "space" and
"mark" frequencies.
OpenWebRX+ comes with three different RTTY settings, selected via digital mode drop-down list:
RTTY-170 (45)
This is the mode commonly used by HAM operators, with 170Hz bandwidth
and 45bd bitrate. You can find transmissions in this mode just above
Morse code transmissions on most HAM HF bands.
RTTY-450 (50N)
This mode is used by the German weather service, most often found at the
10100kHz frequency. OpenWebRX+ includes default (yellow) bookmarks for
this and other German weather RTTY frequencies. This mode uses 450Hz
bandwidth and 50bd bitrate, with "mark" and "space" frequencies
reversed.
RTTY-85 (50N)
This mode is often used at the LF and VLF bands, where available
bandwidth is limited. It has 85Hz bandwidth and 50bd bitrate, with
"mark" and "space" frequencies reversed.
In order to receive a teletype transmission in OpenWebRX+, press the USB button at the receiver panel and tune to an RTTY transmission, which looks like two signals close together. Then select one of the RTTY decoders described above. It will present you with a zoomed secondary waterfall that may contain multiple RTTY signals. Once you click on an RTTY signal you are interested in, the decoded text will show up below the secondary waterfall, with unrecognized characters shown as underscores.
The slow scan television (SSTV) protocol lets radio amateurs exchange small static images over airwaves. Most SSTV frequencies are listed in the OpenWebRX+ band plan and will thus show up as green bookmarks. In order to reliably receive SSTV images in OpenWebRX+, do the following:
Select "SSTV" digital mode and tune exactly 1900Hz below the SSTV carrier frequency, or use any of the provided SSTV bookmarks.
Wait until the next SSTV transmission starts. OpenWebRX+ will not receive partial SSTV transmissions since it needs to obtain the image format information from the transmission header.
The received SSTV images will show up in a separate panel on top of the waterfall display. Click on an image to download it to your computer or mobile device.
The only SSTV formats currently supported by OpenWebRX+ are Robot36, Robot72, Martin1, Martin2, Scottie1, Scottie2, and ScottieDX. Other SSTV formats, including digital SSTV, will not be received.
Today, the HF radio fax protocol is mainly used to broadcast weather maps and related information to vessels at sea. The US National Weather Service regularly publishes weather fax schedules you can use to tune to a nearby fax broadcast. Also, OpenWebRX+ provides default (yellow) bookmarks for most known weather fax frequencies. In order to reliably receive a fax in OpenWebRX+, do the following:
Select "FAX" digital mode and tune exactly 1900Hz below the fax carrier frequency, or use any of the provided fax bookmarks.
Wait until the next fax transmission starts. OpenWebRX+ will not receive partial fax transmissions since it needs to obtain the image format information from the transmission header.
The received fax images will show up in a separate panel on top of the waterfall display. Click on an image to download it to your computer or mobile device.
The fax decoder inside OpenWebRX+ supports 120LPM transmissions in IOC576 and IOC288 formats. As an administrator, you have some control over fax decoding. Following options are available in "Settings | General | Demodulation and Decoding | Fax Transmissions":
Transmission speed
The transmission speed controls how many fax lines per minute the
decoder is going expect. The most common value is 120LPM. Do not
change it unless you are absolutely sure you need a different one.
Post-process received images to reduce noise
When enabled, this option makes fax decoder post-process received images
for better contrast. Some grayscale gradients may get lost as result
though.
Receive color images
This experimental option should allow OpenWebRX+ receive color faxes. It
has not been tested due to lack of samples though.
Use amplitude modulation
This experimental option lets OpenWebRX+ receive faxes encoded using AM
mode, rather than usual USB. So far, it has not been tested due to lack
of samples.
While mostly an outdated technology, wireless pagers are still in use at hospitals, businesses, and for automated reporting. Pager traffic is commonly found at 150-165MHz, as well as other VHF and UHF bands. OpenWebRX+ can decode both POCSAG and FLEX paging protocols at different speeds.
Keep in mind that your local laws may prohibit you from listening to the pager traffic. Please, check before you do!
In order to monitor pager messages in OpenWebRX+, select "Page" digital mode and tune to the exact middle of a pager signal. You will see decoded pager messages in a separate panel on top of the waterfall display.
A lot of pager messages carry numeric or binary data. As an administrator, you can choose to ignore these unreadable messages by going to "Settings | General | Demodulation and Decoding | Miscelaneous" and enabling the "Filter out empty, numeric, or unreadable pager messages" option.
Many modern wireless devices, such as weather stations, security sensors, tire pressure sensors, car keys, etc., use radio frequencies to communicate. These devices are normally found in 433-435MHz, 902-928MHz, and some other bands. In order to monitor smart device transmissions in OpenWebRX+, do the following:
Look around ISM frequencies for signals that may be produced by wireless devices.
Once you see any suspicious signals, tune near them and select the "ISM" digital mode. The ISM decoder will monitor and display a wide swath of spectrum around your tuned frequency.
Wait until the signals reappear. If the ISM decoder is able to understand them, the decoded data will appear in a separate panel on top of the waterfall display.
If you are unable to decode any ISM signals or do not see any on the waterfall, try testing the decoder with your wireless car keys. It is important to know their signalling frequency though.
The Automatic Packet Reporting System (APRS) lets HAM operators exchange digital data, messages, and share their locations with the world. The APRS uses 144.39MHz frequency in the North America, 144.8MHz in Europe. Please note that the OpenWebRX bandplan only has European APRS frequency enabled. If your receiver is in the North America, edit the bandplan to switch to the 144.39MHz frequency.
In order to monitor APRS traffic in OpenWebRX, select "Packet" digital mode and tune to one of the above frequencies. You will see decoded APRS messages in a separate panel on top of the waterfall display. Moreover, the sources of these messages will pop up at the map, shown by clicking the Map button.
OpenWebRX+ bandplan includes one more APRS entry, at 145.825MHz. This is the International Space Station (ISS) frequency. Several times a day, as ISS flies above the receiver location, you can expect to see APRS reports from really far away at this frequency. These reports are retransmitted by the APRS repeater located at the ISS.
Modern vessels report their locations using a VHF radio system known as AIS. If your OpenWebRX+ receiver is located near a large enough body of water, it may be able to receive AIS position reports and display them at the map.
AIS operates at two maritime band frequencies, 161.975MHz and 162.025MHz. Once you select a profile containing these frequencies, you will see them marked with green bookmarks, since they are part of the band plan. Click on an AIS bookmark and a secondary waterfall should appear, together with the information panel showing received position reports.
Now, if you click on the Map button, you should see ship locations on the map. Clicking on a ship pops up a bubble showing some basic information about that ship.
AIS identifies every vessel with a unique number known as MMSI. OpenWebRX+ shows these MMSI numbers, hyperlinking them to the Vessel Finder website, where you can find photos and other facts about each vessel.
Airplanes periodically report their positions in the air using the ADS-B system, at 1090MHz and 978MHz frequencies. OpenWebRX+ can listen to these frequencies and display received flight information to you.
To receive ADS-B transmissions, select a profile containing one of the ADS-B frequencies. Since these transmissions require 2MHz of bandwidth, the profile must have at least 1MHz of bandwidth at each side of the ADS-B frequency.
Standard ADS-B frequencies are part of the OpenWebRX+ band plan and thus marked with green bookmarks. Once you click on an ADS-B bookmark, a panel will appear showing the reported aircraft with their flight data.
If you click on the Map button, you should see aircraft locations on the map. Clicking on an airplane pops up a bubble showing some basic information about that airplane.
Aircraft are identified with several different IDs, including flight ID, aircraft tail number, and ICAO code (aka Mode-S transponder code). OpenWebRX+ will hyperlink received IDs to the FlightAware website, where you can find airplane photos and other facts about each flight.
This section discusses administering an OpenWebRX server and how it can be used besides providing public access to radio waves.
As a server administrator, you can make OpenWebRX server automatically decode radio transmissions when someone is listening to a profile with these transmissions. This feature can be used to receive SSTV images, faxes, monitor digital HAM traffic, track airplanes, and so forth.
To start with background decoding, go to "Settings | Background Decoding", check the "Enable background decoding services" option, and select transmission modes you would like to receive and decode automatically. Make sure you only select the ones you really need, since running too many background decoders will slow your server down, a lot.
Now, go to an SDR device you want to use for background decoding, let us say "Settings | SDR Devices and Profiles | <Device>", and add the "Run background services on this device" option. Once you have added this option, make sure it is enabled.
At this point, every time someone connects and listens to a <Device> profile, OpenWebRX will automatically decode all enabled signal types at frequencies marked with green bookmarks, i.e. everything that is part of the band plan. If the decoded data is an image or a message log, these will be saved to the /tmp folder and shown once you click the Files button. Location reports, such as FT8, WSPR, APRS, and others, will show up on the map, when you click the Map button.
In order to enable background decoding at a frequency that is not part of the band plan (no green bookmark), you will have to add that frequency to the band plan by editing the following file:
/etc/openwebrx/bands.json
Prior to editing this file, make sure you create a backup copy, in case something goes wrong. Unfortunately, there is no way to edit the band plan via web-based settings at the moment. After editing and saving the file, restart OpenWebRX as follows and make sure there is a green bookmark at the frequency you added:
sudo systemctl restart openwebrx
In the previous section, we discussed how OpenWebRX can decode radio transmissions automatically, while someone is using it. In this section, we are going to make OpenWebRX run the radio and receive signals on its own, when nobody is using it.
Start with an SDR device where you previously enabled background services by going to "Settings | SDR Devices and Profiles | <Device>". Add the "Scheduler" option to this device and find the newly added scheduler selector among other settings. It is going to offer you two different schedule models:
Daylight Scheduler
The daylight scheduler lets you select three profiles to run on the
device during the day, the night, and the "greyline" period (i.e. dawn
and dusk). Since radio waves propagation depends on the time of a day,
this scheme provides easy to configure, yet functional schedule.
Static Scheduler
The static scheduler lets you define your own schedule of as many
entries as you like, with minute precision. While such a schedule is
more difficult to add, it gives you flexibility to switch through
several different profiles each hour.
Once you have your schedule added and saved, OpenWebRX will switch device between scheduled profiles, as long as nobody is using this device. Once all the users disconnect, OpenWebRX will return the SDR device to its currently scheduled profile. It will also run any applicable background decoders you enabled earlier, reporting received data to the map or saving it to the file storage.
In the two previous sections, we discussed how OpenWebRX can be configured to automatically decode various radio transmissions. In this section, we are going to discuss sending the decoded data to online services, such as APRS-IS, PSKReporter, WSPRnet, or MQTT. To configure online reporting, go to the "Settings | Spotting and Reporting" settings page. There are three sections there, for the three types of data OpenWebRX can report:
APRS-IS
The received APRS position reports can be sent to the
APRS-IS network.
In order to do that, fill in your APRS callsign and the nearest server
address. You may also need to provide APRS-IS network password. Finally,
check the "Send received APRS data to APRS-IS" option. The
reported data will show up at the
APRS.fi map.
Please, note that
APRS.fi
does not show multiply reported spots, so some of your reports may not
show there.
If you would also like to report your receiver position to APRS-IS, check the "Send the receiver position to the APRS-IS network" option and fill in information about your receiver and antenna specifics.
Please, note that only one decoder can send data to the APRS-IS network using the same callsign. Thus, if you have more than one APRS decoder running (for example, at 144.39MHz and 145.825MHz), some of your reports will not make it through. To fix this issue, disable all but one APRS frequency in the bandplan file.
PSKReporter
OpenWebRX can report FT8, FT4, JT9, JT65, FST4, JS8, Q65, WSPR, FST4W,
and MSK144 transmissions to the
PSKReporter
website. All you need to do is check the "Enable sending spots to
pskreporter.info" option and fill callsign field with a unique name.
It does not have to be your official HAM callsign, but most
people who have HAM callsigns use them here. The reported data will show
up at the
PSKReporter map.
You may also want to describe your antenna in the antenna information
field, so that other people know how you received the data you are
reporting.
WSPRnet
The
WSPRnet
website only accepts WSPR and FST4W reports. To enable it, check the
"Enable sending spots to wsprnet.org" option and enter your
unique name into the callsign field. It does not have to be your
official HAM callsign, but most people who have HAM callsigns use them
here. The reported data will show up at the
WSPRnet map.
MQTT
The
MQTT
is a protocol for reporting IOT events to multiple remote subscribers.
In order to use MQTT, you will need to have an MQTT broker, such as
Mosquitto.
Once you have a broker, enable MQTT reporting by checking the "Enable
publishing reports to MQTT" option and entering your broker address
into the appropriate field. You may also have to enter your client ID,
username, and password. By default, OpenWebRX+ reports all its events
under the "openwebrx" topic, but that can be changed by entering
your own topic name into the "MQTT topic" field.
OpenWebRX+ offers two map options: Google Maps and a collection of free maps based on the Leaflet library. The very popular OpenStreetMap is part of that collection.
The Google Maps implementation is more detailed and polished, but it may require you to register your credit card with Google to receive an API key. Google may then charge your credit card if you exceed a certain limit of the Google Maps accesses.
The OpenStreetMap and other maps included with the Leaflet are less detailed, but they are totally free. Also, the Leaflet implementation includes some extra layers for weather, maritime annotations, and so forth.
In order to configure the default map, go to "Settings | General | Map | Map Type" and select the map you would like to show to the users by default. Remember that a user can always switch maps by clicking on the Map button. Other map-related options available from the same settings section are:
Google Maps API Key
This is where you enter the Google Maps API key you received from
Google. Leave this field empty if you have no API key. A lot of times,
Google Maps will work anyway, for some reason.
OpenWeatherMap API Key
If you would like to see global weather on Leaflet maps, consider
getting an OpenWeatherMap API key and entering it here. These
keys are free, for limited amount of functionality. Without this key,
OpenWebRX+ will only be able to show you US weather, obtained from
WeatherRadar.
Map Retention Time
This is the time, in seconds, the received location reports stay visible
on the map. A location report will start getting dimmer once it becomes
older than half of the retention time. Once it reaches the retention
time, a location report will disappear from the map.
Callsign Database URL
This is the web site used to look up reported HAM callsigns when you
click them on the map. The "{}" characters will be replaced with
the actual callsign. Two common choices here are
qrz.com and
qrzcq.com.
Vessel Database URL
This is the web site used to look up vessel MMSI numbers when you click
them on the map. The "{}" characters will be replaced with the
actual MMSI number.
Flight Database URL
This is the web site used to look up airline flight IDs when you click
them on the map. The "{}" characters will be replaced with the
actual flight ID.
Aircraft Database URL
This is the web site used to look up aircraft Mode-S IDs when you click
them on the map. The "{}" characters will be replaced with the
actual Mode-S ID.
Once a day, OpenWebRX+ queries the EiBi database for shortwave broadcast schedules. Currently broadcasting stations are indicated with ⍑ markers on the map and with bookmarks in the main receiver window.
You can make OpenWebRX+ create bookmarks for currently broadcasting shortwave stations by setting their maximum range from the receiver via "Settings | General | Display | Shortwave Bookmarks Range". OpenWebRX+ will only create bookmarks for shortwave stations located within that range.
You can also restrict shortwave bookmarks to just a few profiles (such as 49m / 41m / etc):
Disable global shortwave bookmarks by setting "Settings | General | Display | Shortwave Bookmarks Range" to zero.
Go to "Settings | SDR Devices and Profiles | <Device> | <Profile>" and add an option called "Shortwave Bookmarks Range" by clicking on Add.
Set the newly added option to the maximum range from the receiver where you would like to see shortwave bookmarks and save profile settings by clicking on Apply and Save.
It is important to note that the shortwave stations will only show correctly if you set the correct receiver location in "Settings | General | Receiver Information | Receiver Location". It is also important to remember that since OpenWebRX+ queries EiBi once a day, the up-to-date information may not be available immediately after setting the receiver location.
Once a day, OpenWebRX+ queries RepeaterBook.com for the list of repeaters closest to the receiver location. These repeaters are shown with ⋈ markers on the map and with bookmarks in the main receiver window.
You can make OpenWebRX+ create repeater bookmarks by setting their maximum distance from the receiver in "Settings | General | Display | Repeater Bookmarks Range". OpenWebRX+ will only create bookmarks for repeaters located within the preset maximum distance.
You can also restrict repeater bookmarks to just a few profiles (such as VHF / UHF):
Disable global repeater bookmarks by setting "Settings | General | Display | Repeater Bookmarks Range" to zero.
Go to "Settings | SDR Devices and Profiles | <Device> | <Profile>" and add an option called "Repeater Bookmarks Range" by clicking on Add.
Set the newly added option to the maximum distance from the receiver where you would like to see repeaters and save profile settings by clicking on Apply and Save.
It is important to note that the repeaters will only show correctly if you set the correct receiver location in "Settings | General | Receiver Information | Receiver Location". It is also important to remember that since OpenWebRX+ queries the RepeaterBook.com once a day, the up-to-date repeater information may not be available immediately after setting the receiver location.
As a server administrator, you may have legal or technical reasons to restrict your OpenWebRX server use by the public. Always check what radio frequencies and modes you are allowed to listen to at your location. Do not offer prohibited frequencies and modes to the public. Following restrictions are available in the "Settings | General | Receiver Limits":
Maximum Number of Clients
This setting determines how many people can connect to your OpenWebRX
server at once. Anyone trying to connect to a "full" server will be
shown an error message and refused service.
Maximum Number of Files
This setting determines how many SSTV images, faxes, and other files
received from the air OpenWebRX+ is allowed to keep before it starts
deleting oldest files. The received files can be seen by pressing the
Files button at the top of the receiver web
page.
Session Timeout
This value, in seconds, determines how long a user is allowed to use the
OpenWebRX+ receiver. Reloading receiver's web page restarts the time
though, so the timeout is mostly there for people who leave their
computers with the OpenWebRX+ page open.
Usage Policy URL
This web page is shown to a user once their session times out. The
default page explains why there is a timeout and lets users find other
online receivers to listen to.
Allow users to chat with each other
Disable this option if you want to disable the built-in chat facility.
When disabled, the chat panel turns into the log panel that does not
accept any input.
Allow users to record received audio
Disable this option if you do not want your users to record any audio
they are listening to. When disabled, the REC
button will disappear from the user interface. Please, do keep in mind
that this does not prevent your users from recording their audio
by some other means.
Allow users to change center frequency
Enable this option if you would like to let your OpenWebRX+ users
"side-step" their current profile by right-clicking the round arrow
buttons. Since this change will occur to all the users listening to the
same profile, it makes sense to disable it on the servers with many
people listening to the same profiles.
Magic Key
When the magic key string is filled in (i.e. not empty), OpenWebRX+ will
only allow side-stepping profiles to people who know the magic key and
provide it as follows:
http://openwebrx.receiver.org:8073/#key=<magic-key>
OpenWebRX+ lets its administrator monitor connections to the server and ban abusive users. Please, note that since the main goal of the OpenWebRX project is to provide free, open online radio, this facility should be used with extreme care. If you want to have a truly private OpenWebRX server, consider closing it to public access instead.
In order to see currently connected clients, click on the Settings button and scroll to the bottom of the page, until you see the "Clients" display, as shown above. There, you will be able to ban client's IP address for a selected amount of time, or unban previously banned addresses. A banned client will still be able to see the map and files, but won't be able to access the receiver itself.
You can also broadcast a message to all currently connected clients by entering it into the input field and clicking the send button. Your message will show up in clients' log / chat panels.
If you are running OpenWebRX+ behind NGINX, you may not be able to see clients' IP addresses unless you edit this file:
/etc/nginx/sites-enabled/openwebrxand add the following line to the location section:
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
As discussed earlier, OpenWebRX can report received data to an MQTT broker. The data for each mode is sent under the "openwebrx/<mode>" topic. For example, FT8 data is reported as "openwebrx/FT8". A typical report will look as follows:
{
"mode": "FT8",
"timestamp": 1722482895000,
"freq": 7074985,
"msg": "CQ YV6BXN FK60",
"callsign": "YV6BXN",
"locator": "FK60"
}
The common fields present in most reports are:
In addition to reporting received data, OpenWebRX+ uses MQTT to report SDR device changes and other internal events. For example, when an OpenWebRX+ server starts up or shuts down, it sends the following event under the "openwebrx/RX" topic:
{
"mode": "RX",
"timestamp": 1722737506393,
"version": "v1.2.64",
"state": "ServerStarted"
}
The "state" parameter can be either "ServerStarted" or "ServerStopped".
OpenWebRX+ reports SDR device changes under the "openwebrx/RX" topic that can be used by various automation scripts. Thus, an SDR profile change will be reported as follows:
{
"mode": "RX",
"timestamp": 1722483751451,
"source_id": "rspdx",
"source": "RSPdx",
"profile_id": "air-1",
"profile": "Air Band 118-120",
"freq": 118900000,
"samplerate": 2000000
}
The most important fields in the above event are:
When an SDR device starts or stops operating, a state change event is sent to MQTT:
{
"mode": "RX",
"timestamp": 1722483751451,
"source_id": "rspdx",
"source": "RSPdx",
"state": "Running"
}
As seen above, the state change event is very similar to a profile change, but carries SDR state instead of profile information.
OpenWebRX+ reports user activities under the "openwebrx/CLIENT" topic. Thus, a user connecting or disconnecting from the server will be reported as follows:
{
"mode": "CLIENT",
"timestamp": 1722738356255,
"ip": "::ffff:101.23.45.67",
"state": "Connected",
"banned": false
}
The "state" parameter can be either "Connected" or "Disconnected". When a user sends a chat message, that message is similarly reported under the "openwebrx/CLIENT" topic:
{
"mode": "CLIENT",
"timestamp": 1722738521609,
"ip": "::ffff:101.23.45.67",
"name": "Nickname",
"message": "The message text.",
"state": "ChatMessage",
"banned": false
}
Stanislav Lechev (LZ2SLL) has developed a JavaScript plugins framework for OpenWebRX+. There is a bunch of plugins available from his GitHub repository. JavaScript plugins operate in a browser at the client side, rather than the server side, and allow to customize user interface. In order to enable JavaScript plugins, rename the following file:
htdocs/plugins/receiver/init.js.sample
into init.js and edit it to enable or disable individual plugins. The plugins themselves are stored in the following folders:
htdocs/plugins/receiver
Plugins placed into this folder will be loaded into the main receiver
page.
htdocs/plugins/map
Plugins placed into this folder will be loaded into the map view page.
This section attempts to answer some common questions asked by OpenWebRX users. Please, consult with it before seeking help in online forums or chat groups.
Before seeking online help from other OpenWebRX users, please, consider the following steps:
Read other FAQ articles in this document. There is a very good chance they offer solutions to your problems.
Wait for a day or two, maybe things start working, as they often do.
If you are not familiar with Linux and do not want or cannot learn, find a friend familiar with Linux who can offer you hands-on help.
If you are familiar with Linux, look at OpenWebRX logs by typing the following command:
sudo journalctl -u openwebrx
If you need even more log output, edit the following file:
/etc/openwebrx/openwebrx.confand set the log_level in the [core] section:
[core] log_level = DEBUGThen save the edited file and restart OpenWebRX.
If you still need help, ask for it in the Telegram channel or create a separate thread in the forum. Make sure you provide service logs obtained with the above command, as a file, to whoever will be willing to help you.
In a desktop browser, try reloading receiver web page while holding the SHIFT key. In a mobile browser, clear browser cache and reload the page. If this does not help, try restarting the computer running OpenWebRX.
Click on "Settings | Feature Report" and see if the features you are interested in show up as enabled there. If a feature is disabled, the report will tell you what you should do to enable it.
Digital voice modes (DMR, D-STAR, YSF, NXDN) require AMBE codec algorithms patented by Digital Voice Systems Inc. Because of that, neither OpenWebRX nor OpenWebRX+ include digital voice support out of the box. It is your personal responsibility to add necessary pieces to your own OpenWebRX installation.
The proper, legally responsible way to add digital voice modes to OpenWebRX is to attach a licensed USB dongle that implements AMBE codecs in the hardware. Both OpenWebRX and OpenWebRX+ will support common AMBE dongle models with minimal configuration effort.
If you do not wish to use an AMBE codec dongle for whatever reason, there is an unlicensed MBELib software implementation with rather questionable origins. The MBELib use may be interpreted as a patent violation. If you are ok with it, there is a script that adds MBELib support to OpenWebRX. Run it as follows:
sudo install-softmbe.sh
After installing digital voice support by either method, visit "Settings | Feature Report" page to verify that the installation succeeded. You should now see digital voice buttons at the receiver web page.
SDRplay devices and their clones are notoriously glitchy and require a good power source for reliable operation. If you experience timeouts or failures with these devices, try connecting them via a powered USB hub. If this does not help, and you have a geniune SDRplay device (not a clone), open a ticket at the SDRplay website. OpenWebRX developers cannot help you with SDRplay hardware issues.
In general, no. OpenWebRX is a non-profit project, developed by very few people in their spare time. These developers will prioritize features they find personally interesting, repeatedly requested by a lot of people, or easy to implement.
Having said that, there is high probablity that the feature you want is either already implemented, or can be achieved by some other means, or has been considered and avoided for some reason. Please, carefully read this document, especially the FAQ section.
Also, since OpenWebRX is an open-source project, nothing prevents you from adding features you want on your own. Take a look at the original OpenWebRX source code or the OpenWebRX+ source code and consider participating in the OpenWebRX development.
Since OpenWebRX is an open online receiver, it does not let you hide profiles from the public. If you would like to have private access to your receiver, the best option is to make it inaccessible from the Internet.
Having said that, there is an option to prevent users from changing profiles on a specific SDR device connected to OpenWebRX+. It comes useful if this SDR device performs background decoding and changes profiles based on its own schedule. To enable this option, do the following:
Go to "Settings | General Settings | Receiver Limits | Magic Key" and set the magic key value you would like to use to force switching profiles on a protected device.
Go to "Settings | SDR Devices and Profiles | <Device>", select "Require magic key to switch profiles on this device" from the "Additional Optional Settings" and click on Add.
Make sure the "Require magic key to switch profiles on this device" checkbox is checked, then click on Apply and Save.
From now on, users can only change profiles on the device by providing the preconfigured magic key value in the URL, as follows:
http://openwebrx.receiver.org:8073/#key=<magic-key>
Since OpenWebRX works in terms of "profiles", i.e. preconfigured ranges of frequencies, you cannot jump to an arbitrary frequency because that new frequency may require different profile settings. Also, other users listening to the same profile may not appreciate you jumping to a completely new frequency.
Nevertheless, OpenWebRX+ does offer a way to "side-step" the current profile, going to adjacent frequencies. In order to enable side-stepping, do the following:
Go to "Settings | General Settings | Receiver Limits" and make sure the "Allow users to change center frequency" checkbox is checked.
If you would like to protect frequency changes with a magic key, enter it in the adjacent "Magic Key" field.
Click on Apply and Save to save changes.
From now on, you can step outside the preconfigured frequency range by right-clicking the large round arrows at the top of the receiver web page. Mobile users, who do not have a mouse, can simply hold these large round arrows with their finger for about a second.
If a magic key is configured, you will only be able to side-step profiles when providing that key in the URL, as follows:
http://openwebrx.receiver.org:8073/#key=<magic-key>
Due to the way OpenWebRX operates, you cannot just enter any frequency into the input field and expect it to work. The entered frequency must be within the current profile to work. Please, see above for the reasons.
For a special case where you have allowed OpenWebRX+ to step outside the preconfigured frequency range, entering an arbitrary frequency can be enabled with a JavaScript plugin.
If you wish to backup OpenWebRX configuration files, they are located as follows:
/var/lib/openwebrx/settings.json /var/lib/openwebrx/bookmarks.json /var/lib/openwebrx/users.json /etc/openwebrx/openwebrx.conf /etc/openwebrx/bands.json
You should avoid editing configuration files by hand, since they are normally modified via web-based settings interface. If you do decide to edit configuration files, always make sure you have backup copies first. After updating configuration files, restart OpenWebRX with:
sudo systemctl restart openwebrx
While the original OpenWebRX version does not support HTTPS protocol, OpenWebRX+ does. In order to enable HTTPS in OpenWebRX+, you will need the SSL certificate file (cert.pem) and the key for it (key.pem). Once you have these two files, do the following:
sudo cp <cert.pem> /etc/openwebrx/cert.pem sudo cp <key.pem> /etc/openwebrx/key.pem sudo chown openwebrx:openwebrx /etc/openwebrx/cert.pem sudo chown openwebrx:openwebrx /etc/openwebrx/key.pem sudo chmod 660 /etc/openwebrx/cert.pem sudo chmod 660 /etc/openwebrx/key.pem sudo systemctl restart openwebrx
OpenWebRX+ comes with predefined bookmarks for some common frequencies, such as weather information, CB channels, and so on. If you do not like to see these bookmarks, delete them and restart OpenWebRX+ as follows:
sudo rm -f /etc/openwebrx/bookmarks.d/* sudo systemctl restart openwebrx
If you only want to get rid of some bookmarks, delete or edit individual files in the /etc/openwebrx/bookmarks.d folder.
By default, OpenWebRX+ tries to determine the correct temperature sensor automatically. This works 99% of the time, but the remaining 1% may see their temperatures way outside the realistic range. To tell OpenWebRX+ which sensor to use, edit the following file:
/etc/openwebrx/openwebrx.confadding the following line to the [core] section:
[core] temperature_sensor=<full-path-to-your-temperature-sensor>Then save the edited file and restart OpenWebRX+.