{"id":5035,"date":"2020-07-06T19:43:18","date_gmt":"2020-07-06T17:43:18","guid":{"rendered":"https:\/\/deepbluembedded.com\/?p=5035"},"modified":"2023-08-17T23:51:26","modified_gmt":"2023-08-17T20:51:26","slug":"map-function-embedded-c","status":"publish","type":"post","link":"https:\/\/deepbluembedded.com\/map-function-embedded-c\/","title":{"rendered":"Map Function, Constrain, FIR Filters, And Other Math Functions"},"content":{"rendered":"\n\n\n\n\n
\"Previous<\/a><\/td>\nPrevious Tutorial<\/strong><\/a><\/td>\nTutorial 33<\/span><\/strong><\/span><\/td>\nNext Tutorial<\/strong><\/a><\/td>\n\"Next<\/a><\/td>\n<\/tr>\n
<\/td>\nMap Function, Constrain, FIR Filters, And Other Math Functions<\/strong><\/span><\/td>\n<\/td>\n<\/tr>\n
<\/td>\nSTM32 Course Home Page <\/strong><\/span>????<\/a><\/td>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

 <\/p>\n

\"Map<\/p>\n

 <\/p>\n

In this article, we’ll discuss some math functions like map function, constrain, digital filtering, and how to implement them in Embedded-C<\/strong>. We’ll be using these functions in the upcoming tutorials and you’ll find them in the math directory in the STM32 course repo. So I’ve decided to briefly mention each of them at least the ones we’ll be using in the near future. And let’s dive right in!<\/span><\/p>\n

\n

\u00a0 \u00a0Map Function & Implementation In C<\/span><\/strong>\u00a0 \u00a0<\/span><\/strong><\/span><\/h3>\n

 <\/p>\n

Let’s start with the map function which we quite often use in different embedded systems applications. The map function is commonly used as a built-in Arduino<\/a> C function and it’s very handy in a wide range of applications. Mathematically, the mapping function is to find the corresponding value from a certain domain to another domain. Here is an example of this.<\/span><\/p>\n

We can use a potentiometer with an ADC to read the analog voltage and if the ADC is 10-Bit in resolution then its digital output is going to be in this range (domain) [0 up to 1023]. If we’re willing to use this value as a control signal to position a servo motor whose angle has a range (domain) of [0\u00b0 up to 180\u00b0], then we need to do a mapping from the first domain to the second one. As you can see in the diagram below.<\/span><\/p>\n

\"Map<\/p>\n

The map function does this conversion ting from the ADC result to the servo motor angle. The function will simply figure out the conversion ratio from domain1 to domain2, does the arithmetic, and return the result.<\/span><\/p>\n

I personally used to do this manually back in the days in process control exams. The procedure was as follows: first of all, I’ll draw both domains and their ranges on top of each other like in the diagram below. The first one (from 0 up to 1023) and the second one (from 0 up to 180). Then, I take an arbitrarily chosen point (x) which represents the ADC reading at any time instance. And define the goal to be finding out the corresponding point (y) in the other domain that maps to the x point.<\/span><\/p>\n

With keeping in mind the fact that the length of the (orange<\/strong><\/span>) bars are equal and the ratio between each one of them to its full domain range is also equal. Therefore, x\/1023 = y\/180. Which results in the following equation which we also call the (map function) or equation y=(x.180)\/1023<\/span><\/p>\n

\"Map<\/p>\n

Here is an implementation for the map function in C language which we’ll add to our MATH.c source code in the MATH directory. You’ll find it also in the course’s repo on GitHub<\/a>.<\/span><\/p>\n

uint32_t MAP(uint32_t au32_IN, uint32_t au32_INmin, uint32_t au32_INmax, uint32_t au32_OUTmin, uint32_t au32_OUTmax)\r\n{\r\n    return ((((au32_IN - au32_INmin)*(au32_OUTmax - au32_OUTmin))\/(au32_INmax - au32_INmin)) + au32_OUTmin);\r\n}<\/pre>\n
We’ll implement this example at the end of this article as well. To give you an example application code for how to include and use the MATH functions that we’ll be implementing today.<\/span><\/p>\n
 <\/p>\n
\n
\u00a0 Constrain Function<\/span><\/strong>\u00a0\u00a0<\/span><\/strong><\/span><\/h3>\n
 <\/p>\n
The constrain function is a very simple logical operation. We typically perform this function on sensors’ readings when want to hard-limit or cap the readings of a specific sensor and also define a minimum output value to be accepted by the system. <\/span><\/p>\n
Using this function guarantees that any digital controller or calculations performing mathematical operations on a specific sensor’s reading would not go wrong. As it’s guaranteed to fall in the specified range by using this function.<\/span><\/p>\n
Here is a very simple implementation for this function in C language.<\/span><\/p>\n
uint32_t Constrain(uint32_t au32_IN, uint32_t au32_MIN, uint32_t au32_MAX)\r\n{\r\n    if(au32_IN < au32_MIN)\r\n    {\r\n\treturn au32_MIN;\r\n    }\r\n    else if (au32_IN > au32_MAX)\r\n    {\r\n\treturn au32_MAX;\r\n    }\r\n    else\r\n    {\r\n\treturn au32_IN;\r\n    }\r\n}<\/pre>\n
 <\/p>\n
\n
\u00a0 \u00a0Min & Max Functions\u00a0 \u00a0<\/span><\/strong><\/span><\/h3>\n
 <\/p>\n
The min & max functions are commonly used in different applications. And the task required by each of them is very basic and simple. It’s a searching routine that goes through an array of values to find the maximum or minimum and return it back.<\/span><\/p>\n
Sometimes you may have a system that records some variables or sensors’ readings and would like to find the maximum or minimum peaks or drops. Or maybe use this information to know if your data needs some sort of digital filtering or not. In case of high spikes in the readings recorded.<\/span><\/p>\n
Here is an implementation in C for both functions.<\/span><\/p>\n
MATH_DataType MIN(MATH_DataType* IN_Arr, uint32_t au32_LEN)\r\n{\r\n    uint32_t i = 0;\r\n    MATH_DataType MIN = 0;\r\n\r\n    for(i=0; i<au32_LEN; i++)\r\n    {\r\n\tif(IN_Arr[i] < MIN)\r\n\t{\r\n\t    MIN = IN_Arr[i];\r\n\t}\r\n    }\r\n    return MIN;\r\n}\r\n\r\nMATH_DataType MAX(MATH_DataType* IN_Arr, uint32_t au32_LEN)\r\n{\r\n    uint32_t i = 0;\r\n    MATH_DataType MAX = 0;\r\n\r\n    for(i=0; i<au32_LEN; i++)\r\n    {\r\n\tif(IN_Arr[i] > MAX)\r\n\t{\r\n\t    MAX = IN_Arr[i];\r\n\t}\r\n    }\r\n    return MAX;\r\n}<\/pre>\n
Note that the data type being used here is defined so that the user (the programmer) can adjust it if the variable being monitored is a floating-point number of signed values that can go negative. In case of having negative numbers, you have to be careful in the MIN function as defining the min value at the beginning with 0 may not converge to the right result.<\/span><\/p>\n
typedef uint32_t MATH_DataType;<\/pre>\n
 <\/p>\n
\n
\u00a0 \u00a0Moving Average FIR Digital Filter\u00a0 \u00a0<\/span><\/strong><\/span><\/h3>\n
 <\/p>\n
I’ll discuss this topic in detail in the next tutorial and show you how to create a simple yet effective digital filter in order to eliminate the push-button bouncing issue. A moving average filter is a very simple special case of the general Finite Impulse Response (FIR) digital filters.<\/span><\/p>\n
Simple, you’ll save the most recent N values of a sensor’s reading. And constantly add a new reading, remove the oldest one, and calculate the average by summing all readings in the array and divide by N. Now you have got the average value and it’ll be way smoother than the original sensor’s reading.<\/span><\/p>\n
For example, the IMU (gyro + accelerometer) module MPU6050<\/a> which we’ve discussed in detail in a previous tutorial. This sensor’s output is very noisy in nature every when you fix the sensor in place with no motion at all. Here is an example for the output data (the raw data from the sensor) and the same data points but after applying this simple moving average filter (with an order of 20).<\/span><\/p>\n
Raw Data From The Accelerometer Sensor (in Blue)<\/strong><\/span><\/p>\n
Filtered Sensor Data with AVG Filter order 20 (in Red)<\/strong><\/span><\/p>\n
\"Map<\/p>\n
 <\/p>\n
\n
\u00a0Map Function Example Application – LAB\u00a0<\/span><\/strong><\/span><\/h3>\n
 <\/p>\n
In this LAB, we’ll be using the MAP function with the ADC readings from a potentiometer (12-Bit ADC). To control a servo motor’s angle (0 to 180). This example was exactly performed in a previous tutorial (Servo Motor Control)<\/a> but without having the map function implemented in code. So here is an example application for it.<\/span><\/p>\n
The Application Code For This LAB (main.c)<\/strong><\/span><\/p>\n
#include \"main.h\"\r\n#include \"..\/MATH\/MATH.h\"\r\n#include \"..\/ECUAL\/SERVO\/SERVO.h\"\r\n\r\n#define SERVO_Motor1  0\r\n\r\nADC_HandleTypeDef hadc1;\r\n\r\nvoid SystemClock_Config(void);\r\nstatic void MX_GPIO_Init(void);\r\nstatic void MX_ADC1_Init(void);\r\n\r\nint main(void)\r\n{\r\n    uint16_t AD_RES = 0;\r\n    uint16_t Angle = 0;\r\n\r\n    HAL_Init();\r\n    SystemClock_Config();\r\n    MX_GPIO_Init();\r\n    MX_ADC1_Init();\r\n    SERVO_Init(SERVO_Motor1);\r\n\r\n    while (1)\r\n    {\r\n    \t\/\/ Start ADC Conversion\r\n    \tHAL_ADC_Start(&hadc1);\r\n    \t\/\/ Poll ADC1 Perihperal & TimeOut = 1mSec\r\n    \tHAL_ADC_PollForConversion(&hadc1, 1);\r\n    \t\/\/ Read The ADC Conversion Result & Map Servo Motor Angle\r\n    \tAD_RES = HAL_ADC_GetValue(&hadc1);\r\n    \t\/\/ Map The ADC Result To Servo Pulse Width\r\n    \tAngle = MAP(AD_RES, 0, 4096, 0, 180);\r\n    \t\/\/ Move The Servo Motor To The Angle\r\n    \tSERVO_MoveTo(SERVO_Motor1, Angle);\r\n    \tHAL_Delay(1);\r\n    }\r\n}<\/pre>\n
We give the function the input (AD_RES) from the ADC reading that is 12-Bit in resolution so its range is from 0 up to 4096. And the target range from 0 up to 180. And that’s it! the map function will calculate and return the result as Angle and we’ll send it to the Servo_MoveTo function.<\/span><\/p>\n
Here is the result for this LAB<\/strong><\/span><\/p>\n
The same as the previous servo motor LAB that I highly recommend checking it out if you didn’t yet (servo motor control tutorial – LAB27).<\/span><\/p>\n