Updated README

README.md

@@ -4,12 +4,14 @@ Pi-FM-RDS
 
 ## FM-RDS transmitter using the Raspberry Pi
 
-This program generates an FM modulation, with RDS (Radio Data System) data generated in real time.
+This program generates an FM modulation, with RDS (Radio Data System) data generated in real time. It can include monophonic or stereophonic audio.
 
 It is based on the FM transmitter created by [Oliver Mattos and Oskar Weigl](http://www.icrobotics.co.uk/wiki/index.php/Turning_the_Raspberry_Pi_Into_an_FM_Transmitter), and later adapted to using DMA by [Richard Hirst](https://github.com/richardghirst). Christophe Jacquet adapted it and added the RDS data generator and modulator. The transmitter uses the Raspberry Pi's PWM generator to produce VHF signals.
 
 ![](doc/vfd_display.jpg)
 
+**NEW: now supports any sample rate for audio files, and generates FM-Stereo signals!**
+
 ## How to use it?
 
 Pi-FM-RDS, depends on the `sndfile` library. To install this library on Debian-like distributions, for instance Raspbian, run `sudo apt-get install libsndfile1-dev`.
@@ -31,13 +33,13 @@ sudo ./pi_fm_rds
 This will generate an FM transmission on 107.9 MHz, with default station name (PS), radiotext (RT) and PI-code, without audio. The radiofrequency signal is emitted on GPIO 4 (pin 7 on header P1).
 
 
-You can add monophonic sound by referencing a WAV file as follows:
+You can add monophonic or stereophonic audio by referencing a WAV file as follows:
 
 ```
 sudo ./pi_fm_rds -wav sound.wav
 ```
 
-**Current limitation: the WAV file must be sampled at 228 kHz. Use for instance the two files provided, `sound.wav` and `pulses.wav`. I'm working on lifting this restriction.**
+To test stereophonic audio, you can try the file `stereo_44100.wav` provided.
 
 The more general syntax for running Pi-FM-RDS is as follows:
 
@@ -48,7 +50,7 @@ pi_fm_rds [-freq freq] [-wav file.wav] [-ppm ppm_error] [-pi pi_code] [-ps ps_te
 All arguments are optional:
 
 * `-freq` specifies the carrier frequency (in MHz). Example: `-freq 107.9`.
-* `-wav` specifies a WAV file to play as audio. It must be sampled at 228 kHz, but no frequency above 18 kHz must be present. Example: `-wav sound.wav`.
+* `-wav` specifies a WAV file to play as audio. The sample rate does not matter: Pi-FM-RDS will resample and filter it. If a stereo file is provided, Pi-FM-RDS will produce an FM-Stereo signal. Example: `-wav sound.wav`.
 * `-pi` specifies the PI-code of the RDS broadcast. 4 hexadecimal digits. Example: `-pi FFFF`.
 * `-ps` specifies the station name (Program Service name, PS) of the RDS broadcast. Limit: 8 characters. Example: `-ps RASP-PI`.
 * `-rt` specifies the radiotext (RT) to be transmitted. Limit: 64 characters. Example: `-rt 'Hello, world!'`.
@@ -91,6 +93,17 @@ Reception works perfectly with all the devices above. RDS Surveyor reports no gr
 
 ![](doc/galaxy_s2.jpg)
 
+
+### CPU Usage
+
+CPU usage is as follows:
+
+* without audio: 9%
+* with mono audio: 42%
+* with stereo audio: 54%
+
+CPU usage increases dramatically when adding audio because the program has to upsample the (unspecified) sample rate of the input audio file to 228 kHz, its internal operating sample rate. Doing so, it has to apply an FIR filter, which is costly.
+
 ## Design
 
 The RDS data generator lies in the `rds.c` file.
@@ -101,13 +114,25 @@ To get samples of RDS data, call `get_rds_samples`. It calls `get_rds_group`, di
 
 The shaped biphase symbol is generated once and for all by a Python program called `generate_waveforms.py` that uses [Pydemod](https://github.com/ChristopheJacquet/Pydemod), one of my other software radio projects. This Python program generates an array called `waveform_biphase` that results from the application of the RRC filter to a positive-negative impulse pair. *Note that the output of `generate_waveforms.py`, two files named `waveforms.c` and `waveforms.h`, are included in the Git repository, so you don't need to run the Python script yourself to compile Pi-FM-RDS.*
 
-The samples are played by `pi_fm_rds.c` that is adapted from Richard Hirst's [PiFmDma](https://github.com/richardghirst/PiBits/tree/master/PiFmDma). The program was changed to support a sample rate of precisely 228 kHz, four times the RDS subcarrier's 57 kHz.
+Internally, the program samples all signals at 228 kHz, four times the RDS subcarrier's 57 kHz.
+
+The FM multiplex signal (baseband signal) is generated by `fm_mpx.c`. This file handles the upsampling of the input audio file to 228 kHz, and the generation of the multiplex: unmodulated left+right signal (limited to 15 kHz), possibly the stereo pilot at 19 kHz, possibly the left-right signal, amplitude-modulated on 38 kHz (suppressed carrier) and RDS signal from `rds.c`. Upsampling is performed using a zero-order hold followed by an FIR low-pass filter of order 60. I use a sampled sinc windowed by a Hamming window. The filter coefficients are generated at startup so that the filter cuts frequencies above the minimum of:
+* the Nyquist frequency of the input audio file (half the sample rate) to avoid aliasing,
+* 15 kHz, the bandpass of the left+right and left-right channels, as per the FM broadcasting standards.
+
+The samples are played by `pi_fm_rds.c` that is adapted from Richard Hirst's [PiFmDma](https://github.com/richardghirst/PiBits/tree/master/PiFmDma). The program was changed to support a sample rate of precisely 228 kHz.
+
 
 ### References
 
 * [EN 50067, Specification of the radio data system (RDS) for VHF/FM sound broadcasting in the frequency range 87.5 to 108.0 MHz](http://www.interactive-radio-system.com/docs/EN50067_RDS_Standard.pdf)
 
 
+## History
+
+* 2014-04-14: new release that supports any sample rate for the audio input, and that can generate a proper FM-Stereo signal if a stereophonic input file is provided
+* 2014-04-06: initial release, which only supported 228 kHz monophonic audio input files
+
 --------
 
 © [Christophe Jacquet](http://www.jacquet80.eu/) (F8FTK), 2014. Released under the GNU GPL v3.