This question ties into the idea of system "completeness" - everything from selecting the correct examples in a library to making the implementation of a library do the right thing; it even touches on writing a sketch that can work correctly on different boards.
I develop shields, libraries and sketches that need to be agile between Arduino boards, and am looking for a examples of how to write my code to be both agile and easy to understand/modify.
It seems to me that it would be very "end user friendly" being able to use something like the following to identify boards using terms that users also use in the IDE board selection menu:
Does something like this exist? Either way, is there a documented best practice or design pattern that I should be using? Are there similar best practices for shield designers?
This is nice, but in the end is just another illustration of something interesting that hasn't made it back into the mainline Arduino environment.
Maybe I'm asking the wrong question - should I be asking instead where the developer docs for 1.5.x live? You know, the ones that tell us library developers how things SHOULD be done and what the supported core APIs and programming assumptions are...
Robin2:
Are you seriously asking "where is the documentation for open source software" ?
Seriously? Yes, I am.
An overriding goal of the Arduino ecosystem is that it be usable by the uninitiated. That means documentation is required, both for the end users AND for those of us who are trying to contribute. Without sufficient documentation, the project's goal is unreachable; being open source has nothing to do with it.
I have come to the conclusion that documentation is really a thing of the past. End users don't read it, systems are designed so you don't need it, and code is written so anyone can read it.
Open Source is pretty relevant, it's basically a volunteer method of developing. People rarely ever volunteer to write documentation!
The issue of multi-platform libraries is something Arduino have not fully tackled, and possibly is something that can never be addressed satisfactorily, due to the limitations of C++. There is a library metadata file, which AFAIK no one uses, with a small addition it could specify supported platforms.
Getting that far was pretty difficult, the discussion on the dev list ranged from people wanting complete backwards compatibility with the existing libraries, to people wanting a whole new architecture with everything including the kitchen sink. In one case, someone wanting both things at once!
After that discussion, I think everyone was too exhausted to write any supporting code in the IDE, but I think it would not take too much work to implement.
In the meantime, I would recommend a keep it simple approach. When you find some feature is platform dependent, push it down into a HAL layer. Ideally keep all platform specific stuff in one file, or easily identified set of files.
An overriding goal of the Arduino ecosystem is that it be usable by the uninitiated. That means documentation is required, both for the end users AND for those of us who are trying to contribute. Without sufficient documentation, the project's goal is unreachable; being open source has nothing to do with it.
-John
I agree 100%. I reckon the problem is that people who like writing code don't like writing documentation and people who like writing documentation like to be paid. The usual attitude of the code writers seems to be "the code is in the public domain - read it". And "if you see a gap, we would be delighted for you to fill it"
A huge problem with the Arduino system is that there isn't even a recommendation for Library writers to list the Arduino resources their library uses. The obvious result is incompatible libraries. Shields probably suffer in the same way but so far I have had the sense to avoid them.
However, before getting too concerned it is important to recognize that the Arduino has very few resources so it may be very difficult for every option to co-exist without conflict.
And because so many users really are newcomers most of them never notice.
