Suggestion: write hardware independent docs

[beyonlo]

Hi Peter!

Very nice work, but I'm a bit sad when start reading/testing uasyncio v3 code on my esp32. :(

Many docs are referencing and works just with pyboard, and I and many people do not have it and do not have any intention to have one pyboard.

My suggestion is to write the ALL docs where works in any board/processor. Mostly Micro controllers has that peripherals (GPIO, UART, I2C, AD, etc). So, if someone are using any micro controller where is capable to run MicroPython, the demos, examples and so on, will works. For now, the mostly demos, drivers, docs, etc are running just with Pyboard - that is a problem for all people that do not use pyboard. I understand that there are something that is supported just for the Pyboard, and the same for other processors, like as ESP32, like as WIFI/BLE/RMT. But this suggestions is for what is common between all micro controllers.

Anyway, specific features from a board is welcome, I'm just saying to not be the mostly them. ESP32 has, like as I told you, specific hardware features. That is welcome in your tutorial too :). But I know if you prefer to use effort to write docs where more people can use, and this way, is, in my opinion, writing hardware independent docs.

Thank you.

[peterhinch]

Most of the code samples in the tutorial are cross-platform. You should be able to cut and paste most of these on an ESP32, although the few that use specific hardware will need small changes.

MicroPython now supports numerous platforms, all with different hardware and pin numbering. I only own Pyboards, ESP8266 and ESP32 but there are many others, a number which steadily increases.

One choice is to make the code more complex, detecting hardware and changing initialisation to suit. Another is to write multiple port-specific versions. The choice I made was to write simple demos and ask users to modify them to suit their hardware. Writing cross platform code for anything using hardware makes the code longer and harder to read; testing on kit I don't own would be impossible.

The Pyboard is the reference board for MicroPython. Adapting demos for other hardware is generally easily done.

[beyonlo]

One choice is to make the code more complex, detecting hardware and changing initialisation to suit. Another is to write multiple port-specific versions. The choice I made was to write simple demos and ask users to modify them to suit their hardware. Writing cross platform code for anything using hardware makes the code longer and harder to read; testing on kit I don't own would be impossible.

Another great option is write just a piece of code commented for other platform (including imports), like as ESP32. So, user can just uncomment that piece of code and comment the part where about other platform (pyboard for example). In this way the code will no need to detect the hardware, and no longer and harder to read, and you do not need to do a specific port example for each platform. If you would like to add another platform, just edit the example and add a commented piece of code for that platform.

Starting adding ESP32 piece of code on examples is a great idea, because I think it is the most used processor on the MicroPython. A way to confirm that is just to check (if has this feature) the number of downloaded binaries on the micropython page.

Thank you for your time.

[peterhinch]

I have no idea which platforms are most popular nor do I know how to find out. I do know there are an awful lot of platforms; I have chosen just three. I really haven't the enthusiasm for buying and testing ever more hardware.

I think it's reasonable to assume that anyone with the skills to be serious about asynchronous programming can figure out how to assign pin numbers. Many of my drivers are cross-platform. For example the example code in the GPS doc requires only the UART number to be considered to run on another platform.

It's becoming quite difficult to write cross-platform code. See https://github.com/micropython/micropython/issues/5564. As the number of platforms increases, the harder this will become unless some effort is put into solving this.

The compromise I have reached is to try to code in a cross-platform manner but to provide detailed wiring information (and guaranteed testing) on a Pyboard. Whatever its popularity, it is the reference board.

[beyonlo]

I understand your point. This is just a suggestion, because I see in some of your examples the code that run in more than one platform, like this https://github.com/peterhinch/micropython-async/blob/master/v3/as_drivers/htu21d/htu_test.py

I think that interesting and suggested just to continue (if ispossible) to do that or something like that.

Anyway, I appreciate so much your effort to help uasyncio to grown - it is amazing!

Thank you so much.

Best regards.

[pghpete]

Peter, would you be interested in accepting modified code to pull into your project that would run on various boards? Or perhaps simple patches that users could run against your base code for X board compatibility? If so I would be willing to help however I can.

The "patches" idea would keep your code as-is and it would fall on the users shoulders to run a particular patch set that alters the code to work for their boards.

Just a thought.

Thanks!

[peterhinch]

This issue is driving me to distraction and, in my opinion, requires urgent attention from the maintainers.

I get support queries from users where my code fails on some platform because a core language feature is missing. The RP2 port breaks swathes of my code because the cmath module is missing, despite it having plenty of RAM and Flash. Inexplicably, on RP2, machine is present but machine.Signal is not. The time epoch is different from other platforms and from the docs. And so on, ad nauseam.

I have reluctantly concluded that writing cross platform code in MicroPython is impossible in practice. There is no way of knowing what language or library features to use without performing a detailed study of the build system for every platform. Which won't help with new platforms. It would help if I understood the logic behind these choices. I don't.

The best I can do is to support Pyboard, ESP32, ESP8266 and RP2 (if the latter improves).

[peterhinch]

Closing. The issue of code portability is discussed in this RFC.