rework configuration guide
Jakob Ketterl
parent
845b9074ad
commit
b11bef2cbb
|
|
@ -1,44 +1,99 @@
|
|||
Once you have successfully set up your receiver, you will probably want to configure it to your specific needs and purposes. This guide should help you getting started.
|
||||
|
||||
# What's in the box?
|
||||
|
||||
In order to get most people started quickly, the default configuration already includes a set of common SDRs and profiles that cover some amateur radio bands.
|
||||
|
||||
* RTL-SDR USB Stick with profiles for VHF and UHF (2m / 70cm)
|
||||
* Airspy HF with shortwave profiles (20m / 30m / 40m / 80m)
|
||||
* SDRPlay with shortwave profiles (20m / 30m / 40m / 80m)
|
||||
|
||||
It's best to think of this as an example. There's no need to stick to this configuration.
|
||||
|
||||
# Where is the configuration located?
|
||||
|
||||
Starting with OpenWebRX 1.0, most configuration options are available in the new web configuration, which is accessible
|
||||
directly from your browser by clicking the "Settings" icon on the top right of the receiver window.
|
||||
|
||||
You will need to create a user account in order to be able to log into the web configuration. Please see the
|
||||
[user management documentation](https://github.com/jketterl/openwebrx/wiki/User-Management) for details on this step.
|
||||
|
||||
The web configuration has a number of sections that allow you to configure the behavior of your receiver.
|
||||
|
||||
## Configuration files
|
||||
|
||||
Some parts of the configuration are still stored in configuration files.
|
||||
|
||||
Depending on your installation, the configuration files will be located in one of the following location:
|
||||
* `/etc/openwebrx` (this is the default location when installing from packages, on the RasPi images, and also works on manual installs)
|
||||
* stored on a docker volume (if you followed the instructions here, it should be `/var/lib/docker/volumes/openwebrx-config/_data`)
|
||||
* in your checkout directory (manual installation; only if you didn't create config in `/etc/openwebrx`)
|
||||
|
||||
There's three configuration files:
|
||||
* `config_webrx.py` is the central configuration file that contains most of the receiver settings
|
||||
* `bookmarks.json` contains the bookmarks (see the [bookmarks documentation](https://github.com/jketterl/openwebrx/wiki/How-the-bookmarks-work) for details)
|
||||
* `bands.json` contains the bandplan with amateur radio bands and frequencies
|
||||
|
||||
Please note that not all configuration files are necessarily in the same location.
|
||||
|
||||
### `openwebrx.conf`
|
||||
|
||||
This file contains low-level configuration options that typically require few adjustments.
|
||||
|
||||
Defaults:
|
||||
|
||||
```
|
||||
[core]
|
||||
data_directory = /var/lib/openwebrx
|
||||
temporary_directory = /tmp
|
||||
|
||||
[web]
|
||||
port = 8073
|
||||
|
||||
[aprs]
|
||||
symbols_path = /usr/share/aprs-symbols/png
|
||||
```
|
||||
|
||||
There is also the option of storing parts of this configuration in a config directory structure in `/etc/openwebrx/openwebrx.conf.d`. This allows you to override parts of the configuration without the need to modify the original file.
|
||||
|
||||
Modifications to this file or files in the config directory require a restart of OpenWebRX.
|
||||
|
||||
### `bands.json`
|
||||
|
||||
This file contains information about bands and frequencies. It is used to configure digimode frequencies for both [background decoding](https://github.com/jketterl/openwebrx/wiki/Background-decoding) and [green bookmarks](https://github.com/jketterl/openwebrx/wiki/How-the-bookmarks-work), as well as for reverse band lookups on decodes.
|
||||
|
||||
## Deprecated files
|
||||
|
||||
These files have been superseded by the new web configuration and the new configuration storage. The files can still be
|
||||
read by OpenWebRX for migration purposes. See [Migrating to OpenWebRX 1.0](https://github.com/jketterl/openwebrx/wiki/Migrating-to-OpenWebRX-1.0).
|
||||
|
||||
* `config_webrx.py`
|
||||
* `bookmarks.json`
|
||||
|
||||
# Setting up the basics
|
||||
|
||||
There's some basic configuration keys that will describe your receiver to users that visit it. It's recommended to set these if you share your receiver publicly. Also, some of these configs will be used later on.
|
||||
The "General settings" section of the web config contains some basic settings that will describe your receiver to users that visit it. It's recommended to set these if you share your receiver. Some of these settings are also used for other features of the receiver.
|
||||
|
||||
* `receiver_name`: A commonly used name for your receiver or receiver location.
|
||||
* `receiver_location`: Some verbal description of your receiver location (e.g. city, country, ...)
|
||||
* `receiver_asl`: The height of your receivers' antenna above sea level.
|
||||
* `receiver_admin`: The E-Mail where your users can contact you.
|
||||
* `receiver_gps`: The exact location of the receiver (yes, this gets sent to the client. If you want to keep your receiver location a secret, do not fill this out. This will however impose limitations on other features.)
|
||||
* `photo_title`: A short title for the receiver photo, if you set any.
|
||||
* `photo_desc`: Verbose description of the receiver and its location. This can span multiple lines, it is initially displayed when the website is loaded, but will disappear automatically.
|
||||
[[images/settings-general-receiverinfo.png]]
|
||||
|
||||
* "Receiver Name": A commonly used name for your receiver or receiver location.
|
||||
* "Receiver location": Some verbal description of your receiver location (e.g. city, country, ...)
|
||||
* "Receiver elevation": The height of your receivers' antenna above sea level.
|
||||
* "Receiver admin": The E-Mail where your users can contact you.
|
||||
* "Receiver coordinates": The exact location of the receiver (yes, this gets sent to the client. If you want to keep your receiver location a secret, do not fill this in. This will however impose limitations on other features.)
|
||||
* "Photo title": A short title for the receiver photo, if you set any.
|
||||
* "Photo description": Verbose description of the receiver and its location. This input can handle HTML.
|
||||
|
||||
There is a lot of other settings on this and the other sections of the web configuration. Feel free to explore.
|
||||
|
||||
# Setting up SDR devices and profiles
|
||||
|
||||
Please see [SDR device and profile configuration](https://github.com/jketterl/openwebrx/wiki/SDR-device-and-profile-configuration).
|
||||
The "SDR devices and profiles" section is where you set up the SDR devices that OpenWebRX uses, and the profiles that will be available to your users. A device typically corresponds to a physical SDR device that is connected to your receiver (typically via USB or network). A profile defines a frequency range, together with the corresponding parameters for the device.
|
||||
|
||||
Note: In OpenWebRX, one device can only run a single profile at any given time.
|
||||
|
||||
When adding a new device, you will be asked for the "Device type". This type determines what settings will be available on the following pages, so it cannot be changed after creation.
|
||||
|
||||
If your device type is listed on the [supported hardware](https://github.com/jketterl/openwebrx/wiki/Supported-Hardware) page, but is missing from the list, please check if the necessary dependencies are installed on the feature report.
|
||||
|
||||
Some of the device settings are optional, they can be added and removed. These are settings which are only useful in certain situations, or where the default is typically applicable for most use cases.
|
||||
|
||||
Many optional settings are available both on the device settings and on the profiles. These settings will inherit the value configured on the device level if they are not set on the profile.
|
||||
|
||||
## What's in the box?
|
||||
|
||||
In order to get most people started quickly, the default configuration already includes a set of common SDR devices and profiles that cover some amateur radio bands.
|
||||
|
||||
* RTL-SDR USB Stick with profiles for VHF and UHF (2m / 70cm)
|
||||
* Airspy HF with shortwave profiles (20m / 30m / 40m / 80m)
|
||||
* SDRPlay with shortwave profiles (20m / 30m / 40m / 80m)
|
||||
|
||||
It's best to think of this as an example. There's no need to stick to this configuration, the web configuration allows you to remove or add devices at any time.
|
||||
|
||||
# Setting up bookmarks
|
||||
|
||||
|
|
|
|||
|
|
@ -1,285 +0,0 @@
|
|||
The most important part of the OpenWebRX configuration is the `sdrs` section, where the devices and profiles that OpenWebRX works on is set up. The basic structure is a Python dictionary, where the device id is the key and the actual device configuration, another Python dictonary, is the value. The profiles are another dictionary, contained as the `profile` key in the individual device configuration:
|
||||
|
||||
```python
|
||||
sdrs = {
|
||||
"device_id": {
|
||||
"name": "Device name",
|
||||
# ... device options go here ...
|
||||
"profiles": {
|
||||
"profile_id": {
|
||||
"name": "Profile name",
|
||||
# ... profile options go here ...
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
It is of course possible to have multiple devices as well as multiple profiles per device, but the corresponding ids must be unique within their respective dictionary:
|
||||
|
||||
```python
|
||||
sdrs = {
|
||||
"device_id_a": {
|
||||
"name": "Device A",
|
||||
# ... device options go here ...
|
||||
"profiles": {
|
||||
"profile_id_a": {
|
||||
"name": "Profile A",
|
||||
# ... profile options go here ...
|
||||
},
|
||||
"profile_id_b": {
|
||||
"name": "Profile B",
|
||||
# ... more profile options here ...
|
||||
},
|
||||
},
|
||||
},
|
||||
"device_id_b": {
|
||||
"name": "Device B",
|
||||
# ... more device options here ...
|
||||
"profiles": {
|
||||
"profile_id_a": {
|
||||
"name": "Profile A",
|
||||
# ... more profile options here ...
|
||||
},
|
||||
"profile_id_b": {
|
||||
"name": "Profile B",
|
||||
# ... more profile options here ...
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
# Configuration options
|
||||
|
||||
## Device options
|
||||
|
||||
### `name`
|
||||
|
||||
Mandatory key. Should be set to a simple, human-readable string that will appear in the OpenWebRX device / profile switching dropdown.
|
||||
|
||||
### `type`
|
||||
|
||||
Mandatory key. This tells OpenWebRX what driver to use to access the device. You can check the [supported hardware page](https://github.com/jketterl/openwebrx/wiki/Supported-Hardware) for a list of the supported devices. Possible values for this configuration:
|
||||
|
||||
* `rtl_sdr`
|
||||
* `rtl_sdr_soapy`
|
||||
* `sdrplay`
|
||||
* `airspy`
|
||||
* `airspyhf`
|
||||
* `fifi_sdr`
|
||||
* `hackrf`
|
||||
* `lime_sdr`
|
||||
* `perseussdr`
|
||||
* `pluto_sdr`
|
||||
* `red_pitaya`
|
||||
* `soapy_remote`
|
||||
* `uhd`
|
||||
|
||||
### `device`
|
||||
|
||||
Optional key. This can be used to select a specific device if there is more than one physical device of a certain type connected. The format of this key varies depending on the type of device used.
|
||||
|
||||
* `rtl_sdr` devices can pass a serial number (Multiple devices can have the same serial number) you can retrieve the serial number by invoking the 'rtl_eeprom' command for example 'rtl_eeprom -d 0' will give you the first device. If all the devices have the same serial number then you need to set each one to have a unique one again using the 'rtl_eeprom' command, example: 'rtl_eeprom -s 2' This will set the first device with serial number 2, you'll need to unplug the device and plug it back in to see the changes to it. If you want to set a unique one for each device as it's a string, you will need to plug the devices in one at a time with no other device inserted.
|
||||
* all devices running on soapy-based implementations need to pass a soapy device identifier format, e.g. `"serial=1234"`
|
||||
|
||||
### `ppm`
|
||||
|
||||
Optional key. Can be used to offset miscalibrated or uncompensated oscillators, so that the frequency spectrum appears as it is.
|
||||
|
||||
### `port`
|
||||
|
||||
Optional key. This can be used to force the TCP port used to serve IQ data. This is helpful if you intend to use other, third-party software on the same SDR.
|
||||
|
||||
See also: [`rtltcp_compat`](https://github.com/jketterl/openwebrx/wiki/SDR-device-and-profile-configuration#rtltcp_compat)
|
||||
|
||||
This setting will be removed in version 0.21, while the `rtltcp_compat` setting will receive the corresponding port number for `rtl_tcp` style setups.
|
||||
|
||||
### `always-on`
|
||||
|
||||
Optional key. Can be used to force continuous operation of the SDR device. Useful if the device startup is unreliable or unreproducible.
|
||||
|
||||
Boolean option. Set to `True` or `False` (first letter uppercase is mandatory).
|
||||
|
||||
### `services`
|
||||
|
||||
Optional key. Can be used to exclude a device from background decoding services. Defaults to `True`, so must be set to `False` to disable decoding on a give device.
|
||||
|
||||
Boolean option. Set to `True` or `False` (first letter uppercase is mandatory).
|
||||
|
||||
### `profiles`
|
||||
|
||||
Mandatory key. A dictionary containing one or more profile configurations. See example at the top.
|
||||
|
||||
## Device-level Connector source configuration keys
|
||||
|
||||
The following keys are available for sources using one of the connectors from the [owrx_connector package](https://github.com/jketterl/owrx_connector).
|
||||
|
||||
### `rtltcp_compat`
|
||||
|
||||
Optional key. Used to tell the connector to detect incoming connections as `rtl_tcp` style connections and to downsample to 8bit samples, if necessary.
|
||||
|
||||
See also: [`port`](https://github.com/jketterl/openwebrx/wiki/SDR-device-and-profile-configuration#port)
|
||||
|
||||
Boolean option. Set to `True` or `False` (first letter uppercase is mandatory).
|
||||
|
||||
Starting with version 0.21, this setting will receive the port number on which you would expect `rtl_tcp` data instead of the current boolean setting.
|
||||
|
||||
## Profile options
|
||||
|
||||
### `name`
|
||||
|
||||
Mandatory key. This will appear in the in the OpenWebRX device / profile switching dropdown, along with the device name.
|
||||
|
||||
### `center_freq`
|
||||
|
||||
Mandatory key. Sets the middle frequency for the spectrum to be shown, in Hertz.
|
||||
|
||||
## Universal keys
|
||||
|
||||
The keys that follow can be used both on the device and on the profile level, or even both. The profile level takes precedence over the device level, that way you can set a default value on the device, and only override it in the profiles when needed.
|
||||
|
||||
Mandatory universal keys must be set at least on one level for every profile.
|
||||
|
||||
### `samp_rate`
|
||||
|
||||
Mandatory key. Sets the sampling rate to request from the device, and with that, the bandwidth of the spectrum to be shown. The value must be supported by the device, so please make sure to select one of the available sample rates of your device. You can usually get a list of supported rates using the tools provided with the device, e.g. `SoapySDRUtil --probe`.
|
||||
|
||||
### `start_freq`
|
||||
|
||||
Mandatory key. Sets the initial frequency to tune when the website is loaded.
|
||||
|
||||
### `start_mod`
|
||||
|
||||
Optional key. Sets the initial modulation to select when the website is loaded.
|
||||
|
||||
### `rf_gain`
|
||||
|
||||
Optional key. Set the device gain to the specified value. The exact interpretation is up to the driver, e.g. for devices working with the SoapySDR layer, you can set the individual gains by using the SoapySDR format.
|
||||
|
||||
Example for SDRplay devices: `"rf_gain": "RFGR=3,IFGR=20"`.
|
||||
|
||||
Example for HackRF devices: `"rf_gain": "VGA=10,LNA=40"`.
|
||||
|
||||
Can be set to `"auto"` for those devices that support AGC.
|
||||
|
||||
### `lfo_offset`
|
||||
|
||||
Optional key. Can be used to offset the received frequency from the displayed frequency, usually used when there is some kind of local oscillator or mixer in the receiver chain.
|
||||
|
||||
The basic formula is: `center_freq` + `lfo_offset` = actual frequency on the sdr
|
||||
|
||||
Can take negative values.
|
||||
|
||||
If this value is set up correctly, all other frequencies in the configuration as well as the displayed frequency in the website are the actual frequencies received.
|
||||
|
||||
### `waterfall_min_level` and `waterfall_max_level`
|
||||
|
||||
Optional keys. These options are used to set up the dynamic range the waterfall should display.
|
||||
|
||||
The best way to set these values is to adjust the waterfall sliders to your liking in a running session, and then hover over the sliders with the mouse pointer to get the corresponding values.
|
||||
|
||||
### `initial_squelch_level`
|
||||
|
||||
Optional key. Can be used to set the squelch level of the demodulator on initial browser load.
|
||||
|
||||
### `schedule`
|
||||
|
||||
Optional key. Used to set up a schedule for [background decoding](https://github.com/jketterl/openwebrx/wiki/Background-decoding).
|
||||
|
||||
## Universal Connector source configuration keys
|
||||
|
||||
The following keys are available for sources using one of the connectors from the [owrx_connector package](https://github.com/jketterl/owrx_connector).
|
||||
|
||||
### `iqswap`
|
||||
|
||||
Optional key. Can be used to swap I and Q samples, which results in a reversal of the frequency spectrum. Useful in combination with mirroring mixers / oscillators.
|
||||
|
||||
Boolean option. Set to `True` or `False` (first letter uppercase is mandatory).
|
||||
|
||||
## SoapySDR specific keys
|
||||
|
||||
### `antenna`
|
||||
|
||||
Allows to select between the SDR inputs, if available. Please consult `SoapySDRUtil --probe` to get a list of available options.
|
||||
|
||||
## Type specific keys
|
||||
|
||||
Some device types support hardware specific options. You may need to check the device documentation to understand the meaning of these parameters.
|
||||
|
||||
### `bias_tee`
|
||||
|
||||
Available on `rtl_sdr`, `rtl_sdr_soapy`, `sdrplay`, `airspy`, `hackrf`
|
||||
|
||||
Can be used to turn the Bias-Tee power supply on the device on.
|
||||
|
||||
Boolean option. Set to `True` or `False` (first letter uppercase is mandatory).
|
||||
|
||||
### `direct_sampling`
|
||||
|
||||
Available on `rtl_sdr`, `rtl_sdr_soapy`
|
||||
|
||||
This option controls the direct sampling mode available on RTL-SDR Blog v3 devices. Possible values:
|
||||
* `0`: disabled
|
||||
* `1`: direct sampling via I-input
|
||||
* `2`: direct sampling via Q-input
|
||||
|
||||
### `rf_notch` and `dab_notch`
|
||||
|
||||
Available on `sdrplay`
|
||||
|
||||
Used to control the broadcast band filters available on SDRplay devices.
|
||||
|
||||
### `if_mode`
|
||||
|
||||
Available on `sdrplay`
|
||||
|
||||
### `bitpack`
|
||||
|
||||
Available on `airspy`
|
||||
|
||||
Used to tell the driver to pack two 12-bit samples into 3 bytes to save USB bandwidth.
|
||||
|
||||
Boolean option. Set to `True` or `False` (first letter uppercase is mandatory).
|
||||
|
||||
### `attenuator`
|
||||
|
||||
Available on `perseussdr`
|
||||
|
||||
### `adc_preamp`
|
||||
|
||||
Available on `perseussdr`
|
||||
|
||||
### `adc_dither`
|
||||
|
||||
Available on `perseussdr`
|
||||
|
||||
### `wideband`
|
||||
|
||||
Available on `perseussdr`
|
||||
|
||||
### `remote`
|
||||
|
||||
Available on `soapy_remote`, `rtl_tcp` and `runds`.
|
||||
|
||||
Specifies how to connect to the receiver over the network. Format is `host:port`, where host can be any resolve name or IP address. The individual implementations have different behavior when either host or port is left out, but host typically defaults to localhost, port typically defaults to the default port of the protocol (e.g. 1234 for rtl_tcp, 5555 for runds)
|
||||
|
||||
### `remote_driver`
|
||||
|
||||
Available on `soapy_remote`.
|
||||
|
||||
Optional key. Specifies the driver to be used by the remote instance of the SoapySDRServer.
|
||||
|
||||
### `protocol`
|
||||
|
||||
Available on `runds`
|
||||
|
||||
Optional key. Specifies which protocol implementation should be used. Supported values are `eb200` and `ammos`. Defaults to `eb200`.
|
||||
|
||||
### `long`
|
||||
|
||||
Available on `runds`
|
||||
|
||||
Optional key. Switches the connection to 32-bit "long" samples (default is 16-bit).
|
||||
|
||||
Boolean option. Set to `True` or `False` (first letter uppercase is mandatory).
|
||||
|
|
@ -9,7 +9,6 @@
|
|||
|
||||
## Configuration
|
||||
[Configuration](https://github.com/jketterl/openwebrx/wiki/Configuration-guide)<br>
|
||||
[SDR device and profile configuration](https://github.com/jketterl/openwebrx/wiki/SDR-device-and-profile-configuration)<br>
|
||||
[Bookmarks](https://github.com/jketterl/openwebrx/wiki/How-the-bookmarks-work)<br>
|
||||
[Background decoding](https://github.com/jketterl/openwebrx/wiki/Background-decoding)<br>
|
||||
[How to get openwebrx stats into collectd](https://github.com/jketterl/openwebrx/wiki/How-to-get-openwebrx-stats-into-collectd)<br>
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 198 KiB |
Loading…
Reference in New Issue