OpenWebRX+

A Better Online SDR Radio

Installation |  Documentation |  FAQ

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.

How to Get OpenWebRX+

How to Use OpenWebRX+

Main Display

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. The bookmarks let you quickly tune to previously bookmarked frequencies. There are three types of bookmarks in OpenWebRX:

  6. 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.

  7. The Status button toggles the status bar shown at the bottom of the receiver web page.

  8. 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.

  9. The Receiver button toggles the main control panel for the receiver.

  10. 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.

  11. The Files button opens the file browser page with the most recently received SSTV images, faxes, and other data.

  12. The Settings button opens the password protected settings page for configuring OpenWebRX. Normally, only server adminstrator needs to access the server settings.

  13. 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.

Main Controls

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. This button will light up if a digital decoder is active. Click it to toggle digital decoding off.

  6. 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.

  7. Use this slider to control audio volume. Click the speaker button to mute or unmute audio.

  8. 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.

  9. 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.

  10. 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.

  11. 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.

  12. 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.

  13. This drop-down list lets you choose one of the user interface themes. Clicking the adjacent button resets user interface to the default theme.

  14. 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.

  15. The four zoom buttons let you zoom waterfall in and out. Zooming always happens around the currently tuned frequency, keeping it on display.

  16. 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.

  17. 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.

  18. 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.

  19. 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.

Using Mouse and Touch

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):

Frequency Scanner

What is a scanner?

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:

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.

Built-In Chat

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.

Map Display

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.

Locators

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.

Markers

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.

Other Online Receivers

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.

Shortwave Stations

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.

Repeaters

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.

Usage Scenarios

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.

Listening to FM Broadcasts

What is FM broadcasting?

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. In order to see this information, tune to an FM signal and select "RDS" digital mode. You should see the RDS information panel at the bottom of the waterfall, slowly filling with data.

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.

Listening to AM Broadcasts

What is AM broadcasting?

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 Listening (SWL)

What is SWL?

"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.

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.

Listening to Citizens Band (CB)

What is CB?

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.

Listening to HAM Bands

What is HAM?

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:

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.

Listening to Morse Code (CW)

What is CW?

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 enabled the "Show CW codes (dits / dahs) when decoding CW" option.

Receiving Teletype (RTTY)

What is RTTY?

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:

OpenWebRX+ comes with three different RTTY settings, selected via digital mode drop-down list:

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.

Receiving SSTV Images

What is SSTV?

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:

  1. Select "SSTV" digital mode and tune exactly 1900Hz below the SSTV carrier frequency, or use any of the provided SSTV bookmarks.

  2. 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.

  3. 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.

Receiving Fax Images

What is radio fax?

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:

  1. Select "FAX" digital mode and tune exactly 1900Hz below the fax carrier frequency, or use any of the provided fax bookmarks.

  2. 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.

  3. 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":

Monitoring Pager Messages (POCSAG)

What is a pager?

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.

Monitoring Wireless Devices (ISM)

What is ISM?

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:

  1. Look around ISM frequencies for signals that may be produced by wireless devices.

  2. 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.

  3. 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.

Tracking Packet Radio (APRS)

What is APRS?

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 an APRS repeater located at the ISS.

Tracking Ships (AIS)

What is AIS?

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.

Tracking Airplanes (ADS-B)

What is ADS-B?

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.

Administrator Features

This section discusses administering an OpenWebRX server and how it can be used besides providing public access to radio waves.

Background Decoding

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

Scheduled Decoding

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:

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.

Reporting Decoded Data

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, and WSPRnet. 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:

Configuring Map

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:

Configuring Shortwave Schedules

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):

  1. Disable global shortwave bookmarks by setting "Settings | General | Display | Shortwave Bookmarks Range" to zero.

  2. Go to "Settings | SDR Devices and Profiles | <Device> | <Profile>" and add an option called "Shortwave Bookmarks Range" by clicking on Add.

  3. 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.

Configuring Repeaters

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):

  1. Disable global repeater bookmarks by setting "Settings | General | Display | Repeater Bookmarks Range" to zero.

  2. Go to "Settings | SDR Devices and Profiles | <Device> | <Profile>" and add an option called "Repeater Bookmarks Range" by clicking on Add.

  3. 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.

Limiting Receiver Use

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":

Monitoring Receiver Use

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/openwebrx
and add the following line to the location section:
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

Frequently Asked Questions

OpenWebRX broken after upgrade!

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.

New OpenWebRX features do not show up!

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 do not show up!

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.

My SDRplay device does not work reliably!

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.

Can you implement a feature I want?

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.

How do I hide some profiles from users?

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:

  1. 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.

  2. 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.

  3. 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>

How do I jump to any frequency?

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:

  1. Go to "Settings | General Settings | Receiver Limits" and make sure the "Allow users to change center frequency" checkbox is checked.

  2. If you would like to protect frequency changes with a magic key, enter it in the adjacent "Magic Key" field.

  3. 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>

Where are OpenWebRX configuration files?

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

How do I make OpenWebRX use HTTPS protocol?

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

How do I get rid of default yellow bookmarks?

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 files in the /etc/openwebrx/bookmarks.d folder.

My CPU temperature is wrong!

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.conf
adding the following line to the [core] section:
[core]
temperature_sensor=<full-path-to-your-temperature-sensor>
Then save the edited file and restart OpenWebRX+.


©2023-2024 Marat Fayzullin