# SPDX-License-Identifier: MIT # SPDX-FileCopyrightText: Copyright 2024 Sam Blenny # # Hardware: # - Adafruit ESP32-S3 TFT Feather - 4MB Flash, 2MB PSRAM (#5483) # - Adafruit USB Host FeatherWing with MAX3421E (#5858) # - 8BitDo SN30 Pro USB gamepad # # Pinouts: # | TFT feather | USB Host | ST7789 TFT | # | ----------- | -------- | ---------- | # | SCK | SCK | | # | MOSI | MOSI | | # | MISO | MISO | | # | D9 | IRQ | | # | D10 | CS | | # | TFT_CS | | CS | # | TFT_DC | | DC | # # Related Documentation: # - https://learn.adafruit.com/adafruit-esp32-s3-tft-feather # - https://learn.adafruit.com/adafruit-1-14-240x135-color-tft-breakout # - https://learn.adafruit.com/adafruit-usb-host-featherwing-with-max3421e # - https://docs.circuitpython.org/en/latest/shared-bindings/displayio/ # - https://docs.circuitpython.org/projects/display_text/en/latest/api.html # - https://learn.adafruit.com/circuitpython-display_text-library?view=all # from board import D9, D10, SPI, TFT_CS, TFT_DC from digitalio import DigitalInOut, Direction from displayio import Bitmap, Group, Palette, TileGrid, release_displays from fourwire import FourWire import gc from max3421e import Max3421E from micropython import const from supervisor import ticks_ms from usb.core import USBError from terminalio import FONT from time import sleep from adafruit_display_text import bitmap_label import adafruit_imageload from adafruit_st7789 import ST7789 from catapult import Catapult from gamepad import ( XInputGamepad, UP, DOWN, LEFT, RIGHT, START, SELECT, A, B, X, Y) from skeletons import Skeletons from statemachine import StateMachine def handle_input(machine, prev, buttons, repeat): # Respond to gamepad button state change events. # # This function translates from the packed bitfield of gamepad button # states into the state machine's input event constants. If you wanted to # remap the gamepad buttons, or convert this program to use a different # type of gamepad (or keyboard, or mouse, etc), this function would be a # great place to start. If you want to change how the input device works # here, you'll probably also need to make some matching changes in main(). # diff = prev ^ buttons mh = machine.handleGamepad #print(f"{buttons:016b}") if repeat: # Check for hold-time triggered repeating events if (buttons & A): mh(machine.A_HOLD) else: # Check for edge-triggered events if (diff & A) and (buttons & A): # A pressed mh(machine.A_DN) elif (diff & A) and (not (buttons & A)): # A released mh(machine.A_UP) elif (diff & SELECT) and (buttons == SELECT): # SELECT pressed mh(machine.SELECT) elif (diff & START) and (buttons == START): # START pressed mh(machine.START) def elapsed_ms(prev, now): # Calculate elapsed ms between two timestamps from supervisor.ticks_ms(). # # The CircuitPython ticks counter rolls over at 2**29, so this uses a bit # mask of (2**29)-1 = 0x3fffffff for the subtraction. If you want to learn # more about why doing it this way gives the correct result even when the # interval spans a rollover, try reading about "modular arithmetic", # "integer overflow", and "two's complement" arithmetic. # MASK = const(0x3fffffff) return (now - prev) & MASK def main(): # This function has initialization code and the main event loop. Under # normal circumstances, this function does not return. # The Feather TFT defaults to using the built-in display for a console. # So, first, release the default display so we can re-initialize it below. release_displays() gc.collect() # Initialize SPI bus which gets shared by ST7783 (TFT) and Max3421E (USB) spi = SPI() # Initialize ST7789 display with native display size of 240x135px. # IMPORTANT: Note how auto_refresh is set to false. This gives the state # machine and event loop code (see below) more direct control over when the # display refreshes. The point is to minimize SPI bus contention between # the display and the USB host chip, and to hopefully reduce tearing. # TFT_W = const(240) TFT_H = const(135) bus = FourWire(spi, command=TFT_DC, chip_select=TFT_CS) display = ST7789(bus, rotation=270, width=TFT_W, height=TFT_H, rowstart=40, colstart=53, auto_refresh=False) gc.collect() # Load PNG images and put them into TileGrid objects: # This is is the most memory intensive thing in the whole program. Doing # these large heap allocations early, then keeping the objects around for # the the length of the program, helps to avoid memory fragmentation. # gc.collect() # Background image with moon, trees, hill, and grass (bmp0, pal0) = adafruit_imageload.load( "pumpkin-toss-bkgnd.png", bitmap=Bitmap, palette=Palette) bkgnd = TileGrid(bmp0, pixel_shader=pal0) gc.collect() # Title screen overlay gc.collect() (bmp1, pal1) = adafruit_imageload.load( "pumpkin-toss-title.png", bitmap=Bitmap, palette=Palette) x = ((TFT_W // 2) - bmp1.width) // 2 y = ((TFT_H // 2) - bmp1.height) // 2 title_screen = TileGrid(bmp1, pixel_shader=pal1, x=x, y=y) # Shared spritesheet for catapult, pumpkin and skeleton animation cycles (bmp2, pal2) = adafruit_imageload.load( "pumpkin-toss-sprites.png", bitmap=Bitmap, palette=Palette) gc.collect() # Mark background color (black) as transparent pal2.make_transparent(0) # Prepare instances of the Catapult and Skeletons classes using the shared # spritesheet. These objects manage the details of setting TileGrid tiles # to draw animation cycles for sprites. The main reasons for these classes # are: # 1. Have a dedicated spot for the lists of tile numbers that define each # frame of the various animation cycles # 2. Export functions and constants that the state machine can use to # control animations at a higher level of abstraction (without having to # clutter the state machine code with tile numbers from the spritesheet) # The x,y coordinates come from my bkgnd-with-grid.jpeg reference image. # cat = Catapult(bmp2, pal2, x=0, y=25, splat_y=57, chg_x=0, chg_y=8) skels = Skeletons(bmp2, pal2, x0=54, x1=116, y=44) # Make a text label for status messages status = bitmap_label.Label(FONT, text="", color=0xFF8000) status.x = 8 # NOTE: these are 1x coordinates! (sprites use 2x) status.y = 8 # NOTE: these are 1x coordinates! (sprites use 2x) # Arrange all the TileGrids and sub-groups into the root display group. The # sprites and background use 2x scaling (grp2), but the status line goes in # a 1x scaled group (grp1) because the built-in font looks huge at 2x. # grp1 = Group(scale=1) grp2 = Group(scale=2) grp2.append(bkgnd) grp2.append(skels.group()) grp2.append(cat.group()) grp2.append(title_screen) grp1.append(grp2) grp1.append(status) display.root_group = grp1 display.refresh() # This initializes the state machine object, giving it references to the # sprite manager objects (Catapult and Skeletons) and status text label # object. The point of structuring the code this way is to have the state # machine be responsible for higher level timing and sprite behavior, while # the sprite managers take care of low-level details about TileGrid # changes. There's also some subtle memory allocation and data flow stuff # going on here, with the goal of keeping display updates smooth, at a # steady frame rate: # # 1. The sprite manager objects (cat and skels) contain references to # large bitmaps which were loaded above from PNG files. Allocating # these objects early and keeping references to them alive for the whole # length of the program helps to avoid memory fragmentation, flash # access, and pressure on the garbage collector. This should reduce # timing jitter due to memory allocations and garbage collection. # # 2. The state machine causes the sprite manager objects to update TileGrid # tile numbers, but calls to displayio.Display.refresh() only happen # in the event loop, here in the main() function (remember the display # was initialized with auto_refresh=false). This allows several tile # updates for different sprites to happen together in the same animation # frame, with hopefully just one display refresh per frame. # machine = StateMachine(grp2, cat, skels, title_screen, status) # Initialize MAX3421E USB host chip which is needed by usb.core to make # gamepad input work. print("Initializing USB host port...") gc.collect() usbHost = Max3421E(spi, chip_select=D10, irq=D9) gc.collect() sleep(0.1) # Initialize gamepad manager object (see gamepad.py) gp = XInputGamepad() # Gamepad status update strings for debug prints on the serial console and # display status line GP_FIND = 'Finding USB gamepad' GP_READY = 'gamepad ready' GP_ERR1 = 'USB ERR1: bug in code.py?' GP_ERR2 = 'USB ERR2: gamepad unplugged?' # Cache frequently used callables to save time on dictionary name lookups # (this is a standard MicroPython performance boosting trick) _collect = gc.collect _elapsed = elapsed_ms _ms = ticks_ms _refresh = display.refresh # MAIN EVENT LOOP # This sets up a loop to run the following sequence over and over: # # 1. Attempt to poll a USB gamepad for button press inputs # # 2. Check for gamepad input events, and if needed, call the appropriate # state machine input event handler # # 3. Call the state machine's tick() function to update animations and # other timer-controlled state # # 4. If requested by the state machine, refresh the display # # Initialize timers for gamepad button hold detection. DELAY_MS = const(133) # Gamepad button hold delay before repeat (ms) REPEAT_MS = const(133) # Gamepad button interval between repeats (ms) prev_ms = _ms() hold_tmr = 0 repeat_tmr = 0 # OUTER LOOP: try to connect to a USB gamepad. print(GP_FIND) status.text = GP_FIND _refresh() while True: _collect() # Begin by updating the display, even if gamepad is not connected now_ms = _ms() interval = _elapsed(prev_ms, now_ms) if interval >= 16: prev_ms = now_ms # Update animations and display if needed if machine.tick(interval): _refresh() try: # Attempt to connect to USB gamepad if gp.find_and_configure(): status.text = "" # clear the "Finding USB gamepad" status text _refresh() print(gp.device_info_str()) connected = True prev_btn = 0 hold_tmr = 0 repeat_tmr = 0 # INNER LOOP: gamepad is connected, so start polling buttons # # IMPORTANT: gp.poll() here is a generator that polls the # gamepad buttons at the start of each iteration through this # loop. Doing it this way avoids many memory allocations that # would be required to poll using a regular class method call. # The point of this approach is to get a better frame rate with # less of latency and jitter. # for buttons in gp.poll(): # Update A-button timers now_ms = _ms() interval = _elapsed(prev_ms, now_ms) prev_ms = now_ms if buttons & A: hold_tmr += interval repeat_tmr += interval else: hold_tmr = 0 repeat_tmr = 0 # Handle hold-time triggered gamepad input events if hold_tmr >= DELAY_MS: if hold_tmr == repeat_tmr: # First re-trigger event after initial delay repeat_tmr -= DELAY_MS handle_input(machine, prev_btn, buttons, True) elif repeat_tmr >= REPEAT_MS: # Another re-trigger event after repeat interval repeat_tmr -= REPEAT_MS handle_input(machine, prev_btn, buttons, True) # Handle edge-triggered gamepad input events if prev_btn != buttons: handle_input(machine, prev_btn, buttons, False) # Save button values prev_btn = buttons # # --- UPDATE ANIMATIONS & DISPLAY -------------------------- # This part is short but very important. The call to # .tick() below lets the state machine update the animation # cycles for sprites and do whatever other timer-based # things need to be done. You could implement this in a # different way using async, but I prefer it this way. The # advantage of this approach is you can see how the gamepad # polling and state machine updates take turns. # need_refresh = machine.tick(interval) if need_refresh: _refresh() # Doing garbage collection after every refresh makes # the loop run slower. But, it seems to reduce jitter, # making for a smoother frame rate. It's too close to # make an easy call, but this method seems to look # subjectively a little better than other ways I tried. _collect() # --------------------------------------------------------- # # [END OF INNER LOOP] # Making it here means gp.poll() decided to end the loop with a # `return`, which is possible but not normal (see gamepad.py). print(GP_ERR1) print(GP_FIND) status.text = GP_ERR1 _refresh() else: # Making it here means no gamepad is connected, and when # gp.find_and_configure() looked, it did not find one. This # normal and often happens at boot time because it takes a # while for all the USB stuff to initialize. # # Since there is no gamepad yet, wait a bit, then try again. # sleep(0.1) except USBError as e: # Making it here means there was a USBError exception during a call # to gp.find_and_configure() or gp.poll(). # # This is normal when someone unplugs the gamepad. When that # happens, it's usually possible to reconnect without resetting # CircuitPython. But, sometimes, more serious and mysterious # USBError exceptions happen and usb.core gets confused. In that # case, further calls to find_and_configure() don't work until # after resetting the board. # # So, hope for the best, log the error, and stay in the outer loop # so it can attempt to find a gamepad. # print(GP_ERR2) print(GP_FIND) status.text = GP_ERR2 _refresh() main()