Designing an API for my arduino program

I'm building a project using arduino that controls several LED strips using FastLED. I want to build a library for openframeworks or processing that can send data to the arduino to display on the LEDs.

I want to make this interface easy to use for other programmers and it to be as fast as possible. Is there some kind of best practice for designing a simple API? I've tried googling but it's hard to find information on the design practices for this kind of thing?
thanks in advance.

How will openFrameworks or Processing communicate with the Arduino ? A serial link, perhaps, or some other way ?

Yes with serial. Sorry forgot to mention that in the post

Then the first limitation is speed. Use the fastest baud rate that both ends of the link can work at reliably

I assume that the library is for the Arduino. If so it should be agnostic as to what it is interfaced with

Is the API going to be 1 way or 2 way. ie, is the Arduino going to be able to feed back its status or is it going to just receive commands with the risk of buffer overflow ?

API aside, have you got any code written for the Arduino and is it written so as not to block interaction via Serial ? ie no use of delay(), while loops or long for loops ?

One API command will presumably be "stop whatever you are doing", hence the need for non blocking code. Have you got a list of API commands that you want to use ?

I haven't started the project yet. I'm in the planning stage.

It will be mostly 1 way, sending the LED colours. I might have debugging functions for the api that will request data from the Arduino. Any requests will be non blocking.

Sparkfun has a nice essay how to write a library:

well, you could start with a documentation.
What do want to achieve with your "API"?
What will your API make it easier / better / faster for others to handle the strip?
What interfaces & methods will one need?

As a result the answers might give you hints, how the "easier - better - faster" interface should look like.

I suggest that the first thing to is to write some functions on the Arduino that control the LEDs and base the LED actions on the value of some variables and test them thoroughly on the Arduino. The classic things to do with a string or strings of programmable LEDs is to change the pattern, usually by having a function for each, but that can be difficult to exit from cleanly. Better to use switch/case and to have a case for each pattern with non blocking code. That gives you an easy way to receive serial data in loop() between executing the steps of a case

A simple API could accept a pattern number and switch to the requested one after tidying up the state of the LEDs, and run the pattern at a default speed. You could add a speed parameter to the API call and use a default value if it is not present or out of range.

If, for any reason you want a range of LEDs to do something then the API should accept the start and end numbers of the range and similarly with a range of colours to cut down the number of characters sent

There is a balance between sending clear values such as "pattern=1, speed=10" and "1,10" so maybe a compromise of "p1,s10" would be used

Have you considered adding a checksum to teh API messages to help prevent corrupted messages being acted on ?

How complicated do you want to make the API ?

I think this is excellent advice. I find that writing documentation causes me to see the interface from the user's perspective. Too often, when writing documentation as an afterthought, I realized a better way to design it and had to go back and rewrite a bunch of code.

Another suggestion I'll provide is to consider the common API conventions in the Arduino world. For example, many libraries have a begin function, so Arduino users are accustomed to this and will find your API more intuitive. Perhaps not relevant for this particular application, but the Arduino core library provides some classes like Print and Stream you can inherit from

A documentation doesn't replace a software description or a software design document but it's better than just start coding. Imho an early (basic) user documentation can be the source to elaborate the use cases / functional and non functional requirements / needed APIs.

You can let it check by others if your library is useful for them and gain feedback before you release your first version.

And on release date: you have your documentation "ready" also :wink: