Essential Hub

../_images/hub-essential.png
class EssentialHub(top_side=Axis.Z, front_side=Axis.X)

LEGO® SPIKE Essential Hub.

Initializes the hub. Optionally, specify how the hub is placed in your design by saying in which direction the top side (with the button) and the front side (with the USB port, and I/O ports A and B) are pointing.

Parameters
  • top_side (Axis) – The axis that passes through the top side of the hub.

  • front_side (Axis) – The axis that passes through the front side of the hub.

Using the hub status light

light.on(color)

Turns on the light at the specified color.

Parameters

color (Color) – Color of the light.

light.off()

Turns off the light.

Blinks the light at a given color by turning it on and off for given durations.

The light keeps blinking indefinitely while the rest of your program keeps running.

This method provides a simple way to make basic but useful patterns. For more generic and multi-color patterns, use animate() instead.

Parameters
  • color (Color) – Color of the light.

  • durations (list) – Sequence of time values of the form [on_1, off_1, on_2, off_2, ...].

light.animate(colors, interval)

Animates the light with a sequence of colors, shown one by one for the given interval.

The animation runs in the background while the rest of your program keeps running. When the animation completes, it repeats.

Parameters
  • colors (list) – Sequence of Color values.

  • interval (Number, ms) – Time between color updates.

Using the button

button.pressed() Collection[Button]

Checks which buttons are currently pressed.

Returns

Set of pressed buttons.

Using the IMU

imu.up() Side

Checks which side of the hub currently faces upward.

Returns

Side.TOP, Side.BOTTOM, Side.LEFT, Side.RIGHT, Side.FRONT or Side.BACK.

imu.tilt() Tuple[int, int]

Gets the pitch and roll angles. This is relative to the user-specified neutral orientation.

The order of rotation is pitch-then-roll. This is equivalent to a positive rotation along the robot y-axis and then a positive rotation along the x-axis.

Returns

Tuple of pitch and roll angles.

imu.acceleration(axis) float: mm/s²
imu.acceleration() vector: mm/s²

Gets the acceleration of the device along a given axis in the robot reference frame.

Parameters

axis (Axis) – Axis along which the acceleration should be measured.

Returns

Acceleration along the specified axis. If you specify no axis, this returns a vector of accelerations along all axes.

imu.angular_velocity(axis) float: deg/s
imu.angular_velocity() vector: deg/s

Gets the angular velocity of the device along a given axis in the robot reference frame.

Parameters

axis (Axis) – Axis along which the angular velocity should be measured.

Returns

Angular velocity along the specified axis. If you specify no axis, this returns a vector of accelerations along all axes.

imu.heading() float: deg

Gets the heading angle relative to the starting orientation. It is a positive rotation around the z-axis in the robot frame, prior to applying any tilt rotation.

For a vehicle viewed from the top, this means that a positive heading value corresponds to a counterclockwise rotation.

Note

This method is not yet implemented.

Returns

Heading angle relative to starting orientation.

imu.reset_heading(angle)

Resets the accumulated heading angle of the robot.

Note

This method is not yet implemented.

Parameters

angle (Number, deg) – Value to which the heading should be reset.

Using the battery

battery.voltage() int: mV

Gets the voltage of the battery.

Returns

Battery voltage.

battery.current() int: mA

Gets the current supplied by the battery.

Returns

Battery current.

Getting the charger status

charger.connected() bool

Checks whether a charger is connected via USB.

Returns

True if a charger is connected, False if not.

charger.current() int: mA

Gets the charging current.

Returns

Charging current.

charger.status() int

Gets the status of the battery charger, represented by one of the following values. This corresponds to the battery light indicator right next to the USB port.

  1. Not charging (light is off).

  2. Charging (light is red).

  3. Charging is complete (light is green).

  4. There is a problem with the charger (light is yellow).

Returns

Status value.

System control

system.set_stop_button(button)

Sets the button or button combination that stops a running script.

Normally, the center button is used to stop a running script. You can change or disable this behavior in order to use the button for other purposes.

Parameters

button (Button) – A button such as Button.CENTER, or a tuple of multiple buttons. Choose None to disable the stop button altogether.

system.name() str

Gets the hub name. This is the name you see when connecting via Bluetooth.

Returns

The hub name.

system.storage(self, offset, write=)
system.storage(self, offset, read=) bytes

Reads or writes binary data to persistent storage.

This lets you store data that can be used the next time you run the program.

The data will be saved to flash memory when you turn the hub off normally. It will not be saved if the batteries are removed while the hub is still running.

Once saved, the data will remain available even after you remove the batteries.

Parameters
  • offset (int) – The offset from the start of the user storage memory, in bytes.

  • read (int) – The number of bytes to read. Omit this argument when writing.

  • write (bytes) – The bytes to write. Omit this argument when reading.

Returns

The bytes read if reading, otherwise None.

Raises

ValueError – If you try to read or write data outside of the allowed range.

You can store up to 512 bytes of data on this hub.

system.shutdown()

Stops your program and shuts the hub down.

system.reset_reason() int

Finds out how and why the hub (re)booted. This can be useful to diagnose some problems.

Returns

  • 0 if the hub was previously powered off normally.

  • 1 if the hub rebooted automatically, like after a firmware update.

  • 2 if the hub previously crashed due to a watchdog timeout, which indicates a firmware issue.

Status light examples

Turning the light on and off

from pybricks.hubs import EssentialHub
from pybricks.parameters import Color
from pybricks.tools import wait

# Initialize the hub.
hub = EssentialHub()

# Turn the light on and off 5 times.
for i in range(5):

    hub.light.on(Color.RED)
    wait(1000)

    hub.light.off()
    wait(500)

Changing brightness and using custom colors

from pybricks.hubs import EssentialHub
from pybricks.parameters import Color
from pybricks.tools import wait

# Initialize the hub.
hub = EssentialHub()

# Show the color at 30% brightness.
hub.light.on(Color.RED * 0.3)

wait(2000)

# Use your own custom color.
hub.light.on(Color(h=30, s=100, v=50))

wait(2000)

# Go through all the colors.
for hue in range(360):
    hub.light.on(Color(hue))
    wait(10)

Creating light animations

from pybricks.hubs import EssentialHub
from pybricks.parameters import Color
from pybricks.tools import wait
from umath import sin, pi

# Initialize the hub.
hub = EssentialHub()

# Make an animation with multiple colors.
hub.light.animate([Color.RED, Color.GREEN, Color.NONE], interval=500)

wait(10000)

# Make the color RED grow faint and bright using a sine pattern.
hub.light.animate([Color.RED * (0.5 * sin(i / 15 * pi) + 0.5) for i in range(30)], 40)

wait(10000)

# Cycle through a rainbow of colors.
hub.light.animate([Color(h=i * 8) for i in range(45)], interval=40)

wait(10000)

IMU examples

Testing which way is up

from pybricks.hubs import EssentialHub
from pybricks.parameters import Color, Side
from pybricks.tools import wait

# Initialize the hub.
hub = EssentialHub()

# Define colors for each side in a dictionary.
SIDE_COLORS = {
    Side.TOP: Color.RED,
    Side.BOTTOM: Color.BLUE,
    Side.LEFT: Color.GREEN,
    Side.RIGHT: Color.YELLOW,
    Side.FRONT: Color.MAGENTA,
    Side.BACK: Color.BLACK,
}

# Keep updating the color based on detected up side.
while True:

    # Check which side of the hub is up.
    up_side = hub.imu.up()

    # Change the color based on the side.
    hub.light.on(SIDE_COLORS[up_side])

    # Also print the result.
    print(up_side)
    wait(50)

Reading the tilt value

from pybricks.hubs import EssentialHub
from pybricks.tools import wait

# Initialize the hub.
hub = EssentialHub()

while True:
    # Read the tilt values.
    pitch, roll = hub.imu.tilt()

    # Print the result.
    print(pitch, roll)
    wait(200)

Using a custom hub orientation

from pybricks.hubs import EssentialHub
from pybricks.tools import wait
from pybricks.geometry import Axis

# Initialize the hub. In this case, specify that the hub is mounted with the
# top side facing forward and the front side facing to the right.
# For example, this is how the hub is mounted in BLAST in the 51515 set.
hub = EssentialHub(top_side=Axis.X, front_side=-Axis.Y)

while True:
    # Read the tilt values. Now, the values are 0 when BLAST stands upright.
    # Leaning forward gives positive pitch. Leaning right gives positive roll.
    pitch, roll = hub.imu.tilt()

    # Print the result.
    print(pitch, roll)
    wait(200)

Reading acceleration and angular velocity vectors

from pybricks.hubs import EssentialHub
from pybricks.tools import wait

# Initialize the hub.
hub = EssentialHub()

# Get the acceleration vector in g's.
print(hub.imu.acceleration() / 9810)

# Get the angular velocity vector.
print(hub.imu.angular_velocity())

# Wait so we can see what we printed
wait(5000)

Reading acceleration and angular velocity on one axis

from pybricks.hubs import EssentialHub
from pybricks.tools import wait
from pybricks.geometry import Axis

# Initialize the hub.
hub = EssentialHub()

# Get the acceleration or angular_velocity along a single axis.
# If you need only one value, this is more memory efficient.
while True:

    # Read the forward acceleration.
    forward_acceleration = hub.imu.acceleration(Axis.X)

    # Read the yaw rate.
    yaw_rate = hub.imu.angular_velocity(Axis.Z)

    # Print the yaw rate.
    print(yaw_rate)
    wait(100)

System examples

Using the stop button during your program

from pybricks.hubs import EssentialHub
from pybricks.parameters import Color, Button
from pybricks.tools import wait, StopWatch

# Initialize the hub.
hub = EssentialHub()

# Disable the stop button.
hub.system.set_stop_button(None)

# Check the button for 5 seconds.
watch = StopWatch()
while watch.time() < 5000:

    # Set light to green if pressed, else red.
    if hub.button.pressed():
        hub.light.on(Color.GREEN)
    else:
        hub.light.on(Color.RED)

# Enable the stop button again.
hub.system.set_stop_button(Button.CENTER)

# Now you can press the stop button as usual.
wait(5000)

Turning the hub off

from pybricks.hubs import EssentialHub
from pybricks.tools import wait

# Initialize the hub.
hub = EssentialHub()

# Say goodbye and give some time to send it.
print("Goodbye!")
wait(100)

# Shut the hub down.
hub.system.shutdown()