What is a Function?

Functions act similar to a variable in that we are using one thing to represent another. However, where a variable typically is used in place of something short, such as a number, a function can take the place of several lines of code.

This can be incredibly useful if there is a section of code we know will be repeated or to break apart our code into chunks for easy editing.

Creating a new Function in Blocks

If we want to create a new function in our Blocks program, we start by pulling a block from the Functions menu:

Next we will replace "do something" with an appropriate name. Maybe in this case we are adding a new function for climbing:

Once our function is named it will appear in the "Functions" menu to be added to the main loop or wherever we need it within our code!

All that's left is to add whatever code we'd like to be within this function:

If the block is deleted this will remove the function from the "Functions" menu.

When to use Functions - Example

Let's say we are working on an autonomous code where we want our robot to drive roughly in a square. Remember that autonomous means this code will move the robot on its own when play is pressed:

Next, let's say we need the robot to do something between one of the turns, such as move its arm or open a servo's claw. There's a couple of ways we could approach this without functions:

Already our code is getting a little long so let's move our side motion and turn into a function:

Now our loop may look like this:

When we test our code we may notice our robot isn't exactly driving in a square shape. Thankfully with our function in place we only need to change the needed value in one place:

This change to the function will be reflected anywhere DRIVE_AND_TURN used.

Give it a try by changing the right motor's power or the timer to refine your square!

Looking to take the next steps with your robot or to learn more about programming? In "Part 4: Going Beyond!" we have additional tutorials and short lessons to explore.

This section may continue to grow in the future so be sure to check back for new updates!

Configuration

Before getting started with programming we needed to create a configuration file. Below is an overview of how the robot is configured for the TeleOp code to function as expected:

Example Program:

Gamepad Layout:

Programming Teleop - Blocks

Initialization:

For this program, we'll set the motors to RUN_WITHOUT_ENCODER along with their direction

Moving Forward and Backwards:

For a mecanum drivetrain all 4 motors will be given a command to follow when the left joystick is moved along the Y-axis of the joystick. For moving forward and back all wheels must turn the same direction.

Strafing:

For this example, strafing is controlled by the left stick's X-axis allowing the robot to slide left and right. In order to achieve this movement, the motors move in diagonal pairs, so frontLeft and backRight will move the opposit direction of backLeft and frontRight, similar to the X shape the wheels make.

Turning:

Lastly, we have turning set by itself on the right joystick's X-axis. To turn our left and right pairs of wheels will spin in opposite directions.

How a Mecanum Drivetrain is programmed largely depends on the driver's preference for how the controller is configured.

In our provided example, the left joystick controls forward/back and strafe then the right joystick controls turning. This code is based on the sample provided by FIRST for Blocks (BasicOmniOpMode) available in the Robot Controller Console.

Mecanum Configuration

Mecanum Example Code

Mecanum Code Breakdown

This example makes use of to help organize the code!

At the very beginning of our program, our MOTOR_SETTINGS function is called. Within it the drivetrain motors are set to RUN_WITHOUT_ENCODER and are set to run the appropriate direction.

Establishing Variables

Next, we need to create some new variables in order to use mecanum.

Let's break those down first:

Calculating Motor Movement with the Gamepad

At the beginning of the MECANUM_DRIVE function, our variables for each movement direction are being set to the value generated by the movement of the matching joystick axis.

Since we now have four motors in play, our equation for setting the needed power to each motor gets a little more complicated.

Our robot first needs to determine the combined movement of the gamepads's left joystick:

Then calculate with the right stick's value:

All our calculations together allows for movement when the left joystick is moved at an angle, such as for strafing along a diagonal!

Quick Check! - Understanding Motor Power

Let's take a closer look at how our motor power is being determined. For example, our leftFrontPower variable will equal:

So what if we move our left joystick all the way to the left side along the X-axis. To our robot, our equation will read something like this:

Take a moment to think: What would be the power of our other motors?

What about a more complicated example? What if we had the left joystick at an angle, all the way to the left and halfway towards the top? Or had our left stick forward and right stick all the way right?

Setting Motor Power

For our last step, our robot sets the power of each pair of motors based on all our calculations!

Normalizing Input Values

While driving, there's a possibility a value may fall outside the range of the motor's power (-1 to 1). To help make sure no inputs are lost because of this, we can use a technique called "normalizing".

What normalizing does is take all of our calculated values and scales them appropriately to remain inside the intended range.

Creating a Max Variable

First we need to create a new variable called "max".

In Blocks, we use something called a "list", also known as an "array" to store a set of numbers. In this case, we will be storing all of our motor powers.

But first, we need to add a block from our "Math" menu. We will change this using the dropdown to "max", meaning it is returning the largest value from our list of motor powers.

Since our motor power will sometimes be negative, such as when turning in reverse, we want to make sure we're using the absolute value of our motor powers.

Creating the If/Else Statement

Next, we will set up our to check if our "max" is higher than 1 and therefore outside the motor's range.

Using this statement, we'll readjust each of our motor's power back to be within range proportionally by dividing each by the max value.

Now our full drivetrain function will look like the following: