I especially love the ability to flip and reverse things, since I try to avoid comparing any two objects in different orientations, to cut down on mistakes.
It would be really cool if the community had a more general purpose open standard interactive diagramming tool for this sort of thing.
I guess the easy way would be to mark up photographs with pin locations, which would map to pins in a table, allowing for multiple tables in a document.
I'm not sure how you'd capture the data in a way that could be rendered to something like a screen reader or a more abstract diagram though, without a lot of complexity and edge cases.
Would it be enough to just verbally describe the mapping between pin numbers and the physical layout, as in "Across then down, starting at upper left", or would you need a meta data scheme for that?
There are a surprising number of pitfalls, since there's always some complexity most top-level diagrams don't reveal, but I feel is necessary to capture/avoid duplication of work- specifically, I mean documenting the pinout of the chip (RP2350, ATMEGA32U4, STM32H750, RP2 etc) and then translating that to a board layout.
I think the closest I've come is a prototype Pinout rewrite which started with chip [1] and board [2] JSON files.
Then, as you explore, there's the whole problem of presenting this information. I chose to capture information such as header type, orientation and pin-count but sometimes a header is too small (or there are too many headers) to document in-band so the kinda skeuomorphic presentation of the Pico pinouts doesn't work.
Perhaps that's where something like the minimap [3] from my "advanced" RP2350A pinout comes in.
Having a small representation of the board with the pin headers separate could work. It's been a while, IIRC a Fritzing [4] part involved creating a vector graphic of a part and naming the individual pin objects such that they could be mapped to a table of signals. I think SVG is compatible with this approach but... yeah, requiring people to create detailed board artwork (as good as it looks) is a stretch. The same could work for a good photo and just a table of offsets, as you suggest.
TLDR: This is a great idea and something I've wanted to do for ages. But I don't think I've got enough breadth of experience to do it alone.
1. https://github.com/pinout-xyz/pinout-2024/blob/main/chips/bc... 2. https://github.com/pinout-xyz/pinout-2024/blob/main/boards/r... 3. https://rp2350a.pinout.xyz
The bigger ones have PHYs for USB HS, USB-C (5Gbps) and 10/100M Ethernet integrated (!). And their development environment (Mounriver Studio) isn't too bad - I didn't had the immediate urge to port everything to CMake/VSCode.
But they need some kind of pin planning tool. It's awful to use the datasheet and find the correct pin functionalities and their mutual exclusions... STM32 mastered this with their STM32CubeIDE tool: select a feature (like USART1) and the right pins light up - alternate pins are easy to locate.
They also should clean up their license mess on OpenWCH (their GitHub page). Lots (all?) of their HALs are Opensource - but the right version with right SPDX tags are often a bit hidden.
I made a basic one for the RP2350- https://rp2350b.pinout.xyz/
Though STM32Cube has a very different approach, handles lots of mutually exclusive features and peripherals and a bunch of extra stuff for controlling code gen IIRC.