Debugging ESP32 Timer Interrupts: A Tale of API Compatibility

 

The Silent Signal Generator

 

Have you ever spent hours debugging code that should work but doesn't? Recently, I faced this exact challenge with an ESP32-based signal generator project. The symptoms were perplexing: all configuration parameters were correctly set, the web interface was working flawlessly, but the CTCSS tone output was completely silent. The culprit? 

A timer interrupt that refused to fire...

The Setup

The project uses an ESP32 to generate precise CTCSS (Continuous Tone-Coded Squelch System) tones for radio applications with  a GPS to "discipline" the time for 0.5% or less accuracy. 

Yeah! Overkill, I know, but the architecture is straightforward:

1. A web interface for controlling tone parameters (frequency, level, on/off)

2. WebSockets for real-time communication

3. A timer interrupt running at 10 kHz to drive the DAC output

4. Direct Digital Synthesis (DDS) with a sine lookup table for waveform generation

Everything seemed perfect in theory, but in practice, the DAC remained stubbornly silent.

The Investigation: Hours of Head-Scratching

 

What followed were countless hours of frustrating debugging and head-scratching. I tried everything: different timer configurations, checking hardware connections, simplifying the code, even rewriting the interrupt handler from scratch. I attempted various approaches: minimizing critical sections to reduce conflicts with WebSockets, trying different timer frequencies, toggling GPIO pins to verify hardware functionality, and even considering direct register access to bypass the Arduino API entirely. Nothing worked. The timer stubbornly refused to fire its interrupt, and the oscilloscope showed a flat line where a beautiful sine wave should have been.

The extensive debug logged every aspect of the system and for no reason, the interrupt was silent. 

At one point, my frustration reached such heights that I was ready to abandon the Arduino framework entirely and start learning Assembler or Machine Code just to manipulate the ESP32's DAC at the lowest possible level. 

Anything to get that stubborn signal flowing! A pattern finally emerged: the timer was being initialized correctly (the code was compiling and running without errors), but the interrupt service routine (ISR) counter remained at zero. This meant the timer was configured but never actually firing its interrupt.

[DIRECT DEBUG] Timer status check:
ISR counter value: 0
CTCSS enabled: YES
CTCSS frequency: 100.00
Timer initialized: YES

The code was using the ESP32 Arduino Core 3.2.1, and the timer setup looked correct:

timer = timerBegin(timerFreq);
timerAttachInterrupt(timer, &onTimer);
timerAlarm(timer, alarmValue, autoReload, reloadCount);
timerStart(timer);

 

The Breakthrough: API Version Matters

After multiple failed attempts to fix the issue within the 3.2.1 framework, I discovered something crucial: ESP32 Arduino Core versions have significantly different timer APIs.

The newer 3.2.1 version had simplified the API, removing critical parameters like timer number selection and edge-triggered interrupt options. These simplifications made the API easier to use but less powerful for specialized applications like precise signal generation.

 

 

 

The Solution: Strategic Downgrade

The solution was to downgrade to ESP32 Arduino Core 2.0.9, which offers a more comprehensive timer API. This allowed explicit control over:

1. Timer selection - Using Timer 1 to avoid conflicts with system functions

2. Edge-triggered interrupts - For more responsive and reliable timing

3. Precise prescaler settings - For accurate frequency generation

The updated code looked like this:

// ESP32 Arduino Core 2.0.9 API with explicit timer number
int timerNumber = 1; // Using timer 1 to avoid conflicts
uint16_t prescaler = 80; // 80MHz / 80 = 1MHz timer frequency

timer = timerBegin(timerNumber, prescaler, true); // true = count up
timerAttachInterrupt(timer, &onTimer, true); // true = edge triggered

uint32_t alarmValue = 1000000 / DDS_SAMPLE_RATE; // 100 ticks for 10kHz
timerAlarmWrite(timer, alarmValue, true); // true = auto reload
timerAlarmEnable(timer);

 

 

The Results

The results were immediate and impressive:

[DIRECT DEBUG] Timer status check:
ISR counter value: 2232839
CTCSS enabled: YES
CTCSS frequency: 254.00
Timer initialized: YES

[INFO] ISR count: 2240000, Time since last report: 1003 ms
[INFO] Actual interrupt frequency: 9970.09 Hz (expected: 10000 Hz)
[INFO] DAC output active: yes, CTCSS enabled: yes

The timer was now firing at approximately 9970-9980 Hz (within 0.3% of the target 10 kHz), and the oscilloscope confirmed a clean CTCSS signal output from the DAC.

 

 

Key Takeaways

1. API Compatibility Matters: Always check API compatibility when upgrading frameworks or libraries. What works in one version may not work in another, even if the code compiles without errors.

2. Explicit is Better than Implicit: When working with hardware-level features like timers, explicit control often yields better results than simplified APIs.

3. Effective Debugging: Implement counters and detailed logging to make invisible problems visible. The ISR counter was crucial in diagnosing this issue.

4. Sometimes Downgrading is Upgrading: Don't be afraid to use an older version if it offers functionality that better suits your specific needs.

Conclusion: From Frustration to Triumph

After hours of pulling my hair out (not quite) and questioning my sanity (and programming abilities - truly!), the solution turned out to be something I never would have guessed initially. 

Those moments when you stare at perfectly valid code that simply won't work are some of the most frustrating in an amateur developer's life. Yet they're also the moments that teach us the most.

This experience reinforced an important lesson in embedded systems development: understanding the underlying hardware and API capabilities is just as important as writing correct code. Sometimes the most elegant solution isn't using the latest version, but rather the version that gives you the control you need.

The relief when seeing that ISR counter finally incrementing was indescribable. The ESP32 Signal Generator now produces perfect CTCSS tones with rock-solid timing, proving that with the right approach, even the most stubborn bugs can be conquered. The countless hours of head-scratching were ultimately worth it, not just for the working project, but for the deeper understanding gained along the way.

Have you encountered similar API compatibility issues in your projects? Share your experiences in the comments below!