1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266

# 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 | Adalogger          |
# | ----------- | -------- | ---------- | ------------------ |
# |  SCK        |  SCK     |            | SCK (SD)           |
# |  MOSI       |  MOSI    |            | MOSI (SD)          |
# |  MISO       |  MISO    |            | MISO (SD)          |
# |  SDA        |          |            | SDA (RTC)          |
# |  SCL        |          |            | SCL (RTC)          |
# |  D9         |  IRQ     |            |                    |
# |  D10        |  CS      |            | (Not SDCS!)        |
# |  D11        |          |            | SDCS (wire jumper) |
# |  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://learn.adafruit.com/adafruit-adalogger-featherwing/rtc-with-circuitpython
# - https://docs.circuitpython.org/en/latest/shared-bindings/time/index.html
#
from board import D9, D10, D11, I2C, 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 time import sleep, struct_time
from usb.core import USBError

from adafruit_pcf8523 import PCF8523
from adafruit_st7789 import ST7789
from charlcd import CharLCD
from gamepad import (
    XInputGamepad, UP, DOWN, LEFT, RIGHT, START, SELECT, A, B, X, Y)
from sevenseg import SevenSeg
from statemachine import StateMachine


def handle_input(machine, prev, buttons, repeat):
    # Respond to gamepad button state change events
    diff = prev ^  buttons
    mh = machine.handleGamepad
    #print(f"{buttons:016b}")

    if repeat:
        # Check for hold-time triggered repeating events
        if (buttons == UP):        # UP held
            mh(machine.UP, True)
        elif (buttons == DOWN):    # DOWN held
            mh(machine.DOWN, True)
    else:
        # Check for edge-triggered events
        if (diff & A) and (buttons == A):  # A pressed
            mh(machine.A, False)
        elif (diff & B) and (buttons == B):  # B pressed
            mh(machine.B, False)
        elif (diff & UP) and (buttons == UP):  # UP pressed
            mh(machine.UP, False)
        elif (diff & DOWN) and (buttons == DOWN):  # DOWN pressed
            mh(machine.DOWN, repeat)
        elif (diff & LEFT) and (buttons == LEFT):  # LEFT pressed
            mh(machine.LEFT, False)
        elif (diff & RIGHT) and (buttons == RIGHT):  # RIGHT pressed
            mh(machine.RIGHT, False)
        elif (diff & START) and (buttons == START):  # START pressed
            mh(machine.START, False)


def elapsed_ms(prev, now):
    # Calculate elapsed ms between two timestamps from supervisor.ticks_ms().
    # The ticks counter rolls over at 2**29, and (2**29)-1 = 0x3fffffff
    MASK = const(0x3fffffff)
    return (now - prev) & MASK


def main():
    release_displays()
    gc.collect()
    spi = SPI()

    # Initialize ST7789 display with native display size of 240x135px.
    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()
    # Set up the 5 digit/dots sprites to build a 7-segment time display
    # Each sprite is 5*8px wide by 6*8 px high (= 40x48px).

    # Configure the character display areas at top and bottom of screen.
    # This uses a 6x8 px spritesheet font for ASCII characters (32..127).
    SCALE = 2
    PAD = 2
    COLS = 20
    Y1 = (TFT_H // SCALE) - 8 - PAD
    charLCD = CharLCD(cols=COLS, x=0, y0=PAD, y1=Y1, scale=SCALE)
    gc.collect()

    # Configure the 7-segment clock digits display area in the center of the
    # screen. There are eight 7-segment sprites, and each sprite is 30px wide by
    # 50px high.
    X = (TFT_W - (8 * 30)) // 2
    Y = (TFT_H - 50) // 2
    digits = SevenSeg(x=X, y=Y)
    gc.collect()

    # Add the TileGrids to the display's root group
    gc.collect()
    grp = Group(scale=1)
    grp.append(charLCD.group())
    grp.append(digits.group())
    display.root_group = grp
    display.refresh()

    # Initialize MAX3421E USB host chip which is needed by usb.core.
    # The link between usb.core and Max3421E happens by way of invisible
    # magic in the CircuitPython core, kinda like with displayio displays.
    print("Initializing USB host port...")
    gc.collect()
    usbHost = Max3421E(spi, chip_select=D10, irq=D9)
    gc.collect()
    sleep(0.1)

    # Initialize RTC
    rtc = PCF8523.PCF8523(I2C())
    gc.collect()
    # Example, reset time to 2024-09-14 01:23:45:
    # rtc.datetime = struct_time((2024, 9, 14, 1, 23, 45, 0, -1, -1))

    # Initialize State Machine
    machine = StateMachine(digits, charLCD, rtc)

    # Gamepad status update strings
    GP_FIND   = 'Finding USB gamepad'
    GP_READY  = 'gamepad ready'
    GP_DISCON = 'gamepad disconnected'
    GP_ERR    = 'gamepad connection error'

    # Cache frequently used callables to save time on dictionary name lookups
    # NOTE: rtc.datetime is a property, so we can't cache it here!
    _collect = gc.collect
    _elapsed = elapsed_ms
    _ms = ticks_ms
    _refresh = display.refresh
    _setMsg = charLCD.setMsg
    _updateDigits = machine.updateDigits

    # Read RTC time and update display digits
    prevST = rtc.datetime
    _updateDigits(prevST)

    # MAIN EVENT LOOP
    # Establish and maintain a gamepad connection
    gp = XInputGamepad()
    print(GP_FIND)
    _setMsg(GP_FIND, top=False)
    _refresh()
    need_refresh = False
    # OUTER LOOP: Update clock and try to connect to a USB gamepad.
    # Start timers for RTC polling and gamepad button hold detection. The point
    # the RTC timer is to avoid burning unecessary clock cycles waiting for the
    # I2C bus, which is slow.
    RTC_MS    = const(100)  # RTC poll interval (ms)
    DELAY_MS  = const(900)  # Gamepad button hold delay before repeat (ms)
    REPEAT_MS = const(300)  # Gamepad button interval between repeats (ms)
    prev_ms = _ms()
    rtc_ms = 0
    hold_tmr = 0
    repeat_tmr = 0
    while True:
        _collect()
        now_ms = _ms()
        if need_refresh or (_elapsed(rtc_ms, now_ms) >= RTC_MS):
            # Check clock (RTC) and update time display if needed
            rtc_ms = now_ms
            nowST = rtc.datetime
            if need_refresh or (nowST != prevST):
                prevST = nowST
                _updateDigits(prevST)
                _refresh()
                need_refresh = False
        try:
            # Attempt to connect to USB gamepad
            if gp.find_and_configure():
                print(gp.device_info_str())
                connected = True
                _setMsg(GP_READY, top=False)
                _refresh()
                # INNER LOOP: Update clock and poll gamepad for button events
                prev_btn = 0
                hold_tmr = 0
                repeat_tmr = 0
                for buttons in gp.poll():
                    # Update timers
                    now_ms = _ms()
                    interval = _elapsed(prev_ms, now_ms)
                    prev_ms = now_ms
                    if buttons == 0:
                        hold_tmr = 0
                        repeat_tmr = 0
                    elif prev_btn != buttons:
                        hold_tmr = 0
                        repeat_tmr = 0
                    else:
                        hold_tmr += interval
                        repeat_tmr += interval
                    # Check RTC and update display if needed
                    if need_refresh or (_elapsed(rtc_ms, now_ms) >= RTC_MS):
                        rtc_ms = now_ms
                        nowST = rtc.datetime
                        if need_refresh or (nowST != prevST):
                            prevST = nowST
                            _updateDigits(prevST)
                            _refresh()
                            _collect()
                            need_refresh = False
                    # 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)
                            need_refresh = True
                        elif repeat_tmr >= REPEAT_MS:
                            # Another re-trigger event after repeat interval
                            repeat_tmr -= REPEAT_MS
                            handle_input(machine, prev_btn, buttons, True)
                            need_refresh = True
                    # Handle edge-triggered gamepad input events
                    if prev_btn != buttons:
                        handle_input(machine, prev_btn, buttons, False)
                        need_refresh = True
                    # Save button values
                    prev_btn = buttons
                # If loop stopped, gamepad connection was lost
                print(GP_DISCON)
                print(GP_FIND)
                _setMsg(GP_FIND, top=False)
                _refresh()
            else:
                # No connection yet, so sleep briefly then try again
                sleep(0.1)
        except USBError as e:
            # This might mean gamepad was unplugged, or maybe some other
            # low-level USB thing happened which this driver does not yet
            # know how to deal with. So, log the error and keep going
            print(e)
            print(GP_ERR)
            print(GP_FIND)
            _setMsg(GP_FIND, top=False)
            _refresh()


main()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

# SPDX-License-Identifier: MIT
# SPDX-FileCopyrightText: Copyright 2024 Sam Blenny
#
from displayio import Bitmap, Group, Palette, TileGrid
import gc
from micropython import const

import adafruit_imageload


class CharLCD:
    # Simulate a dot matrix character LCD using sprites

    def __init__(self, cols=8, x=0, y0=0, y1=32, scale=2):
        # Args:
        # -  cols: number of columns (monospace characters) in the display
        # -     x: x coordinate of both lines' top-left corners
        # -    y0: y coordinate of top line's top-left corner
        # -    y1: y coordinate of bottom lines's top-left corner
        # - scale: scaling factor for the font (scale=2 means 2x zoom)
        self.cols = cols
        # Load font spritesheet into Bitmap and Palette objects
        gc.collect()
        (bmp, pal) = adafruit_imageload.load(
            "ascii-font.bmp", bitmap=Bitmap, palette=Palette)
        gc.collect()
        # Make a Group with TileGrids for the top line, with top left corner at
        # (x0, y0), and the bottom line, with top left corner at (x1, y1)
        tg0 = TileGrid(
            bmp, pixel_shader=pal, width=cols, height=1,
            tile_width=6, tile_height=8, x=x, y=y0, default_tile=0)
        gc.collect()
        tg1 = TileGrid(
            bmp, pixel_shader=pal, width=cols, height=1,
            tile_width=6, tile_height=8, x=x, y=y1, default_tile=0)
        gc.collect()
        self.tg0 = tg0
        self.tg1 = tg1
        g = Group(scale=scale)
        g.append(tg0)
        g.append(tg1)
        self.grp = g

    def group(self):
        return self.grp

    def setMsg(self, msg, top=True):
        # Show message left-aligned on the top or bottom character LCD.
        # - msg: string or bytes (should have ASCII chars in range 32..127)
        # - top: True: show msg on top line; False: show msg on bottom line
        #
        ASCII_SPACE = const(32)  # first sprite: space (blank rectangle)
        ASCII_DEL = const(127)   # last sprite: DEL (up/down arrows)
        _tg = self.tg0 if top else self.tg1
        _cols = self.cols

        # Set sprites for characters of the message (max length = self.cols)
        for (i, char) in zip(range(_cols), msg):
            # Convert the character to a sprite number and update the TileGrid
            n = char if (type(char) == int) else ord(char)
            if (n < ASCII_SPACE) or (ASCII_DEL < n):
                n = ord('?')  # Replace out of range chars with '?'
            # Change sprite if current value differs from previous value
            sprite = n - 32      # spritesheet starts at ' ', so subtract 32
            if _tg[i] != sprite:
                _tg[i] = sprite

        # Clear right padding area with space characters
        for i in range(len(msg), _cols):
            if _tg[i] != 0:
                _tg[i] = 0   # spritesheet starts at ' ', so 0 is space

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

# SPDX-License-Identifier: MIT
# SPDX-FileCopyrightText: Copyright 2024 Sam Blenny
#
from displayio import Bitmap, Group, Palette, TileGrid
import gc
from micropython import const

import adafruit_imageload


class SevenSeg:
    # Simulate a 7-segment LED clock display using sprites

    def __init__(self, x=0, y=0, cols=8):
        # Args:
        # - x: x coordinate of first digit's top-left corner
        # - y: y coordinate of top line's top-left corner
        # Load font spritesheet into Bitmap and Palette objects
        #
        # CAUTION 1: This uses adafruit_imageload.load() with a PNG file, and
        # the PNG loader currently has a bug where sprites are misaligned by
        # one pixel. (https://github.com/adafruit/circuitpython/issues/9587 )
        # To work around the bug, I made the spritesheet with 1 pixel of
        # vertical padding above and below the important area of each digit.
        #
        # CAUTION 2: When I tried this spritesheet with a BMP file, the image
        # loaded without any exceptions, but the resulting bitmap was badly
        # glitched (rows were skewed, colors were wrong, etc). The BMP file was
        # about 14KB, so maybe it overflowed a buffer or something? Not sure.
        #
        gc.collect()
        (bmp, pal) = adafruit_imageload.load(
            "digit-sprites.png", bitmap=Bitmap, palette=Palette)
        gc.collect()
        # Make a Group with TileGrids with top left corner at (x, y)
        tg = TileGrid(
            bmp, pixel_shader=pal, width=cols, height=1,
            tile_width=30, tile_height=50, x=x, y=y, default_tile=12)
        gc.collect()
        self.tg = tg
        self.cols = cols
        g = Group(scale=1)
        g.append(tg)
        self.grp = g

    def group(self):
        return self.grp

    def setDigits(self, digits):
        # Show message left-aligned on the top or bottom character LCD.
        # - digits: string or bytes in the set: "0123456789: "
        #
        ASCII_SPACE = const(32)
        ASCII_DASH  = const(45)
        ASCII_ZERO  = const(48)
        ASCII_COLON = const(58)  # conveniently, ASCII ":" is right after "9"!
        _DASH_SPRITE  = const(11)
        _SPACE_SPRITE = const(12)
        _tg = self.tg
        _cols = self.cols

        # Set sprites for characters of the message (max length = self.cols)
        for (i, char) in zip(range(_cols), digits):
            # Convert the character to a sprite number and update the TileGrid
            n = char if (type(char) == int) else ord(char)
            sprite = _SPACE_SPRITE                        # default: ' '
            if (ASCII_ZERO <= n) and (n <= ASCII_COLON):  # '0'..'9' and ':'
                sprite = n - ASCII_ZERO
            elif n == ASCII_DASH:                         # '-'
                sprite = _DASH_SPRITE
            if _tg[i] != sprite:         # Avoid triggering redundant repaints
                _tg[i] = sprite

        # Clear right padding area with space characters
        for i in range(len(digits), _cols):
            if _tg[i] != _SPACE_SPRITE:
                _tg[i] = _SPACE_SPRITE

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240

# SPDX-License-Identifier: MIT
# SPDX-FileCopyrightText: Copyright 2024 Sam Blenny
#
# Table of states and state transitions:
#
# | State   | UP     | DOWN   | LEFT    | RIGHT   | A       | B    | START   |
# | ------- | ------ | ------ | ------- | ------- | ------- | ---- | ------- |
# | hhmm    | nop    | nop    | mmss    | mmss    | nop     | hhmm | setHMin |
# | mmss    | nop    | nop    | hhmm    | hhmm    | nop     | hhmm | setHMin |
# | setYr   | year+1 | year-1 | setSec  | setMDay | setMDay | hhmm | hhmm    |
# | setMDay | day+1  | day-1  | setYr   | setHour | setHour | hhmm | hhmm    |
# | setHour | hour+1 | hour-1 | setMDay | setHMin | setHMin | hhmm | hhmm    |
# | setHMin | min+1  | min-1  | setHour | setSec  | setSec  | hhmm | hhmm    |
# | setSec  | sec=0  | sec=0  | setHMin | setYr   | setYr   | hhmm | hhmm    |
#
# Related documentation:
# - https://docs.circuitpython.org/projects/datetime/en/latest/api.html
# - https://docs.circuitpython.org/en/latest/shared-bindings/time/index.html#time.mktime
#
from micropython import const
from time import mktime

from adafruit_datetime import datetime, timedelta


# State Transition Constants (private)
# CAUTION: These values must match row indexes of StateMachine.TABLE
_HHMM    = const(0)
_MMSS    = const(1)
_SetYr   = const(2)
_SetMDay = const(3)
_SetHour = const(4)
_SetHMin = const(5)
_SetSec  = const(6)

# Action Constants (private)
_NOP    = const(7)
_YrInc  = const(8)
_YrDec  = const(9)
_DayInc = const(10)
_DayDec = const(11)
_HrInc  = const(12)
_HrDec  = const(13)
_MinInc = const(14)
_MinDec = const(15)
_Sec00  = const(16)


class StateMachine:

    # Button Press Constants (public)
    # CAUTION: These values must match column indexes of StateMachine.TABLE
    UP    = const(0)
    DOWN  = const(1)
    LEFT  = const(2)
    RIGHT = const(3)
    A     = const(4)
    B     = const(5)
    START = const(6)

    # LookUp Table (private) of actions (including NOP and state transitions)
    # for possible button press events in each of the possible states. NOP is
    # short for "No OPeration", and it means to do nothing.
    _TABLE = (
        # UP      DOWN     LEFT      RIGHT     A         B      START       State
        (_NOP,    _NOP,    _MMSS,    _MMSS,    _NOP,     _HHMM, _SetHMin),  # hhmm
        (_NOP,    _NOP,    _HHMM,    _HHMM,    _NOP,     _HHMM, _SetHMin),  # mmss
        (_YrInc,  _YrDec,  _SetSec,  _SetMDay, _SetMDay, _HHMM, _HHMM   ),  # setYr
        (_DayInc, _DayDec, _SetYr,   _SetHour, _SetHour, _HHMM, _HHMM   ),  # setMDay
        (_HrInc,  _HrDec,  _SetMDay, _SetHMin, _SetHMin, _HHMM, _HHMM   ),  # setHour
        (_MinInc, _MinDec, _SetHour, _SetSec,  _SetSec,  _HHMM, _HHMM   ),  # setHMin
        (_Sec00,  _Sec00,  _SetHMin, _SetYr,   _SetYr,   _HHMM, _HHMM   ),  # setSec
    )

    def __init__(self, digits, charLCD, rtc):
        # Save references to character LCD display, digits display, and RTC
        self.digits = digits
        self.charLCD = charLCD
        self.rtc = rtc
        # Start in the state for Clock Mode with hours and minutes sub-mode
        self.state = _HHMM

    def updateDigits(self, st):
        # Update clock digits from current state and struct_time object, st.
        # struct_time(tm_year, tm_mon, tm_mday, tm_hour, tm_min, tm_sec,
        #     tm_wday, tm_yday, tm_isdst)
        _setD = self.digits.setDigits
        _setM = self.charLCD.setMsg
        s = self.state
        if (s == _HHMM):
            # Simple clock like, "12:00"
            _setD('  %02d:%02d' % (st.tm_hour, st.tm_min))
        elif (s == _MMSS):
            # Full date and time like, "2024-09-12 12:00:01"
            _setM('%04d-%02d-%02d' % (st.tm_year, st.tm_mon, st.tm_mday))
            _setD('%02d:%02d:%02d' % (st.tm_hour, st.tm_min, st.tm_sec))
        elif (s == _SetHour) or (s == _SetHMin) or (s == _SetSec):
            # for setting hours, minutes, or seconds like, "12:00:01"
            _setD('%02d:%02d:%02d' % (st.tm_hour, st.tm_min, st.tm_sec))
        elif (s == _SetYr):
            # for setting the year
            _setD('   %04d' % (st.tm_year))
        elif (s == _SetMDay):
            # for setting the month and day
            _setD('  %02d-%02d' % (st.tm_mon, st.tm_mday))

    def handleGamepad(self, button, repeat):
        # Handle a button press event
        # args:
        # - button: one of the button constants
        # - repeat: True if this is a hold-time triggered repeating event

        # Check lookup table for the response code for this button event
        if button < UP or button > START:
            print("Button value out of range:", button)
            return
        r = self._TABLE[self.state][button]

        # Cache frequently used names to reduce time used by dictionary lookups
        _rtc = self.rtc
        _setM = self.charLCD.setMsg
        _fromtimestamp = datetime.fromtimestamp

        # The help message for Set Mode uses a special up/down arrows sprite
        # that is mapped in the sprite sheet to ASCII DEL (0x7f)
        SET_HELP     = b"\x7f:+/-  B:Exit  A:OK"
        SET_HELP_SEC = b"\x7f:=00  B:Exit  A:OK"

        # Handle the response code
        # First, check for state transition codes
        if r == _HHMM:
            self.state = r
            _setM(b'')
            _setM(b'', top=False)
        elif r == _MMSS:
            self.state = r
            _setM(b'')
            _setM(b'', top=False)
        elif r == _SetYr:
            self.state = r
            _setM(b'   SET       YEAR')
            _setM(SET_HELP, top=False)
        elif r == _SetMDay:
            self.state = r
            _setM(b'   SET  MONTH-DAY')
            _setM(SET_HELP, top=False)
        elif r == _SetHour:
            self.state = r
            _setM(b'   SET       HOUR')
            _setM(SET_HELP, top=False)
        elif r == _SetHMin:
            self.state = r
            _setM(b'   SET    MINUTES')
            _setM(SET_HELP, top=False)
        elif r == _SetSec:
            self.state = r
            _setM(b'   SET    SECONDS')
            _setM(SET_HELP_SEC, top=False)

        # Second, check for action codes that don't change the state
        elif r == _NOP:
            return

        # Third, check for action codes that modify the RTC date or time
        else:
            # To avoid surprising things like unintentionally changing the day
            # when you're trying to set the minutes (e.g. crossing midnight),
            # we need a struct_time object. But, to do math with time deltas in
            # a way that accounts for leap years, days per month, etc., we need
            # a datetime object. So, make both:
            st = _rtc.datetime                  # struct_time
            now = _fromtimestamp(mktime(st))    # datetime
            # Unpack the struct_time with shorter names
            (year, month, day) = (st.tm_year, st.tm_mon, st.tm_mday)
            (hour, min_, sec) = (st.tm_hour, st.tm_min, st.tm_sec)

            if r == _YrInc:
                # Increment Year
                n = 5 if repeat else 1
                if year + n > 2037:
                    # Don't go above 2037 because attempting to do so causes
                    # a CircuitPython long int overflow error. Note that
                    # 19 January 2038 is the Unix time 32-bit overflow date.
                    # see https://en.wikipedia.org/wiki/Year_2038_problem
                    n = 2037 - year
                _rtc.datetime = (now + timedelta(days=(n*365))).timetuple()
            elif r == _YrDec:
                # Decrement Year
                n = -5 if repeat else -1
                if year + n < 2001:
                    # Don't go below 2001 because adafruit_pcf8523 doesn't like
                    # years below 2000
                    n = 2001 - year
                _rtc.datetime = (now + timedelta(days=(n*365))).timetuple()
            elif r == _DayInc:
                # Increment Day
                n = 10 if repeat else 1
                if (month == 12) and (day + n > 31):
                    # Do not go past December 31 (avoid changing year)
                    n = 31 - day
                _rtc.datetime = (now + timedelta(days=n)).timetuple()
            elif r == _DayDec:
                # Decrement Day
                n = -10 if repeat else -1
                if (month == 1) and (day + n < 1):
                    # Do not go past January 1 (avoid changing year)
                    n = 1 - day
                _rtc.datetime = (now + timedelta(days=n)).timetuple()
            elif r == _HrInc:
                # Increment Hour
                n = 4 if repeat else 1
                if hour + n > 23:
                    # Do not go past 23:xx (avoid changing day)
                    n = 23 - hour
                _rtc.datetime = (now + timedelta(hours=n)).timetuple()
            elif r == _HrDec:
                # Decrement Hour
                n = -4 if repeat else -1
                if hour + n < 0:
                    # Do not go past 00:xx (avoid changing day)
                    n = 0 - hour
                _rtc.datetime = (now + timedelta(hours=n)).timetuple()
            elif r == _MinInc:
                # Increment Minute
                n = 10 if repeat else 1
                if (hour == 23) and (min_ + n > 59):
                    # Do not go past 23:59 (avoid changing day)
                    n = 59 - min_
                _rtc.datetime = (now + timedelta(minutes=n)).timetuple()
            elif r == _MinDec:
                # Decrement Minute
                n = -10 if repeat else -1
                if (hour == 0) and (min_ + n < 0):
                    # Do not go past 00:00 (avoid changing day)
                    n = 00 - min_
                _rtc.datetime = (now + timedelta(minutes=n)).timetuple()
            elif r == _Sec00:
                # Round seconds to nearest minute
                delta = -(sec) if (sec <= 30) else (60-sec)
                _rtc.datetime = (now + timedelta(seconds=delta)).timetuple()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161

# SPDX-License-Identifier: MIT
# SPDX-FileCopyrightText: Copyright 2024 Sam Blenny
#
# Gamepad driver for XInput compatible USB wired gamepad with MAX421E.
#
# The button names used here match the Nintendo SNES style button
# cluster layout, but the USB IDs and protocol match the Xbox 360 USB
# wired controller. This is meant to work with widely available USB
# wired xinput compatible gamepads for the retrogaming market. In
# particular, I tested this package using my 8BitDo SN30 Pro USB wired
# gamepad.
#
# CAUTION: If you try to use a USB adapter with a wireless xinput
# compatible gamepad, it probably won't work with this driver in its
# current form. In my testing, compared to wired gamepads, USB wireless
# adapters have extra delays and errors that require retries and
# low-level error handling. I haven't been able to get a USB wireless
# gamepad adapter working yet in CircuitPython yet.
#
from micropython import const
from struct import unpack
from time import sleep
from usb import core
from usb.core import USBError


# Gamepad button bitmask constants
UP     = const(0x0001)  # dpad: Up
DOWN   = const(0x0002)  # dpad: Down
LEFT   = const(0x0004)  # dpad: Left
RIGHT  = const(0x0008)  # dpad: Right
START  = const(0x0010)
SELECT = const(0x0020)
L      = const(0x0100)  # Left shoulder button
R      = const(0x0200)  # Right shoulder button
B      = const(0x1000)  # button cluster: bottom button (Nintendo B, Xbox A)
A      = const(0x2000)  # button cluster: right button  (Nintendo A, Xbox B)
Y      = const(0x4000)  # button cluster: left button   (Nintendo Y, Xbox X)
X      = const(0x8000)  # button cluster: top button    (Nintendo X, Xbox Y)

class XInputGamepad:

    # Constants for USB device IO
    _INTERFACE  = const(0)
    _TIMEOUT_MS = const(5)
    _ENDPOINT   = const(0x81)

    def __init__(self):
        # Initialize buffer used in polling USB gamepad events
        self.buf64 = bytearray(64)
        # Variable to hold the gamepad's usb.core.Device object
        self.device = None

    def find_and_configure(self):
        # Connect to a USB wired Xbox 360 style gamepad (vid:pid=045e:028e)
        #
        # Returns: True = success, False = device not found or config failed
        # Exceptions: may raise usb.core.USBError or usb.core.USBTimeoutError
        #
        device = core.find(idVendor=0x045e, idProduct=0x028e)
        sleep(0.1)
        if device:
            self._configure(device)  # may raise usb.core.USBError
            return True              # end retry loop
        else:
            # No gamepad was found
            self.reset()
            return False

    def _configure(self, device):
        # Prepare USB gamepad for use (set configuration, drain buffer, etc)
        #
        # Exceptions: may raise usb.core.USBError or usb.core.USBTimeoutError
        #
        try:
            # Make sure CircuitPython core is not claiming the device
            if device.is_kernel_driver_active(_INTERFACE):
                device.detach_kernel_driver(_INTERFACE)
            # Make sure that configuration is set
            device.set_configuration()
        except USBError as e:
            self.reset()
            raise e
        # Initial reads may give old data, so drain gamepad's buffer. This
        # may raise an exception (with no string description nor errno!)
        # when buffer is already empty. If that happens, ignore it.
        try:
            sleep(0.1)
            for _ in range(8):
                __ = device.read(0x81, self.buf64, timeout=_TIMEOUT_MS)
        except USBError as e:
            if e.errno is None:
                pass  # this is okay
            else:
                self.reset()
                raise e
        # All good, so save a reference to the device object
        self.device = device

    def poll(self):
        # Generator to poll gamepad for button changes (ignore sticks/triggers)
        # Yields:
        #   buttons: Uint16 containing bitfield of individual button values
        # Exceptions: may raise usb.core.USBError or usb.core.USBTimeoutError
        #
        # This generator is meant to be used with a `for` loop. The point is to
        # allow for faster polling by reducing the Python VM overhead spent on
        # memory allocation, method calls, and dictionary lookups. To read more
        # about generators, see https://peps.python.org/pep-0255/
        #
        # Expected endpoint 0x81 report format:
        #  bytes 0,1:    prefix that doesn't change      [ignored]
        #  bytes 2,3:    button bitfield for dpad, ABXY, etc (uint16)
        #  byte  4:      L2 left trigger (analog uint8)  [ignored]
        #  byte  5:      R2 right trigger (analog uint8) [ignored]
        #  bytes 6,7:    LX left stick X axis (int16)    [ignored]
        #  bytes 8,9:    LY left stick Y axis (int16)    [ignored]
        #  bytes 10,11:  RX right stick X axis (int16)   [ignored]
        #  bytes 12,13:  RY right stick Y axis (int16)   [ignored]
        #  bytes 14..19: ???, but they don't change
        #
        if self.device is None:
            # Caller is trying to poll buttons when gamepad is not connected
            return
        # Caching frequently used objects saves time on dictionary name lookups
        _devread = self.device.read
        _buf = self.buf64
        _unpack = unpack
        # Generator loop (note how this uses yield instead of return)
        prev = 0
        while True:
            try:
                # Poll gamepad endpoint to get button and joystick status bytes
                n = _devread(_ENDPOINT, _buf, timeout=_TIMEOUT_MS)
                if n < 14:
                    # skip unexpected responses (too short to be a full report)
                    yield prev
                # Only bytes 2 and 3 are interesting (ignore sticks/triggers)
                (buttons,) = _unpack('<H', self.buf64[2:4])
                prev = buttons
                yield buttons
            except USBError as e:
                self.reset()
                raise e

    def device_info_str(self):
        # Return string describing gamepad device (or lack thereof)
        d = self.device
        if d is None:
            return "[Gamepad not connected]"
        (v, pi, pr, m) = (d.idVendor, d.idProduct, d.product, d.manufacturer)
        if (v is None) or (pi is None):
            # Sometimes the usb.core or Max3421E will return 0000:0000 for
            # reasons that I do not understand
            return "[bad vid:pid]"
        else:
            return "Connected: %04x:%04x prod='%s' mfg='%s'" % (v, pi, pr, m)

    def reset(self):
        # Reset USB device and gamepad button polling state
        self.device = None