Bug Report: alarm.pin.PinAlarm Mis-maps to Incorrect Pins on ESP32 Feather

[keen101]

Bug Report: alarm.pin.PinAlarm Mis-maps to Incorrect Pins on ESP32 Feather
Description

alarm.pin.PinAlarm consistently fails to wake the board on the configured pin. Instead, it wakes up on a completely different, incorrect, and seemingly random pin. This behavior has been observed with multiple confirmed RTC-capable GPIOs and appears to be a fundamental bug in the core alarm module's handling of the PinAlarm configuration.

Board Information

Board Name: Adafruit Feather HUZZAH32 with ESP32 (identified via serial console)

CircuitPython Version: 9.2.8 on 2025-05-28

CircuitPython Build: CircuitPython for the Adafruit Feather HUZZAH32 with ESP32

Hardware Setup

Adafruit Feather HUZZAH32 with ESP32

Adafruit Adalogger FeatherWing (with PCF8523 RTC) and microSD card inserted.

A wire connected from the INT pin on the Adalogger FeatherWing to the specified GPIO on the Feather board.

No other connections were made to the tested pins. The RTC INT output is an open-drain, active-low signal.

Reproduction Steps

Flash the above-mentioned CircuitPython firmware to the board.

Connect a wire from the Adalogger FeatherWing INT pin to the GPIO pin to be tested.

Upload the provided code.py to the board, ensuring the RTC_INTERRUPT_PIN constant is set to the correct pin.

Open the serial console to monitor the output.

Observe the wake-up behavior after the board enters deep sleep.

Expected Behavior

The board should wake up from deep sleep, and the alarm.wake_alarm.pin should report the exact pin that was configured in the alarm.pin.PinAlarm call.

Actual Behavior (Examples)

In all three tests, the PinAlarm wakes the board on a different pin.

Test 1: Configured GPIO32

Configured Pin: microcontroller.pin.GPIO32 (board.D32)

Actual Wakeup Pin: microcontroller.pin.GPIO9

Serial Output (from user's earlier test):

Board woke up! Wake reason: PinAlarm on microcontroller.pin.GPIO9 (RTC INT)
MISMATCH: Configured for board.D32, but woke up on microcontroller.pin.GPIO9!
Test 2: Configured GPIO27

Configured Pin: microcontroller.pin.GPIO27 (board.D27)

Actual Wakeup Pin: board.TX (microcontroller.pin.GPIO1)

Serial Output (from user's full log):

...
Adalogger PCF8523 RTC found and initialized.

---

Board woke up! Wake reason: PinAlarm on board.TX (RTC INT)
  MISMATCH: Configured for board.D27, but woke up on board.TX!
Current RTC time: 2025-07-17 23:03:56
RTC reports it lost power! Time will need to be set.

---

Wake Count: 1
Current Mode: INITIAL_FREQUENT_WAKEUPS
...
Test 3: Configured GPIO4

Configured Pin: microcontroller.pin.GPIO4 (board.A5)

Actual Wakeup Pin: microcontroller.pin.GPIO10

Serial Output (from user's full log):

...
Adalogger PCF8523 RTC found and initialized.

---

Board woke up! Wake reason: PinAlarm on microcontroller.pin.GPIO10 (RTC INT)
  MISMATCH: Configured for board.A5, but woke up on microcontroller.pin.GPIO10!
Current RTC time: 2025-07-17 23:10:58
RTC reports it lost power! Time will need to be set.

---

Wake Count: 2
Current Mode: INITIAL_FREQUENT_WAKEUPS
...
Code to Reproduce

Python

import board
import digitalio
import time
import microcontroller
import busio
from adafruit_pcf8523.pcf8523 import PCF8523
import adafruit_datetime as datetime
import alarm

# --- Configuration ---
# Change this to GPIO32, GPIO27, or GPIO4 for testing
# Example: RTC_INTERRUPT_PIN = microcontroller.pin.GPIO27
RTC_INTERRUPT_PIN = microcontroller.pin.GPIO4

INITIAL_DEEP_SLEEP_SECONDS = 5
INITIAL_FREQUENT_WAKEUPS_COUNT = 3

NORMAL_ULP_TIMER_BACKUP_SECONDS = 75
RTC_ALARM_INTERVAL_SECONDS = 60 

# --- Onboard LED Setup ---
try:
    led = digitalio.DigitalInOut(board.LED)
except AttributeError:
    try:
        led = digitalio.DigitalInOut(board.GPIO13)
    except AttributeError:
        while True:
            time.sleep(1)
led.direction = digitalio.Direction.OUTPUT

# Explicitly define GPIO3 (RX) and GPIO1 (TX) for control
try:
    gpio3_rx = digitalio.DigitalInOut(microcontroller.pin.GPIO3)
    gpio3_rx.direction = digitalio.Direction.INPUT
    gpio3_rx.pull = digitalio.Pull.UP
except Exception:
    gpio3_rx = None
try:
    gpio1_tx = digitalio.DigitalInOut(microcontroller.pin.GPIO1)
    gpio1_tx.direction = digitalio.Direction.INPUT
    gpio1_tx.pull = digitalio.Pull.UP
except Exception:
    gpio1_tx = None

def run_blink_code(num_blinks=3, blink_duration=0.2):
    for i in range(num_blinks):
        led.value = True
        time.sleep(blink_duration)
        led.value = False
        time.sleep(blink_duration)

# --- RTC Setup (for Adalogger FeatherWing with PCF8523) ---
try:
    i2c = busio.I2C(board.SCL, board.SDA)
    rtc = PCF8523(i2c)
except Exception:
    rtc = None

# --- Main Program Logic ---
wake_alarm = alarm.wake_alarm
if wake_alarm:
    if isinstance(wake_alarm, alarm.pin.PinAlarm):
        actual_wake_pin = wake_alarm.pin
    
try:
    if len(alarm.sleep_memory) < 1:
        alarm.sleep_memory = bytearray(1)
    wake_count = alarm.sleep_memory[0]
except Exception:
    wake_count = 0

if wake_count < INITIAL_FREQUENT_WAKEUPS_COUNT:
    current_mode = "INITIAL_FREQUENT_WAKEUPS"
    sleep_duration_seconds = INITIAL_DEEP_SLEEP_SECONDS
else:
    current_mode = "NORMAL_OPERATION"
    sleep_duration_seconds = NORMAL_ULP_TIMER_BACKUP_SECONDS

if current_mode == "INITIAL_FREQUENT_WAKEUPS":
    run_blink_code(num_blinks=1, blink_duration=0.2)
elif current_mode == "NORMAL_OPERATION":
    run_blink_code(num_blinks=3, blink_duration=0.2)

# --- Configure Wakeup Sources ---
alarms_to_set = []
ulp_timer_alarm = alarm.time.TimeAlarm(monotonic_time=time.monotonic() + sleep_duration_seconds)
alarms_to_set.append(ulp_timer_alarm)

if rtc and current_mode == "NORMAL_OPERATION":
    rtc.alarm_status = False
    now_struct_time = rtc.datetime
    next_alarm_minute = (now_struct_time.tm_min + 1) % 60
    next_alarm_hour = now_struct_time.tm_hour
    if next_alarm_minute == 0:
        next_alarm_hour = (next_alarm_hour + 1) % 24
    alarm_time_struct = time.struct_time((
        now_struct_time.tm_year, now_struct_time.tm_mon, now_struct_time.tm_mday,
        next_alarm_hour, next_alarm_minute, 0,
        now_struct_time.tm_wday, -1, -1
    ))
    rtc.alarm = (alarm_time_struct, "minutely")
    rtc.alarm_enable = True
elif rtc and current_mode == "INITIAL_FREQUENT_WAKEUPS":
    rtc.alarm_enable = False

rtc_pin_alarm = alarm.pin.PinAlarm(RTC_INTERRUPT_PIN, value=False)
alarms_to_set.append(rtc_pin_alarm)

wake_count += 1
alarm.sleep_memory[0] = wake_count & 0xFF

if gpio3_rx:
    gpio3_rx.deinit()
if gpio1_tx:
    gpio1_tx.deinit()
led.deinit()

time.sleep(1)
alarm.exit_and_deep_sleep_until_alarms(*alarms_to_set)

[bablokb]

I think the documentation is very explicit on this behavior (https://docs.circuitpython.org/en/latest/shared-bindings/alarm/index.html#alarm.exit_and_deep_sleep_until_alarms):

After restart, an alarm equivalent to the one that caused the wake-up will be available as alarm.wake_alarm. Its type and/or attributes may not correspond exactly to the original alarm.

[keen101]

Oh, thank you. I will look into this!

…

On Fri, Jul 18, 2025, 12:25 AM bablokb ***@***.***> wrote: *bablokb* left a comment (adafruit/circuitpython#10498) <#10498 (comment)> I think the documentation is very explicit on this behavior ( https://docs.circuitpython.org/en/latest/shared-bindings/alarm/index.html#alarm.exit_and_deep_sleep_until_alarms ): After restart, an alarm *equivalent* to the one that caused the wake-up will be available as alarm.wake_alarm <https://docs.circuitpython.org/en/latest/shared-bindings/alarm/index.html#alarm.wake_alarm>. *Its type and/or attributes may not correspond exactly to the original alarm.* — Reply to this email directly, view it on GitHub <#10498 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACXJTQ4GOBPVT3SUQ3NSKL3JCHNLAVCNFSM6AAAAACBZVMCF6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTAOBXGIYDMNJYHA> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[dhalbert]

@keen101 You are not seeing Pretending to deep sleep until alarm, CTRL-C or file write., right? On an ESP32 it should not do fake deep sleep, because there is no USB.

Have you tried this test with an ESP32-S2 or ESP32-S3, if you have those boards? I would be interested to know if you get different pin results. I probably tested this with S2 or S3, but at the time, we may not have even had an ESP32 build.

@bablokb It was not our intention to give incorrect pin numbers. I wrote that line to caution against expecting exactly the same alarm, and even before pin alarms were implemented. It may have been a caution against expecting the same time interval (I think we can't remember the time interval). I will try to make that more precise.

[dhalbert]

@keen101 as a workaround for now, if the wakeup signal persists, you could check the .value of the wakeup pins to see which one has the wakeup signal.

[bablokb]

@bablokb It was not our intention to give incorrect pin numbers. I wrote that line to caution against expecting exactly the same alarm, and even before pin alarms were implemented. It may have been a caution against expecting the same time interval (I think we can't remember the time interval). I will try to make that more precise.

At least for the RP2xxx the code does not record any pin-number:

    alarm->base.type = &alarm_pin_pinalarm_type;
    // TODO: how to obtain the correct pin from memory?
    alarm->pin = NULL;
    return alarm;

see:

circuitpython/ports/raspberrypi/common-hal/alarm/pin/PinAlarm.c

Line 90 in e815e40

// TODO: how to obtain the correct pin from memory?

Now that is the port I know best so I thought the docs are absolutely right.

As a side note, this old comment claims there is a fix in progress that only needs testing. I would be happy to test it if you make your changes available.

[dhalbert]

As a side note, this old comment claims there is a fix in progress that only needs testing. I would be happy to test it if you make your changes available.

@eightycc picked this up as part of doing RP2350 sleep, which is still in progress. I can't find a fix that I personally did, so maybe that comment was about a fix he was testing. But I don't remember!

[keen101]

Hello Dan, (and others),

Thank you for the quick replies and for looking into this. I'm a beginner with CircuitPython and am still learning the ins and outs, so I really appreciate your help. Yes, just trying to test out early deep sleep code with the esp32 with the goal of emulating some of the work being done at Colorado State University with environmental / agriculture sensors and IOT.

From what I can tell, I don't seem to be getting the "Pretending to deep sleep" message. My board's serial logs show rst:0x5 (DEEPSLEEP_RESET), which seems to indicate it's going into a true deep sleep. At least I think I am interpreting that correctly.

I don't have an ESP32-S2 or ESP32-S3 board to test with right now, but I am planning on getting one in the near future for the native USB support. I would be happy to run the tests again if I am able to get one. I just happened to have an early gen esp32 feather on hand, though the native-usb of an S3 would be so much easier for code drag and drop.

I hope the logs I provided in the original post are still helpful. Thank you again for all of your hard work on this!

I will look into the .value idea you had for a workaround. I would appreciate hearing back if the fix-in-progress (that needs testing) ends up being working and being merged into newer firmware. If you have any additional questions I will do my best to answer them or do some testing / digging to figure them all out.

Thanks,
-Andrew