
                              Readme File for Code Example:
        CE482 - Using the Fast Fourier Transform (FFT) for Frequency Detection
        ----------------------------------------------------------------------

This file contains the following sections:
1. Code Example Description
2. Output Verification
3. Folder Contents
3. Suggested Development Resources
5. Reconfiguring the project for a different dsPIC30F device
6. Reconfiguring the project for a different FFT Size:
7. Revision History


1. Code Example Description:
----------------------------
Microchip's 16-bit dsPIC Digital Signal Controllers feature a DSP Engine in the CPU that is capable of executing a Fast Fourier Transform (FFT) 
with great efficiency (high speed and low RAM usage). The on-chip features enabling the FFT implementation include, bit-reversed addressing,
Multiply-accumulate (MAC) type instructions and the ability to store and retrieve constants stored in Program memory.

Microchip provides a DSP functions library that provides in-place FFT functions.

In this code example, we demonstrate how the DSP library functions can be used to perform an FFT on an input signal (vector). The code example is
reconfigurable to perfrom an FFT of any size, including common sizes of 64, 128, 256 and 512 points. The code example also allows the user to place 
the FFT coefficients (known as Twiddle Factors) in RAM or in Program Flash Memory. The project may be easily reconfigured by modifying the header
 file, FFT.h. By default, the example implements a 256-point FFT using coefficients stored in Program Flash memory.

The input signal for our example will be 256 points of a Square wave signal of frequency 1KHz sampled at 10 KHz. This signal was first generated by
 dsPICworks and then exported as an assembler file from dsPICworks. After exporting it out, the assembler file was modified to ensure the samples
 reside in Y-data space.

The FFT operation is performed on the input signal, in-place. This means that the output of the FFT resides in the same RAM locations where the
 input signal used to reside. The FFT is performed in the following steps:

1. Initialization: Generate Twiddle Factor Coefficients and store them in X-RAM or alternately use twiddle factor coefficients stored in
 Program Flash.

2. Scale the input signal to lie within the range [-0.5, +0.5]. For fixed point fractional input data, this translates to input samples in 
the range [0xC000,0x3FFF]. The scaling is achieved by simply right-shifting the input samples by 1 bit, assuming the input samples lie 
in the fixed point range [0x8000,0x7FFF] or [-1,+1).

3. Convert the real input signal vector to a complex vector by placing zeros in every other location to signify a complex input whose
 imaginary part is 0x0000.

4. Butterfly computation: This is achieved by performing a call to the FFTComplexIP() function.

5. Bit-Reversed Re-ordering: The output array is re-ordered to be in bit-reversed order of the addresses. This is achieved by a function
 call to BitReverseComplex().

6. SquareMagnitude computation: We then need to compute the magnitude of each complex element in the output vector, so that we can estimate 
the energy in each spectral component/frequency bin. This is achieved by a call to a special C-callable routine, SquareMagnitudeCplx(), 
written in assembler language. This routine will  be incorporated into the DSP library in future revisions of the C30 toolsuite. At that time,
 you may remove the source file, cplxsqrmag.s from the project and include the latest DSP library file, libdsp-coff.a.

7. Peak-picking: We then find the frequency component with the largest energy by using the VectorMax() routine in the DSP library.

8. Frequency Calculation: The value of the spectral component with the highest energy, in Hz, is calculated by multiplying the array index of 
the largest element in the output array with the spectral (bin) resolution ( = sampling rate/FFT size).


2. Output Verification:
-------------------
  Observe output variable peakFrequency in debugger. Value should be almost near to 1Khz.


3. Folder Contents:
-------------------
a. firmware
        This folder contains all the C, Assembler source files and include files(*.c,
        *.s, *.h) and project specific files used in demonstrating the described example. 
b. system_config
		This folder contains the chip-set specific configuration code. More specifically it in-turn contains a folder called exp16/ 
		which holds configuration files.
c. exp16/
		This folder contains various folders like dspic33ep512gm710/dspic33ep512mu810/dspic33ep256gp506 depending on the platform.Each platform folder contain,configuration 
		specific source files.


4. Suggested Development Resources:
-----------------------------------
        a. Explorer 16 Demo board with dspic33ep512gm710/dspic33ep512mu810/dspic33ep256gp506 controller

5. Reconfiguring the project for a different dsPIC33E device:
-------------------------------------------------------------
The Project/Workspace can be easily reconfigured for dspic33ep512gm710/dspic33ep512mu810/dspic33ep256gp506 device.
Please use the following general guidelines:
        a. Change device selection within MPLAB IDE to dspic33ep512gm710/dspic33ep512mu810/dspic33ep256gp506 device of
        your choice by using the following menu option:
        MPLAB X>>Configuration drop-down option>><Listed Device Configuration>

        b. Re-build the MPLAB project using the menu option:
        MPLAB X>>Build Main Project

        c. Download the hex file into the device and run.

6. Reconfiguring the project for a different FFT Size:
-------------------------------------------------------------
The project has been configured for a 256-pt FFT to be performed on a 30F6014A device.
Perform the following steps in sequence to change the device and FFT size.

        (i) Change device selection within MPLAB IDE to a dsPIC33E device of
        your choice by using the following menu option:
        MPLAB X>>Project Properties>>Device

        (ii) Provide the correct device linker script and header file for your
        device. Device linker scripts and header files are available in your
        MPLAB xc16 installation folder under:
        Device Linker Script-
                YourDrive:>Program Files\Microchip\xc16\support\gld
        Device C Header file-
                YourDrive:>Program Files\Microchip\xc16\support\h
        Device ASM Include file-
                YourDrive:>Program Files\Microchip\xc16\support\inc

        (iii) In the file FFT.h, perform the following changes:
                - Change FFT_BLOCK_LENGTH to either 64, 128, 256 or 512
                - Correspondingly, change LOG2_BLOCK_LENGTH to either 6, 7, 8 or
                  9 respectively
                - If you would like to store Twiddle Factors coefficients in RAM
                instead of Program Memory comment out the line of code as shown:
                "//#define FFTTWIDCOEFFS_IN_PROGMEM "

        (iv)  This project uses an input squarewave signal provided as PCM
              samples in the file, "inputsignal_square1khz.c" in the array named
              "sigCmpx[]". This array should be of length, FFT_BLOCK_LENGTH and
              type "fractcomplex". So, for a 64-pt FFT, it should contain only
              64 data samples and padded initially with 64 zeroes. This array
              stores the output of the complex FFT operation and eventually
              stores the magnitudes of the frequency bins.
              Modify this array to suit the FFT size you are using. In a real
              application, your data will likely be input from a real-world
              signal.

        (v)  Re-build the MPLAB project using the menu option:
        MPLAB X>>Build Main Project

        
7. Revision History :
---------------------
        09/30/2005 - Initial Release of the Code Example
        01/05/2006 - Corrected cplxsqrmag.s
        01/17/2006 - Added "5. Reconfiguring the project for a different FFT 
                     Size:" in this readme file and corrected an extern 
                     definition in the main_FFTExample.c file
		02/12/2013 - Ported the code example to dsPIC33E device.
		1/22/2014  - Code Example updated for dspic33ep512gm710/dspic33ep512mu810/dspic33ep256gp506
		12/19/2014 - Code Example updated and added with test automation code