Arduino-toneac-esp32 not compatible with esp32 3.0.0+

[AxiomGreg]

The library ToneAC32 library at GitHub - uhorstr/arduino-toneac-esp32: ESP32 support for the Arduino toneAC library. works with the esp32 board library version 2.0.17 and below, but produces compile errors with the 3.0.x versions. I discovered this by accident when the IDE prompted me for an update. It looks like the signatures to some timer libraries were changed (in a breaking, not backwards compatible manner). The fix would either be a to change the esp32 library to be backwards compatible or to revise he ToneAC32 library to work with both versions. It looks like the ToneAC32 library may no longer be supported by the author.

[ptillisch]

Hi @AxiomGreg. There is some information about the breaking changes made in version 3.0.0 of the "esp32" boards platform here:

espressif/arduino-esp32/blob/master/docs/en/migration_guides/2.x_to_3.0.rst

This might provide some guidance regarding the changes that must be made to the library in order to make it compatible with the latest versions of the platform.

---

As a workaround, you can use the Arduino IDE Boards Manager to install the last version of the platform before the breaking changes were made:

1. Select Tools > Board > Boards Manager... from the Arduino IDE menus to open the "Boards Manager" view in the left side panel.
2. Scroll down through the list of boards platforms until you see the "esp32" entry.
3. Select "2.0.17" from the drop-down menu in the "" entry.
4. Click the "INSTALL" button at the bottom of the entry.
5. Wait for the installation process to finish, as indicated by a notification at the bottom right corner of the Arduino IDE window:

   Successfully installed platform ...

Arduino IDE will occasionally notify you that a new version of the boards platform is available, you'll need to refrain from accepting the offer that will cause an update back to the problematic version of the platform. If you find these notifications annoying, you can disable them via the advanced settings.

I'll provide instructions you can follow to do that:

1. Press the Ctrl+Shift+P keyboard shortcut (Command+Shift+P for macOS users) to open the "Command Palette".
   A menu will appear on the editor toolbar:
   
2. Select the "Preferences: Open Settings (UI)" command from the menu.
   ⓘ You can scroll down through the list of commands to find it or type the name in the field.
   A "Preferences" tab will open in the Arduino IDE main panel.
3. Type arduino.checkForUpdates in the "Search Settings" field of the "Preferences" tab.
4. Uncheck the box under the "Arduino: Check For Updates" setting.
5. Close the Preferences tab by clicking its X icon.

If you disable the automatic update check, make sure to periodically do a manual check for newer versions of Arduino IDE and your installed boards platforms and libraries. You can check for new versions of Arduino IDE by selecting Help > Check for Arduino IDE Updates from the Arduino IDE menus. You can check for new versions of boards platforms and libraries by selecting "Updatable" from the "Type" menu in the Boards Manager and Library Manager views.

@AxiomGreg

It looks like the ToneAC32 library may no longer be supported by the author.

I see they don't have the issue tracker in the repository enabled so unfortunately there isn't a good way to notify the maintainer of the problem.

This is a fork of the original library:
https://bitbucket.org/teckel12/arduino-toneac

There is relatively recent activity in that project. You could try pushing the changes made by uhorstr to add ESP32 support back upstream to the original library.

[AxiomGreg]

Thank you for the detailed response and suggestions. After uninstalling the latest and installing 2.0.17, all is well again. I really wish that these kinds of updates would remain backwards compatible. How hard would it be to keep the old methods around and create new revised ones, especially when the signature changes? Not doing so, only contributes to the quagmire (sorry for the rant). Oh well, another option is for me to make my own copy of the ToneAC32 library and make the appropriate revisions. For now, I've downloaded the 2.0.17 zip file of the board and will keep it in a project reference folder with a note, just for some added future insurance. Thanks again!

[ptillisch]

@AxiomGreg

Thank you for the detailed response and suggestions. After uninstalling the latest and installing 2.0.17, all is well again.

You are welcome. I'm glad you are able to use the library again now.

@AxiomGreg

How hard would it be to keep the old methods around and create new revised ones, especially when the signature changes?

Breaking changes made to a project dependency can definitely be frustrating. I don't follow the development of the 3rd party "esp32" boards platform closely and haven't looked closely at the specifics of the changes so I don't have any insight regarding how easily they could have avoided breakage while still progressing in the development of the platform.

These changes have definitely generated some support requests here on the forum, and will likely continue to do so for years into the future since, as you pointed out, some of the affected projects are not maintained and thus will likely never be updated to compatibility with esp32 platform versions >2.x. They also affected several of Arduino's projects.

However, it should be noted that the "esp32" boards platform developers followed all best practices regarding clearly communicating to users about breaking changes (which not all developers are so conscientious about doing). They complied with the "Semantic Versioning" specification by bumping the major version number from 2.x to 3.0.0 when releasing the breaking changes. They included a warning about breaking changes in the release notes and provided a migration guide.

[AxiomGreg]

I may be biased because I work in the process automation industry where we have many 3rd party developers that integrate I/O devices via a common core framework that we provide. A revised version of that framework can be installed onto an end user's system at any time when they download support for a new device. Since we don't own or develop the specific I/O device software, we don't have the ability to release all device I/O software along with a change to our core. The framework is dynamically linked, so if we were to remove previous functionality, it might break some or ALL of our customer's systems when a customer simply downloads support for a new device. Due to that dependency, we simply can't, and don't EVER make a breaking change to our core framework. At times, we may deprecate functionality, but we never remove it. Imagine updating your OS to a newer version and suddenly your printer no longer works because they revised the driver interface and removed the old interface thereby losing backwards compatibility. Now you have to cross your fingers and hope that your printer manufacturer has a revised driver that fixes the problem. Completely unacceptable.

I can't imagine what would make the esp32 core unique in this regard. Thank you for your additional comments.

[ptillisch]

@AxiomGreg

Due to that dependency, we simply can't, and don't EVER make a breaking change to our core framework.

Sometimes it is necessary to make breaking changes in order to make significant advancements in a project. We don't always have perfect vision and foresight when designing an API in the early days of a project.

Sometimes it is technically possible to maintain compatibility, but not feasible to properly maintain the resulting extra code with the available resources. Keep in mind that open source software projects are often built on volunteer labor, with little or no financial resources for paid developer salaries. Even a passionate volunteer may be less interested in dedicating their time to maintaining legacy code for the benefit of a small number of users (who might have migrated to the new API anyway if it wasn't for the existence of that code).

@AxiomGreg

Imagine updating your OS to a newer version and suddenly your printer no longer works because they revised the driver interface and removed the old interface thereby losing backwards compatibility.

I think it is a bad analogy. This is a breakage in an API for use by programmers, not the breakage of an end user product. Dealing with breaking changes in dependencies is simply a standard part of the job of being a developer. The developers of dependent projects can either update their code to the new API, or continue to use the version of the dependency from before the breakage. Either way, there is no impact on the end user product.

@AxiomGreg

I can't imagine what would make the esp32 core unique in this regard.

It is not unique. Breaking changes in APIs are very common throughout the software and firmware development ecosystem.

To pick a random example, this npm package has 82.6 k dependent projects:

commander

It is at version 12.x

[AxiomGreg]

Fair points, thank you for your response. Yes, my analogy was for end users, not developers so not quite the same. But to the Arduino community, it could be argued that developers are end users. As a developer myself, I would prefer to limit breaking changes as much as possible, but on the other hand, I don't like to see a ton of legacy code and like to keep things clean (avoid code "rot"). I suppose it's a balance. In my particular case, it puts me in a difficult position and IMO works against the platform being "plug and play". I now have the following options:

1. Use a different library that happens to work with the latest version (if one even exists).
2. Write my own library, or fork the existing library with a fix.
3. Use an old version of the core (my current solution). It prevents me from upgrading if other features are necessary, but that may or may not be a problem.

As an experienced developer, it took me at least an hour to track the problem down and recover. I sympathize with the "makers" and such, who are learning and just trying to make something work. I realize there is really no perfect solution.

At any rate, thanks again for your well-informed response!