Headless Server

This page describes how to setup a command-line wfview server. This topic is for advanced users only. For most users, the normal graphical server setup is sufficient.

The following documentation is very “beta” and is not ready yet… but feel free to have a look.

Building the Server

The normal wfview repository should first be cloned. (You can clone from other branches if you wish though — check our branch list.)

git clone --depth 1 --recurse-submodules https://gitlab.com/eliggett/wfview.git

Next, create a build directory and enter the build directory:

mkdir build
cd build

Now run qmake. Be careful to specify the correct pro file:

qmake ../wfview/wfserver.pro

Now run make. You can run make -j4 for a faster build using four cores (or more) if your hardware is up to the task:

make -j4


wfserver uses the same type of configuration file as wfview, with many of the same options. The default location for the settings file is ~/.config/wfview/wfserver.ini. The first time wfserver is run, it will create a basic configuration file if one does not exist yet. This is the simplest way to get started.






  • AudioSystem sets the audio system to:
    • 0: QtAudio, default, most compatible and best usual choice
    • 1: Port Audio
    • 2: RT Audio

[Radios] (these start with “1\” since this is for the first radio):

  • AudioInput: This is the input to wfview, from the radio’s receiver. “default” may work on some installs but it is best to set this variable manually. If possible, use wfview’s usual GUI client to see what the audio device would be called for your radio. You can also run wfserver with the debug flag to see a list of audio devices found:
    • wfserver --debug
  • AudioOutput: This is the output of wfview, used for the radio’s transmit audio.
  • ForceRTSasPTT: Set this to true if your radio interface needs the RTS pin used for PTT. For radios that have a PTT CI-V command (such as the 7300), set this to false.
  • GUID: Internally-generated ID, do not alter
  • RigCIVuInt: The CI-V address, in unsigned integer, for the radio. Note: If your radio has CI-V Transceive enabled, then you should not need to set this (set it to zero). wfserver will automatically find the radio. For older radios, set the CI-V address here to match the radio.
  • RigName: String, radio name used in some debug messages. Recommended format is the same as the model — “IC-7300” for example. If set to “<NONE>”, wfview will fill this in with the model number of the radio discovered.
  • SerialPortBaud: Set this to the same baud rate as the radio. Higher baud rates are recommended but not always better. For the IC-7300, you must use 115200 for the waterfall to work.
  • SerialPortRadio: Set this to the device path for the serial port. “auto” will simply grab /dev/ttyUSB0.
  • WaterfallFormat: Using this variable, wfview can force the waterfall into the “standard” ethernet or serial-style format. This is useful because some radio control programs expect the waterfall one or the other format.
    • 1: “combined” format, which Icom radios send over network
    • 0: “serial” format (default), which Icom radios send over serial. In this format, a single line of spectrum data is split up into about 11 chunks.
  • size: Indicates how many radios are defined. Yes, it may be possible one day to handle several radios from one server. For now, this value should be set to 1.


  • Server X Port: These are the three UDP ports that wfserver will use. Remember, do not remap the ports with a router, always keep the ports the same number on both sides of the router.
  • ServerEnabled: Set to true to enable the server
  • Users and passwords: Set the users and passwords here. Passwords can either be plaintext or “pseudo-encrypted” format. Use wfview to generate them on a GUI client.
  • UserType:
    • 0 = Full User, has transmit capability
    • 1 = Full User with No Transmit
    • 2 = Monitor only, no controls

Audio Levels

You can adjust the input (capture) levels in the terminal using alsamixer and amixer. Be careful, sometimes there are adjustments that merely scale the level and then there are adjustments that actually set the ADC conversion gain. We want the conversion gain.

To bring up the capture levels for card #1, use this command (try card #0 and #2 as well until you see the controls you expect):

alsamixer -c 1 --view=capture

Once adjusted, make a note of the adjustment level. You can then script amixer to make this adjustment for you just prior to starting wfserver using a startup script:

amixer –set-volume=33 -c 1 –device=”capture” (note this is wrong, I need to figure this one out)

Running Automatically

You can create a systemd script to automatically run wfserver on startup. DO NOT EVER run wfserver as root. This is entirely unnecessary and not supported at all. If you have permission errors, try and dig to the root of the issues (ie, serial port ownership or group membership, typically).

To run wfserver in a terminal with persistence, for now, it is recommended to use the “screen” session manager program. Simply hit control-a, d, to detach the screen session and keep wfserver running. We will add a background fork mechanism later.