RFC: Hardware API: finalising machine.Pin

[pythoncoder]

LEDs and Pins are different objects, physically and logically. The confusion arises because one way to implement a physical LED is to connect it to a pin. A Pin object produces an electrical output which is high or low. An LED object is either ON or OFF.

If you view them in that way inversion makes no sense for either.

[deshipu]

I think it makes a lot of sense to ship the drivers for all the hardware present on the official boards -- such as LEDs, buttons, accelerometer, hobby servo connectors, etc. However, I feel they should not go in the "machine" module, but rather in a separate module, specific to the board, such as "pyb", "wipy" or "esp", or perhaps a new "board" module.

[Turbinenreiter]

I think it makes a lot of sense to ship the drivers for all the hardware present on the official boards -- such as LEDs, buttons, accelerometer, hobby servo connectors, etc. However, I feel they should not go in the "machine" module, but rather in a separate module, specific to the board, such as "pyb", "wipy" or "esp", or perhaps a new "board" module.

I think so, too. 'machine' supports the microcontroller, 'board' supports the board.

[Lysenko]

I think it makes a lot of sense to ship the drivers for all the hardware present on the official boards -- such as LEDs, buttons, accelerometer, hobby servo connectors, etc. However, I feel they should not go in the "machine" module, but rather in a separate module, specific to the board, such as "pyb", "wipy" or "esp", or perhaps a new "board" module.

I think so, too. 'machine' supports the microcontroller, 'board' supports the board.

OK, so presumably there would be a 'lowest common denominator' core API which should be broadly portable (SPI, UART, I2C, Timers etc). Do you allow that to be extended via IFDEFs to cope with chip specific functions (CAN, BT, WiFi, FPU etc.) or split those off as independently loadable modules?

[Turbinenreiter]

OK, so presumably there would be a 'lowest common denominator' core API which should be broadly portable (SPI, UART, I2C, Timers etc). Do you allow that to be extended via IFDEFs to cope with chip specific functions (CAN, BT, WiFi, FPU etc.) or split those off as independently loadable modules?

If a microcontroller has a CAN bus, it's machine module has a CAN module. Defines are used in the board definition files, i.e. 'mpconfigboard.h' to activate or deactivate a module.

[Lysenko]

If a microcontroller has a CAN bus, it's machine module has a CAN module. Defines are used in the board definition files, i.e. 'mpconfigboard.h' to activate or deactivate a module.

I think I maybe phrased that badly: I intended to ask how you proposed that such situations be handled, not how are they handled now (though the two may be the same). You mentioned driver portability so I thought you were maybe suggesting that a CAN class (for example) should sit at a higher level so that it could be configured to use machine, board or attached peripheral resources, depending on what is available. That involves an additional layer of indirection of course.

[deshipu]

I just remembered one more thing that doesn't seem to be covered. The teensy, among other boards (but I suspect this is quite common) has the ability of measuring capacitance on some of its pins, which is commonly used for touch detection. Is that already covered under the ALT modes for the pins, or should we think about it?

[dhylands]

I think that there are always going to be cases where you need to set an the alternate function of a pin, so we definitely want to keep that functionality. The original post suggests pin.alt() or pin.alt(new-alt). The alternate functions are just integers, and a port can either provide a constant (if that makes sense), or you can pass one in.

Some other examples where you need to specifically initialize pins:

• Quadrature decoding needs 2 or 3 pins. The Timer API only allows a single pin to be specified - which covers off most non-quadrature usages. You need to use the machine.Pin to set the appropriate alternate functions for the other pins not initialized by the TImer API.
• ADC sampling using differential signals needs 2 pins. The ADC API only allows a single pin to be specified - which covers the more typical single-ended use cases. You need to use the machine.Pin API to set the alternate function for the pin not initialized by the ADC API.

[deshipu]

I wonder if the discussions here actually have any effect at all. I'd love to have some conclusions and an actual plan, eventually, so that we can actually work on making this happen. Instead, everything seems to be just hanging in the air, new "problems" are thrown in as distractions to derail the discussion, and in the mean time quietly there have been some commits that change the documentation of the very API we are discussing here. What is going on?

[pfalcon]

I wonder if the discussions here actually have any effect at all. I'd love to have some conclusions and an actual plan, eventually, so that we can actually work on making this happen. Instead, everything seems to be just hanging in the air, new "problems" are thrown in as distractions to derail the discussion, and in the mean time quietly there have been some commits that change the documentation of the very API we are discussing here. What is going on?

It definitely has. The main effect is understanding that discussing it in such format ("let's discuss how HW API should look") doesn't lead us anywhere. There're 2 main issues:

• People who aren't around long enough get impression that MicroPython doesn't have hardware API and they have tabula rasa to paint it. That's not the case. MicroPython does have hardware API, and for quite a while. We can clarify something, adjust something. Add minor things. Shave parts sticking out which we don't have enough hands to support for now. But that's it. No throw away and start from scratch. No U-turns.
• There's no structure in such discussions, people just throw more or less random things in fire, hardly listening to each other.

So, we're back to how we have been doing it most of the time: there's a single ticket per single feature which is proposed to be changed/added/etc. So, please consider this discussion to have been loud village get-together to energize everyone. We're now back to civilized and organized progress-looking proceedings. I personally suggest everyone interested to do the following:

Choose 3 (three) things you would like to change in the current Hardware API the most, and submit them on github.


Please choose carefully (makes sense to use this thread to arrange who submits what to avoid wishes burnt in duplicates). Ditto for submitting what's already included in the API.

Other effects of this discussion:

• https://github.com/micropython/micropython/issues/2602 - Organizational announcement of the current stage of the project
• https://github.com/micropython/micropython/pull/2559 - Unlocking docs changes which were deadlocked by unmaintained cc3200 (aka wipy) port
• https://github.com/micropython/micropython/pull/2571 - Clarification of how HW API is supposed to be used (have been supposed all this time)
• https://github.com/micropython/micropython/issues/2603 - Rethought proposal for signal inversion support based on the feedback received

There also will be further organizational announcements, in particular how voting is to be handled in case of Swan, Pike and Crab situations. The announcements will come from BDFL (check https://github.com/micropython/micropython/issues/2602), so there was no concern regarding authority of them.