Standard API for drivers?

Discuss development of drivers for external hardware and components, such as LCD screens, sensors, motor drivers, etc.
Target audience: Users and developers of drivers.
User avatar
deshipu
Posts: 1385
Joined: Thu May 28, 2015 5:54 pm

Standard API for drivers?

Post by deshipu » Fri Apr 15, 2016 10:42 am

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?

User avatar
kfricke
Posts: 342
Joined: Mon May 05, 2014 9:13 am
Location: Germany

Re: Standard API for drivers?

Post by kfricke » Fri Apr 15, 2016 5:44 pm

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.

User avatar
marfis
Posts: 205
Joined: Fri Oct 31, 2014 10:29 am
Location: Zurich / Switzerland

Re: Standard API for drivers?

Post by marfis » Fri Apr 15, 2016 7:04 pm

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.

User avatar
pythoncoder
Posts: 4921
Joined: Fri Jul 18, 2014 8:01 am
Location: UK
Contact:

Re: Standard API for drivers?

Post by pythoncoder » Sat Apr 16, 2016 6:17 am

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

Turbinenreiter
Posts: 288
Joined: Sun May 04, 2014 8:54 am

Re: Standard API for drivers?

Post by Turbinenreiter » Sat Apr 16, 2016 6:52 am

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

User avatar
kfricke
Posts: 342
Joined: Mon May 05, 2014 9:13 am
Location: Germany

Re: Standard API for drivers?

Post by kfricke » Sat Apr 16, 2016 7:49 am

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

User avatar
marfis
Posts: 205
Joined: Fri Oct 31, 2014 10:29 am
Location: Zurich / Switzerland

Re: Standard API for drivers?

Post by marfis » Sat Apr 16, 2016 8:53 am

@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.

User avatar
kfricke
Posts: 342
Joined: Mon May 05, 2014 9:13 am
Location: Germany

Re: Standard API for drivers?

Post by kfricke » Sat Apr 16, 2016 10:58 am

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 ;) )!?

User avatar
pythoncoder
Posts: 4921
Joined: Fri Jul 18, 2014 8:01 am
Location: UK
Contact:

Re: Standard API for drivers?

Post by pythoncoder » Sun Apr 17, 2016 9:29 am

@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.
Peter Hinch

pfalcon
Posts: 1155
Joined: Fri Feb 28, 2014 2:05 pm

Re: Standard API for drivers?

Post by pfalcon » Sat Apr 30, 2016 7:20 pm

marfis wrote: 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?
Awesome MicroPython list
Pycopy - A better MicroPython https://github.com/pfalcon/micropython
MicroPython standard library for all ports and forks - https://github.com/pfalcon/micropython-lib
More up to date docs - http://pycopy.readthedocs.io/

Post Reply