Standard API for drivers?

[deshipu]

I wonder if it would make sense to agree on a standard(ish) API for the drivers for various hardware, so that once you learn to use a few of them, learning to use others will be come easier. I mean small things, like where to put the constants, how to call the initialization method ("init" versus "begin"), whether to initialize on class creation, how to pass the pins being used, how to pass the spi/i2c objects, etc.

This is more than just desire to have consistent interfaces. For instance, if we agree that any i2c drivers should just receive an i2c object in their initialization, instead of having them create it, then those drivers suddenly become much easier to port between platforms (or will even work without modification).

It would be also nice if the the same classes of hardware (displays, sensors, human interfaces, etc.) used consistent naming for their methods (like update/show) and ordering of parameters.

What do you think? Would that make sense?

[kfricke]

In my opinion your suggestions do make sense and some are not needed to be discussed. As you noticed those practices are needed to make drivers portable across the MicroPython platforms.
Things you did not mention are memory allocation and usage optimizations. @pythoncoder gave most of the best practices and i also did look at Damiens recent drivers (display/SSD1306) for things like use of "const()", comments and stuff. Code comment style (# vs."""..."""') seems to have influence on memory usage as well (I#d have to dig through the forum and github for details).

As this is the python side of the project we should start to provide pull requests i'd say.

[marfis]

I agree on that, thats an important aspect and should be clarified.

from pauls answer on my pull request https://github.com/micropython/micropython/pull/1843 there will be more driver provided by him or damien as part of the 8266 kickstarter.

I guess once they release those drivers, a short "best practices" for uPy driver development can be established.

Btw In the above link there is a clear statement of both Damien and Paul that properties should be avoided.

[pythoncoder]

Alas some of my drivers use properties - I was surprised to read that they are frowned upon. But I can see the reason.

[Turbinenreiter]

I don't, what's wrong with properties?

[kfricke]

There is a nice little post in a thread regarding this. Nothig sreiously bad, just a wast of RAM.

[marfis]

@Turbinenreiter: See the responses on the link above.

I cannot judge implementation efficiencies of properties but Damiens argument makes a lot of sense to me.

[kfricke]

One aspect for drivers should be to use pre-allocated memory (buffers) where possible to make sure they do not scramble up the heap (and thereby GC) too much and enable ISR embedded operation of a driver.

Also with the "new" machine.I2C interface currently implemented on the ESP port it seems reasonable to notice that it differs from the old pyb.I2C interface in the way that the read and write access methods now do only use buffer protocol objects. A global trend with MicroPython to notice.
In addition to this i would like to mention the memoryview thread for some usefull insights.

Maybe we should generally take the new already mentioned (but not yet linked) SSD1306 driver as a starting reference point (which is missing read operations )!?

[pythoncoder]

@Turbinenreiter Re properties I gather there are two reasons. Firstly there seems to be a cost in terms of RAM usage and performance. Secondly accessing a property can trigger code execution which isn't evident to the caller, whereas accessing a method evidently leads to code running.

I'll bow to Damien and Paul's expertise on the first point. I'm only partly convinced by the second - triggering execution is, after all, the purpose of properties - but I'm willing to go along with the convention in future.

[pfalcon]

from pauls answer on my pull request https://github.com/micropython/micropython/pull/1843 there will be more driver provided by him or damien as part of the 8266 kickstarter.

I guess once they release those drivers, a short "best practices" for uPy driver development can be established.

That's not exactly what I wanted to say. I meant that we (MicroPython maintainers) got the task of developing consistent set of drivers (and thus API) as part of ESP8266 KS campaign. So, progress on that matter is definitely coming. We welcome also community initiative to drive that, but I hope you agree that we should be involved too. But then it's not ideal time for us to do that now, as we need to get basic functionality done and handle the actual release. One of the problem we have with MicroPython development is that we now even have enough people around, but still too many areas to work on, so people spread thin, and there's lack of momentum in many areas. So, implications I'd mean are:

1. Everyone interested, let's get together, keep in touch and prepare to work on it when time arrives. Threads like this is very useful in that regard.
2. If community wants to drive that effort, it's very welcome, but please be prepared that maintainers make tehir votes/adjustments later .

But in no way I mean "guys, relax, we know it all, and will have it done for you". We don't (know it all), and really need community involvement to get it well and right.

So, discussing various aspects of it is very helpful (especially if too much of bikeshedding is avoided ). For example, hopefully we settled on no-properties, next thing I myself can't decide on is number representation. Floating-point is so easy and natural, and even micro:bit has it, but some ports don't and some new won't. And if we leave them out, how can we call it a design of general sensor API? Another question is units, apparently we should select one unit for each sensing type? Actually, fiddling with units may get FP-vs-int problem solved, e.g. if we standardize of centi-degrees for temperature, we can use int's, but will it be convenient for users?