Design API

[johnpatek]

Before adding support for any specific boards, the API should be defined. This is both an intentional decision to prevent bias in design, and also due to the uncertainty over which boards will be targeted by PreGuardAI. A few guidelines will be helpful when creating the API:

• Prioritize embedded principles - for functions where the API differs wildly between microcontrollers and microcomputers, the design should favor the microcontroller, which will often be more constrained and rigid in its implementation. A platform like raspberry pi will have a better selection of libraries to emulate these embedded patterns.
• Keep the abstractions thin - while this is a balancing act, we want to keep the HAL as thin as possible, such that its only purpose is to abstract away low level API differences between target platforms. For something like HTTP, it is okay to just create an abstraction over the embedded HTTP clients offered by various platforms. Conversely, for audio, the abstraction should only provide an interface for raw audio over I2S, it should not manage audio codecs.
• Mitigate growing pains - The HAL will expand in both directions. The frontend(API surface) will grow to include more functions, while the backend(target implementations) will grow to support more platforms. There is no perfect recipe to handle this, but a healthy preference for modularity and statelessness seems like a good starting point.

[johnpatek]

@a6guerre we can work together on this one. Once we have discussed the high level requirements, we should have a better picture of what this API needs to look like.