Pull request #30: Develop

Merge in MCU16CE/dspic33e-code-examples from develop to master

* commit '7b773db5009bab64395d9bdf7e51a42dd7ea358c':
  MCU16GITHUB-1278 - Updated version number in changelog
  MCU16GITHUB-1278 - Update main.json with version number
  MCU16GITHUB-1278 - Updated readme, main.json and changelog
  MCU16GITHUB-1278 - FFT Twid factor corrected.
  MCU16GITHUB-1278 - FFT peakFrequency calculation corrected.
  updated jenkinsfile

Author: Vineeth Krishna R

.citd/Jenkinsfilek8s

@@ -53,6 +53,9 @@ pipeline {
         MPLABX_PROJECT_SOURCE = "../"
     }
 
+    triggers { 
+        cron(env.BRANCH_NAME == 'develop' ? 'H H 1 * *': '') 
+    } 
     options {
         timestamps()
         timeout(time: 45, unit: 'MINUTES')

.main-meta/main.json

@@ -4,7 +4,7 @@
    "content":{
       "metaDataVersion":"1.3.0",
       "name":"com.microchip.mplabx.project.dspic33e-code-examples",
-      "version":"1.0.0",
+      "version":"1.0.1",
       "displayName":"dsPIC33E Code Examples",
       "projectName":"dspic33e-code-examples",
       "shortDescription":"dsPIC33E Code Examples",

changelog.md

@@ -1,3 +1,14 @@
+# dsPIC33E Code Examples v1.0.1
+### Release Highlights
+
+Minor corrections on [FFT code example](dspic33e-fft-dsplib).
+
+### Features Added\Updated
+
+* Updated peakFrequency calculation formula to avoid rounding errors.
+* Corrected twiddle factors initialization in [twiddle_factors.c](dspic33e-fft-dsplib/firmware/src/twiddle_factors.c) for FFT lengths of 64 to 256. 
+
+
 # dsPIC33E Code Examples v0.1.0
 ### Release Highlights
 

dspic33e-fft-dsplib/.main-meta/main.json

@@ -4,10 +4,10 @@
    "content":{
       "metaDataVersion":"1.3.0",
       "name":"com.microchip.mplabx.project.dspic33e-fft-dsplib",
-      "version":"1.0.0",
-      "displayName":"FFT dsplib",
+      "version":"1.0.1",
+      "displayName":"FFT implementataion in dsPIC33E",
       "projectName":"dspic33e-fft-dsplib",
-      "shortDescription":"FFT dsplib",
+      "shortDescription":"Example code for dsPIC33E devices, demonstrating the implementation of FFT operations using the XC16/XC-DSC DSP Library.",
       "ide":{
          "name":"MPLABX",
          "semverRange":">=6.00"
@@ -18,7 +18,7 @@
       },
       "dfp":{
          "name":"dsPIC33E-GM-GP-MC-GU-MU_DFP",
-         "semverRange":"^1.3.85"
+         "semverRange":"^1.7.316"
       },
       "device":{
          "metaDataVersion":"1.0.0",
@@ -33,7 +33,9 @@
 	  "peripherals":[
       ],
       "keywords":[
-         "DSP"
+         "DSP",
+		 "FFT",
+		 "Algorithm"
       ]
    }
 }

dspic33e-fft-dsplib/README.md

@@ -1,6 +1,6 @@
 ![image](../images/microchip.jpg)
 
-##  FFT DSPLIB
+##  FFT Implementation using DSP Library
 
 ## Description:
 
@@ -10,42 +10,108 @@ Multiply-accumulate (MAC) type instructions and the ability to store and retriev
 
 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 
+This code example demonstrates how the DSP library functions can be used to perform an FFT operation on an input signal (vector) and find the spectral component with the highest energy. 
+
+## Configuration
+
+### Reconfiguring the project for a different dsPIC33E device:
+
+ The Project can be easily reconfigured for dspic33ep512gm710/dspic33ep512mu810/dspic33ep256gp506 device by following the below steps - 
+1. Open project in MPLAB-X.
+2. In MPLAB X>>Configuration drop-down option>>Listed Device Configuration
+3. Re-build the MPLAB® project using the menu option: Clean and Build Main Project
+
+### Reconfiguring the project for a different FFT Size:
+
+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.
+ file, [fft.h](firmware/src/fft.h).
+- 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 - `#define FFTTWIDCOEFFS_IN_PROGMEM`
 
-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.
+## Operation
 
-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:
+The FFT is performed in the following steps:
+
+1. Initialization: 
+
+   i. Generate Twiddle Factor Coefficients and store them in X-RAM. The twiddle factors can be generated using the following function:
+      ```C
+      #ifndef FFTTWIDCOEFFS_IN_PROGMEM					/* Generate TwiddleFactor Coefficients */
+           TwidFactorInit (LOG2_BLOCK_LENGTH, &twiddleFactors[0], 0);	/* We need to do this only once at start-up */
+      #endif
+      ```
+
+      Alternatively, you may also use the pre-generated twiddle factors stored in Program Flash.
+
+   ii. Initialize the input vector in Y-memory at an address aligned to `4 x FFT_BLOCK_LENGTH` as shown below.
+      
+      ```C
+      fractcomplex sigCmpx[FFT_BLOCK_LENGTH] __attribute__ ((eds, space(ymemory), aligned (FFT_BLOCK_LENGTH * 2 *2)));
+      ```
+      
+   iii. 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)_.
+
+   iv. 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_.
 
-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).
+2. Butterfly computation: 
+   
+   This is achieved by performing a call to the FFTComplexIP() function.
+   ```C
+   #ifndef FFTTWIDCOEFFS_IN_PROGMEM
+       FFTComplexIP (LOG2_BLOCK_LENGTH, &sigCmpx[0], &twiddleFactors[0], COEFFS_IN_DATA);
+   #else
+       FFTComplexIP (LOG2_BLOCK_LENGTH, &sigCmpx[0], (fractcomplex *) __builtin_psvoffset(&twiddleFactors[0]), (int) __builtin_psvpage(&twiddleFactors[0]));
+   #endif
+   ```
 
-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.
+3. Bit-Reversed Re-ordering: The output array is re-ordered to be in bit-reversed order of the addresses. This is achieved by -
+   ```C
+   /* Store output samples in bit-reversed order of their addresses */
+    BitReverseComplex (LOG2_BLOCK_LENGTH, &sigCmpx[0]);
+   ```
 
-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.
+4. 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 DSP Library's routine, SquareMagnitudeCplx(). 
+   ```C
+   /* Compute the square magnitude of the complex FFT output array so we have a Real output vetor */
+       SquareMagnitudeCplx(FFT_BLOCK_LENGTH/2, &sigCmpx[0], output);
+   ```
+
+
+5. Peak-picking: We then find the frequency component with the largest energy by using the VectorMax() routine in the DSP library.
+   ```C
+   /* Find the frequency Bin ( = index into the SigCmpx[] array) that has the largest energy i.e., the largest spectral component */
+       VectorMax(FFT_BLOCK_LENGTH/2, output, &peakFrequencyBin);
+   ```
+
+
+6. 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 as follows - 
+   ```C
+   /* Compute the frequency (in Hz) of the largest spectral component */
+       peakFrequency = (uint32_t) peakFrequencyBin*((float)SAMPLING_RATE/FFT_BLOCK_LENGTH);
+   ```
+
+
+### Input
+
+The input signal used in the example will be 512 points of a Square wave signal of frequency 1KHz sampled at 10 KHz.
+
+### Output
+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. 
+
+Observe output variable `peakFrequency` in debug mode. Value should be almost near to 1Khz
 
-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).
 
 ## Hardware Used
 
@@ -57,4 +123,4 @@ the largest element in the output array with the spectral (bin) resolution ( = s
 
 - MPLAB® X IDE v6.00 or newer (https://www.microchip.com/mplabx)
 - MPLAB® XC16 v2.00 or newer (https://www.microchip.com/xc)
-
+- MPLAB® XC16/XC-DSC DSP Library. Documentation can be found at `compiler_installation_folder/docs/dsp_lib`