Is there any kind of standard for the naming of peripheral pin assignments? If not, can we please implement one?

[gitcnd]

It would be nice if code was portable. Unfortunately, I'm not aware of any standards (except for the poorly supported Arduino LED_BUILTIN) for the naming of things like LED pins (and whether or not the logic on them is inverted), SD_CARD CS/SCK/MISO/MOSI pins, LCD displays (and their type and size etc), speakers and amplifier circuits, ambient light sensors, Touch-display pins, and in general the entire gamut of hardware options.

I'm also unaware of any attempts to try and create any kind of file format which could be added to a build so that programs running on the hardware can use "well known" names for things that require assignment.

Does any of the above exist?

Please can we put our collective heads together and come up with something to solve this?

• Where's the best place to store circuit-device specific assignments (in a file on the OS? inside the firmware itself? something else?)
• What's the best format for such a file to be in? (name/value? json? ...)
• What's the best-practice for the names that belong to these things? (SD_MISO? MISO_SD? SDCard.Pin.Miso? ...)

I think our community would be greatly advantaged if something like this was built/specified/included, so that manufacturers of boards can simply supply this file (or just put it in a "copy/paste" section inside their store listing) - because we as users will then know that we will be able to painlessly get things working, and we will be able to share and contribute our code to others with different boards, whereupon it will just magically work there as well...

[gitcnd]

... and maybe also some consideration of recommended separation of bus settings, and names for those, so contention between devices (e.g. different speeds) can be managed better by driver writers (e.g. SD Card and LCD Touchscreen), along with some mechanism so we can have our code support SPI bus speed etc re-initialization (and only when required)

[jimmo]

Just to clarify, are you raising this specifically to MicroPython or by "our community" do you mean embedded programming in general?

FWIW, MicroPython has support for pin naming (via the pins.csv file). The idea being that you can write your code using e.g. machine.Pin.board.FOO and your code will run on any board that maps a FOO pin. When someone defines a MicroPython board, they write this file based on what's typically written on the silkscreen.

[gitcnd]

Yes - specifically to MicroPython (don't get me started on the wider embedded community - I've been on panels trying to sort out the IoT security sh*tshow for a few years now - nobody cooperates with anyone else, and the higher up the chain-of-responsibility you go, the worse it gets - all the way to government which is total paralysis - but I digress). I've been looking at code and drivers from a few dozen random places, and nothing works "out of the box", but after I fuss around in datasheets to find pin assignments, and replace all the hard-coded numbers in peoples files, everything seems to work nicely.

I've been writing MCU drivers and other things for probably a decade or so now (just hobby stuff - low level C/assembly, but all non-python though) - I've never once come across or heard of any "pins.csv" before (update - nor it seems has google? esp32-cam "pins.csv" got me 3 results.. to expired domains...)

Maybe it's an educational problem? - nobody's telling anyone about this, nor making the files available for anyone, nor telling anyone to use names instead of hardcoding pin numbers, etc. I've flashed about a dozen micropython boards this week from .bin files I've found in half a dozen different places, and yeah, still never seen anything by anyone about defining names for any pins; not to mention I've never gotten (or seen or been told about) any such files for any of the 50 or so ESP32 boards I've accumulated of the last few years :-(

Heck - even half the boards I use in Arduino don't bother to define LED_BUILTIN - it seems to be an industry-wide problem.

machine.Pin.board.FOO sounds too simplistic/naïve to be useful though? e.g. What if it was an LED? How do you turn it on? [the level differs between boards], What if your LED is RGB? Or RGBW? or RGBWW? or WS2812? or what if you need specific SPI data rates (what's a generic portable way to resolve multiple devices with different needs) ... working this out is not a trivial thing.

And as for "FOO" - that's useless if there's no master standard - machine.Pin.board.SD_MISO and machine.Pin.board.MISO_SD or machine.Pin.board.SD_DAT0 (those last parts being actual circuit markings from just me getting my SD working today) ... where's the list of what people should be calling these things? Or the never-ending infuriation of clock pins being named SCK or CLK or other random abbreviations.

So yeah... now I'm even more confused than before I asked the question :-)

[andrewleech]

machine.Pin.board.FOO sounds too simplistic/naïve to be useful though? e.g. What if it was an LED? How do you turn it on? [the level differs between boards], What if your LED is RGB? Or RGBW? or RGBWW? or WS2812? or what if you need specific SPI data rates (what's a generic portable way to resolve multiple devices with different needs) ... working this out is not a trivial thing.

Yes this is the basic problem, every piece of hardware is just different. If micropython tried to provide a common pin naming scheme for all boards it would probably end up be just by pin numbers, eg pin1, pin2, pin3 etc then every board could have that and code would "run". However then users would still need to look up datasheets to figure out what pin1 does :-D

But in reality, MCU's all call their pins different things, esp's generally have just a pin number but stms have PA0, PB0, PC5 etc for the different gpio banks so you can't just apply a single number / name scheme to everything without a lookup table somewhere to users to reference.

Alternatively as @jimmo said micropython board definitions can add pin aliases to put user friendly names on pins that map to board silkscreen lables or functions which is great for a user of that board, but of course software using those pin names won't work on a different board.

The best solution I know of is to write your bulk code as a library that has pin objects passed in, then users can define the pins that suit their board and just pass them to the library!

[scruss]

I've never once come across or heard of any "pins.csv" before

It's a MicroPython thing: pins.csv - 159 files in micropython/micropython.

Adafruit's very early CircuitPython versions were basically "let's add consistent pin names and functional code to MicroPython". Very quickly they hit the complete/consistent problem (you get to pick one: complete or consistent) when they used different MCU vendors for their boards, though.

[peterhinch]

The best solution I know of is to write your bulk code as a library that has pin objects passed in, then users can define the pins that suit their board and just pass them to the library!

Absolutely. This also extends to interfaces: pass UARTs, I2C or SPI instances, as objects. Then you can confine all hardware dependencies to a small, user-defined config file and write the whole library in a hardware-agnostic fashion.

[cboostwvanooijen]

Small contribution: when naming things, first don't surprise the user, so if the datasheet or the silk on the board names the pins, do (at least) use those names. (If the datasheet and the silk disagree - well, we live in a shitty world ... maybe provide both. That is, if the two name sets don't collide....)

If you get to choose names, order the words ouside to inside, like a set of objects. So sd_miso, not miso_sd. (I prefer snake case, but that is a different war.)

Whenever reasonable, prefer to have signals active high. I am a great fan of OO and decorators, so I often use an inverter (invert pin decorator) to adapt this convention to the hardware world, which is often active-low.

Context: I am a former embedded head lecturer. Naming things was a major subject in my courses.

[robert-hh]

Actually there is a kind of common practice. The ports usually have two name groups for pin, as visible in the Pin.board and Pin.cpu classes. Pin.cpu uses the names from the CPU data sheet. Pin.board uses the names of the board silkscreen as preferred option, if existing, or the board documentation as second choice. Some ports do not have the Pin.board class populated, like the RP2040 or ESP32.
Some ports allow to use an integer for a Pin. Then things get blurred. Most of the time the integer is the GPIO number. That's the case e.g. for RP2040, ESP32, NRF and SAMD. If there are more than one GPIO bank, then the numbers are extended, e.g. 0..31 for for PAxx, 32...63 for PBxx, and so on. But it is NOT the physical pin number of the board. That's a common mistake with the RP2040 board. At some other ports the number is the Index into the pins.csv file, like the MIMXRT port. For this port that matches with the "Dnn" board names, so 12 maps with "D12".