Thanks Collin, for such an honest appraisal.
Within the next few months, I plan to work on a new CAN library for different hardware. I had hoped to work towards compatibility with a well-defined official Arduino CAN API. Seems such an API is still some distance in the future?
When talking about APIs for Arduino, it's usually good to refer to Arduino's style guide.
Bringing up new hardware AND designing an official API (implementing and testing on Due as well) might be more work that I can realistically take on? Then again, I'll need to implement something for an API. I really do care deeply about compatibility. I know from experience that starting without an API plan usually results with an API deeply rooted in the hardware's specific details. From what I can see, it looks like the Atmel guy did this, then you've been adding the higher level stuff?
My hope at this point, if you and others are willing, would be to discuss what the final, official Arduino CAN API might be, in a perfect universe where we all had plenty of time to actually work on the code?
I've been reviewing the existing CAN APIs. So far, I've found 3 Arduino libraries: this one, Seeed's for their MCP2515-based shield, and ChipKit. Seeed's API is fairly simple, just 8 public functions. ChipKit's API is horribly complex. The other API I've seen which seems the most Arduino-like, is mbed's:
http://mbed.org/handbook/CAN#api
I'd like to ask a couple specific API questions...
#1: How do you feel about using a special typedef or object for message data, versus primitive types? Currently Due, Chipkit and mbed use these. It does allow passing more info together, like the ID, length, timestamp. But it also doubles the API, from just one object that communicates to 2 objects, with more stuff to learn to create and extract the data.
#2: Does providing mailboxes in the API add more benefit for users than the increase in complexity and overall size of the API they require? For many Arduino users, the ease of learning is key. An API with fewer than 10 functions, where all have simple names, seems approachable. Seeed and mbed don't expose mailbox functionality. Due and ChipKit have APIs with dozens of functions and long lists of constants. So my question is whether mailbox access (rather than simple read & write) is really beneficial for some uses, and what those applications might be?