Documentation

[rufsiany-sr]

I'm a bit puzzled about how to use the library. Unless I miss something, there is no clear information on the public methods to use in the client code. Opening the *.h files helps, but the comments are vague and misleading: e.g.:
// frequency (in hertz) and duration (in milliseconds). Duration = 0 or not specified => run indefinitely
However, there is no Duration argument.
Also, why AttachInterrupt starts the timer? Usually, attaching the callback function is separated from starting the timer. One would have also expected some parameter to distinguish between running the timer once, defined multiple times or undefinitively.
Why are there multiple methods for the same action: detachInterrupt vs disableTimer?
All in all, the potentially very useful library is broken by the lack of clear documentation.

[khoih-prog]

Check Documentation #9

The Interrupt-related library was written with the expectation that the users are experienced in hardware/firmware, and can read the public source code, examples to understand and apply / adapt into the real use-cases.

[rufsiany-sr]

Sure, your library, your decision whether to write documentation or not.
But at least I am not the only one who complains about the lack of it, so you may rethink your approach.
BTW: I do have the necessary experience, so I wrote my own code.
Thanks for the answer anyway.

[RDJunc]

If I may add my two cents....

Libraries like yours are an invaluable service to the community and greatly appreciated. Users like me certainly have no right to insist on any level of documentation or support but the fact does remain that the community is made up of a people with a wide variety of skills. It is the less skilled people that benefit the most from these libraries. Being experience in hardware and firmware in one thing. Being able to extract usage information and design intent is another. No one is asking for complete manuals but even more heavily commented code in the examples would be helpful. I think I fall into that typiccal user category. Far from a newbie but not a software engineer. I am quite capable of using a tool but not expert enough to design the tool itself.

Here is my particular issue...

In simplified form, I am developing a device that controls a servo via BLE. It uses the ESP32-C2 device. I am using Visual Studio with Visual Micro as the IDE. The code uses the ESP32_NEW_ISR_SERVO library. What I have implemented so far is working as intended.

For the timer and interrupt library, I am using the ESP32_NEW_TIMERINTERRUPT library. I use it for several timers.

I am using a timer for a blink routine. It runs constantly but only blinks the LEDS whose struct variable for blinking is set. (LED0.IsBlinking = true).

There is a button to initiate the BLE connection. A pin interrupt routine detects when a button is pressed. This puts the device into Bluetooth advertising mode. In this mode, the blue BLE LED is set for blinking which indicates that the device is advertising and is ready to be connected to. If a BLE connection is made, the LED stops blinking but remains on. When the BLE connection is dropped, the LED goes off. This all works.

There is another timer for BLE timout. This is a timer that starts when the BLE button is pressed, the LED starts blinking, and the device starts advertising. The purpose of this timeout timer is turn off the LED and stop the BLE advertising if a BLE connection has not been made within 30 seconds of pressing the button. I have not been able to get this to work. I have not been able to figure out how to set a timer for a specific duration, run an ISR when it expires, and then disable that timer. The timer needs to be reset and start again if the BLE button is pressed again.

The documentation for the library is not very comprehensive. There is no definition of each function in the library, its syntax, and usage. This timeout timer should be straight forward in that I could be able to start the timer with the button press, turn off BLE advertising when the timer expires and disable the timer until the button is pressed again.

I'm not even sure I am using the right libraries. There are ESP-32-C3, ESP-32_NEW, and ESP_GENERIC libraries. Which one should I be using? How do the enable and disable functions work? I am perfectly willing to do the research so pointing me in the right direction for documentation, etc. would be greatly appreciated.

[khoih-prog]

Thanks for your interest in the libraries.

Please have a look at Thanks! #62

This is so true, and you have to understand that for library writers, the writings of correct README.md is considered as a torture, as we are not professional technical writers and also have tunnel vision about what is necessary / good for other users.

I'd appreciate if you can help in modifying the README.md, certainly whenever you have time, then make a PR to contribute back.

I wish I have all the time in the world to make everything ( 120+ and increasing libraries to maintain, create, bug-fix, support, etc. ) perfect. But as you can experience yourself, there is so much a single guy can do, especially in free time.

---

Just a quick look at your so-called design doc, the usage of rare and precious Hardware Timer Interrupt is so overkilling. I think normal function using millis() can do the required (non-critical and not-to-be-super-precise) job. You can also check and use SimpleTimer or a similar library

---

The new ESP32_New_TimerInterrupt Library supersedes all other ESP32_XY_TimerTimerInterrupt libraries, which are created for pre-v2.0.0 ESP32-core. Those superseded libraries will be archived and won't be maintained, just to be kept for pre-v2.0.0 ESP32 core usage.

Just read the features of each library, for example

• ESP32_S2_TimerInterrupt Features
• ESP32_C3_TimerInterrupt Features
• etc.

and know why each library was created.

[RDJunc]

I do not want to seem ungrateful for the work you have put in. As one that also contributes to community technology, I can appreciate the work it takes. That said though, it does not reduce the need to make these contributions useable for the community. Sure, documentation is an unrewarding chore but that doesn't make it any less necessary. Having lots of libraries that are confusing to use is less desireable that fewer libraries that are widely used.

May I make a suggestion here. You have many libraries that do the same thing but with exceptions to their use. Those exceptions are not always clear and obvious. There are ESP32, ESP32-C3, ESP32-S3, core 2.x, and pre-core 2.x libraries. One well documented consolidated library would be far more useful. Archiving pre-core 2.0 leaves out a lot of users that for various reasons.

As to my application, I was not providing a design document. It was just one simple example for one aspect of the project. There are other features that require more precise timing. It seems inefficient to use millis(), a simple timer library, and your library when one should handle all the requirements.