When learning a text programming language, the first step is to understand its syntax. This language syntax prescribes the rules for writing statements (lines of code), and how to indicate code blocks that consist of multiple statements.

In Python, each statement begins with a level of indentation and ends with a line break. Indentation is the number of spaces before a statement. Lines with the same number of spaces have the same indentation level and belong to the same code block. The SPIKE App uses 4 spaces for each indentation level.

You write code in the Code Editor, which has features to help you write it correctly. For example, when you start a new code block, like a function or if statement, the Editor indents the next line with four extra spaces. Also, it numbers each line to make it easier to navigate your code.

Syntax highlighting in the Code Editor shows comments, keywords, text, and numbers in different colors so the code is easier to read. In the code below, the comment on the first line is green, the keywords print, if, and True are blue, the text 'LEGO' is magenta, and the number 123 is orange.

The code above is an example program, which you’ll find throughout the Getting Started chapters. Each example has a Copy icon in the top right corner:

Press this icon to copy the whole example program. Then right-click or long-press the Code Editor and choose Paste from the menu to paste the code. You can also press CTRL+V on Windows or Command+V on Mac.

To control the SPIKE Prime Hub, sensors, and motors, you’ll need the SPIKE Prime modules. Modules are used to organize related code. There’s one for each SPIKE Prime component, e.g., the motor module contains the code to control the motors. To use the functionality of a module, first import it with the import statement:

Import the modules you need once at the beginning of your Python program. See the SPIKE Prime Modules section of this User Guide for more on the modules and their functionality.

The SPIKE Prime Hub is a small computer called a microcontroller, which has limited memory and processing power. Since the full Python programming language would use too much memory, the Hub runs MicroPython, a highly optimized version of the Python language that can run on microcontrollers. The modules to control the SPIKE Prime Hub, sensors, and motors are also highly optimized by using optimized data types.

You’ve seen that the Code Editor shows text and numbers in different colors – because they’re different data types. Python further distinguishes between whole numbers and decimals. Whole numbers are also known as integers, or type int, which is optimized in MicroPython. Decimals use the unoptimized float type, so the SPIKE Prime modules avoid this data type. This means you have to stick to whole numbers or use different units to describe decimals. For half a second, you can use 500 milliseconds instead of 0.5 seconds.

Can you copy some of the example code in this chapter and paste it to the Code Editor?

In the previous example, you used the write() function. A function is a block of code that performs a task when you call it. You define a function with the def keyword, followed by the function name, parentheses, and a colon. The body of the function is indented and contains all the code that runs when you call the function. You call a function by writing the function name and parentheses. Make sure to unindent the function call, otherwise it’s part of the function body.

The example below defines the hello() function, which writes “Hello, World!” on the Light Matrix, and calls the function once. Try to run the example code. Remember to first delete any existing code from the Code Editor, before you copy, paste, and run the code.

In the example above, the hello() function has no parameters, so it writes “Hello World” on the Light Matrix each time you call it. To make it more dynamic, add a parameter name inside the parentheses of the function definition. The code block in the function body can then use this parameter to do something different based on its value. An example of this is the write() function, which has one required parameter: the text to write on the Light Matrix.

The example below adds a name parameter to the hello() function, which then writes 'Hello, ' + name + '!' on the Light Matrix. Notice the + operator, which lets you add pieces of text together. Text is also known as a string, or type str. It is surrounded by either single (') or double (") straight quotation marks, using the same type around a given text string. The updated hello() function has one required parameter of type str, so you can pass the string 'World' as an argument when you call it to write “Hello, World!” on the Light Matrix.

Try running the example code. Don’t forget to delete any existing code from the Code Editor before you copy, paste, and run your new code.

You’ll see the text “Hello, World!” scrolling across the Light Matrix once again.

Can you change the code so the Hub greets you instead of the world?

This program will show a face with blinking eyes on the Light Matrix of the Hub. Copy the code below and paste it into the Code Editor. Then run the program. As always, delete any existing code from the Code Editor before pasting the new code.

When you run this program, you’ll see that the smiley face blinks after a second. The program calls the show_image() function from the hub.light_matrix module to show an image on the Light Matrix. The program uses the sleep_ms() function from the time module to add delays for a number of milliseconds between different images. In the code, each comment describes what the next line of code should do.

Although commenting every line of code is tempting, the result is that you’ll Write Everything Twice. These WET comments don’t help readers if the code is self-explanatory. Instead, follow the DRY principle and Don’t Repeat Yourself.

In the example below, the lines of code that blink the eyes are inside the new blink() function. The program then calls the function three times, so the eyes blink three times. Notice that this time, the comments describe only the main parts of the code to help readers understand what that code should do.

Can you change the code to keep the eyes open longer each time they blink?

Now connect a second motor to port B and try the program below.

Notice that both motors run 360 degrees (one rotation) at 720 degrees per second, starting and ending at the same time. Since the two motor statements are on separate lines, you might expect them to run one by one. However, they run at the same time because the run_for_degrees() is an awaitable function. That means you can wait for it to complete, but you don’t have to. By default, the program immediately continues to the next line of code while the awaitable code runs to completion in the background. This makes it possible to run multiple commands at the same time.

To effectively use awaitable code with the flexibility to run commands either concurrently or sequentially, you must run your code in an asynchronous function using a run loop. The runloop module controls the run loop on the Hub, and lets you run asynchronous functions with its run() function. An asynchronous function, also known as a coroutine, is an awaitable that uses the async keyword before the function definition. The convention is to name the coroutine containing your main program main(). The code below shows the general structure of a program using a run loop.

In the body of a coroutine, you can use the await keyword before calling an awaitable command. This pauses the coroutine until the command completes. Without the keyword, the program immediately continues to the next line of code in the coroutine. You can still use regular (not awaitable) code inside the coroutine. However, doing so will always pause or block the whole program until the command completes.

The program below defines the main() coroutine, which uses the await keyword before the two run_for_degrees() function calls. It uses the run() function from the runloop module to run the main() coroutine on the final line of code.

Try the sample code. You should see that both motors run 360 degrees (one rotation) at 720 degrees per second, one at a time.

Can you change the code to run both motors at the same time again?

It’s important to understand that it matters where a variable is created. When you create a variable inside a function, it’s only available to that function. This is called a local variable. If you want to use a variable across different functions in your program, you must create the variable outside the functions, for example underneath your import statements. This is called a global variable.

Once again, you’ll see both motors run 360 degrees (one rotation) at 720 degrees per second, one at a time. This time the velocity variable has global scope and a new degrees variable has local scope. You can use the global velocity variable both inside and outside of the main() function, but you can only use the local degrees variable inside the main() function where it is defined.

It can be tempting to define all your variables at the top of your program so they have global scope, because then you can conveniently use them in your whole program. However, this also means that the value of those variables can be changed from anywhere in your program, with undesired side effects. Instead, tightly scope your variables, so only the parts of your program that need to use and change them have access.

In Python, the simplest way to repeat some code a number of times is to use a for loop with the built-in range() function. For example, to repeat something four times, you write for i in range(4): followed by the code you want to run four times. You can think of range(4) as the tuple (0, 1, 2, 3). Tuples and lists such as [1, 2, 3] are iterables. The for loop takes an iterable and loops over its values until it reaches the end.

When a for loop iterates over a tuple or list, it changes the value of a local variable on each iteration. So far, you’ve explicitly created variables and assigned them a value using the = sign. In a for loop, the name of the local variable is defined after the for keyword, in this case i. Each time the loop runs, the value of this local variable i changes. It will be 0 the first time the loop runs and 3 the last time it runs, corresponding to the values in (0, 1, 2, 3).

The next example uses a for loop to change the global velocity variable four times to run the motor on port A with a different velocity each time. To enable changing the global variable velocity in the local context of the main() function, you need to use the global keyword before velocity at the start of the function body.

Run the example code. You’ll see the motor on port A run 360 degrees four times, at four different velocities, faster each time. The final time, the motor on port B runs 360 degrees once at 990 degrees per second.

Can you change the code so the motor on port A runs a different number of degrees each time?

You can also use a while loop to repeat something forever instead of a specific number of times. In Python, the simplest way to create such a loop is to write while True: followed by the code you want to run forever. The next example uses a while True loop to run a little disco show forever or until you stop the program.

Notice that the Power Button lights up in random colors, with a random delay between each color change. The example uses the randint() function again to generate a number between 1 and 9 (both included), which corresponds to the different color numbers excluding black (0) and white (10).

If you want the light show to only include certain colors, you can put them in a list and then choose a random color from it. You create a new list like a variable, first writing the list name, then the = sign, and finally the values inside square brackets, separated with commas. For a simple list with at least two items, write my_list = [1, 2]. You can add as many values as you want.

As you’ve seen in the previous examples, each color is represented by a different number. You use this number to set the light to that color, for example, number 9 will set the light to red. However, using numbers for colors can make it harder for other readers to know what your code will do. You could add comments to describe each value, but a better way is to make variables for each color. The color module has a variable RED so you can write color.RED instead of the number 9 in your code. (A variable listed with all capital letters is a constant, which means you shouldn’t change it.)

The example below imports the color module and uses some of the color constants to create the list colors. This time, the randint() function determines how many times the for loop runs, and the light turns white at the end of this little random light show.

You’ll see the Power Button light change to a random color from the list, for a random number of times, with a random delay between each color change. The example uses the choice() function to pick a random color from the colors list.

Can you change the code so there are different colors in the colors list?

Sometimes your program doesn’t do what you expect it to do. You can use the print() function to debug your program when that happens. The print() function writes whatever you pass as the argument to the Console window below the Code Editor, in this case the force of the Force Sensor. Run the program again and notice the value that appears in the Console.

You’ll see a single number in the console, and unless you were pressing the Force Sensor when you started the program, that number is 0. Running a motor at 0 degrees per second doesn’t do much, so the problem is that the program only checks the sensor value once at the start of the program. To update the motor velocity based on the force for as long as the program runs, you’ll need to use the while True loop again.

The Console also displays error messages when something goes wrong while running your program. One common error happens when you run a program to control a motor or read a sensor that isn’t connected. Disconnect the Force Sensor and run the same program one last time. You’ll see an error in the Console informing you that there was a problem, what the problem was, and on what line of code it happened.

The Console helped you find two bugs. Reconnect the Force Sensor to port B to fix the second bug and then run the program below that fixes the first bug by wrapping the code in a while True loop.

Press the Force Sensor while the program is running. You’ll see the motor speeding up or slowing down depending on how hard you press the Force Sensor. You’ll also see a lot of variable values written in the Console. The Force Sensor force is measured in decinewtons (dN) and since the maximum force it can measure is 10 newtons, the maximum value in dN is 100. Running a motor at 100 degrees per second still isn’t very fast!

Instead of storing the value of the Force Sensor in a variable, you can also define a function that returns this value. Separating the different parts of your program this way makes it easier to organize your code and fix bugs if they happen.

The next program defines a motor_velocity() function that returns the desired motor velocity based on the force of the Force Sensor instead of using a variable.

Press the Force Sensor while the program is running. You’ll see the motor speeding up or slowing down depending on how hard you press the Force Sensor. The motor_velocity() function multiplies the force value by 5, so the velocity will be between 0 and 500 degrees per second.

Can you change the code to run the motor at 1000 degrees per second when the Force Sensor is fully pressed?

You can add more than one condition by extending the if statement with an elif statement that checks another condition. You can add as many of these as you need, and they follow the same syntax as the if statement. The elif should be on the same indentation level as the first if statement, and the elif keyword is followed by a logical expression and a colon. Indent the next line(s) of code that should run when this condition is True.

Sometimes, none of the conditions in the if and elif statements are True. In this case, you can run some code by adding an else statement without any condition. This runs when all the previous conditions are False.

For example, the program below adds an elif and else statement to also beep if the left button is pressed.

Wave a red LEGO brick in front of the Color Sensor and press the left button on the Hub while the program is running. You’ll hear a beep for as long as the red color is detected, and a short beep each time the left button is pressed.

The example defines two functions to do the logic tests and return the result. The red_detected() function checks if the color detected by the Color Sensor is red and returns the result True or False. The left_pressed() function uses the pressed() function from the hub.button module and uses the > operator to check if the value is greater than 0 and returns the result.

The code in the if statement here is largely the same as the first example, but now it uses the red_detected() function in two places instead of repeating the condition for the if and while statements. The elif statement uses the left_pressed() function to check if the left button on the Hub is pressed for more than 0 milliseconds.

Note that the elif statement only runs when the condition of the first if statement is False. Therefore, pressing the button while the Color Sensor detects something red has no effect. You should carefully consider the order of your if and elif conditions and check the most important ones first. The else statement stops the sound if neither condition is True.

When you use if/elif/else statements to test for multiple conditions, only one of the blocks will run. These conditions are mutually exclusive. You’ve seen that while the color red was detected, pressing the left button had no effect. To truly check multiple conditions, you must check them at the same time. Like adding several stacks of Word Blocks, in Python you can run multiple coroutines with the run() function from the runloop module. Until now, you’ve called it with the main() coroutine as its only argument, but it’s possible to pass multiple coroutines as comma-separated arguments.

For example, the program below divides the code that checks the detected color and the pressed button into two coroutines. The run() function on the final line of code starts both coroutines at the same time.

Wave a red LEGO brick in front of the Color Sensor and press the left button on the Hub while the program is running. Like before, you’ll hear a beep for as long as the red color is detected, and a short beep each time the left button is pressed. This time, it’s possible to press the left button and hear a beep while the red color is detected because both functions run at the same time.

When you create your own coroutines, remember that:

• Your coroutines should at least await one command.
• When you use a tight while loop, use await runloop.sleep_ms(1) inside the loop to give other coroutines a chance to start and run.

Can you change the code to detect a different color than red?

This Getting Started section has barely scratched the surface of what’s possible with Python and SPIKE Prime. Explore these two other sections of the Python User Guide.

1. Examples Find example programs that show how to use Python to solve various tasks. Copy and try them, then modify them to suit your needs.
2. SPIKE Prime Modules Find documentation of all the functions and variables in the SPIKE Prime modules with short examples of how to use them.

On the LEGOeducation.com/lessons website, select the product SPIKE™ Prime with Python. You’ll find several unit plans with 6–8 lessons each (available in English only). These 50+ lessons cover a wide range of topics, from debugging to sensor control, and from simple games to data and math functions. Discover the many possibilities and become an expert using Python with SPIKE Prime.

Create a new Python project and get coding!

The bargraph module is used make bar graphs in the SPIKE App

To use the bargraph module simply import the module like so:

bargraph details

The display module is used show images in the SPIKE App

To use the display module simply import the module like so:

display details

The linegraph module is used make line graphs in the SPIKE App

To use the linegraph module simply import the module like so:

linegraph details

The music module is used make music in the SPIKE App

To use the music module simply import the module like so:

music details

The sound module is used play sounds in the SPIKE App

To use the sound module simply import the module like so:

sound details

BLACK = 0

MAGENTA = 1

PURPLE = 2

BLUE = 3

AZURE = 4

TURQUOISE = 5

GREEN = 6

YELLOW = 7

ORANGE = 8

RED = 9

WHITE = 10

UNKNOWN = -1

clear(port: int) -> None

Turn off all pixels on a Color Matrix

get_pixel(port: int, x: int, y: int) -> tuple[int, int]

Retrieve a specific pixel represented as a tuple containing the color and intensity

set_pixel(port: int, x: int, y: int, pixel: tuple[color: int, intensity: int]) -> None

Change a single pixel on a Color Matrix

show(port: int, pixels: list[tuple[int, int]]) -> None

Change all pixels at once on a Color Matrix

color(port: int) -> int

Returns the color value of the detected color. Use the color module to map the color value to a specific color.

reflection(port: int) -> int

Retrieves the intensity of the reflected light (0-100%).

rgbi(port: int) -> tuple[int, int, int, int]

Retrieves the overall color intensity and intensity of red, green and blue.

Returns tuple[red: int, green: int, blue: int, intensity: int]

data(port: int) -> tuple[int]

Retrieve the raw LPF-2 data from a device.

id(port: int) -> int

Retrieve the device id of a device. Each device has an id based on its type.

get_duty_cycle(port: int) -> int

Retrieve the duty cycle for a device. Returned values is in range 0 to 10000

ready(port: int) -> bool

When a device is attached to the hub it might take a short amount of time before it's ready to accept requests.
Use ready to test for the readiness of the attached devices.

set_duty_cycle(port: int, duty_cycle: int) -> None

Set the duty cycle on a device. Range 0 to 10000

clear(port: int) -> None

Turns off all the lights in the Distance Sensor connected to port.

distance(port: int) -> int

Retrieve the distance in millimeters captured by the Distance Sensor connected to port. If the Distance Sensor cannot read a valid distance it will return -1.

get_pixel(port: int, x: int, y: int) -> int

Retrieve the intensity of a specific light on the Distance Sensor connected to port.

set_pixel(port: int, x: int, y: int, intensity: int) -> None

Changes the intensity of a specific light on the Distance Sensor connected to port.

show(port: int, pixels: list[int]) -> None

Change all the lights at the same time.

force(port: int) -> int

Retrieves the measured force as decinewton. Values range from 0 to 100

pressed(port: int) -> bool

Tests whether the button on the sensor is pressed. Returns true if the force sensor connected to port is pressed.

raw(port: int) -> int

Returns the raw, uncalibrated force value of the force sensor connected on port port

To use the Button module add the following import statement to your project:

All functions in the module should be called inside the button module as a prefix like so:

The light module includes functions to change the color of the light on the SPIKE Prime hub.

To use the Light module add the following import statement to your project:

All functions in the module should be called inside the light module as a prefix like so:

To use the Light Matrix module add the following import statement to your project:

All functions in the module should be called inside the light_matrix module as a prefix like so:

To use the Motion Sensor module add the following import statement to your project:

All functions in the module should be called inside the motion_sensor module as a prefix like so:

This module contains constants that enables easy access to the ports on the SPIKE Prime hub. Use the constants in all functions that takes a port parameter.

To use the Port module add the following import statement to your project:

All functions in the module should be called inside the port module as a prefix like so:

To use the Sound module add the following import statement to your project:

All functions in the module should be called inside the sound module as a prefix like so:

device_uuid() -> str

Retrieve the device id.

hardware_id() -> str

Retrieve the hardware id.

power_off() -> int

Turns off the hub.

temperature() -> int

Retrieve the hub temperature. Measured in decidegrees celsius (d°C) which is 1 / 10 of a degree celsius (°C)

absolute_position(port: int) -> int

Get the absolute position of a Motor

get_duty_cycle(port: int) -> int

Get the pwm of a Motor

relative_position(port: int) -> int

Get the relative position of a Motor

reset_relative_position(port: int, position: int) -> None

Change the position used as the offset when using the run_to_relative_position function.

run(port: int, velocity: int, *, acceleration: int = 1000) -> None

Start a Motor at a constant speed

run_for_degrees(port: int, degrees: int, velocity: int, *, stop: int = BRAKE, acceleration: int = 1000, deceleration: int = 1000) -> Awaitable

Turn a motor for a specific number of degrees
When awaited returns a status of the movement that corresponds to one of the following constants:

motor.READY
motor.RUNNING
motor.STALLED
motor.CANCELED
motor.ERROR
motor.DISCONNECTED

run_for_time(port: int, duration: int, velocity: int, *, stop: int = BRAKE, acceleration: int = 1000, deceleration: int = 1000) -> Awaitable

Run a Motor for a limited amount of time
When awaited returns a status of the movement that corresponds to one of the following constants:

motor.READY
motor.RUNNING
motor.STALLED
motor.ERROR
motor.DISCONNECTED

run_to_absolute_position(port: int, position: int, velocity: int, *, direction: int = motor.SHORTEST_PATH, stop: int = BRAKE, acceleration: int = 1000, deceleration: int = 1000) -> Awaitable

Turn a motor to an absolute position.
When awaited returns a status of the movement that corresponds to one of the following constants:

motor.READY
motor.RUNNING
motor.STALLED
motor.CANCELED
motor.ERROR
motor.DISCONNECTED

run_to_relative_position(port: int, position: int, velocity: int, *, stop: int = BRAKE, acceleration: int = 1000, deceleration: int = 1000) -> Awaitable

Turn a motor to a position relative to the current position.
When awaited returns a status of the movement that corresponds to one of the following constants:

motor.READY
motor.RUNNING
motor.STALLED
motor.CANCELED
motor.ERROR
motor.DISCONNECTED

set_duty_cycle(port: int, pwm: int) -> None

Start a Motor with a specific pwm

stop(port: int, *, stop: int = BRAKE) -> None

Stops a motor

velocity(port: int) -> int

Get the velocity (deg/sec) of a Motor

READY = 0

RUNNING = 1

STALLED = 2

CANCELLED = 3

ERROR = 4

DISCONNECTED = 5

COAST = 0

BRAKE = 1

HOLD = 2

CONTINUE = 3

SMART_COAST = 4

SMART_BRAKE = 5

CLOCKWISE = 0

COUNTERCLOCKWISE = 1

SHORTEST_PATH = 2

LONGEST_PATH = 3

move(pair: int, steering: int, *, velocity: int = 360, acceleration: int = 1000) -> None

Move a Motor Pair at a constant speed until a new command is given.

move_for_degrees(pair: int, degrees: int, steering: int, *, velocity: int = 360, stop: int = motor.BRAKE, acceleration: int = 1000, deceleration: int = 1000) -> Awaitable

Move a Motor Pair at a constant speed for a specific number of degrees.
When awaited returns a status of the movement that corresponds to one of the following constants from the motor module:

motor.READY
motor.RUNNING
motor.STALLED
motor.CANCELED
motor.ERROR
motor.DISCONNECTED

move_for_time(pair: int, duration: int, steering: int, *, velocity: int = 360, stop: int = motor.BRAKE, acceleration: int = 1000, deceleration: int = 1000) -> Awaitable

Move a Motor Pair at a constant speed for a specific duration.
When awaited returns a status of the movement that corresponds to one of the following constants from the motor module:

motor.READY
motor.RUNNING
motor.STALLED
motor.CANCELED
motor.ERROR
motor.DISCONNECTED

move_tank(pair: int, left_velocity: int, right_velocity: int, *, acceleration: int = 1000) -> None

Perform a tank move on a Motor Pair at a constant speed until a new command is given.

move_tank_for_degrees(pair: int, degrees: int, left_velocity: int, right_velocity: int, *, stop: int = motor.BRAKE, acceleration: int = 1000, deceleration: int = 1000) -> Awaitable

Perform a tank move on a Motor Pair at a constant speed until a new command is given.
When awaited returns a status of the movement that corresponds to one of the following constants from the motor module:

motor.READY
motor.RUNNING
motor.STALLED
motor.CANCELED
motor.ERROR
motor.DISCONNECTED

move_tank_for_time(pair: int, left_velocity: int, right_velocity: int, duration: int, *, stop: int = motor.BRAKE, acceleration: int = 1000, deceleration: int = 1000) -> Awaitable

Perform a tank move on a Motor Pair at a constant speed for a specific amount of time.
When awaited returns a status of the movement that corresponds to one of the following constants from the motor module:

motor.READY
motor.RUNNING
motor.STALLED
motor.CANCELED
motor.ERROR
motor.DISCONNECTED

pair(pair: int, left_motor: int, right_motor: int) -> None

pair two motors (left_motor & right_motor) and store the paired motors in pair.
Use pair in all subsequent motor_pair related function calls.

stop(pair: int, *, stop: int = motor.BRAKE) -> None

Stops a Motor Pair.

unpair(pair: int) -> None

Unpair a Motor Pair.

PAIR_1 = 0
First Motor Pair
PAIR_2 = 1
Second Motor Pair
PAIR_3 = 2
Third Motor Pair

UP = 0

RIGHT = 1

DOWN = 2

LEFT = 3

run(*functions: Awaitable) -> None

Start any number of parallel async functions. This is the function you should use to create programs with a similar structure to Word Blocks.

sleep_ms(duration: int) -> Awaitable

Pause the execution of the application for any amount of milliseconds.

until(function: Callable[[], bool], timeout: int = 0) -> Awaitable

Returns an awaitable that will return when the condition in the function or lambda passed is True or when it times out