The Circuit Python Gizmo Module

In this tutorial, we will introduce the circuitpython_gizmo module and the print function. You will learn how to get input from your gamepad and how to send text back to your computer to help debug your code.

The print Function

When your Gizmo is connected to a computer, your CircuitPython programs are able to send information back to your computer. The messages your Gizmo sends will show up in the "serial" viewer in the Mu editor. Your code sends these messages by calling the print function.

communication protocols used in electronics. Often this refers to a UART used to communicate between microcontrollers. For our purposes here, the USB connection is emulating a simple "serial" communication protocol.

To use the print function, give it the message you want to send. This can be text, numbers, or variables. The print function is always available, so you don't have to import any modules to use it.

# Sending text
print("Hello from Gizmo!")

# Sending variables
value = 100
print(value)

You can also embed variables into text messages to give more context. Just put an 'f' in front of your message and wrap the variable names in curly brackets. For example:

count = 2
print(f"The count is {count}.")
# This will print "The count is 2."

The circuitpython_gizmo Module

The circuitpython_gizmo module gives access to the unique features of the Gizmo. This includes pin name constants and gamepad values. This is all done with the Gizmo class.

import circuitpython_gizmo

# Create a new Gizmo object
gizmo = circuitpython_gizmo.Gizmo()

The Gizmo class has several useful variables and functions. Firstly, it features a number of useful constants for referencing the ports on the Gizmo.

• gizmo.MOTOR_N - the nth motor port (1 - 8)
• gizmo.GPIO_N - the nth gpio port (1 - 8)
• gizmo.ADC_N - the nth analog port (1 - 3)
• gizmo.NEOPIXEL - the Neopixel port
• gizmo.UART_TX and gizmo.UART_RX - the transmit and receive pins for the UART port

Gizmo can also be used to retrieve the gamepad states.

There are six axes available:

• gizmo.axes.left_x - Left stick X-axis (0-255)
• gizmo.axes.left_y - Left stick Y-axis (0-255)
• gizmo.axes.right_x - Right stick X-axis (0-255)
• gizmo.axes.right_y - Right stick Y-axis (0-255)
• gizmo.axes.dpad_x - D-pad X-axis (0, 127, or 255)
• gizmo.axes.dpad_y - D-pad Y-axis (0, 127, or 255)

There are twelve buttons available:

• gizmo.buttons.x - X button
• gizmo.buttons.a - A button
• gizmo.buttons.b - B button
• gizmo.buttons.y - Y button
• gizmo.buttons.left_shoulder - Left shoulder button
• gizmo.buttons.right_shoulder - Right shoulder button
• gizmo.buttons.left_trigger - Left trigger
• gizmo.buttons.right_trigger - Right trigger
• gizmo.buttons.back - Back button
• gizmo.buttons.start - Start button
• gizmo.buttons.left_stick - Left joystick stalk
• gizmo.buttons.right_stick - Right joystick stalk

Finally, the refresh function must be called at regular intervals to get the latest information from the system processor. This is usually done towards the start of your program's infinite while loop.

while True:
  gizmo.refresh()

Logging Gamepad State

Let's put everything we've introduced here together in a simple program that counts how many times a button on our gamepad is pressed.

First, import the Circuit Python Gizmo module.

import circuitpython_gizmo

Then, create three variables:

• gizmo: a Gizmo object and a counter variable
• count: a number that will track how many times the button has been pressed
• previous_button_state: a boolean (True/False) that will remember whether the button was pressed in the previous loop iteration

gizmo = circuitpython_gizmo.Gizmo()
count = 0
previous_button_state = False

Next, in a while loop, refresh the Gizmo object to get the latest information.

while True:
  gizmo.refresh()

Still in the loop, check if the A button has been pressed. If it is pressed now and wasn't pressed last time, we know this is the start of a new press and the count should increas by 1.

  if gizmo.buttons.a and not previous_button_state:
    count += 1
    print(f"The button has been pressed {count} times.")

Finally, end the loop (outside of the if) by updating previous_button_state.

  previous_button_state = gizmo.buttons.a

The complete program looks like this:

import circuitpython_gizmo

gizmo = circuitpython_gizmo.Gizmo()
count = 0
previous_button_state = False

while True:
  gizmo.refresh()
  if gizmo.buttons.a and not previous_button_state:
    count += 1
    print(f"The button has been pressed {count} times.")
  previous_button_state = gizmo.buttons.a

To run this program, make sure your Gizmo battery is plugged in and the Gizmo is connected to your driver station.

Recap

In this tutorial, we've introduced the circuitpython_gizmo module and the print function. With these new tools, we wrote a program that counts button presses on your gamepad.