ROADMAP

[Gadgetoid]

Pinout 2024

The scope of this project is simple: rewrite Pinout from the ground up, while trying to avoid all the pitfalls I fell into while organically growing the original site.

I aim to achieve this by:

• Asking other people for input 😆
• Treating accurate storage of pinout information and its presentation in a website as two separate problems

Scope

This project will include

• An explicit schema for, and validation for, defining a board pinout in json
• Board pinout definitions for all Raspberry Pi versions back to the original board
• An open invitation for Raspberry Pi compatible boards to contribute their json definitions and be represented (somehow?) in the site
• A micro-site aiming to replace Pinout.xyz, but including separate documentation for all supported boards (default to Pi 5?)
• Dark-mode/light-mode themes

This project will not include

• Translation of any kind. Realistically I cannot maintain good translations, and no translations are better than bad ones I cannot verify. Past contributors of translations are encouraged to take this project and build/maintain their own version of Pinout. It's welcome to live in this GitHub org.
• Non-Pi compatible boards. I don't really know how to reconcile our add-ons (as in HATs and pHATs and mini HATs) database with no-compatible boards.

Chip & Board Definitions

A "board" is understood to mean a single-board computer, such as the Raspberry Pi 5.

Board definitions now live in https://github.com/pinout-xyz/pinout-2024/tree/main/boards and aim to paint a complete picture of the technical specifications of each board respectively. A board is a collection of chip signals routed to a header. At time of writing they also include some data about the type and orientation of headers in an effort to aid visual presentation. Whether they should be concerned with this is debatable!

Chip definitions live at https://github.com/pinout-xyz/pinout-2024/tree/main/chips and aim to document the signals available on a chip, independent of any board-specific implementation.

Board and Chip definitions are validated against the JSON Schema documented and stored in https://github.com/pinout-xyz/pinout-2024/tree/main/schema. This validation happens via GitHub CI Workflows but you can run it locally:

*make a virtual env you maverick*
pip install -r requirements-dev.txt
make pytest

Add-on Definitions

An "add-on" is considered to be a HAT or pHAT or Mini HAT or any add-on that uses one of the documented headers in some fashion. Traditionally Pinout would only document boards that used the 40-pin header, but this requirement has been relaxed on a case-by-case basis. We may consider removing these, since they do not adhere to the central premise of the website (pinout documentation, not marketing...)

Website(s)

The intention of this project is to generate one or more websites from the board definition files.

Whether or not that will happen in this repository is debatable. It might serve us better to collect board and add-on definitions here, and leave visual presentation to other projects. This would help keep concerns rigorously separated.

See #2 for progress on the website visual design.

How You Can Help

• Trying to port your Raspberry Pi compatible board to our json format - run make pytest to validate against the scema
• Help porting other Raspberry Pi boards
• Help get the json files correct and complete
• Track down high resolution photos of all the boards we currently document
• Offer suggestions, critique, comments and questions to help steer this project
• If all else fails, please chuck me a dollar, no really, it helps me buy coffee and fast food so I can stay on task 😆

References

• Raspberry Pi board comparison - https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#introduction
• ELinux WiKi for BCM2835 (Pi 1, 2?) - https://elinux.org/RPi_BCM2835_GPIOs
• ELinux Wiki for BCM2711 (Pi 4...) - https://elinux.org/RPi_BCM2711_GPIOs
• pinctrl FSEL lookup table - https://github.com/raspberrypi/utils/blob/b9c63214c535d7df2b0fa6743b7b3e508363c25a/pinctrl/gpiochip_rp1.c#L83

[lurch]

An open invitation for Raspberry Pi compatible boards to contribute their json definitions and be represented (somehow?) in the site

Non-Pi compatible boards. I don't really know how to reconcile our add-ons (as in HATs and pHATs and mini HATs) database with no-compatible boards.

Could you clarify what you mean by a "Raspberry Pi compatible board" and a "Non-Pi compatible board" ? 😕

Will this new repo also include add-on boards (i.e. HAT / pHAT / HAT+) or is this repo just concerned with the "main boards" ?

You may be interested to hear that a big comparison table recently got added to https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#introduction 🙂

---

I just had a quick look at https://github.com/pinout-xyz/pinout-2024/blob/main/schema/__init__.py (and the files in https://github.com/pinout-xyz/pinout-2024/tree/main/boards )

• not obvious what the alternating and around directions indicate
• it looks like valid_pin_subtypes is effectively valid_power_pin_subtypes ?
• perhaps it'd also be useful to include which corner of the header is "pin 1" ?
• perhaps valid_header_types should also include "ffc" ? 😉
• I'm not sure what makes your canonical_mode "canonical" 🤔
• Slightly wacky suggestion, but I wonder if it might be worth splitting things up even further, and having a section in the board JSON file which defines just the GPIO pins, listed in GPIO order; and then a separate section which defines which GPIO pin appears at which physical header pin? This would e.g. make it easier to cross-reference the GPIO section against the output of pinctrl funcs 0-28

[lurch]

P.S. Is "pinout-2024" just a temporary name? Or will this repo "look old" nest year? 👴

P.P.S. Can I assume that you won't be including WiringPi numbers? 🤣

[Gadgetoid]

It’s a temporary name, I’ll probably rename and archive pinout.xyz when it comes time to swap over.

Unsure about WiringPi- the project is still crawling along. They won’t be included in the board definitions in any case, it would be the static HTML manglers responsibility to handle those… somehow…

The splitting up suggestion is interesting. I, too, found the order of pins to be… confusing. Having a full document of chip signals and then mapping those to headers would also allow chip sharing between boards- IE: CM4 vs Pi4.

Such complete underlying Pinout documentation is a little ambitious for me alone (I’m not known for my focus and precision) but I could probably add the signals we’re using so far and hope they get fleshed out.

Splitting out could make “canonical” more of a presentation layer thing too. It’s just the “default” (except it’s not really a default) mode which is presented on the Pinout diagram presently. Canonical was the best alternative to default I could think up 🤣

But we probably need another json that sits between the board/chip data and supplements it for presentation… friendly names, icons, etc.

Alternating - the pins alternate from left to right of the header
Around - Pico style, maybe “clockwise” “counter-clockwise” are better terms? Do any headers do ccw? On a single row header, or multiple row header these terms are meaningless - maybe it’s better just to be explicit about coordinates in your “header” definition files…

[Gadgetoid]

Okay I have split boards into "chips" and "boards", though I still have "canonical_mode" for now 😆

It's a lot cleaner and more rational, and a lot more expressive, though it's an extra level of indirection when generating visualisations from the data- the point of the data is not to make visualisation easy, it's to make it correct.

[lurch]

You seem to have missed the comments I placed above the horizontal-divider 😉 (I was attempting to separate general-project comments from schema-specific comments)

[Gadgetoid]

Oh sorry, standard ADHD "only read the last part of any wall of text" problems 😆

Could you clarify what you mean by a "Raspberry Pi compatible board" and a "Non-Pi compatible board" ? 😕

I guess the more apt term is "clone." Let's go with "clone." If it's like- to pick a totally random example- the BeagleY-AI and intends to be pin-compatible then I don't super mind hosting documentation for it. It's useful for me to have some of these boards on-hand so I don't footgun myself into another non-standard GPIO mess.

Will this new repo also include add-on boards (i.e. HAT / pHAT / HAT+) or is this repo just concerned with the "main boards" ?

Yes. Migrating add-ons over is essential before the new site can replace the old. It needs to be 1:1 feature compatible, basically. But better, better where it can be better.

You may be interested to hear that a big comparison table recently got added to https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#introduction 🙂

I find Pi's documentation borderline unusable because everything is on one long, long, long page and my brain just checks right out. But actually, yes, the table up top is very useful!