Code the Gemma M0 with CircuitPython

Gemma M0

The Gemma M0 is just right for this project for a few reasons. It's inexpensive, has three digital input pins to read the two flippers and the plunger, it can output HID USB keyboard strokes over USB, and it draws very little power, so the iPad and iPhone won't mind powering it! Plus, it has an RGB DotStar LED that can be used as a multi-color indicator!

Coding Options

The Gemma M0 can currently be coded with either the Arduino IDE or CircuitPython. For this project, we'll use CircuitPython. It's very simple to set up -- all you need to do is plug it into your computer via USB and it shows up as a USB thumb drive. Then, you can write code in any text editor and save the file to the Gemma M0. That's all it takes, it immediately runs the code. Talk about fast iteration!

iCade Standard

Since the iPad doesn't have a game controller port on it like a video game console, game developers have come up with a few clever ways to interface physical controls with the device. One such standard is the iCade protocol, made by ION Audio for their line of iPad desktop arcade cabinets and controllers. 

The iCade standard interfaces with iOS as an HID keyboard, and is typically paired over Bluetooth. However, plugging in a wired HID keyboard works just as well, which makes it very straightforward to build your own controller!

The Gemma M0 is going to act as a USB HID keyboard so that it can "type" the keystrokes that the iCade standard uses.

Here's what the button mapping looks like for the standard iCade:

Keyboard Mapping

The first test I performed was to figure out the key mappings needed. I did so by pairing a Bluetooth keyboard to the iPad, launching Pinball Arcade, and setting the controller type to iCade in the game's settings. Then, I typed the key pairs seen in the diagram above until I knew which key combos did what.

The mapping for pinball looks like this:

Test Code

The next test I did was to have the Gemma M0 press the flipper buttons by telling it to "type" the "LVHR" combo over and over. Here's how you can make the Gemma M0 type the keystrokes.

First, make sure you've followed the basic guide to setting up the Gemma M0. Once you've successfully run the basic Blinky code example on your Gemma M0, move on to the next step.

If nothing happens when you plug in your Gemma M0, make sure the built-in ON/OFF switch is turned on!

The Gemma M0 ships with all of the libraries we'll need (HID library and DotStar library) already installed on the board, so we can immediately start coding this example!

With the Gemma M0 plugged into your computer, open the CIRCUTPY drive that shows up, and edit the code.py (or main.py, either will work) file in your text editor.

Copy and paste the code below into your text editor and then save the file, overwriting the existing code.py file on the root of the Gemma M0. Be careful where your cursor is when you save, since the program will cause the Gemma M0 to start spewing the letters "lhvr" as if you were banging on your keyboard!

Download: file
        # Gemma IO demo - Keyboard emu
# key tester

#import libraries
from board import *
import time
from adafruit_hid.keyboard import Keyboard
from adafruit_hid.keycode import Keycode
# the keyboard object
kbd = Keyboard()


##############
#the main loop
while True:
    # type "l" to press right flipper
    #this is actually a lower case letter, since we didn't use a shift modifier
    kbd.press(Keycode.L)
    kbd.release(Keycode.L)
    time.sleep(0.1) #pause .1 seconds

    # type "h" to press left flipper
    kbd.press(Keycode.H)
    kbd.release(Keycode.H)
    time.sleep(0.1) #pause .1 seconds

    # type "v" tor release right flipper
    kbd.press(Keycode.V)
    kbd.release(Keycode.V)
    time.sleep(0.1) #pause .1 seconds

    # type "r" tor release left flipper
    kbd.press(Keycode.R)
    kbd.release(Keycode.R)
    time.sleep(0.1) #pause .1 seconds

#testing area:
#  place cursor after comment hash symbol below before saving file to Gemma M0
#  so the typed letters don't mess with your code!
#
#

  
  

If you want to test it out on your pinball game, go ahead and plug the Gemma M0 into the iPad using the USB to Lightning adapter. The iPad will autodetect the device and open a camera import window. You can ignore this and switch to your iCade compatible pinball game, such as Pinball Arcade. When you start a new game, it will immediately begin flipping the flippers for you automatically! Launch a ball onto the field with the on-screen plunger and watch it play by itself for a bit!

Button Code

Now it's time to rewrite the code so that the two flippers and the plunger aren't haunted by the ghost of Tommy, but instead, respond to your arcade buttons!

Copy and paste the code below into your text editor and save it onto your Gemma M0 as code.py

Download: file
# Gemma IO demo - Keyboard emu
# iCade Pinball Edition by John Park and Tod Kurt

#import libraries
import digitalio
from board import *
import time
import adafruit_dotstar as dotstar
from adafruit_hid.keyboard import Keyboard
from adafruit_hid.keycode import Keycode

# Allows three buttons on a Gemma M0 to control iCade standard Pinball Arcade
# game on iOS using USB to Lightning "camera connector"

# iCade keyboard mappings
# See developer doc at: http://www.ionaudio.com/products/details/icade

#    WE     YT UF IM OG
# AQ< -->DC
#    XZ     HR JN KP LV

#control key is triggered by a press, doesn't repeat, second control key is
#triggered by a release

######
#setup
# The button pins we'll use, each has an internal pullup
buttonpins = [D0, D1, D2]
# our array of button objects
buttons = []

# The keycode pair sent for each button:
# D0 is left flipper -  iCade key sequence (hold, release) is "hr"
# D1 is right flipper - iCade key sequence (hold, release) is "lv"
# D2 is plunger -       iCade key sequence (hold, release) is "xz"

keys_pressed = [Keycode.H, Keycode.L, Keycode.X]
keys_released = [Keycode.R, Keycode.V, Keycode.Z]

# the keyboard object
kbd = Keyboard()

# make all pin objects, make them inputs w/pullups
for pin in buttonpins:
    button = digitalio.DigitalInOut(pin)
    button.direction = digitalio.Direction.INPUT
    button.pull = digitalio.Pull.UP
    buttons.append(button)

# which buttons have been pressed
buttons_pressed = [False] * len(buttons)

led = digitalio.DigitalInOut(D13)
led.direction = digitalio.Direction.OUTPUT

#set up on board DotStar
pixel = dotstar.DotStar(APA102_SCK, APA102_MOSI, 1, brightness=0.1)
pixel.fill([0, 50, 0]) #color in b - g - r color order
pixel.show()
###################left        plunger     right
pixelPressed =  [ [50,50,50], [0,0,100], [100,0,0] ] #pixel colors per button
pixelReleased = [ [0,100,0], [0,100,0], [0,100,0] ] #back to green 

print("Waiting for button presses")

##############
#the main loop
while True:
    # check each button for press
    for button in buttons:
        i = buttons.index(button)
        if (not button.value and not buttons_pressed[i]):   # button pressed
            pixel.fill([pixelPressed[i][0], pixelPressed[i][1], pixelPressed[i][2]])
            pixel.show()
            print("Button #%d Pressed" % i)

            # save the index of the button pressed
            buttons_pressed[i] = True

            # turn on the LED
            led.value = True

            # type the "press" keycode!
            k = keys_pressed[i]   # get the corresp. keycode
            kbd.press(k)
            kbd.release(k)

            # turn off the LED
            led.value = False

    # check pressed buttons for release
    for button in buttons:
        i = buttons.index(button)
        if( buttons_pressed[i] and button.value): # released
            pixel.fill([pixelReleased[i][0], pixelReleased[i][1], pixelReleased[i][2]])
            pixel.show()
            print("Button #%d Released" % i)
            buttons_pressed[i] = False

            # turn on the LED
            led.value = True

            # type the "release" keycode!
            k = keys_released[i]
            kbd.press(k)
            kbd.release(k)

            # turn off the LED
            led.value = False

    time.sleep(0.01)

#testing area
#

Next, we'll connect the arcade buttons to the Gemma M0.

This guide was first published on Sep 05, 2017. It was last updated on Sep 05, 2017. This page (Code the Gemma M0 with CircuitPython) was last updated on Aug 23, 2019.