# Digital Command Center — by KM4SPL

## Multi-mode decoder preview

This is a receive-only development preview. It includes decoder integration for
FT8, FT4, WSPR, JS8, PSK31 and RTTY. The browser demo uses synthetic messages;
the installed station app uses the engines below. No decoder integration sends
messages, keys PTT, or transmits audio.

| Mode | Actual decoding engine | Input |
|---|---|---|
| FT8 | WSJT-X `jt9` | Station audio or a mono 16-bit WAV; 15-second periods |
| FT4 | WSJT-X `jt9` | Station audio or WAV; 7.5-second periods |
| WSPR | WSJT-X `wsprd` | Station audio or WAV; 120-second periods |
| JS8 | JS8Call | Decoded activity and directed messages over its local TCP API |
| PSK31 | fldigi, BPSK31 modem | Incremental received text over local XML-RPC |
| RTTY | fldigi, RTTY modem | Incremental received text over local XML-RPC |

The preview does not contain a newly written JS8/PSK31/RTTY signal demodulator.
Those three modes require the corresponding external decoder application to be
running and receiving the audio. All JS8 receive speeds are handled by JS8Call.
For RTTY, start with fldigi's 45.45-baud / 170-Hz shift configuration and adjust
it to match the signal being received.

## Start on Windows

Install Python 3.11 or newer from python.org. Extract the preview ZIP and open a
terminal in its `dcc` folder:

```powershell
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe run.py --no-audio
```

Open **http://127.0.0.1:8765**. `--no-audio` is useful for WAV tests and external
decoder integrations while no radio is connected. It does not open a microphone.
To select a USB radio audio input later:

```powershell
.\.venv\Scripts\python.exe run.py --list-audio
.\.venv\Scripts\python.exe run.py --device "USB Audio CODEC"
```

Device names depend on your radio and operating system. A numeric input device
number from `--list-audio` also works. Do not choose your computer microphone
when you intend to decode the radio's USB audio.

## Start on Linux / Raspberry Pi

Install Python, ALSA utilities, and your distribution's WSJT-X package. In the
`dcc` folder create a virtual environment and install `requirements.txt`, then
run `python run.py`. ALSA defaults to `plughw:CARD=CODEC,DEV=0`; override it using
`FT8_AUDIO_DEVICE`. `--device` selects the optional PortAudio backend.

## Decoder setup

### FT8, FT4 and WSPR

Install [WSJT-X](https://wsjt.sourceforge.io/wsjtx.html). On Windows the app
looks in `C:\WSJT\wsjtx\bin` and `C:\Program Files\WSJT-X\bin`, then PATH.
For another install location, set these before starting DCC:

```powershell
$env:DCC_JT9_PATH='C:\your-wsjtx-folder\bin\jt9.exe'
$env:DCC_WSPRD_PATH='C:\your-wsjtx-folder\bin\wsprd.exe'
```

The complete WSJT-X installation must remain present so its DLLs are available.
Its decoders run as separate programs in temporary working directories.

### JS8

Install [JS8Call](https://js8call.com/downloads.html). In its Reporting settings,
enable the **TCP API** on `127.0.0.1:2242`. Select the radio audio input in
JS8Call and start receiving. Select JS8 in DCC. A different TCP port can be set
using `DCC_JS8_PORT` before starting DCC.

DCC receives `RX.ACTIVITY` and `RX.DIRECTED`, retaining decoded text, callsign,
grid, audio offset, SNR and speed when supplied by JS8Call. It never uses
`TX.SEND_MESSAGE` or other transmit commands.

### PSK31 and RTTY

Install [fldigi](https://www.w1hkj.org/). Enable XML-RPC on
`127.0.0.1:7362`, configure its audio input, and select **BPSK31** or **RTTY**.
Select the matching mode in DCC. A different port can be set with
`DCC_FLDIGI_PORT`. DCC reports a mode mismatch instead of labeling one modem's
output as another. It reads the receive buffer non-destructively, so it does
not consume another logging program's receive queue. Existing text is skipped
when first connecting; subsequent text is displayed.

Choose the signal/audio offset in fldigi; DCC's RX filter then selects which
received text appears in RX Frequency. DCC does not take over fldigi's radio.
For recorded audio use fldigi's File → Audio → Playback. For JS8 use JS8Call's
recording playback. The DCC file-upload decoder currently supports FT8/FT4/WSPR.

## Controls and behavior

- **Digital mode** selects the decoder independently of the radio's USB/USB-D
  mode. Selecting a digital mode does not automatically retune real hardware.
- Band selection uses the selected mode's frequency presets; unsupported
  combinations report an error. These are starting points; check your local
  band plan. WSPR presets are dial frequencies, not signal center frequencies.
- **Decoder setup / Test WAV** shows engine requirements and supports local
  FT8/FT4/WSPR recording tests (mono PCM, 16-bit, at most 125 seconds / 25 MB).
  Multi-period recordings are decoded one period at a time; an incomplete
  trailing period is skipped. Results stay in the recording-test window.
- Audio is resampled to 12 kHz with an anti-alias filter. UTC capture windows
  are split at sample boundaries; missing/partial cycles are discarded.
- Mode changes invalidate queued/in-progress results. The bounded receive
  history remains available when returning to a previous mode.
- RX Frequency uses the selected audio offset, not all band messages.
- If a decoder disconnects, the status shows the problem and reconnects.
  Receiver failures do not start a transmitter.

## Validation in this preview

- Official WSJT-X recordings decoded by real WSJT-X 2.6.1 executables:
  **22 FT8, 19 FT4, and 9 WSPR messages**. App parsers validated against these
  outputs; wrapper tests exercise the same command-line integration.
- JS8Call and fldigi receive integrations tested with real localhost TCP and
  XML-RPC connections carrying protocol fixtures. Hardware reception and full
  JS8Call/fldigi audio playback have not yet been tested here.
- Tests cover cycle splitting, gaps, stale-result rejection, mode isolation,
  WAV resampling, malformed messages, local-only configuration, persistence,
  and desktop/mobile controls.
- The website demo now has mode-specific sample messages and timing. Its
  tones and contacts remain simulations, not an audio decoding benchmark.

## Protocol references

- [WSJT-X user guide and sample recordings](https://wsjt.sourceforge.io/wsjtx-main_en.html)
- [WSJT-X jt9 command-line source](https://github.com/WSJTX/wsjtx/blob/master/lib/jt9.f90)
- [JS8Call API specification](https://github.com/JS8Call-improved/JS8Call-improved/blob/master/docs/API.md)
- [JS8Call release notes and current 160-meter preset](https://js8call.com/downloads.html)
- [fldigi XML-RPC reference](https://www.w1hkj.org/FldigiHelp/xmlrpc_control_page.html)

The preview does not bundle WSJT-X, JS8Call, or fldigi binaries. Obtain them
from their projects. Their licenses and copyrights remain with their authors.