Functions

Functions contain code that can be reused throughout your program, which helps organize complex logic. Think of a function as a program within a program. Parameters specify different input values for your function; they are like a variable but only apply to the function, and they are not global to the rest of the program.

Start Program

You have probably noticed that every text program has a function called Start Program:
JavaScript: startProgram()
Python: start_program() 

This is a special function: Sphero expects the code inside the  Start Program to be the program's "main activity." For this reason, some programmers refer to Start Program as the 'main loop' in their code.

If your start Program function contains a loop, it must also contain a small delay, otherwise you will see a runtime error about spending too much time inside the function:

JavaScript:

async function startProgram() {

    while (true) {

        // Your code here...

        await delay(0.033); // <-- without this, you will get a runtime error.

    }

}

Python:

async def start_program():

    # <-- without this, you will get a runtime error.

    while True:

        # Your code here...

        await delay(0.033)

If the loop inside Start Program calls functions that have built-in delays, you don't need the extra delay at the end.

Defining Functions

Functions can be defined anywhere in a program, but in the examples below we define them above the main loop for simplicity. Usually, the order in which functions appear in your program doesn't matter. Even if other functions are defined before the Start Program function, Start Program will be run first (there are exceptions to this, but they are outside the scope of this wiki).

When programming with JavaScript, use function to define your function. When programming with Python, use def. For example:
JavaScript: function blink()
Python: def blink()

See the below blink function example that changes the LED's to red for 1 second, then green for 1 second. If you call this function from Start Program, it does exactly what you expect, executing the logic in the function:
JavaScript:

async function blink() {

    await Sound.Effects.Click.play();

    setMainLed({ "r": 255, "g": 0, "b": 0 });

    await delay(1);

    setMainLed({ "r": 0, "g": 255, "b": 0 });

    await delay(1);

}

async function startProgram() {

    await blink();

}

Python:

async def blink():

    await Sound.Effects.Click.play()

    set_main_led({'r': 255, 'g': 0, 'b': 0})

    await delay(1)

    set_main_led({'r': 0, 'g': 255, 'b': 0})

    await delay(1)

async def start_program():

    await blink()

Parameters

Parameters are like variables, but they are local to a function in that they only serve the function; they are not global to the rest of the program. Like variables, their four types are number, string, boolean, and color. Parameters are very helpful in quickly changing inputs without modifying the core function, or if you want to call a function many times and make changes to the input each time.

The below Blink Parameters example extends the blink function by enabling you to control the blink time and number via the parameters time and loop. You can call the function with different values each time. If you write this program without parameters it would require a lot more code:
JavaScript:

async function blinkParams(time, loops) {

    for (var _i1 = 0; _i1 < loops; _i1++) {

        await Sound.Effects.Click.play();

        setMainLed({ r: 255, g: 0, b: 0 });

        await delay(time);

        setMainLed({ r: 0, g: 255, b: 0 });

        await delay(time);

        await delay(0.025);

    }

}

async function startProgram() {

    await blinkParams(0.5, 5);

    await blinkParams(0.15, 10);

}

Python:

async def blink_params(time, loops):

    _i1 = 0

    while _i1 < loops:

        await Sound.Effects.Click.play()

        set_main_led({'r': 255, 'g': 0, 'b': 0})

        await delay(time)

        set_main_led({'r': 0, 'g': 255, 'b': 0})

        await delay(time)

        await delay(0.025)

        _i1 += 1

async def start_program():

    await blink_params(0.5, 5)

    await blink_params(0.15, 10)