re-arranged and edited README_freedv.md, added some supporting comments to freedv_api.h and demo programs

Author: drowe67

README_freedv.md

@@ -10,24 +10,41 @@ This document gives an overview of the technology inside FreeDV, and some additi
 
 ![FreeDV mode knob](http://www.rowetel.com/images/codec2/mode_dv.jpg)
 
-## Reading Further
+## FreeDV API
 
-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)
+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 |
+
+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
 
@@ -80,34 +97,6 @@ These modes use constant amplitude modulation like FSK or FM, and are designed f
 
 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 API
-
-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 | Demonstrates usage of the codec2_* function calls. |
-| freedv_700d_rx | Demonstrates how to receive a FreeDV voice signal. |
-| freedv_700d_tx | Demonstrates how to transmit a FreeDV voice signal. |
-| freedv_datac1_rx | Demonstrates how to receive a FreeDV data signal. |
-| freedv_datac1_tx | Demonstrates how to transmit a FreeDV data signal. |
-
-See also [freedv_api.h](src/freedv_api.h) and [freedv_api.c](src/freedv_api.c), and the full featured command line demo programs [freedv_tx.c](src/freedv_tx.c) & [freedv_rx.c](src/freedv_rx.c):
-
-```
-$ ./freedv_tx 1600 ../../raw/hts1.raw - | ./freedv_rx 1600 - - | aplay -f S16_LE
-$ cat freedv_rx_log.txt
-```
-
-Note that FreeDV expects and outputs 16-bit integer samples at one of two rates: freedv_get_modem_sample_rate() for transmit output/receive input and freedv_get_speech_sample_rate() for transmit input/receive output. These are typically 8000 Hz but can vary depending on the current FreeDV mode.
-
 ## 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.
@@ -204,3 +193,23 @@ $ ./src/freedv_tx 700D ../raw/ve9qrp.raw - --clip 0 --testframes | ./src/cohpsk_
 ```
 
 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)
+

demo/freedv_700d_rx.c

@@ -4,7 +4,7 @@
   AUTHOR......: David Rowe
   DATE CREATED: April 2021
 
-  Demo receive program for FreeDV API 700D mode, see freedv_700d_tx.c for
+  Demo receive program for FreeDV API (700D mode), see freedv_700d_tx.c for
   instructions.
  
 \*---------------------------------------------------------------------------*/

demo/freedv_700d_tx.c

@@ -4,7 +4,7 @@
   AUTHOR......: David Rowe
   DATE CREATED: April 2021
 
-  Demo transmit program for FreeDV API 700D functions.
+  Demo transmit program using the FreeDV API (700D mode).
  
   usage:
   

src/freedv_api.h

@@ -9,7 +9,8 @@
 
   1. README_freedv.md
   2. Notes on function use in freedv_api.c
-  3. The sample freedv_tx.c and freedv_rx.c programs
+  3. Simple demo programs in the "demo" directory
+  4. The full featured command line freedv_tx.c and freedv_rx.c programs
 
 \*---------------------------------------------------------------------------*/