# Codec 2 README

Codec 2 is an open source (LGPL 2.1) low bit rate speech codec: http://rowetel.com/codec2.html

Also included:

  + The FreeDV API for digital voice over radio. FreeDV is an open source digital voice protocol that integrates modems, codecs, and FEC [README_freedv](README_freedv.md)
  + APIs for raw and Ethernet packet data over radio [README_data](README_data.md)
  + High performance coherent OFDM modem for HF channels [README_ofdm](README_ofdm.md)
  + High performance non-coherent FSK modem [README_fsk](README_fsk.md)
  + An STM32 embedded version of FreeDV 1600/700D/700E for the [SM1000](stm32/README.md)
  + Coherent PSK modem [README_cohpsk](README_cohpsk.md) for HF channels
  + FDMDV DPSK modem [README_fdmdv](README_fdmdv.md) for HF channels

## Quickstart

1. Install packages (Debian/Ubuntu):
   ```
   sudo apt install git build-essential cmake
   ```
   Fedora/RH distros:
   ```
   sudo dnf groupinstall "Development Tools" "C Development Tools and Libraries"
   sudo dnf install cmake
   ```

1. Build Codec 2:
   ```
   git clone https://github.com/drowe67/codec2.git
   cd codec2
   mkdir build_linux
   cd build_linux
   cmake ..
   make
   ```

1. Listen to Codec 2:
   ```
   cd codec2/build_linux
   ./demo/c2demo ../raw/hts1a.raw hts1a_c2.raw
   aplay -f S16_LE ../raw/hts1a.raw
   aplay -f S16_LE hts1a_c2.raw
   ```
1. Compress, decompress and then play a file using Codec 2 at 2400 bit/s:
   ```
   ./src/c2enc 2400 ../raw/hts1a.raw hts1a_c2.bit
   ./src/c2dec 2400 hts1a_c2.bit hts1a_c2_2400.raw
   ```
   which can be played with:
   ```
   aplay -f S16_LE hts1a_c2_2400.raw
   ```
   Or using Codec 2 using 700C (700 bits/s):
   ```
   ./src/c2enc 700C ../raw/hts1a.raw hts1a_c2.bit
   ./src/c2dec 700C hts1a_c2.bit hts1a_c2_700.raw
   aplay -f S16_LE hts1a_c2_700.raw
   ```
1. If you prefer a one-liner without saving to files:
   ```
   ./src/c2enc 1300 ../raw/hts1a.raw - | ./src/c2dec 1300 - - | aplay -f S16_LE
   ```

1. Or you can use your microphone and headphones to encode and listen to the result on the fly:
   ```
   br=1300; arecord -f S16_LE -c 1 -r 8000 | ./src/c2enc $br - - | ./src/c2dec $br - - | aplay -f S16_LE -
   ```

## FreeDV 2020 support (building with LPCNet)

1. Build codec2 initially without LPCNet
   ```
   cd ~
   git clone https://github.com/drowe67/codec2.git
   cd codec2 && mkdir build_linux && cd build_linux
   cmake ../
   make
   ```

1. Build LPCNet:
   ```
   cd ~
   git clone https://github.com/drowe67/LPCNet
   cd LPCNet && mkdir build_linux && cd build_linux
   cmake -DCODEC2_BUILD_DIR=~/codec2/build_linux ../
   make
   ```

1. (Re)build Codec 2 with LPCNet support:
   ```
   cd ~/codec2/build_linux && rm -Rf *
   cmake -DLPCNET_BUILD_DIR=~/LPCNet/build_linux ..
   make
   ```

## Programs

+ See `demo` directory for simple examples of using Codec and the FreeDV API.

+ `c2demo` encodes a file of speech samples, then decodes them and saves the result.

+ `c2enc` encodes a file of speech samples to a compressed file of encoded bits.  `c2dec` decodes a compressed file of bits to a file of speech samples.

+ `c2sim` is a simulation/development version of Codec 2.  It allows selective use of the various Codec 2 algorithms.  For example switching phase modelling or quantisation on and off.

+ `freedv_tx` & `freedv_rx` are command line implementations of the FreeDV protocol, which combines Codec 2, modems, and Forward Error Correction (FEC).

+ `cohpsk_*` are coherent PSK (COHPSK) HF modem command line programs.

+ `fdmdv_*` are differential PSK HF modem command line programs (README_fdmdv).

+ `fsk_*` are command line programs for a non-coherent FSK modem (README_fsk).

+ `ldpc_*` are LDPC encoder/decoder command line programs, based on the CML library.

+ `ofdm_*` are OFDM PSK HF modem command line programs (README_ofdm).

## Building and Running Unit Tests

CTest is used as a test framework, with support from [GNU Octave](https://www.gnu.org/software/octave/) scripts.

1. Install GNU Octave and libraries on Ubuntu with:
   ```
   sudo apt install octave octave-common octave-signal liboctave-dev gnuplot python3-numpy sox valgrind
   ```
1. To build and run the tests:
   ```
   cd ~/codec2
   rm -Rf build_linux && mkdir build_linux
   cd build_linux
   cmake -DUNITTEST=1 ..
   make
   ```

1. To just run tests without rebuilding:
   ```
   ctest
   ```

1. To get a verbose run (e.g. for test debugging):
   ```
   ctest -V
   ```

1. To just run a single test:
   ```
   ctest -R test_OFDM_modem_octave_port
   ```

1. To list the available tests:
   ```
   ctest -N
   ```

1. Many Octave scripts rely on the CML LDPC library.  To run these from the Octave CLI, you need to set
   the `CML_PATH` environment variable.  A convenient way to do this is using a `.octaverc` file
   in your `codec/octave` directory.  For example on a Linux machine, create a `.octaverc` file:
   ```
   setenv("CML_PATH","../build_linux/cml")
   ```

## Directories
```
cmake       - cmake support files
demo        - Simple Codec 2 and FreeDv API demo applications
misc        - misc C programs that have been useful in development,
              not reqd for Codec 2 release. Part of Debug build.
octave      - Octave scripts used to support development
script      - shell scripts for playing and converting raw files
src         - C source code for Codec 2, FDMDV modem, COHPSK modem, FreeDV API
raw         - speech files in raw format (16 bits signed linear 8 kHz)
stm32       - STM32F4 microcontroller and SM1000 FreeDV Adaptor support
unittest    - Code to perform and support testing. Part of Debug build.
wav         - speech files in wave file format
```
## GDB and Dump Files

1. To compile with debug symbols for using gdb:
   ```
   cd ~/codec2
   rm -Rf build_linux && mkdir build_linux
   cd build_linux
   CFLAGS=-g cmake ..
   make
   ```

1. For dump file support (dump data from c2sim for input to Octave development scripts):
   ```
   cd ~/codec2
   rm -Rf build_linux && mkdir build_linux
   cd build_linux
   CFLAGS=-DDUMP cmake ..
   make
   ```

## Building for Windows on a Linux machine

On Ubuntu 17 and above:
   ```
   sudo apt-get install mingw-w64
   mkdir build_windows && cd build_windows
   cmake .. -DCMAKE_TOOLCHAIN_FILE=/home/david/freedv-dev/cmake/Toolchain-Ubuntu-mingw32.cmake -DUNITTEST=FALSE -DGENERATE_CODEBOOK=/home/david/codec2/build_linux/src/generate_codebook
   make
   ```

## Building for Windows on a Windows machine

 ```
 mkdir build_windows (Or what ever you want to call your build dir)
 cmake -G "MinGW Makefiles" -D CMAKE_MAKE_PROGRAM=mingw32-make.exe
 Or if you use ninja for building cmake -G "Ninja" ..
 mingw32-make or ninja  depends on what you used in the last command
 wait for it to build.
 ```


## Including Codec 2 in an Android project

In an Android Studio 'NDK' project (a project that uses 'native' code)
Codec 2 can be added to the project in the following way.

1. Add the Codec 2 source tree to your app (e.g. in app/src/main/codec2)
   (e.g. as a git sub-module).

1. Add Codec 2 to the CMakeList.txt (app/src/main/cpp/CMakeLists.txt):

    ```
    # Sets lib_src_DIR to the path of the target CMake project.
    set( codec2_src_DIR ../codec2/ )
    # Sets lib_build_DIR to the path of the desired output directory.
    set( codec2_build_DIR ../codec2/ )
    file(MAKE_DIRECTORY ${codec2_build_DIR})

    add_subdirectory( ${codec2_src_DIR} ${codec2_build_DIR} )

    include_directories(
	    ${codec2_src_DIR}/src
	    ${CMAKE_CURRENT_BINARY_DIR}/../codec2
    )
    ```

1. Add Codec 2 to the target_link_libraries in the same file.

## Building Codec 2 for Microcontrollers

Codec 2 requires a hardware Floating Point Unit (FPU) to run in real time.

Two build options have been added to support building on microcontrollers:
1. Setting the `cmake` variable MICROCONTROLLER_BUILD disables position independent code (-fPIC is not used).  This was required for the IMRT1052 used in Teensy 4/4.1).

1. On ARM machines, setting the C Flag \_\_EMBEDDED\_\_ and linking with the ARM CMSIS library will improve performance on ARM-based microcontrollers. \_\_REAL\_\_ and FDV\_ARM\_MATH are additional ARM-specific options that can be set to improve performance if required, especially with OFDM modes.

A CMakeLists.txt example for a microcontroller is below:

```
set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY)
set(MICROCONTROLLER_BUILD 1)

set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -mlittle-endian -ffunction-sections -fdata-sections -g -O3")
set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -ffunction-sections -fdata-sections")

add_definitions(-DCORTEX_M7 -D__EMBEDDED__)
add_definitions(-DFREEDV_MODE_EN_DEFAULT=0 -DFREEDV_MODE_1600_EN=1 -DFREEDV_MODE_700D_EN=1 -DFREEDV_MODE_700E_EN=1 -DCODEC2_MODE_EN_DEFAULT=0 -DCODEC2_MODE_1300_EN=1 -DCODEC2_MODE_700C_EN=1)

FetchContent_Declare(codec2
    GIT_REPOSITORY https://github.com/drowe67/codec2.git
    GIT_TAG origin/master
    GIT_SHALLOW ON
    GIT_PROGRESS ON
)
FetchContent_GetProperties(codec2)
if(NOT ${codec2_POPULATED})
    FetchContent_Populate(codec2)
endif()
set(CMAKE_REQUIRED_FLAGS "")

set(LPCNET OFF CACHE BOOL "")
add_subdirectory(${codec2_SOURCE_DIR} ${codec2_BINARY_DIR} EXCLUDE_FROM_ALL)
```

## Building Debian packages

To build Debian packages, simply run the "cpack" command after running "make". This will generate the following packages:

+ codec2: Contains the .so and .a files for linking/executing applications dependent on Codec2.
* codec2-dev: Contains the header files for development using Codec2.

Once generated, they can be installed with "dpkg -i" (once LPCNet is installed). If LPCNet is not desired, CMakeLists.txt can be modified to remove that dependency.

# README_cohpsk.md

## Introduction

## Quickstart

1. BER test in AWGN channel with just less that 2% average bit error rate:

   ```
    $ ./cohpsk_get_test_bits - 5600 | ./cohpsk_mod - - | ./cohpsk_ch - - -30 | ./cohpsk_demod - - | ./cohpsk_put_test_bits -
    <snip>
    SNR3k(dB):  3.41 C/No: 38.2 PAPR:  8.1
    BER: 0.017 Nbits: 5264 Nerrors: 92

  ```

2. Plot some of the demod internal states, used to chase down freq offset problemL

   ```
    $ cd build_linux/src
    $ ./cohpsk_get_test_bits - 5600 | ./cohpsk_mod - -  | ./cohpsk_ch - - -40 -f -20 | ./cohpsk_demod -o cohpsk_demod.txt - - | ./cohpsk_put_test_bits -
    $ cd ../../octave
    $ octave --no-gui
    $ cohpsk_demod_plot("../build_linux/src/cohpsk_demod.txt")
   ```

3. Run Octave<-> tests

   ```
   $ cd ~/codec2/build_linux/unittest
   $ ./tochpsk
   $ cd ~/codec2/octave
   $ octave --no-gui
   octave> tcohpsk
   ```

## References

## C Code

## Octave Scripts

# README_data.md

# Introduction

FreeDV can be used to send data over radio channels.  Two APis are supported:
+ VHF packet data channel which uses Ethernet style framing.
+ Raw frames of modem data over VHF and HF channels.

## Credits

The VHF data channel was developed by Jeroen Vreeken.

## Quickstart

VHF packet data API:

1. Simple test using mode 2400A and VHF packet data

   ```sh
   $ cd ~/codec2/build_linux
   $ ./src/freedv_data_tx 2400A - --frames 15 | ./src/freedv_data_rx 2400A -

   ```
   You can listen to the modem signal using:
   ```sh
   $ ./src/freedv_data_tx 2400A - --frames 15 | aplay -f S16_LE -r 48000

   ```

2. Same for 2400B and 800XA

   ```sh
   $ ./src/freedv_data_tx 2400B - --frames 15 | ./src/freedv_data_rx 2400B -
   $ ./src/freedv_data_tx 800XA - --frames 15 | ./src/freedv_data_rx 800XA -

   ```

3. Using a different callsign and secondary station id

   ```sh
   $ ./src/freedv_data_tx 2400A - --callsign T3ST --ssid 15 --frames 15 | src/freedv_data_rx 2400A -
   ```

Raw modem frame API:

1. Let's send a 128 byte frame containing some text over the modem:
   ```sh
   padding=$(head -c 115 < /dev/zero | tr '\0' '-'); echo "Hello World" $padding > in.txt
   ./src/freedv_data_raw_tx --bursts 1 datac3 in.txt - | ./src/freedv_data_raw_rx --framesperburst 1 datac3 - -
   Hello World --------
   ```
   Note we've padded the input frame to 126 bytes, the DATAC3 framesize (less CRC).

# VHF Packet Data Channel

The FreeDV VHF data channel operates on a packet level. The FreeDV modems however typically operate on a fixed frame base. This means that data packets have to be sent in multiple frames.

The packet format is modeled after Ethernet. As a result, any protocol that is compatible with Ethernet can potentially be used over a FreeDV data link. (There are of course practical limits. Browsing the world wide web with just a few hundred bits per second will not be a pleasant experience.)

## Header optimization

When there are no packets available for transmission a small 'filler' packet with just the sender's address will be sent.
When there is a packet available not all of the header needs to be sent. The sender's address can often be left out if it was already sent in a previous frame. Likewise when the packet has no specific destination but is targeted at a multicast address, this can also be transmitted in a single bit as opposed to a 6 byte broadcast address.


## Addressing

Since the format is based on Ethernet, a 6 byte sender and destination address is used. It is possible to encode an ITU compatible callsign in these bytes. See http://dmlinking.net/eth_ar.html for more info. Or have a look at freedv_data_tx.c and freedv_data_rx.c for an actual implementation.

## Packet types

The 2 byte EtherType field is used to distinguish between various protocols.

## Checks

Not all channels are perfect, and especially since a packet is split up over multiple frames, bits might get lost. Each packet therefore has a CRC which is checked before it is accepted.  Note there is No FEC on 2400A/2400B/800XA.

## Available modes

The data channel is available for modes 2400A, 2400B and 800XA.

## API

The data channel is part of the regular FreeDV API.

### Initialization

After creating a new freedv instance with freedv_open(), a few more calls need to be done before the data channel is usable.

  ```
   void freedv_set_data_header             (struct freedv *freedv, unsigned char *header);
  ```

The address that will be used for 'filler' packets must be set. The freedv_set_data_header() function must be called with a 6 byte header.

  ```
   typedef void (*freedv_callback_datarx)(void *, unsigned char *packet, size_t size);
   typedef void (*freedv_callback_datatx)(void *, unsigned char *packet, size_t *size);
   void freedv_set_callback_data           (struct freedv *freedv, freedv_callback_datarx datarx, freedv_callback_datatx datatx, void *callback_state);
  ```

Using freedv_set_callback_data() two callback functions can be provided. The datarx callback will be used whenever a new data packet has been successfully received. The datatx callback will be used when a new data packet is required for transmission.

### Operation

  ```
   void freedv_datatx  (struct freedv *f, short mod_out[]);
  ```

During normal operation the freedv_datatx() function can be used whenever a data frame has to be sent. If no data is available it will request new data using the datatx callback. The callback function is allowed to set 'size' to zero if no data is available or if it wishes to send an address frame.

For reception the regular freedv_rx() functions can be used as received data will automatically be reported using the datarx callback. Be aware that these functions return the actual number of received speech samples. When a data frame is received the return value will be zero. This may lead to 'gaps' in the audio stream which will have to be filled with silence.

### Examples

The freedv_data_tx and freedv_data_rx test programs implement the minimum needed to send and receive data packets.

## Mixing voice and data

Encoding only voice data is easy with the FreeDV API. Simply use the freedv_tx() function and provide it with speech samples.
Likewise encoding only data is also easy. Make sure to provide a source of data frames using the freedv_set_callback_data() function, and use the freedv_datatx() function to generate frames.

However there are many use cases where one would like to transmit a mix of voice and data. For example one might want to transmit their callsign in a machine readable format, or a short position report. There are a few ways to do this:

### Data bursts at start and/or end of transmission

This method simply transmits voice frames during the transmission, except for a few moments. For example when the user keys the radio the software uses the freedv_datatx() function for a number of frames before switching to regular voice frames.
Likewise when the user releases the key the software may hold it for a number of frames to transmit data before it releases the actual radio.

Be careful though: depending on your setup (radio, PC, soundcard, etc) the generated frames and the keying of your radio might not be perfectly in sync and the first or last frames might be lost in the actual transmission. Make sure to take this into account when using this method.

### Data and voice interleaved

Another method is to generate a mixed stream of frames. Compared to a small burst at the beginning or end a lot more data can be sent. We only need a way to choose between voice or data such that the recovered speech at the other side is not impacted.

#### Detect voice activity

When it is possible to determine activity in the voice signal (and it almost always is) this presence can be used to insert a data frame by calling freedv_datatx() instead of freedv_tx()/freedv_codectx(). This method is used in the freedv_mixed_tx demo program. When the option --codectx is given the codec2 library is used to determine the activity.

  ```
   $ ./src/freedv_mixed_tx 2400A ../raw/hts1a.raw - --codectx | src/freedv_data_rx 2400A -
   $ ./src/freedv_mixed_tx 2400A ../raw/hts1a.raw - | src/freedv_data_rx 2400A -
  ```

The advantage of this method is that the audio is not distorted, there was nothing (or near nothing) to distort. A drawback is that constant voice activity may mean there are insufficient frames for data.

### Receiving mixed voice and data

Receiving and decoding a mixed voice and data stream is (almost) as easy as receiving a regular voice-only transmission.
One simply uses the regular API calls for reception of speech samples. In addition, the callback functions are used for data.
There is one caveat though: when a data frame is received the API functions (like freedv_rx) will return zero as this is the amount of codec/voice data received.
For proper playback silence (or comfort noise) should be inserted for the duration of a frame to restore the timing of the original source speech samples.
An example of how this is done is provided in freedv_mixed_rx

  ```
   $ ./src/freedv_mixed_tx 2400A ../raw/hts1a.raw - | src/freedv_mixed_rx 2400A - ./hts1a_out.raw
  ```

### Insert a data frame periodically

This is a very simple method, simply insert a data frame every n frames, (e.g. once every 10 seconds). Since single FreeDV frames are relatively short (tens of milliseconds) the effect on received audio will be minor. The advantage of this method is that one can create a guaranteed amount of data bandwidth. A drawback is some interruption in the audio that may be noticed.

### Combination of the above.

A combination of the two methods may also be used. Send data when no voice is active and insert a frame when this does not occur for a long time.

# Raw Data using the FreeDV API

The raw data API can be used to send frames of bytes over radio channels.   The frames are protected with FEC and have a 16-bit checksum to verify correct transmission.  However the raw data API may lose frames due to channel impairments, loss of sync, or acquisition delays.  The caller must handle these situations.  The caller is also responsible for segmentation/re-assembly of the modem frames into larger blocks of data.

Several modes are available which support FSK and OFDM modulation. FSK is aimed at VHF And UHF applications, and the OFDM modes have been optimised for multipath HF radio channels.

For simple examples of how use the FreeDV API with raw data frames, see the demo programs [freedv_data1_tx.c](demo/freedv_data1_tx.c) and [freedv_data1_rx.c](src/freedv_data1_rx.c) The full featured sample programs [freedv_data_raw_tx.c](src/freedv_data_raw_tx.c) and [freedv_data_raw_rx.c](src/freedv_data_raw_rx.c) can be used to experiment with the raw data API.

## FSK LDPC Raw Data Mode

The FSK_LDPC mode uses 2 or 4 FSK in combination with powerful LDPC codes, and was designed for VHF or UHF AWGN channels. Parameters such as the number of FSK tones, sample rate, symbol rate, and LDPC code can be selected at initialisation time.  The frame format is:
```
| Preamble | UW | payload data | CRC | parity | UW | payload data | CRC | parity | ........... |
           | frame 1 -------------------------| frame 2 -------------------------| ... frame n |
```
Only one preamble is transmitted for each data burst, which can contain as many frames as you like.  Each frame starts with a 32 bit Unique Word (UW), then the FEC codeword consisting of the data and parity bits.  At the end of the data bits, we reserve 16 bits for a CRC.

Here is an example of sending some text:
```
$ cd codec2/build_linux/src
$ echo 'Hello World                    ' |
  ./freedv_data_raw_tx FSK_LDPC - - 2>/dev/null |
  ./freedv_data_raw_rx FSK_LDPC - - 2>/dev/null |
  hexdump -C
00000000  48 65 6c 6c 6f 20 57 6f  72 6c 64 20 20 20 20 20  |Hello World     |
00000010  20 20 20 20 20 20 20 20  20 20 20 20 20 20        |              ..|
00000020
```
Notes:
1. The input data is padded to 30 bytes.  The (512,256) code sends 256 data bits every frame, we reserve 16 for a CRC, so there are 240 bits, or 30 bytes of payload data required for one frame.
1. The '2>/dev/null' command redirects stderr to nowhere, removing some of the debug information the test programs usually display to make this example easier to read.

When testing, it's convenient to use an internal source of test data. Here is an example where we send a single burst of 10 test frames:
```
$ cd codec2/build_linux/src
$ ./freedv_data_raw_tx --testframes 10 FSK_LDPC /dev/zero - | ./freedv_data_raw_rx --testframes FSK_LDPC - /dev/null
Nbits: 50 N: 4000 Ndft: 1024
bits_per_modem_frame: 256 bytes_per_modem_frame: 32
bytes_per_modem_frame: 32
Frequency: Fs:  8.0 kHz Rs:  0.1 kHz Tone1:  1.0 kHz Shift:  0.2 kHz M: 2

frames processed: 131  output bytes: 320 output_packets: 10
BER......: 0.0000 Tbits:  5440 Terrs:     0
Coded BER: 0.0000 Tbits:  2560 Terrs:     0
```
The default is 100 bits/s 2FSK. The (512,256) code sends 256 data bits (32 bytes) with every codeword, the remaining 256 bits reserved for parity.  The `--testframes` mode reports `320 output bytes` (10 frames where sent), and `Tbits: 2560`, so all of our data made it through.

In real world operation, 16 of the data bits are reserved for a CRC, leaving 240 payload data bits per frame. Taking into account the overhead of the UW, CRC, and parity bits, we send 240 payload data bits for every out of 544, so the payload data rate in this example is (240/512)*(100 bits/s) = 44.1 bits/s.

We can add some channel noise using the `cohpsk_ch` tool and see how it performs:
```
$ ./freedv_data_raw_tx --testframes 1 --bursts 10 FSK_LDPC /dev/zero - |
  ./cohpsk_ch - - -5 --Fs 8000 --ssbfilt 0 |
  ./freedv_data_raw_rx --testframes -v FSK_LDPC - /dev/null
<snip>
frames processed: 336  output bytes: 320 output_packets: 10
BER......: 0.0778 Tbits:  5440 Terrs:   423
SNR3k(dB): -13.00 C/No: 21.8 PAPR:  7.5
Coded BER: 0.0000 Tbits:  2560 Terrs:     0
```
The `cohpsk_ch` stderr reporting is mixed up with the testframes results but we can see that over a channel with a -13dB SNR, we obtained a raw bit error rate of 0.0778 (nearly 8%).  However the LDPC code cleaned that up nicely and still received all 10 packets with no errors.

Here is an example running 4FSK at 20000 bits/s (10000 symbols/s), at a sample rate of 200 kHz:
```
$./freedv_data_raw_tx -m 4 --Fs 200000 --Rs 10000 --tone1 10000 --shift 10000 --testframes 100 --bursts 10 FSK_LDPC /dev/zero - |
 ./cohpsk_ch - - -12 --Fs 8000 --ssbfilt 0 |
 ./freedv_data_raw_rx -m 4 --testframes -v --Fs 200000 --Rs 10000 FSK_LDPC --mask 10000 - /dev/null
 <snip>
 frames processed: 5568  output bytes: 30144 output_packets: 942
BER......: 0.0691 Tbits: 528224 Terrs: 36505
Coded BER: 0.0022 Tbits: 248576 Terrs:   535
```
Some notes on this example:
1. We transmit 10 bursts, each of 100 frames in length, 1000 packets total.  There are a couple of frames silence between each burst.  This gives the acquisition algorithms a good work out.
1. Only 942 packets make it though this rather noisy channel, a 6% Packet Error Rate (PER).  In a real world application, a higher protocol layer would need to detect this, and arrange for re-transmission of missing packets.  If the SNR was a few dB better, all 1000 packets would likely make it through.  If it was 1dB worse, nothing would get through; LDPC codes have a very sharp "knee" in the PER versus SNR curve.
1. Our first tone `--tone` is at 10kHz, and each tone is spaced `--shift` by 10kHz, so we have FSK tones at 10,20,30, and 40 kHz.  For good performance, FSK tones must be spaced by at least the symbol rate Rs.
1. Although the `cohpsk_ch` utility is designed for 8kHz sample rate operation, it just operates on sampled signals, so it's OK to use at higher sample rates.  It does have some internal filtering so best to keep your signal well away from 0 and (sample rate)/2.  The SNR measurement is calibrated to a 3000 Hz noise bandwidth, so won't make much sense at other sample rates.  The third argument `-12` sets the noise level of the channel.
1. The `--mask` frequency offset algorithm is used, which gives better results on noisy channels, especially for 4FSK.

### Reading Further

1. Examples in the [ctests](CMakeLists.txt).
1. [FSK_LDPC blog post](http://www.rowetel.com/?p=7467)

## OFDM Raw Data modes for HF Radio

These modes use an OFDM modem with powerful LDPC codes and are designed for sending data over HF radio channels with multipath fading.  At the time of writing (April 2021) they are a work in progress, but usable as is.  The current modes supported are:

| FreeDV Mode | RF bandwidth (Hz) | Payload data rate bits/s | Payload bytes/frame | FEC | Duration (sec) | MPP test | Use case |
| :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
| DATAC0 | 500 | 291 | 14 | (256,128) | 0.44 | 70/100 at 0dB | Reverse link ACK packets (all SNRs) |
| DATAC1 | 1700 | 980 | 510 | (8192,4096) | 4.18 | 92/100 at 5dB | Forward link data (medium SNR) |
| DATAC3 | 500 | 321 | 126 | (2048,1024) | 3.19 | 74/100 at 0dB | Forward link data (low SNR) |

Notes:
1. 16 bits (2 bytes) per frame are reserved for a 16 bit CRC, e.g. for `datac3` we have 128 byte frames, and 128-2=126 bytes/frame of payload data.
1. SNR is the target operating point SNR for each mode.
1. "MPP test" is the number of packets received/transmitted on a simulated MultiPath Poor channel (1Hz Doppler spread, 2ms delay) at the operating point SNR.

From the callers point of view, the frame format of each burst is:
```
| Preamble | payload data | CRC | payload data | CRC | ........... | Postamble |
           | frame 1 -----------| frame 2 -----------| ... frame N |
```
In the next layer down, each frame is comprised of several OFDM "modem frames", that contain pilot, unique word, and FEC symbols to handle syncronisation and error correction over the challenging HF channel.  The preamble and postamble are used to locate the burst and estimate it's frequency offset.  Having both a pre and postamble increases the probability of successful detection of the burst in a fading channel. Here are some single frame bursts a MPP channel at 5dB SNR:

![](doc/pre_post_amble_mpp.png)

You can see what a mess the MPP channel makes.  Sometimes we find the pre-amble, other times the post-amble.  Using both increases the probability of detecting the burst, it's a form of time diversity.  If the probability of missing the pre-amble is P(fail)=0.1, then the probability of missing the pre and post-amble is P(fail)*P(fail)=0.01. If we find either we can work out where the burst starts and start demodulating.

Here is an example of sending 3 bursts of 2 frames/burst, a total of 6 frames:
```
./src/freedv_data_raw_tx --framesperburst 2 --bursts 3 --testframes 6 DATAC0 /dev/zero - |
./src/freedv_data_raw_rx --framesperburst 2 --testframes DATAC0 - /dev/null --vv
<snip>
BER......: 0.0000 Tbits:  1536 Terrs:     0
Coded BER: 0.0000 Tbits:   768 Terrs:     0
Coded PER: 0.0000 Tpkts:     6 Tpers:     0
```

Lets add some noise and a 20 Hz frequency offset:
```
./src/freedv_data_raw_tx --framesperburst 2 --bursts 3 --testframes 6 DATAC0 /dev/zero - |
./src/cohpsk_ch - - -20 --Fs 8000 -f 20 |
./src/freedv_data_raw_rx --framesperburst 2 --testframes DATAC0 - /dev/null --vv
<snip>
marks:space: 0.83 SNR offset: -0.79
cohpsk_ch: SNR3k(dB):    -0.36  C/No....:    34.42
<snip>
BER......: 0.0195 Tbits:  1536 Terrs:    30
Coded BER: 0.0000 Tbits:   768 Terrs:     0
Coded PER: 0.0000 Tpkts:     6 Tpers:     0
```
We still received 6 frames OK (Tpkts field), but in this case there was a raw BER of about 2% which the FEC cleaned up nicely (Coded BER 0.0).  Just above that we can see the "SNR offset" and "cohpsk_ch: SNR3k" fields.  In the silence between bursts the modem signal has zero power, which biases the SNR measured by the `conhpsk_ch` channels simulation tool.  This bias is the "SNR offset".  So the true SNR for this test is actually:
```
SNR = -0.36 - (-0.79) = 0.43 dB
```

In the `raw` directory is a real world off-air sample of a signal sent between Adelaide and Melbourne (800km) using about 20W on 40m.  This can be decoded with:
```
./src/freedv_data_raw_rx datac1 --framesperburst 1 --testframes ../raw/test_datac1_006.raw /dev/null --vv
<snip>
BER......: 0.0134 Tbits: 73728 Terrs:   986
Coded BER: 0.0000 Tbits: 36864 Terrs:     0
Coded PER: 0.0000 Tpkts:     9 Tpers:     0
```

It's also useful to listen to the file, you can hear co-channel SSB, the bursts starting and stopping, and some fading:
```
aplay -f S16_LE ../raw/test_datac1_006.raw
```

Here is a spectrogram (waterfall on it's side - time flows from left to right, frequency on the Y axis):

![](doc/test_datac1_006_spectrogram.png)

The multipath channel carves notches out of the signal, and the level rises and falls.  The 27 carriers of the `datac1` channel can also be observed.  The SSB is the fuzz along the top. The SNR varied between 8 and 16dB. The fading is even more obvious on the scatter diagram:

![](doc/test_datac1_006_scatter.png)

The X shape is due to the level of each carrier changing with the fading.  In some cases a carrier is faded down to zero.  The FEC helps clean up any errors due to faded carriers.

## SNR estimation and clipping

The modem estimates the SNR of every received packet, which can be useful for selecting the best mode to maximise bit rate while  minimising the packet error rate.

Clipping (compression) is enabled by default on each modem waveform to maximise the Peak to Average Power Ratio (PAPR).  Power amplifiers are usually rated in terms of peak power (PEP). For a given peak power, clipping increases SNR over the channel by 3-4dB.

Clipping works by introducing controlled distortion, which affects the SNR estimator in the modem.  When clipping is enabled, the SNR reported by the datac0 and datac3 modes will start to roll off and reach a plateau at about 8dB with no channel noise.  For the same channel SNR, datac1 will return a higher (and more accurate) SNR estimate.  If clipping is disabled, the datac0 and datac3 modes will report a more accurate SNR.

This command line demonstrates the effect:
```
./src/freedv_data_raw_tx datac3 /dev/zero - --testframes 10 --bursts 10 --clip 1 | ./src/cohpsk_ch - - -100 --fading_dir unittest  --Fs 8000 | ./src/freedv_data_raw_rx datac3 - /dev/null --testframes --framesperburst 1 -v
```
Try adjusting `--clip` and third argument of `cohpsk_ch` (noise level) for different modes.  Note the SNR estimates returned from `freedv_data_raw_rx` compared to the SNR from the channel simulator `cohpsh_ch`. You will notice clipping also increases the RMS power and reduces the PER for a given noise level.

## Reading Further

Resources:
1. See the raw data example in Quickstart section above.
1. For simple examples of how use the FreeDV API, see the demo programs [freedv_datac1_tx.c](demo/freedv_datac1_tx.c) and [freedv_datac1_rx.c](demo/freedv_datac1_rx.c)
1. [freedv_data_raw_tx.c](src/freedv_data_raw_tx.c) and [freedv_data_raw_rx.c](src/freedv_data_raw_rx.c) are more full deatured example programs.
1. The modem waveforms designs are described in this [spreadsheet](doc/modem_codec_frame_design.ods).
1. Examples in the [ctests](CMakeLists.txt) (look for "FreeDV API raw data")
1. [Codec 2 HF Data Modes Part 1 blog post](http://www.rowetel.com/?p=7167)
1. [HF Data Acquisition](https://github.com/drowe67/codec2/pull/171) GitHub Pull Request

# README_fdmdv

## Introduction

A 1400 bit/s (nominal) Frequency Division Multiplexed Digital Voice (FDMDV) modem based on [FreeDV 1600 Specification](https://freedv.org/freedv-specification).  Used for FreeDV 1600.

The FDMDV modem was first implemented in GNU Octave, then ported to C. Algorithm development is generally easier in Octave, but for real-time work we need the C version.  Automated units tests ensure the operation of the Octave and C versions are identical.

## Quickstart

Built as part of codec2, see [README](README.md) for build instructions.

1. Generate some test bits and modulate them:
    ```
    $ ./fdmdv_get_test_bits test.c2 1400
    $ ./fdmdv_mod test.c2 test.raw
    $ play -r 8000 -s -2 test.raw
    ```

1. Two seconds of test frame data modulated and sent out of sound device:
    ```
    $ ./fdmdv_get_test_bits - 2800 | ./fdmdv_mod - - | play -t raw -r 8000 -s -2 -
    ```

1. Send 14000 modulated bits (10 seconds) to the demod and count errors:
    ```
    $  ./fdmdv_get_test_bits - 14000 | ./fdmdv_mod - - | ./fdmdv_demod - - 14 demod_dump.txt | ./fdmdv_put_test_bits -
    ```
    Use Octave to look at plots of 1 second (1400 bits) of modem operation:
    ```
    $ cd ../octave
    $ octave --no-gui
    octave:1> fdmdv_demod_c("../src/demod_dump.txt",14000)
    ```

1. Run Octave simulation of entire modem and AWGN channel:
    ```
    $ cd ../octave
    $ octave
    octave:1> fdmdv_ut
    ```

1. NOTE: If you would like to play modem samples over the air please convert the 8 kHz samples to 48 kHz.  Many PC sound cards have wildly inaccurate sample clock rates when set to 8 kHz, but seem to perform OK when set for 48 kHz.  If playing and recording files you can use the sox utility:
    ```
    $ sox -r 8000 -s -2 modem_sample_8kHz.raw -r 48000 modem_sample_48kHz.wav
    ```
    For real-time applications, the fdmdv.[ch] library includes functions to convert between 48 and 8 kHz sample rates.

1. Send 20 seconds at 2000 bit/s (20 carriers) to demod and count errors:
    ```
    $ ./fdmdv_get_test_bits - 20000 20 | ./fdmdv_mod - - 20 | ./fdmdv_demod - - 20 | ./fdmdv_put_test_bits - 20
    ```

1. Test with timing slips due to sample clock offset of 1000ppm:
    ```
    $ ./fdmdv_get_test_bits - 30000 | ./fdmdv_mod - - | sox -t raw -r 8000 -s -2 - -t raw -r 7990 - | ./fdmdv_demod - - 14 demod_dump.txt | ./fdmdv_put_test_bits -
    octave:98> fdmdv_demod_c("../build_linux/src/demod_dump.txt",28000)
    27552 bits  0 errors  BER: 0.0000
    ```

## References

1. [FreeDV 1600 Specification](https://freedv.org/freedv-specification)
3. [Testing a FDMDV Modem](http://www.rowetel.com/blog/?p=2433)
4. [FDMDV Modem Page](http://www.rowetel.com/blog/?p=2458)

## C Code

| File | Description |
| --- | --- |
| src/fdmdv_mod.c | C version of modulator that takes a file of bits and converts it to a raw file of modulated samples |
| src/fdmdv_demod.c | C version of demodulator that takes a raw file of modulated samples and outputs a file of bits. Optionally dumps demod states to a text file which can be plotted using the Octave script fdmdv_demod_c.m |
| src/codec2_fdmdv.h | Header file that exposes FDMDV C API functions.  Include this file in your application program |
| src/fdmdv.c | C functions that implement the FDMDV modem |
| src/fdmdv-internal.h | internal states and constants for FDMDV modem, shouldn't be exposed to application program |
| unittest/tfdmdv.c | Used to conjunction with unittest/tfdmdv.m to automatically test C FDMDV functions against Octave versions |

## Octave Scripts

Note these require some Octave packages to be installed, see [README](README.md)

| File | Description |
| --- | --- |
| fdmdv.m | Functions and variables that implement the Octave version of the FDMDV modem |
| fdmdv_ut.m | Unit test for fdmdv Octave code, useful while developing algorithm.  Includes tx/rx plus basic channel simulation |
| fdmdv_mod.m | Octave version of modulator that outputs a raw file. The modulator is driven by a test frame of bits.  This can then be played over a real channel or through a channel simulator like PathSim.  The sample rate can be changed using "sox" to simulate differences in tx/rx sample clocks |
| fdmdv_demod.m | Demodulator program that takes a raw file as input, and works out the bit error rate using the known test frame.  Can be used to test the demod performs with off-air signals, or signals that have been passed through a channel simulator |
| fdmdv_demod_c.m | Takes an output text file from the C demod fdmdv_demod.c and produces plots and measures BER. Useful for evaluating fdmdv_demod.c performance. The plots produced are identical to the Octave version fdmdv_demod.m, allowing direct comparison of the C and Octave versions |
| tfdmdv.m | Automatic tests that compare the Octave and C versions of the FDMDV modem functions.  First run unittest/tfdmdv, this will generate a text file with test vectors from the C version.  Then run the Octave script tfdmdv and it will generate Octave versions of the test vectors and compare each vector with the C equivalent.  It plots the vectors and errors (green).  It also produces an automatic checklist based on test results.  If the Octave or C modem code is changed, this script should be used to ensure the C and Octave versions remain identical |

1. Typical fdmdv_ut run:
    ```
    octave:6> fdmdv_ut
    Eb/No (meas): 7.30 (8.29) dB
    bits........: 2464
    errors......: 20
    BER.........: 0.0081
    PAPR........: 13.54 dB
    SNR.........: 4.0 dB
    ```
    It also outputs lots of nice plots that show the operation of the modem.

    For a 1400 bit/s DQPSK modem we expect about 1% BER for Eb/No = 7.3dB, which corresponds to SNR = 4dB (3kHz noise BW). The extra dB of measured power is due to the DBPSK pilot. Currently the noise generation code doesn't take the pilot power into account, so in this example the real SNR is actually 5dB.

1. To generate 10 seconds of modulated signal:
    ```
    octave:8> fdmdv_mod("test.raw",1400*10);
    ```
    To demodulate 2 seconds of the test.raw file generated above:
    ```
    octave:9> fdmdv_demod("test.raw",1400*2);
    2464 bits  0 errors  BER: 0.0000
    ```
    It also produces several plots showing the internal states of the demod.  Useful for debugging and observing what happens with various channels.

## Modelling sample clock errors using sox


This introduces a simulated 1000ppm error:
    ```
    sox -r 8000 -s -2 mod_dqpsk.raw -s -2 mod_dqpsk_8008hz.raw rate -h 8008
    ```

# FreeDV Technology

FreeDV is an open source digital voice protocol that integrates modems, speech codecs, and FEC.

On transmit, FreeDV converts speech to a modem signal you can send over a radio channel.  On receive, FreeDV takes off air modem signals and converts them to speech samples.

FreeDV is available as a GUI application, an open source library (FreeDV API), and in hardware (the SM1000 FreeDV adaptor).  FreeDV is part of the Codec 2 project.

This document gives an overview of the technology inside FreeDV, and some additional notes on building/using the FreeDV 2020 and 2400A/2400B modes.

![FreeDV mode knob](http://www.rowetel.com/images/codec2/mode_dv.jpg)

## FreeDV API

The general programming model is:
  ```
  speech samples -> FreeDV encode -> modulated samples (send over radio) -> FreeDV decode -> speech samples
  ```

The `codec2/demo` directory provides simple FreeDV API demo programs written in C and Python to help you get started, for example:

```
cd codec2/build_linux
cat ../raw/ve9qrp_10s.raw | ./demo/freedv_700d_tx | ./demo/freedv_700d_rx | aplay -f S16_LE
```

The current demo programs are as follows:

| Program | Description |
| --- | --- |
| [c2demo.c](demo/c2demo.c) | Encode and decode speech with Codec 2 |
| [freedv_700d_tx.c](demo/freedv_700d_tx.c) | Transmit a voice signal using the FreeDV API |
| [freedv_700d_rx.c](demo/freedv_700d_rx.c) | Receive a voice signal using the FreeDV API |
| [freedv_700d_rx.py](demo/freedv_700d_rx.py) | Receive a voice signal using the FreeDV API in Python |
| [freedv_datac1_tx.c](demo/freedv_datac1_tx.c) | Transmit raw data frames using the FreeDV API |
| [freedv_datac1_rx.c](demo/freedv_datac1_rx.c) | Receive raw data frames using the FreeDV API |
| [freedv_datac0c1_tx.c](demo/freedv_datac0c1_tx.c) | Transmit two types of raw data frames using the FreeDV API |
| [freedv_datac0c1_rx.c](demo/freedv_datac0c1_rx.c) | Receive two types of raw data frames using the FreeDV API |

So also [freedv_api.h](src/freedv_api.h) and [freedv_api.c](src/freedv_api.c) for the full list of API functions.  Only a small set of these functions are needed for basic FreeDV use, please see the demo programs for minimal examples.

The full featured command line demo programs [freedv_tx.c](src/freedv_tx.c) & [freedv_rx.c](src/freedv_rx.c) demonstrate many features of the API:

```
$ ./freedv_tx 1600 ../../raw/hts1.raw - | ./freedv_rx 1600 - - | aplay -f S16_LE
$ cat freedv_rx_log.txt
```

Speech samples are input to the API as 16 bit signed integers.  Modulated samples can be in real 16 bit signed integer or complex float. The expected sample rates can be found with `freedv_get_speech_sample_rate()` and `freedv_get_modem_sample_rate()`. These are typically 8000 Hz but can vary depending on the current FreeDV mode.

## FreeDV HF Modes

These are designed for use with a HF SSB radio.

| Mode | Date | Codec | Modem | RF BW | Raw bits/s | FEC | Text bits/s | SNR min | Multipath |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 1600 | 2012 | Codec2 1300 | 14 DQPSK + 1 DBPSK pilot carrier | 1125 | 1600 | Golay (23,12) | 25 | 4 | poor |
| 700C | 2017 | Codec2 700C | 14 carrier coherent QPSK + diversity | 1500 | 1400 | - | - | 2 | good |
| 700D | 2018 | Codec2 700C | 17 carrier coherent OFDM/QPSK | 1000 | 1900 | LDPC (224,112)  | 25 | -2 | fair |
| 700E | 2020 | Codec2 700C | 21 carrier coherent OFDM/QPSK | 1500 | 3000 | LDPC (112,56)  | 25 | 1 | good |
| 2020 | 2019 | LPCNet 1733 | 31 carrier coherent OFDM/QPSK | 1600 | 3000 | LDPC (504,396)  | 22.2 | 2 | poor |

Notes:

1. *Raw bits/s* is the number of payload bits/s carried over the channel by the modem.  This consists of codec frames, FEC parity bits, unprotected text, and synchronisation information such as pilot and unique word bits.  The estimates are open to interpretation for the OFDM waveforms due to pilot symbol and cyclic prefix considerations (see spreadsheet).

1. *RF BW* is the bandwidth of the RF signal over the air.  FreeDV is more bandwidth efficient than SSB.

1. *Multipath* is the relative resilience of the mode to multipath fading, the biggest problem digital voice faces on HF radio channels.  Analog SSB would be rated as "good".

1. *Text* is a side channel for low bit rate text such as your location and call sign.  It is generally unprotected by FEC, and encoded with varicode. The exception is if reliable_text support is turned on (see reliable_text.c/h); this results in text protected by LDPC(112,56) FEC with interleaving.

1. *SNR Min* is for an AWGN channel (no multipath/fading).

1. All of the modems use multiple parallel carriers running at a low symbol rate of around 50 Hz.  This helps combat the effects of multipath channels.

1. Some of the Codec 2 modes (2400/1300/700C etc) happen to match the name of a FreeDV mode.  For example FreeDV 700C uses Codec 2 700C for voice compression. However FreeDV 700D *also* uses Codec 2 700C for voice compression, but has a very different modem waveform to FreeDV 700C.  Sorry for the confusing nomenclature.

1. Coherent demodulation gives much better performance than differential, at the cost of some additional complexity.  Pilot symbols are transmitted regularly to allow the demod to estimate the reference phase of each carrier.

1. The 1600 and 700C waveforms use parallel tone modems, later modes use OFDM.  OFDM gives tighter carrier packing which allows higher bit rates, but tends to suffer more from frequency offsets and delay spread.

1. At medium to high SNRs, FreeDV 700C performs well (better than 700D) on fast fading multipath channels with large delay spread due its parallel tone design and high pilot symbol rate.  It employs transmit diversity which delivers BER performance similar to modes using FEC.  FreeDV 700C also has a short frame (40ms), so syncs fast with low latency.  Fast sync is useful on marginal channels that move between unusable and barely usable.

1. FreeDV 700D uses an OFDM modem and was optimised for low SNR channels, with strong FEC but a low pilot symbol rate and modest (2ms) cyclic prefix which means its performance degrades on multipath channels with fast (> 1Hz) fading.  The use of strong FEC makes this mode quite robust to other channel impairments, such as static crashes, urban HF noise, and in-band interference.

1. FEC was added fairly recently to FreeDV modes.  The voice codecs we use work OK at bit error rates of a few %, and packet error rates of 10%. Raw bit error rates on multipath channels often exceed 10%.  For reasonable latency (say 40ms) we need small codewords. Thus to be useful we require a FEC code that works at over 10% raw BER, has 1% output (coded) bit error rate, and a codeword of around 100 bits.  Digital voice has unusual requirements, most FEC codes are designed for data which is intolerant of any bit errors, and few operate over 10% raw BER.  Powerful FEC codes have long block lengths (1000's of bits) which leads to long latency.  However LDPC codes come close, and can also "clean up" other channel errors caused by static and interference.  The use of OFDM means we now have "room" for the extra bits required for FEC, so there is little cost in adding it, apart from latency.

## FreeDV VHF Modes

These modes use constant amplitude modulation like FSK or FM, and are designed for VHF and above.  However 800XA can be run over HF or VHF on a SSB radio.

| Mode | Date | Codec2 | Modem | RF BW | Raw bits/s | FEC | Text bits/s |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 2400A | 2016 | 1300 | 4FSK | 5kHz | 2400 | Golay (23,12) | 50 |
| 2400B | 2016 | 1300 | baseband/analog FM | analog FM | 2400 | Golay (23,12) | 50 |
| 800XA | 2017 | 700C |  4FSK | 2000 | 800 | - | N |
| FSK_LDPC | 2020 | - | 2 or 4 FSK |  user defined | user defined | LDPC | - | - |

The FSK_LDPC mode is used for data, and has user defined bit rate and a variety of LDPC codes available.  It is discussed in [README_data](README_data.md)

## FreeDV 2400A and 2400B modes

FreeDV 2400A and FreeDV 2400B are modes designed for VHF radio. FreeDV 2400A is designed for SDR radios (it has a 5 kHz RF bandwidth), however FreeDV 2400B is designed to pass through commodity FM radios.

Demos of FreeDV 2400A and 2400B:
```
$ ./freedv_tx 2400A ../../raw/ve9qrp_10s.raw - | ./freedv_rx 2400A - - | play -t .s16 -r 8000 -
$ ./freedv_tx 2400B ../../raw/ve9qrp_10s.raw - | ./freedv_rx 2400B - - | play -t .s16 -r 8000 -
```
Note for FreeDV 2400A/2400B the modem signal sample rate is 48kHz.  To
listen to the modem tones from FreeDV 2400B, or play them into a FM HT
mic input:
```
$ ./freedv_tx 2400B ../../raw/ve9qrp_10s.raw - | play -t .s16 -r 48000 -
```
Simulate FreeDV 2400B passing through a 300 to 3000 Hz audio path using sox to filter:
```
$  ./freedv_tx 2400B ../../raw/ve9qrp_10s.raw - | sox -t .s16 -r 48000 - -t .s16 - sinc 300-3000 | ./freedv_rx 2400B - - | play -t .s16 -r 8000 -
```

## FreeDV 2020 support (building with LPCNet)

1. Build codec2 initially without LPCNet
   ```
   $ cd ~
   $ git clone https://github.com/drowe67/codec2.git
   $ cd codec2 && mkdir build_linux && cd build_linux
   $ cmake ../
   $ make
   ```

1. Build LPCNet:
   ```
   $ cd ~
   $ git clone https://github.com/drowe67/LPCNet
   $ cd LPCNet && mkdir build_linux && cd build_linux
   $ cmake -DCODEC2_BUILD_DIR=~/codec2/build_linux ../
   $ make
   ```

1. (Re)build Codec 2 with LPCNet support:
   ```
   $ cd ~/codec2/build_linux && rm -Rf *
   $ cmake -DLPCNET_BUILD_DIR=~/LPCNet/build_linux ..
   $ make
   ```

## FreeDV 2020 tests with FreeDV API

```
$ cat ~/LPCNet/wav/wia.wav | ~/LPCNet/build_linux/src/lpcnet_enc -s | ./ofdm_mod --mode 2020 --ldpc --verbose 1 -p 312 | ./ofdm_demod --mode 2020 --verbose 1 --ldpc -p 312 | ~/LPCNet/build_linux/src/lpcnet_dec -s | aplay -f S16_LE -r 16000
```
Listen the reference tx:
```
$ cat ~/LPCNet/wav/wia.wav | ~/LPCNet/build_linux/src/lpcnet_enc -s | ./ofdm_mod --mode 2020 --ldpc --verbose 1 -p 312 | aplay -f S16_LE
```

Listen the freedv_tx:
```
$ ./freedv_tx 2020 ~/LPCNet/wav/wia.wav - | aplay -f S16_LE
```

FreeDV API tx, with reference rx from above:
```
$ ./freedv_tx 2020 ~/LPCNet/wav/wia.wav - | ./ofdm_demod --mode 2020 --verbose 1 --ldpc -p 312 | ~/LPCNet/build_linux/src/lpcnet_dec -s | aplay -f S16_LE -r 16000
```

FreeDV API tx and rx:
```
$ ./freedv_tx 2020 ~/LPCNet/wav/all.wav - | ./freedv_rx 2020 - - | aplay -f S16_LE -r 16000
$ ./freedv_tx 2020 ~/LPCNet/wav/all.wav - --testframes | ./freedv_rx 2020 - /dev/null --testframes -vv
```

Simulated HF slow fading channel, 10.8dB SNR:
```
$ ./freedv_tx 2020 ~/LPCNet/wav/all.wav - | ./cohpsk_ch - - -30 --Fs 8000 --slow | ./freedv_rx 2020 - - | aplay -f S16_LE -r 16000
```
It falls down quite a bit with fast fading (--fast):

AWGN (noise but no fading) channel, 2.8dB SNR:
```
$ ./freedv_tx 2020 ~/LPCNet/wav/all.wav - | ./cohpsk_ch - - -22 --Fs 8000 | ./freedv_rx 2020 - - | aplay -f S16_LE -r 16000
```

## Command lines for PER testing 700D/700E PER with clipper

AWGN:
```
$ ./src/freedv_tx 700D ../raw/ve9qrp.raw - --clip 0 --testframes | ./src/cohpsk_ch - - -16 --Fs 8000 | ./src/freedv_rx 700D - /dev/null --testframes
```
MultiPath Poor (MPP):
```
$ ./src/freedv_tx 700D ../raw/ve9qrp.raw - --clip 0 --testframes | ./src/cohpsk_ch - - -24 --mpp --fading_dir unittest --Fs 8000 | ./src/freedv_rx 700D - /dev/null --testframes
```

Adjust `--clip [0|1]` and 3rd argument of `cohpsk_ch` to obtain a PER of just less than 0.1, and note the SNR and PAPR reported by `cohpsk_ch`.  The use of the `ve9qrp` samples makes the test run for a few minutes, in order to get reasonable multipath channel results.

## Reading Further

1. [FreeDV web site](http://freedv.org)
1. [FreeDV GUI User Manual](https://github.com/drowe67/freedv-gui/blob/master/USER_MANUAL.md)
1. [Codec 2](http://rowetel.com/codec2.html)
1. FreeDV can also be used for data [README_data](https://github.com/drowe67/codec2/blob/master/README_data.md)
1. [FreeDV 1600 specification](https://freedv.org/freedv-specification)
1. [FreeDV 700C blog post](http://www.rowetel.com/wordpress/?p=5456)
1. [FreeDV 700D Released blog post](http://www.rowetel.com/wordpress/?p=6103)
1. [FreeDV 2020 blog post](http://www.rowetel.com/wordpress/?p=6747)
1. [FreeDV 2400A blog post](http://www.rowetel.com/?p=5119)
1. [FreeDV 2400A & 2400B](http://www.rowetel.com/?p=5219)
1. Technical information on various modem waveforms in the [modem codec frame design spreadsheet](https://github.com/drowe67/codec2/blob/master/doc/modem_codec_frame_design.ods)
1. [Modems for HF Digital Voice Part 1](http://www.rowetel.com/wordpress/?p=5420)
1. [Modems for HF Digital Voice Part 2](http://www.rowetel.com/wordpress/?p=5448)
1. [FDMDV modem README](README_fdmdv.md)
1. [OFDM modem README](README_ofdm.md)
1. Many blog posts in the [rowetel.com blog archives](http://www.rowetel.com/?page_id=6172)

# README_fsk

A FSK modem with a non-coherent demodulator.  Performance is within a fraction of a dB of ideal.  The demodulator automagically estimates the tone frequencies and tracks frequency drift.

Here is a typical Bit Error Rate (BER) versus Eb/No curve:

![BER versus Eb/No curve](doc/fsk_modem_ber_8000_100.png)

Note how close the theory line is to measured performance.

This modem can demodulate FSK signals that sound like [this sample](doc/lockdown_3s.wav); and is used to receive images from the [edge of space](https://github.com/projecthorus/wenet):

![HAB image from edge of space](doc/wenet_image.jpg)

## Credits

The Octave version of the modem was developed by David Rowe.  Brady O'Brien ported the modem to C, and wrote the C/Octave tests.  The modem is being maintained by David Rowe.  Mark Jessop has helped improve the modem operation by testing against various balloon telemtry waveforms.  Bill Cowley has developed the Log Likelihood Ratio (LLR) algorithms for 4FSK.

## Quickstart

1. Build codec2:
   ```
   $ cd codec2 && mkdir build_linux && cmake .. && make
   ```

1. Generate 1000 test bits, modulate them using 2FSK using a 8000 Hz sample rate, 100 bits/s, play on your sound card:
   ```
   $ cd ~/codec2/build_linux/src
   $ ./fsk_get_test_bits - 1000 | ./fsk_mod 2 8000 100 1200 1200 - - | aplay -f S16_LE
   ```
    The low tone frequency is 1200Hz, and the upper tone 1200 + 1200 = 2400Hz.

1. Add the demodulator and measure the bit error rate over 10,000 bits of 100 bit/s 2FSK:
   ```
   $ ./fsk_get_test_bits - 10000 | ./fsk_mod 2 8000 100 1200 100 - - | ./fsk_demod 2 8000 100 - - | ./fsk_put_test_bits -
   <snip>
   [0099] BER 0.000, bits tested   9900, bit errors    0
   PASS
   ```
   We get a Bit Error Rate (BER) of 0, as there is no channel noise to induce bit errors.

1. Same thing but this time with 4FSK, and less verbose output:
   ```
   $ ./fsk_get_test_bits - 10000 | ./fsk_mod 4 8000 100 1200 100 - - | ./fsk_demod 4 8000 100 - - | ./fsk_put_test_bits -q -
   <snip>
   [0099] BER 0.000, bits tested   9900, bit errors    0
   PASS
   ```

1. Lets add some channel noise:
   ```
   $ ./fsk_get_test_bits - 10000 | ./fsk_mod 2 8000 100 1200 100 - - | ./cohpsk_ch - - -26 --Fs 8000 | ./fsk_demod 2 8000 100 - - | ./fsk_put_test_bits -b 0.015 -
   <snip>
   SNR3k(dB): -5.76 C/No: 29.0 PAPR:  3.0
   [0099] BER 0.010, bits tested   9900, bit errors  103
   PASS
   ```
   The cohpsk_ch utility takes the FSK modulator signal, and adds calibrated noise to it (the -26 value specifies the noise).  Try changing the noise level, and note how the Bit Error Rate (BER) changes.  The BER is 0.01, which is right on theory for this sort of FSK demodulator at this SNR (2FSK non-coherent demodulator Eb/No=9dB).

   The SNR is calculated using the signal power divided by the noise power in 3000 Hz.  The C/No value is the same thing, but uses a noise bandwidth of 1 Hz.  There is less noise power when you look at just 1Hz, so C/No is higher. Peak to Average Power ratio (PAPR) is 3dB as a FSK signal is just a single sine wave, and a sine wave peak is 3dB higher than it's average.

1. You can visualise the C modem operation with a companion python script, for example:
   ```
   $ ./fsk_get_test_bits - 10000 | ./fsk_mod -p 10 4 8000 400 400 400 - - | ./fsk_demod -p 10 -t1 4 8000 400 - /dev/null 2>stats.txt
   $ python ../../octave/plot_fsk_demod_stats.py stats.txt
   ```

1. Send some digital voice using FSK at 800 bits/s, and try the two 2400 bits/s FSK modes:
   ```
   $ ./freedv_tx 800XA ../../raw/ve9qrp.raw - | ./freedv_rx 800XA - - -vv | aplay -f S16_LE
   $ ./freedv_tx 2400A ../../raw/ve9qrp.raw - | ./freedv_rx 2400A - - -vv | aplay -f S16_LE
   $ ./freedv_tx 2400B ../../raw/ve9qrp.raw - | ./freedv_rx 2400B - - -vv | aplay -f S16_LE
   ```

1. LDPC encoded 4FSK, with framing:
   ```
   $ cd ~/codec2/build_linux/src
   $ ./ldpc_enc /dev/zero - --code H_256_512_4 --testframes 200 |
     ./framer - - 512 5186 | ./fsk_mod 4 8000 100 1000 100 - - |
     ./cohpsk_ch - - -24 --Fs 8000  |
     ./fsk_demod -s 4 8000 100 - - |
     ./deframer - - 512 5186  |
     ./ldpc_dec - /dev/null --code H_256_512_4 --testframes
   <snip>
   SNR3k(dB): -7.74 C/No: 27.0 PAPR:  3.0
   Raw   Tbits: 100352 Terr:   6701 BER: 0.067
   Coded Tbits:  50176 Terr:    139 BER: 0.003
         Tpkts:    196 Tper:      4 PER: 0.020
   ```
   In this example the unique word is the 16 bit sequence `5186`.  See also several ctests using these application. Other codes are also available:
   ```
   $ ./ldpc_enc --listcodes

   H2064_516_sparse     rate 0.80 (2580,2064)
   HRA_112_112          rate 0.50 (224,112)
   HRAb_396_504         rate 0.79 (504,396)
   H_256_768            rate 0.33 (768,256)
   H_256_512_4          rate 0.50 (512,256)
   HRAa_1536_512        rate 0.75 (2048,1536)
   H_128_256_5          rate 0.50 (256,128)
   ```
   If you change the code you also need to change the `frameSizeBits` argument in `framer/deframer` (`512` in the example above).

1. The FSK/LDPC/framer steps above have been combined in a FreeDV API mode.  See "FSK LDPC Raw Data Mode" in [README_data.md](README_data.md).

1. FSK modem C files in ```codec2/src```:

   | File | Description |
   | ---  | --- |
   | fsk.c/fsk.h | core FSK modem library |
   | fsk_mod.c | command line modulator |
   | fsk_demod.c | command line demodulator |
   | fsk_get_test_bits.c | source of test bits |
   | fsk_put_test_bits.c | test bit sync, counts bit errors and packet errors |
   | fsk_mod_ext_vco.c | modulator that uses an external FSK oscillator |
   | framer.c | adds a unique word to a frame of bits to implement frame sync for LDPC codewords |
   | deframer.c | locates and strips a unique word to implement frame sync for LDPC codewords |
   | tollr.c | converts bits to LLRs for testing LDPC framing |

1. GNU Octave files in ```codec2/octave```:

   | File | Description |
   | ---  | --- |
   | fsk_lib.m | Core FSK modem library |
   | fsk_lib_demo.m | A demonstration of fsk_lib, runs a single point BER test |
   | fsk_demod_file.m | Demodulates FSK signals from a file, useful for debugging FSK waveforms |
   | fsk_lock_down.m | simulations to support the "lock down" low SNR waveform |
   | tfsk.m | automated test that compares the C and Octave versions of the modem |
   | fsk_cml.m | Symbol rate experiments with FSK modem LLR estimation and LDPC |
   | fsk_cml_sam.m | Sample rate experiments with FSK modem LLR estimation and LDPC |
   | fsk_llr_plot.m | Plots curves from fsk_cml.m & fsk_cml_sam.m |
   | fsk_lib_ldpc_demo.m | CML library LLR routines and LDPC codes with fsk_lib.m |

   You can run many of them from the Octave command line:
   ```
   $ octave --no-gui
   octave:1> fsk_lib_demo
   ```

1. A suite of automated ctests that exercise the C and Octave code:
   ```
   $ cd ~/codec2/build_linux
   $ ctest -R test_fsk
   1/9 Test #39: test_fsk_lib ......................   Passed    3.37 sec
   3/9 Test #41: test_fsk_modem_octave_port ........   Passed    4.17 sec
   4/9 Test #42: test_fsk_modem_mod_demod ..........   Passed    0.06 sec
   5/9 Test #43: test_fsk_2fsk_ber .................   Passed    0.24 sec
   6/9 Test #44: test_fsk_4fsk_ber .................   Passed    0.12 sec
   7/9 Test #45: test_fsk_4fsk_ber_negative_freq ...   Passed    0.07 sec
   8/9 Test #46: test_fsk_4fsk_lockdown ............   Passed    2.84 sec
   9/9 Test #47: test_fsk_vhf_framer ...............   Passed    0.06 sec
   ```
   These are written in ```codec2/CmakeLists.txt```, inspect them to find out how we test the modem.

1. ```fsk_demod_file.m``` is useful for peering inside the modem, for example when debugging.
   ```
   $ cd ~/codec2/build_linux/src
   $ ./fsk_get_test_bits - 1000 | ./fsk_mod 2 8000 100 1000 1000 - ../../octave/fsk.s16
   $ octave --no-gui
   octave:1> fsk_demod_file("fsk.s16",format="s16",8000,100,2)
   ```

## Further Reading

   Here are some links to projects and blog posts that use this modem:

   1. [Horus Binary](https://github.com/projecthorus/horusbinary) High Altitude Balloon (HAB) telemetry protocol, 3 second updates, works at 7dB lower SNR that RTTY.
   1. [Testing HAB Telemetry, Horus binary waveform](http://www.rowetel.com/?p=5906)
   1. A really useful reference on a variety of modulation techniques from [Atlanta DSP](http://www.atlantarf.com/FSK_Modulation.php).  I keep this handy when experimenting with modems.
   1. The [RTTY modem project](http://www.rowetel.com/?p=4629) that kicked off the FSK modem work.
   1. [Wenet](https://github.com/projecthorus/wenet) - high speed SSTV images from balloons at the edge of space
   1. [Wenet High speed SSTV images](http://www.rowetel.com/?p=5344)
   1. [FreeDV 2400A and 2400B](http://www.rowetel.com/?p=5219), digital speech for VHF/UHF radios.
   1. [HF FSK with Rpitx](http://www.rowetel.com/?p=6317), a zero hardware FSK transmitter using a Pi
   1. [Eb/No and SNR worked Example](http://www.rowetel.com/wordpress/?p=4621)
   1. [FSK LLR LDPC Code Experiments](https://github.com/drowe67/codec2/pull/129)
   1. [FreeDV API FSK LDPC Raw Data Mode](README_data.md)

# README_ofdm

An Orthogonal Frequency Division Multiplexed (OFDM) modem designed for digital voice over HF SSB.  Typical configuration for FreeDV 700D is 700 bit/s voice, a rate 0.5 LDPC code, and 1400 bit/s raw data rate over the channel.

The OFDM modem was first implemented in GNU Octave, then ported to C. Algorithm development is generally easier in Octave, but for real time work we need the C version.  Automated units tests ensure the operation of the Octave and C versions are identical.

## Credits

Steve, David, Don, Richard

## References

1. Spreadsheet describing the [waveform design](doc/modem_codec_frame_design.ods)  The OFDM tab descrives the baseline 700D OFDM waveform.

1. This modem can be used for sending [raw data frames](README_data.md) over HF channels.

1. [Towards FreeDV 700D](https://www.rowetel.com/?p=5573)

1. [FreeDV 700D - First Over The Air Tests](https://www.rowetel.com/?p=5630)

1. [Steve Ports an OFDM modem from Octave to C](https://www.rowetel.com/?p=5824)

1. [Modems for HF Digital Voice Part 1](http://www.rowetel.com/wordpress/?p=5420)

1. [Modems for HF Digital Voice Part 2](http://www.rowetel.com/wordpress/?p=5448)

# Examples

Built as part of codec2-dev, see [README](README.md) for build instructions.

1. Generate 10 seconds of test frame bits, modulate, and play audio
   out of sound device (SoX v14.4.2):
   ```
   $  build_linux/src$ ./ofdm_mod --in /dev/zero --testframes 10 | play --type s16 --rate 8000 --channels 2 -
   ```

1. Generate 10 seconds of uncoded test frame bits, modulate, demodulate, count errors:
   ```
   $  build_linux/src$ ./ofdm_mod --in /dev/zero --testframes 10 | ./ofdm_demod --out /dev/null --testframes --verbose 1 --log demod_dump.txt
   ```
   Use Octave to look at plots of C modem operation:
   ```
     $ cd ../../octave
     $ octave --no-gui
     octave:1> ofdm_demod_c("../build_linux/src/demod_dump.txt")
   ```

1. Run Octave versions of mod and demod (called tx and rx to avoid namespace clashes in Octave):
   ```
   $ cd ~/octave
   $ octave --no-gui
   octave:1> ofdm_tx("ofdm_test.raw","700D",10)
   octave:1> ofdm_rx("ofdm_test.raw")
   ```
   The Octave modulator ofdm_tx can simulate channel impairments, for
   example AWGN noise at 4dB SNR:
   ```
     octave:1> ofdm_tx("ofdm_test.raw", "700D", 10, 4)
   ```
   The Octave versions use the same test frames as C so can interoperate.
   ```
     build_linux/src$ ./ofdm_demod --in ../../octave/ofdm_test.raw --out /dev/null --testframes --verbose 1
   ```

1. Run mod/demod with LDPC FEC; 60 seconds, 3dB SNR:
   ```
     octave:6> ofdm_ldpc_tx('ofdm_test.raw',"700D",60,3)
     octave:7> ofdm_ldpc_rx('ofdm_test.raw',"700D")
   ```
   C demodulator/LDPC decoder:
   ```
   build_linux/src$ ./ofdm_demod --in ../../octave/ofdm_test.raw --out /dev/null --verbose 1 --testframes --ldpc
   ```

1. Pass Codec 2 700C compressed speech through OFDM modem:
   ```
   build_linux/src$ ./c2enc 700C ../../raw/ve9qrp_10s.raw - --bitperchar | ./ofdm_mod --ldpc | ./ofdm_demod --ldpc | ./c2dec 700C - - --bitperchar | play --type s16 --rate 8000 --channels 1 -
   ```

1. Listen to signal through simulated fading channel in C:
   ```
   build_linux/src$ ./c2enc 700C ../../raw/ve9qrp_10s.raw - --bitperchar | ./ofdm_mod --ldpc | ./cohpsk_ch - - -20 --Fs 8000 --slow -f -5 | aplay -f S16
   ```

1. Run test frames through simulated channel in C:
   ```
   build_linux/src$ ./ofdm_mod --in /dev/zero --ldpc --testframes 20 | ./cohpsk_ch - - -24 --Fs 8000 -f -10 --fast | ./ofdm_demod --out /dev/null --testframes --verbose 1 --ldpc
   ```

1. Run codec voice through simulated fast fading channel, just where it starts to fall over:
   ```
   build_linux/src$ ./c2enc 700C ../../raw/ve9qrp.raw - --bitperchar | ./ofdm_mod --ldpc | ./cohpsk_ch - - -24 --Fs 8000 -f -10 --fast | ./ofdm_demod --ldpc --verbose 1 | ./c2dec 700C - - --bitperchar | aplay -f S16
   ```

1. FreeDV 1600 on the same channel conditions, roughly same quality at 8dB higher SNR:
   ```
   build_linux/src$ ./freedv_tx 1600 ../../raw/ve9qrp_10s.raw - | ./cohpsk_ch - - -30 --Fs 8000 -f -10 --fast | ./freedv_rx 1600 - - | aplay -f S16
   ```

1. Using FreeDV API test programs:
   ```
   build_linux/src$ ./freedv_tx 700D ../../raw/hts1a.raw - --testframes | ./freedv_rx 700D - /dev/null --testframes
   build_linux/src$ ./freedv_tx 700D ../../raw/hts1a.raw - | ./freedv_rx 700D - - | aplay -f S16
   build_linux/src$ ./freedv_tx 700D ../../raw/ve9qrp.raw - | ./cohpsk_ch - - -26 --Fs 8000 -f -10 --fast | ./freedv_rx 700D - - | aplay -f S16
   ```

## FreeDV 2020 extensions

1.  20.5ms symbol period, 31 carrier waveform, (504,396) code, but only 312 data bits used, so we don't send unused data bits.  This means we need less carriers (so more power per carrier), and code rate is increased slightly:
    ```
    build_linux/src$ ./ofdm_mod --in /dev/zero --testframes 300 --mode 2020 --ldpc 1 --verbose 1 -p 312 | ./cohpsk_ch - - -22 --Fs 8000 -f 10 --ssbfilt 1 | ./ofdm_demod --out /dev/null --testframes --mode 2020 --verbose 1 --ldpc -p 312

    SNR3k(dB):  2.21 C/No: 37.0 PAPR:  9.6
    BER......: 0.0505 Tbits: 874020 Terrs: 44148
    Coded BER: 0.0096 Tbits: 649272 Terrs:  6230
    ```

## Acquisition tests

1. Acquisition (getting sync) can be problematic in fading channels. Some special tests have been developed, that measure acquisition time on off air 700D samples at different time offsets:
   ```
   octave:61> ofdm_ldpc_rx("../wav/vk2tpm_004.wav", "700D", "", 5, 4)
   build_linux/src$ ./ofdm_demod --in ../../wav/vk2tpm_004.wav --out /dev/null --verbose 2 --ldpc --start_secs 5 --len_secs 4
   ```

1. Different time offsets effectively tests the ability to sync on fading channel in different states.  Stats for a series of these tests can be obtained with:
   ```
   octave:61> ofdm_time_sync("../wav/vk2tpm_004.wav", 30)
   <snip>
   pass: 30 fails: 0 mean: 1.35 var 0.51
   ```

## Octave Acceptance Tests

Here are some useful tests for the Octave, uncoded modem.

The rate 1/2 LDPC code can correct up to about 10% raw BER, so a good test is to run the modem at Eb/No operating points that produce just less that BER=0.1. The BER2 measure truncates the effect of any start up transients, e.g. as the frequency offset is tracked out.

1. HF Multipath:
   ```
   octave:580> ofdm_tx("ofdm_test.raw","700D",60,2,'mpm',20)
   octave:581> ofdm_rx("ofdm_test.raw")
   BER2.: 0.0803 Tbits: 84728 Terrs:  6803
   ```

1. AWGN:
   ```
   octave:582> ofdm_tx("ofdm_test.raw","700D",60,-2,'awgn')
   octave:583> ofdm_rx("ofdm_test.raw")
   BER2.: 0.0885 Tbits: 84252 Terrs:  7459
   ```

## C Acceptance Tests

Here are some useful tests for the LDPC coded C version of the modem, useful to verify any changes.

1. AWGN channel, -2dB:
   ```
   ./ofdm_mod --in /dev/zero --ldpc --testframes 60 --txbpf | ./cohpsk_ch - - -20 --Fs 8000 -f -10 | ./ofdm_demod --out /dev/null --testframes --verbose 1 --ldpc

   SNR3k(dB): -1.85 C/No: 32.9 PAPR:  9.8
   BER......: 0.0815 Tbits: 98532 Terrs:  8031
   Coded BER: 0.0034 Tbits: 46368 Terrs:   157
   ```

1. Fading HF channel:
   ```
   ./ofdm_mod --in /dev/zero --ldpc --testframes 60 --txbpf | ./cohpsk_ch - - -24 --Fs 8000 -f -10 --fast | ./ofdm_demod --out /dev/null --testframes --verbose 1 --ldpc

   SNR3k(dB):  2.15 C/No: 36.9 PAPR:  9.8
   BER......: 0.1015 Tbits: 88774 Terrs:  9012
   Coded BER: 0.0445 Tbits: 41776 Terrs:  1860
   ```

   Note: 10% Raw BER operating point on both channels, as per design.

# Data Modes

The OFDM modem can also support datac1/datac2/datac3 modes for packet data.  The OFDM modem was originally designed for very short (28 bit) voice codec packets.  For data, packets of hundreds to thousands of bits a desirable so we can use long, powerful FEC codewords, and reduce overhead.  The datac1/datac2/datac3 QPSK modes are currently under development.

Here is an example of running the datac3 mode in a low SNR AWGN channel:

```
./src/ofdm_mod --mode datac3 --ldpc --in  /dev/zero --testframes 60 --verbose 1 | ./src/cohpsk_ch - - -20 --Fs 8000 | ./src/ofdm_demod --mode datac3 --ldpc --out /dev/null --testframes -v 1
<snip>
SNR3k(dB): -3.54 C/No: 31.2 PAPR: 10.4
BER......: 0.1082 Tbits: 36096 Terrs:  3905 Tpackets:    47
Coded BER: 0.0000 Tbits: 12032 Terrs:     0
```
Note despite the raw BER of 10%, 47/50 packets are received error free.

# C Code

| File | Description |
| :-- | :-- |
| ofdm.c | OFDM library |
| codec2_ofdm.h | API header file for OFDM library |
| ofdm_get_test_bits | Generate OFDM test frames |
| ofdm_mod | OFDM modulator command line program |
| ofdm_demod | OFDM demodulator command line program, supports uncoded (raw) and LDPC coded test frames, LDPC decoding of codec data, and can output LLRs to external LDPC decoder |
| ofdm_put_test_bits | Measure BER in OFDM test frames |
| unittest/tofdm | Run C port of modem to compare with octave version (see octave/tofdm) |
| cohpsk_ch | From COHPSK modem development, useful C channel simulator |

# Octave Scripts

| File | Description |
| :-- | :-- |
| ofdm_lib | OFDM library |
| ofdm_dev | Used for modem development, run various simulations |
| ofdm_tx | Modulate test frames to a file of sample, cam add channel impairments |
| ofdm_rx | Demod from a sample file and count errors |
| tofdm | Compares Octave and C ports of modem |
| ofdm_ldpc_tx | OFDM modulator with LDPC FEC |
| ofdm_ldpc_rx | OFDM demodulator with LDPC FEC |

## Specifications

Nominal FreeDV 700D configuration:

| Parameter | Value |
| :-- | :-- |
| Modem | OFDM, pilot assisted coherent QPSK |
| Payload bits/s | 700 |
| Text bits/s | 25 (note 4) |
| Unique Word | 10 bits |
| Carriers | 17 |
| RF bandwidth | 944 Hz |
| Symbol period | 18ms
| Cyclic Prefix | 2ms (note 1)
| Pilot rate | 1 in every 8 symbols |
| Frame Period | 160ms |
| FEC | rate 1/2 (224,112) LDPC |
| Operating point | |
|   AWGN | Eb/No -0.5dB SNR(3000Hz): -2.5dB (note 2) |
|   HF Multipath | Eb/No  4.0dB SNR(3000Hz):  2.0dB (note 3) |
|   Freq offset | +/- 60  Hz   (sync range) |
| Freq drift | +/- 0.2 Hz/s (for 0.5 dB loss) |
| Sample clock error | 1000 ppm |

Notes:

1. Modem can cope with up to 2ms of multipath
1.
   ```
   Ideal SNR(3000) = Eb/No + 10*log10(Rb/B)
                     = -1 + 10*log10(1400/3000)
                     = -4.3 dB
   ```
   So we have about 1.8dB overhead for synchronisation, implementation loss,  and the text channel.
1. "CCIR Poor" HF Multipath channel used for testing is two path, 1Hz Doppler, 1ms delay.
1. The text channel is an auxillary channel, unprotected by FEC, that typically carries callsign/location information for Ham stations.