Mirrors should think longer before they reflect…

Jean Cocteau

In the previous lesson we learnt what functions are and what they are used for. We also mentioned one type of function: Functions with return, which we will be taking a closer look at in this post. Are you ready to master the art of functions even more? Do you fancy being a wizard in flow-based programming? Or maybe you just want to make the bitbloq community programs even better? Let´s do it!

For today´s examples, you will need:

1 x Zum bloq mini servo
1 x Zum bloq potentiometer
1 x Zum bloq light sensor
1 x Zum bloq buzzer
1 x Zum bloq LCD
A ZUM BT 328 controller board or one compatible with Arduino UNO
A USB cable

The “function with return” block and the “call function with return” blocks

The functions with return are very similar to functions without return. The key difference is how they are used.

Functions with return create a “mini-program” for obtaining, preparing or modifying a variable. The function with return will return this value to us at the moment that we request it, without having to tell the program how to obtain this data again and again. An example could be a function that maps the value of the potentiometer and then returns the mapped value of the same component. It could also be a function that reads the ultrasound sensor according to the distance and states roughly how far you are from the object in front of you (a little program such as this could have saved the Titanic, for example).

The variables that we play around with in our functions with return can be of any type: numerical, text or even vectors (variables with three compartments, as explained in the joystick lesson).

Can you see the space in the “function with return” block? That´s where the variable needs to go, which the function will return when called. Now place a variable block to indicate what it has to return, although it can be useful to put a number or text that will always be the same (using a number or text block), as we will see later.

Has anyone noticed that the “call function with return” block has the same form as the ” use a variable” block?

They have exactly the same form because the “call function with return” block can fit anywhere where a variable would fit. In fact, if you understand variables, the functions with return could be like a variable that, before seeing what´s inside the box, just before opening it, things happen inside it and then it lets you see the contents.

Now let´s see if we´ve understood everything.

Example using the function with return blocks

Program for moving the mini servo with the potentiometer, using a function in this case

Remember how the map block works? Click on the link and have a quick look at the example. It will help you to understand how it works.

As you can see, we have two columns of blocks again: the main program on the left and the declaration of the function “Receive_value_from_potentiometer” on the right. The function has the task of indicating its name and when we call it (using the “call function block” of the main program), it will create a variable in the one that stores the current value of the potentiometer. Then it will create another variable to save the value of the potentiometer variable, mapped between 0 and 180 (the degrees that the mini servo must turn) and finally, we have told it to return the value of the variable that the map block has saved. So when we use the “Receive_value_from_potentiometer” block in the main program, it will quickly execute the function from top to bottom and we can enter the mapped value in the “Degrees(0-180)” servo space.

The “If…return…”

What about if the same function returned something different, for example, depending on the light conditions in the room, or whether or not the button was pressed? As with the “If..do” control block, it can add intelligence to our functions, so that they make a decision according to another factor. This is the “If…return…” block

This block can only go within a function with return (don´t worry – bitbloq will remember this even if you don´t). A logical expression (from the logic blocks) needs to go in the first space and if true, the function will terminate immediately and will return the value you have put in the second block as a variable, a number or a fixed text.

I´m including numbers and fixed text because this block has loads of applications. Now carry on with the next example to see how useful it is.

Example using the “If… return…” block

Before analysing the example, let me explain the fun bit of the program. Supposing we were using a light sensor other than the one from “Mi primer Kit de Robótica” (as we already know that this one returns values between 0 and 500 depending on the light that reaches the sensor). What if we didn´t know this value? Now, let´s imagine you made a mistake and the value of the sensor was over 500, the servo being used short circuited and you had to say farewell to your precious servo. Don´t you think it would be perfect if we could create a function to check this value before using the servo? Let´s expand on an example we´ve already used in the mini servo lesson.

Program with a light sensor and checking for errors

Let´s start to look closely at the small function on the bottom right. It´s very simple, right? If the light sensor gives a value greater than or o equal to 500, the function would return the word “ERROR” and if not, it would not execute the “If…return” block and it would then return what corresponds by default: “CORRECT”. Then in the main program, we can see how it only consists of one “If…do…else if…do” and the findings of the logic blocks are called by the Check_light_value function. So when the program reaches this block, it will execute the function and return “CORRECT” or “ERROR”, thus entering into the loop that interests us: If correct, it will move the servo, if not it will warn us with the buzzer. As I imagine you will have an awesome light sensor from our robotics kit, you can use the potentiometer to have a go at this example (and it will return values between 0 and 1023)

The “Return…” block

This block has the same function as the previous one. However, it doesn´t include logic expression, which would make it a bit more versatile. So we can place the block within an “If…do” conditional, but making it carry out more actions before returning the final value to us. Let´s have a look at an example where we create a function to see if any objects are near, at an average distance or far from the ultrasound sensor.

Program for reverse warning system in cars

In this example, we have created a function with return to first read the distance of the ultrasound sensor and store it in a variable. After this, it enters a block “If…do” block which, according to the distance in the variable, will light up an LED if very close, or will switch it off if far away. What´s more, when it is near, it will return the word “near”, or “medium” if at an average distance. If it is far, it will not enter the conditional and it will execute the end of the function, returning the word “far”.

In the main program, we only have one buzzer block, which will sound repeatedly but with a pause in between. The length of the pause will depend on the word returned by the previous function.

Improving the functions: Functions with input parameters

I´m sure by now that you will have noticed the little star on the “function with return” and “function without return” blocks. As with the control blocks, it´s not just there to look pretty. The little star helps us improve the function blocks and make them more powerful. And to that we can add…Input parameters!

– What are you on about? What´s all this about input parameters? It sounds like black magic! – Don´t worry. It sounds hard, but we will see that it´s not that bad.

An input parameter is a variable in our main program that we allow the function to use, which allows us to create an intelligent and reusable function. For example, we can make a function carry out various mathematical calculations using two values given as input parameters.
We could also make a function that makes an LED blink 3 times if we give it an input parameter of 3.
When we create an input parameter in the “function with return” or the “function without return” block, a space for placing a variable or number will then appear in the “call function…” block (of the corresponding type). This is the one that we add to the function so that it can be used. In turn, a variable associated with the input parameter is created and it will have the same value as what you place in the space I was just talking about.
It´s important to know that these variables have been created with the input parameters and that they can only be used within the function.

When we create an input parameter, we also need to give it a name relating to the what the parameter will do in the function, and we have to state whether the input parameter will be a number (int) or text (string). Let´s have a look at an example to make it easier to understand.

Example using functions with input parameters

Program for making calculations with two input parameters and displaying the result on the LCD

In this example, we can see how a function with return and input parameters has been created. The input parameters are “input_1″ and “input_2″ and two variables have been placed in the spaces: “data_12 and “data_2″. Input_1 is now worth the same as data_1 and input_2 is the same as data_2, but we can now use input_1 and input_2 within the function in order to make calculations.

The function returns the final value of the calculation to the main program, where it is displayed on the LCD (click here to see how the last one works). Now we know the theory, all we need to do is keep practising until we have mastered them in everything. Try to use them whenever you can and you will see how they will start to be really useful.