[Library manager] Processor specific examples

Hi,

I've written an Arduino library for ESP32 and ESP8266.

The library uses preprocessor "#if defined (ESP8266)/ #if defined (ESP32)" too determine witch processor is used to choose the correct implementation. The user doesn't need to change any code everything is done behind the scenes.

So version 1 is published and released to the library manger, I have added a few examples but would like to add more.

All examples I've written are generic but I would like to add examples that utilize interrupts in the processor, the problem is that both processors handle interrupts slightly different. Is there a way to tell Arduino IDE to only show Exampel#1 if ESP8266 is selected and only show Example#2 when ESP32 is selected?

I have tried to figure it out with the library specification page but cant figure it out...
https://arduino.github.io/arduino-cli/library-specification/

Also is there a way to change the name in the library manager once the library is published?
Will it "break" if I just change the name in the properties file?

Thanks for any help!

UNI-T:
I've written an Arduino library for ESP32 and ESP8266.

Thanks!

UNI-T:
I would like to add examples that utilize interrupts in the processor, the problem is that both processors handle interrupts slightly different. Is there a way to tell Arduino IDE to only show Exampel#1 if ESP8266 is selected and only show Example#2 when ESP32 is selected?

The Arduino IDE does have some features along these lines:

  • Examples of boards platform bundled libraries are only shown in the File > Examples menu when a board of that platform is selected.
  • Examples of libraries that don't have an entry in their library.properties "architectures" field matching the architecture of the currently selected board are shown under the File > Examples > INCOMPATIBLE menu.

However, neither of those are of help to you. The closest thing would be for you to split the library into two libraries; one for ESP8266, the other for ESP32. However, if there is a significant amount of code in the library shared between the two architectures, then that would result in extra effort to maintain the duplicate code.

What you could do is put the architecture-specific examples under dedicated subfolders:

MyLibrary
|_ examples
|_ Universal
| |_ SomeUniversalExampleSketch
| |_ SomeUniversalExampleSketch.ino
|_ ESP32
| |_ SomeESP32ExampleSketch
| |_ SomeESP32ExampleSketch.ino
|_ ESP8266
|_ SomeESP8266ExampleSketch
|_ SomeESP8266ExampleSketch.ino

This will result in the universal examples being under the File > Examples > MyLibrary > Universal menu, the ESP32-specific examples being under the File > Examples > MyLibrary > ESP32 menu, and the ESP8266-specific examples being under the File > Examples > MyLibrary > ESP8266 menu.

Of course, you can chose the folder structure and names as you like. This is only an example to demonstrate that the examples menu is organized according to subfolders. I have seen some library authors take this approach.

UNI-T:
Also is there a way to change the name in the library manager once the library is published?

Yes:

For the sake of continuity, libraries in the Library Manager list are locked in to the name they had at the time they were added to the list. If you wish to change the name it will need to be done manually by request:

  • Change the name value in your library.properties file and update the version.
  • Create a release or tag that matches the updated version value in library.properties.
  • Submit an issue report requesting the name be changed and the URL of your library's repository.

UNI-T:
Will it "break" if I just change the name in the properties file?

If you do that, all releases of the library made after the name change will be rejected by the Library Manager indexer. So those releases will not be available for installation via Library Manager.

This issue will not occur if you follow the procedure I quoted above.

Hi,

Thanks for such a good answer!

What you could do is put the architecture-specific examples under dedicated subfolders:

MyLibrary
|_ examples
|_ Universal
| |_ SomeUniversalExampleSketch
| |_ SomeUniversalExampleSketch.ino
|_ ESP32
| |_ SomeESP32ExampleSketch
| |_ SomeESP32ExampleSketch.ino
|_ ESP8266
|_ SomeESP8266ExampleSketch
|_ SomeESP8266ExampleSketch.ino

This seems like a reasonable approach, since the difference between the two implementations is not enough to justify keeping track of two libraries.

Its pretty much only the examples that have a larger differences. The actual library just utilizes the WIFI peripheral and some things around them.

I will change the name whenever I do the next update, its not a big enough change to just do a separate release just for a minor name change!

Is it just me or does the Library manager seem rather lacking in documentation...

Thanks for the help!

UNI-T:
Is it just me or does the Library manager seem rather lacking in documentation...

I think the Library Manager FAQ does a pretty good job of documenting it:

That links to the Arduino Library Specification. As long as the library is compliant with the 1.5 format described in the specification, it should be fine for Library Manager.

The confusion I do see regularly is from people who have libraries which are not compliant with the specification. The Library Manager indexer enforces only parts of the specification and there is no documentation about which parts of the specification are enforced. However, it's best to just make the library 100% compliant, so it's not really so important to document which specification violations are permitted and which are prohibited. Even if a specification violation happens to be permitted today, there is no guarantee it will be permitted tomorrow.

I very much welcome feedback on how the documentation might be improved. I'm so intimately familiar with the subject that I might not be able to recognize deficiencies in the documentation. So your perspective is extremely valuable.

The Library Manager FAQ is a publicly editable wiki, so you're welcome to just directly edit it as you like.

The source for the Arduino Library Specification document is hosted here:

so you're welcome to submit a pull request for any fixes or improvements. I happen to be in a position where I am able to merge this sort of pull request, so I can assure you it won't be ignored.

If you don't feel like taking this direct approach to improving the documentation, you'll welcome to just make your suggestions here and I'll consider taking action on them myself.

UNI-T:
Thanks for the help!

You're welcome. I'm glad if I was able to be of assistance. Enjoy!
Per