This is an old revision of the document!
Now that you have designed your FIR and IIR filters using MATLAB, you will implement these filters using C-code that executes on the the ZYBO board. We will be using the queues that you designed previously to ease the overall implementation of these filters. You will verify the correct operation of your filters using provided test code in the ecen390 project directory.
Ultimately, for all of Milestone 3, you are writing the software - the detector - the thing that will detect when and what player frequency “hits” you when playing the game. For Task 1, you are implementing just the filtering and power-computation parts. The diagram below shows you the entire structure for the detector. You are implementing the part contained in the gray box. This consists of the following parts:
Note: The IIR filters and associated queues are now numbered 0 - 9 in this task. This is because 'C' arrays are zero indexed and starting at 0 makes coding easier. In MATLAB for Milestone 2, the frequencies and IIR filters were numbered 1 - 10.
filter_runTest()
function.static
in filter.c
.const static double fir_coeffs[FIR_COEF_COUNT] = {0.25, 0.5, 0.75, 1.0}
. See the examples in the code below.const static double iir_a_coeffs[FREQUENCY_COUNT][IIR_A_COEFF_COUNT] = {{0.25. 0.5, 0.75, 1.0}, {1.0, 2.0, 3.0, 4.0}, …};
xQueue
is called initXQueue()
. Inside this function you would call queue_init()
on xQueue
and then would use queue_overwritePush()
or queue_push()
with a for-loop to fill the xQueue with zeros. You must write a corresponding function for each of your queues and you will call these functions in filter_init()
.filter_addNewInput(value)
must push a value onto xQueue. filter_firFilter()
reads input values from xQueue using queue_readElementAt()
and pushes its output values onto yQueue. filter_iirFilter(filterNumber)
reads input values from yQueue using queue_readElementAt()
and pushes its output values onto zQueue[filterNumber].
1. Declare and initialize 22 queues: an xQueue
to store incoming inputs from the ADC, a yQueue
that holds the history of outputs from the FIR filter, an array of 10 zQueues that hold the history of outputs from the corresponding IIR filters, and an array of 10 outputQueues that accumulate output values from each of the IIR filters for the purpose of power computations. Declare all of these queues as static queue_t
variables in filter.c
. Give each of these queues a meaningful name using the name argument in queue_init()
function.
Here's an example of how to declare and initialize an array of queues. Note this code will not compile “as is.”
#define QUEUE_INIT_VALUE 0.0 #define Z_QUEUE_SIZE IIR_A_COEFFICIENT_COUNT static queue_t zQueue[FILTER_IIR_FILTER_COUNT]; void initZQueues() { for (uint32_t i=0; i<FILTER_IIR_FILTER_COUNT; i++) { queue_init(&(zQueue[i]), Z_QUEUE_SIZE); for (uint32_t j=0; j<Z_QUEUE_SIZE; j++) queue_overwritePush(&(zQueue[i]), QUEUE_INIT_VALUE); } }
2. In filter_init()
, initialize all of the queue's and fill them with zeros. Below is one example, that uses small helper functions to initialize each queue and fill it with zeros. These helper functions are then called from within filter_init()
.
// This must be called before invoking any filter functions. void filter_init() { // Init queues and fill them with 0s. initXQueue(); // Call queue_init() on xQueue and fill it with zeros. initYQueue(); // Call queue_init() on yQueue and fill it with zeros. initZQueues(); // Call queue_init() on all of the zQueues and fill each z queue with zeros. initOutputQueues(); // Call queue_init() on all of the outputQueues and fill each outputQueue with zeros. ...
Note: For queues that are used to store signal histories, always fill them completely with zeros. This provides a stable starting condition.
Note: an empty queue is not the same as a queue that is filled with 0s.
At run-time, you “run” the filters by doing the following:
filter_addNewInput()
will do (once you implement it). When you finish the completion of your laser-tag system, you will use filter_addNewInput()
to take the output from the digitized voltage from your photo-diode-based detector and provide it to the FIR filter.filter_firFilter()
. This will use the appropriate FIR coefficients and the xQueue that contains the necessary signal history to compute the output of the FIR filter. Add this output computed by filter_firFilter()
to the yQueue (filter_firFilter()
also returns this computed value). The yQueue then contains the output from the FIR filter; this is the input for each of the 10 IIR-filters.
The code below provides a little more context. Note that this code will not compile. It is provided as an example of how you will use the filter_addNewInput()
, filter_fir()
and filter_iir()
functions. You would run the code below each time there is at least one new available value. For this task, you are only verifying that your filters work correctly so you don't need to do decimation in this task. If you want to use this code for verification, simply set the decimation factor to 1.
// THIS IS PROVIDED FOR CONTEXT ONLY. // IF YOU USE THIS CODE DIRECTLY IN THIS TASK YOU ARE DOING THINGS WRONG. #define FILTER_IIR_FILTER_COUNT 10 #define FILTER_FIR_DECIMATION_FACTOR 10 uint32_t sampleCount = 0; filter_addNewInput(adcValue); // add a new input to the FIR history queue. sampleCount++; // Keep track of how many samples you have acquired. if (sampleCount == FILTER_FIR_DECIMATION_FACTOR) { // Only invoke the filters after every DECIMATION_FACTOR times. sampleCount = 0; // Reset the sample count when you run the filters. filter_firFilter() // Runs the FIR filter on the accumulated input and places the output in the y-queue. for (uint32_t filterNumber=0; filterNumber<FILTER_IIR_FILTER_COUNT; filterNumber++) { filter_iirFilter(filterNumber); // Run each of the IIR filters. filter_computePower(filterNumber, false, false);// Compute the power for each of the IIR filters. } }
3. Implement all of the power-related functions (they all have the word “power” in their names). You will need to make sure to write filter_computePower()
so that it does not take too much execution time. Carefully think about how you might be able to reuse computations performed in a previous invocation of filter_computePower()
to reduce overall computation time. To initially debug your power code, you can fill the power queues with constant values, say 2.0 for example, and then compare the output from the function with your own calculation. The provided test code contained in the file filterTest.c (see below) provides a comprehensive test of the power functions.
Here's a picture of your overall filter structure to help you understand the purpose of the queues used to compute power. The “Detector” consists of all your filtering code, the power-computing code, and the “Compare and Threshold” code. Note that the code that performs “Compare and Threshold” will be implemented in a later milestone.
For the IIR filters, note that the first a-coefficient (a0) is always 1.0 and is not used in the computation. As such, if your a-coefficient array is of size 11, your z-queue must be size 10 (1 less than the size of the array) because a0 is always ignored. Watch out for this!
To compute power, you must keep a running history of 200 ms of output data from each of the 10 IIR-based band-pass filters. To achieve this, do the following:
static
array of 10 power-output queues in filter.c
(these were the output-queues that were discussed above). These will be indexed by filterNumber
in the various functions that need to access them.currentPowerValue[]
.filter_computePower(filterNumber)
, compute the power for a frequency by computing a sum of the squares of all values contained in the output queue for that frequency. Store this value in the currentPowerValue[]
array at the index that corresponds to that frequency.filter_getCurrentPowerValue(uint16_t filterNumber)
that simply returns the value stored in the array currentPowerValue[]
at filterNumber
.filter_getNormalizedPowerValues(double normalizedArray[], uint16_t* indexOfMaxValue)
. This function does two things:currentPowerValue[]
so that they are distributed between 0.0 and 1.0 and stores these normalized values in the array argument normalizedArray[]
. To compute normalized values, simply find the largest value in the currentPowerValue[]
array and divide all values stored in the array by the largest value.currentPowerValue[]
that contains the highest power value in the argument indexOfMaxValue
.You will need to make sure to write filter_computePower() so that it does not take too much execution time. Carefully think about how you might be able to reuse computations performed in a previous invocation of filter_computePower() to reduce overall computation time.
Verify the correct operation of filter_computePower(), filter_getCurrentPowerValue(), and filter_getNormalizedPowerValues() using your own test code. An easy way to do this is to fill the power queues with constant values, say 2.0 for example, and then compare the output from the function with your own calculation.
The power functions are invoked along with the filtering functions. To provide you with some context, here is a code snippet that demonstrates how the power functions will be used once you finish coding the detector in the next task. Assume that the code below is called continuously and forever.
// THIS IS PROVIDED FOR CONTEXT ONLY. // IF YOU USE THIS CODE DIRECTLY IN THIS TASK YOU ARE DOING THINGS WRONG. filter_addNewInput(scaledAdcValue); // Copy the the scaled ADC value into the main filter input queue. sampleCount++; // Keep track of how many samples you have acquired. if (sampleCount == FILTER_FIR_DECIMATION_FACTOR) { // Only invoke the filters after every DECIMATION_FACTOR times. sampleCount = 0; // Reset the sample count when you run the filters. filter_firFilter(); // Runs the FIR filter on the accumulated input and places the output in the y-queue. // Run all 10 of the IIR filters and compute power in each of the output queues. for (uint32_t filterNumber=0; filterNumber<FILTER_FREQUENCY_COUNT; filterNumber++) { filter_iirFilter(filterNumber); // Run each of the IIR filters. // Compute the power for each of the filters, at lowest computational cost. // false means do not compute from scratch. filter_computePower(filterNumber, false); ... } ...
Note: Remember that these functions are declared in filter.h
To pass off this task, you must run your filter and power code with the provided filterTest.c source code. The test code tests the arithmetic for all of your filters. It also plots the frequency response for the FIR and IIR filters on the TFT display. The provided test code comes in four pieces: histogram.h, histogram.c and filterTest.h and filterTest.c. In filter.h, you will see a section of code labeled “Verification-Assisting Functions”. These accessor functions provide a way for the test-code to access the various named variables in your filter.c code. These accessors are necessary because your naming schemes will likely differ from my test-code.
The filterTest code is a little over 1120 lines and performs several tests:
Note that “aligned” means that coefficient values are multiplied with corresponding queue values using correct indices.
To run this test code, uncomment filter_runTest()
in the body of your main()
code and uncomment #define RUNNING_MODE_TESTS
. Along with various informational and perhaps error messages, the frequency response will be plotted out on the TFT display on the ZYBO carrier board. You can compare your results to those on this page. Your results should look similar.
The informational messages that should appear in your console will look like this if everything passes. Numerical values won't be exact because your FIR filter will be different, but values should be roughly similar:
filter_runFirAlignmentTest passed. filter_runFirArithmeticTest passed. filter_runIirAAlignmentTest passed. filter_runIirBAlignmentTest passed. ===== Starting filter_runPowerTest() ===== Testing to see that the power is computed correctly when forced. Output queues are the correct size. Power values were properly computed when forced. Testing to see that the power is computed correctly incrementally over 3000 trials. Power values were properly computed incrementally. +++++ Exiting filter_runPowerTest +++++ running filter_runFirPowerTest() - plotting power values (frequency response) for frequencies 1.47 kHz to 50.00 kHz for FIR filter to TFT display. freqCount:0, testPeriodPowerValue:1.760509e+03 freqCount:1, testPeriodPowerValue:1.707258e+03 freqCount:2, testPeriodPowerValue:1.655931e+03 freqCount:3, testPeriodPowerValue:1.628428e+03 freqCount:4, testPeriodPowerValue:1.609116e+03 freqCount:5, testPeriodPowerValue:1.588978e+03 freqCount:6, testPeriodPowerValue:1.538183e+03 freqCount:7, testPeriodPowerValue:1.491542e+03 freqCount:8, testPeriodPowerValue:1.417058e+03 freqCount:9, testPeriodPowerValue:1.298423e+03 freqCount:10, testPeriodPowerValue:1.119037e+03 freqCount:11, testPeriodPowerValue:3.572475e+02 freqCount:12, testPeriodPowerValue:5.366949e+02 freqCount:13, testPeriodPowerValue:2.239070e+02 freqCount:14, testPeriodPowerValue:4.032896e+01 freqCount:15, testPeriodPowerValue:1.090589e+00 freqCount:16, testPeriodPowerValue:3.327529e-03 freqCount:17, testPeriodPowerValue:1.363178e-03 freqCount:18, testPeriodPowerValue:1.627174e-03 freqCount:19, testPeriodPowerValue:3.659948e-03 freqCount:20, testPeriodPowerValue:3.264494e-03 Plotting response to square-wave input. running filter_runFirPowerTest(0) - plotting power for all player frequencies for IIR filter(0) to TFT display. running filter_runFirPowerTest(1) - plotting power for all player frequencies for IIR filter(1) to TFT display. running filter_runFirPowerTest(2) - plotting power for all player frequencies for IIR filter(2) to TFT display. running filter_runFirPowerTest(3) - plotting power for all player frequencies for IIR filter(3) to TFT display. running filter_runFirPowerTest(4) - plotting power for all player frequencies for IIR filter(4) to TFT display. running filter_runFirPowerTest(5) - plotting power for all player frequencies for IIR filter(5) to TFT display. running filter_runFirPowerTest(6) - plotting power for all player frequencies for IIR filter(6) to TFT display. running filter_runFirPowerTest(7) - plotting power for all player frequencies for IIR filter(7) to TFT display. running filter_runFirPowerTest(8) - plotting power for all player frequencies for IIR filter(8) to TFT display. running filter_runFirPowerTest(9) - plotting power for all player frequencies for IIR filter(9) to TFT display.
Please pay attention to the following:
You can compare your filter response against those shown on this page.
In this task you will implement the FIR and IIR filters that you designed using MATLAB using 'C' code. Let's start with the FIR filter. Remember that the FIR filter is implemented as a weighted sum of some past number of inputs. Here's an example from Wikipedia:
It can be confusing to transition from the finite array-based approach used in MATLAB to the “infinite” approach that is required in the implementation of a signal-processing system. The inputs and outputs of a real-time signal-processing system are essentially infinite. As such, the array-based notation in the equation above fails us because the output is an indexed array y[n]
. For example, at time=0, you start out computing y[0]
. After playing the game for several minutes, n
would be in the billions. And, it only goes up from there. Simply put, you want to eliminate the [n]
part so that the output is simply y
.
Note that when we read the English-based description from Wikipedia (see above), indexes were not discussed. Remember that the FIR-filter is implemented as a “weighted-sum of some past number of inputs”. All those indexes, the i
, the k
, etc., are just a way to keep the coefficients properly aligned with the data. As long as we can keep the incoming inputs properly aligned with the coefficients, we are good to go.
The idea is pretty simple and is based upon these ideas:
As you have probably guessed at this point, the queues that you implemented as a part of Milestone 1 are the perfect data structure for this purpose.
You can implement a FIR filter using the queues that you have already coded. Consider an example where the FIR filter uses 4 past values to compute its output. In the example code below, I have “pushed” four values onto the queue. Assume that these are 4 values that are based on values from the ZYBO's ADC. Note that for pedagogical purposes, the code below does not necessarily adhere to the coding standard.
#include "queue.h" #include <stdio.h> #define FIR_COEF_COUNT 4 int main() { // Initialization stuff. queue_t xQ; // x is the queue with the input history for the queue. queue_init(&xQ, FIR_COEF_COUNT); // Size of history queue must equal coefficient count. for (uint32_t i=0; i<FIR_COEF_COUNT; i++) // Start out with a queue full of zeros. queue_overwritePush(&xQ, 0.0); const double b[FIR_COEF_COUNT] = {0.25, 0.5, 0.75, 1.0}; // These coefficients are used for this example. // Add some example inputs to the queue. queue_overwritePush(&xQ, -0.1); // Add a new input to the queue (oldest in input history). queue_overwritePush(&xQ, -0.4); // Add a new input to the queue. queue_overwritePush(&xQ, 0.24); // Add a new input to the queue. queue_overwritePush(&xQ, 0.54); // Add a new input to the queue (newest in input history). // Compute output of FIR-filter (y) // using a single lone statement (broken into 4 lines to keep it readable). // This is just for example. You will use a for-loop as shown below. double y; y = queue_readElementAt(&xQ, 0) * b[3] + queue_readElementAt(&xQ, 1) * b[2] + queue_readElementAt(&xQ, 2) * b[1] + queue_readElementAt(&xQ, 3) * b[0]; printf("%lf\n\r", y); // Add new input. queue_overwritePush(&xQ, 0.33); // Compute the next y, exactly the same computation as above but with a concise for-loop instead. // += accumulates the result during the for-loop. Must start out with y = 0. y = 0.0; // This for-loop performs the identical computation to that shown above. for-loop is correct way to do it. for (uint32_t i=0; i<FIR_COEF_COUNT; i++) { y += queue_readElementAt(&xQ, FIR_COEF_COUNT-1-i) * b[i]; // iteratively adds the (b * input) products. } printf("%lf\n\r", y); }
Pictorially, implementing the FIR filter would appear as shown below. As shown, you can see the 4 values that were pushed onto the queue as well as the total computations.
The next computation of y is shown below. You can see that by adding a new value to the queue, all of the other values shifted over, relative to the b
coefficients. Thus you can use the same code to compute y
over and over again.
You can see that the purpose of the queue is to store past values in the order that they were received and make all of the queue-contained values accessible during the computation.
Decimation is really easy. In our laser-tag system we will be decimating by 10. All we do is invoke our FIR-filter each time we receive 10 new samples. As you add incoming samples to the FIR-filter input-queue, only invoke the FIR-filter each time you have received 10 new inputs. You will then invoke the IIR filters right after you invoke the FIR-filter. Decimation-wise, there is nothing required for this task. You will implement this later.
The equation for an IIR filter is shown below.
However, we can simplify this a bit because the first a coefficient is 1.0 and can be ignored.
We finally end up with:
The implementation of the IIR filter is similar to the FIR filter. However, the IIR filter relies on two signal histories: y and z, as shown in the equation above. As you can see from the equation, you would need two queues of different sizes (11 and 10) to keep the necessary signal histories. The only other difference is that the computed value (z
) is also pushed onto the queue that keeps a history of z values. This is essentially what puts the “IIR” in the filter, e.g, feedback.
Note that the following files are provided in your ecen390 project directory. The test code is used to check the correctness of your code.
You are expected to create and implement the following file. See the provided header file (.h) for a description of each function.
Use this code to format your coefficients into arrays that follow correct 'C' syntax. This code is not part of the cloned student repo so you will need to paste it into a file in order to use it with MATLAB.
Instructions:
Note: this code does not include the leading 1.0 coefficient for the a_iir coefficients for the IIR filter because it is not used.
%format of filter coefficients % % FIR vector name: b % % IIR a coefficients % name: a_iir % size: 10, 11 matrix % IIR b coefficients % name: b_iir % size: 10, 11 matrix fileID = fopen('coef.txt', 'wt'); %open file %write FIR filter coefficients fprintf(fileID,'const static double firCoefficients[FIR_FILTER_TAP_COUNT] = {\n') formatSpec = '%1.16e, \n'; fprintf(fileID,formatSpec,b(1:end-1)) formatSpec = '%1.16e};\n\n'; fprintf(fileID,formatSpec,b(end)) %write IIR 'a' filter coefficients %This file does not write the first 'a' coefficient fprintf(fileID,'const static double iirACoefficientConstants[FILTER_FREQUENCY_COUNT][IIR_A_COEFFICIENT_COUNT] = {\n') for lp=1:9 fprintf(fileID,'{') formatSpec = '%1.16e, '; fprintf(fileID,formatSpec,a_iir(lp, 2:end-1)) formatSpec = '%1.16e},\n'; fprintf(fileID,formatSpec,a_iir(lp, end)) end fprintf(fileID,'{') formatSpec = '%1.16e, '; fprintf(fileID,formatSpec,a_iir(10, 2:end-1)) formatSpec = '%1.16e}\n'; fprintf(fileID,formatSpec,a_iir(10, end)) fprintf(fileID,'};\n') fprintf(fileID,'\n') %write IIR b filter coefficients fprintf(fileID,'const static double iirBCoefficientConstants[FILTER_FREQUENCY_COUNT][IIR_B_COEFFICIENT_COUNT] = {\n') for lp=1:9 fprintf(fileID,'{') formatSpec = '%1.16e, '; fprintf(fileID,formatSpec,b_iir(lp, 1:end-1)) formatSpec = '%1.16e},\n'; fprintf(fileID,formatSpec,b_iir(lp, end)) end fprintf(fileID,'{') formatSpec = '%1.16e, '; fprintf(fileID,formatSpec,b_iir(10, 1:end-1)) formatSpec = '%1.16e}\n'; fprintf(fileID,formatSpec,b_iir(10, end)) fprintf(fileID,'};') fclose(fileID);