RDM: Naming boards

[chrysn]

Contribution description

I was recently very frustrated with how off-brand boards were documented.

This is supposed to fix this:

final version rendered

Issues/PRs references

There are probably issues around for concrete boards / board groups whose naming was problematic, but I haven't found them yet.

[chrysn]

As for a transition plan (which I think is best discussed outside of the text, which would persist after transition is over), I'd suggest that

• new boards are named following the conventions,
• particularly broken boards are renamed and fixed without aliases in place,
• some aliasing mechanism is added (which may just be a simple Makefile magic table, so that everything after some line in the Makefile just sees the canonical name). Some aliases may be deprecated, or we just leave them around.
• all boards are renamed (which is now non-disruptive because aliases are in place).

There might be parallel efforts in restructuring the documentation (eg. grouping the list by vendor, and/or ensuring that the doxygen names of the boards match the technical names), but that should be independent.

[kaspar030]

I think this is a great way of getting reviewers!

[aabadie]

#7976 might be useful for board aliases. It's a bit dated but could already be a good start.

[chrysn]

Thanks, yes, #7976 would pretty much be the alias solution. (It even looks like it'd be extensible if we want to handle the "well-known prefixes" part just through aliases, although then we'll have to be wary of questionably-trademarked vendors like stm32-base...). I'd hope that agreeing on a structure for names would not depend on progress on the aliases, but I'm trying to revive that anyway.

[bergzand]

Thanks for tackling this

[kaspar030]

ACK.

[chrysn]

Thanks for you input and reviews. In fixups, I have

• placed an explanation of BBC being a well-known prefix of Micro:bit Educational Foundation, replacing a "this needs a better explanation" comment,
• accepted typo fixes,
• removed the motivation section (that was announced to be removed), and
• added an acknowledgements section.

I'd let this sit for a few days more (which is no requirement of the process, but something I consider good practice), and unless NACKed, will

• set the status to consensus,
• reflow the text to conform to the fixed-width format of RDMs,
• set the RDM number (probably 2) in the header and the file name, and
• merge this.

[benpicco]

That's the only bit I'm a bit conflicted about.
Usually those boards do have a vendor that produces them, but they might just not be very well known.

E.g. with the classic bluepill boards, that's what they were known as. Slapping a noname- prefix would not have helped here at all.

And there are other boards from known vendors, e.g. samr21-xpro that don't contain the vendor name. Should that be microchip-samr21-xpro? (And back when it was merged it would have been atmel-samr21-xpro - do we rename boards after acquisitions or to we retain the original name?)

[chrysn]

Can you find the vendor that produces the black- and bluepill boards? I couldn't, so far.

For the samr series, there may be a useful prefix -- SAM? ATSAM? I don't know these well enough, what's their naming scheme?

Vendor acquisitions are an interesting issue I have not considered, but I'd still rather use aliases here than hope that nobody ever produces collisions, especially when boards are named by vendors in an easy-to-confuse way, such as the "nRF52840 MDK USB Dongle".

[chrysn]

Quoting some conversation with Ben I deem relevant from matrix:

B: If I understand the proposal correctly it would result in a big rename of e.g. nucleo-f030r8 -> stm-nucleo-f030r8
C: New boards would be named like that, and documentation can start using consistent names without starting anything destructive. I wouldn't start renaming any board just-because-rdm, at least not unless we have an alias mechanism in place that makes that rename compatible.
B: Are new nucleo boards then grandfathered in?
C: If it helps consistency within that board family, I don't see a reason not to. [...] for large groups of comaintained boards it probably makes sense to take the decision between purity and practicality in a different direction.

[maribu]

The genuine vendor of the bluepill boards (and other colors) is noname ;-)

[chrysn]

And before I miss that aspect over the topic of going-on-with-nucleo-boards: assuming we find no vendor for the black/bluepill boards, or the same situation arises with a different board (I don't have a concrete example at hand, but not for lack of off-brand boards, but because those I can find details on quickly all happen to be compatible clones of better-described boards), how would you name them without implying that we know how to characterize that board?

[benpicco]

I mean currently we just leave it out, but if that's no longer an option due to consistency, I guess noname or generic are fine.

[maribu]

generic doesn't sound so judgmental as noname. Therefore, I think generic is better.

[chrysn]

It's less judgemental but has has implications of universality -- as if some step of abstraction (generalization) has happened. unknown would be accurate but harsh (and hey, it's not our lack of trying!). Maybe various? (as in "Various Artists"; if it does turn out there is a single one we could still alias/rename, as we'd do if the producer of The Blackboard just stepped forward). Or genericbrand / offbrand or acme based on the Wikipedia article on that topic?

🚲

[chrysn]

Let's just go with "generic".

[chrysn]

Suggested change

	the technical aspects of migrating to that state are discussed in the RDM pull request.
	the technical aspects of migrating to that state are discussed in the RDM pull request.
	Until mechanisms are available for compatibly renaming boards
	(such as those of section 4),
	boards should not be renamed merely to comply with this scheme,
	and new members may still be introduced to existing families with names matching preexisting conventions.

This would make the plan of not-breaking-things-just-because-rdm more visible, and should address the concerns of #18589 (review).

[chrysn]

Added based on the thumbs-up.

Procedurally, I think next steps after the RDM are documenting vendors and known prefixes, and then creating a tracking issue of boards known to not match the new scheme (also gathering new names without renaming). That issue would sit unresolved until aliases are merged, and can then be closed by establishing the relevant aliases.

[miri64]

If there is still time, before this is merged, can you also please (maybe as a final step before merging) reformat the raw text, so it is also somewhat easier to read. While nice for version control, to have ever sentence (and half-sentence) in a line, it makes it a bit hard to read when the RDM is e.g. opened in a terminal.

[chrysn]

Yes, that's one of the final steps on my list. (And as there has now come in controversial feedback, I'd give us some more time to finish the bikeshedding of noname/generic(brand)/offband/acme).

[MrKevinWeiss]

So a few things:

• ✔️ vendor+product+sn is usually a common we to identify unique devices, this could better allow for that by encoding the vendor into the name
• 😬 This means extra typing for users when running boards, small issue, but introduces more typos and makes readability of copy-paste commands a bit harder
  • Though this can be offset by alias somewhat
  • Also autocomplete for boards could help
• 🤨 Should we also encode revision data in as well?
• 🤨 What about also assigning simple numbers to the board as well (I am thinking how protobuf deals with backwards compatibility)?
  • If my everyday is working with say and esp32-wroom-32 and a samr21-xpro liek can be a lot easier if I get used to BOARD=3 make and BOARD=62 make rather than typing...
• ✔️ Better categorization when looking at the sorted list

I feel like this is a step in the direction of providing boards with more metadata that would eventually allow things like skipping some boards for CI, though I image it would not all be encoded in the directory name.

[MrKevinWeiss]

Also should we say anything about matching some label of the board. Ideally we should be able to look at a board and know what the name is (which is not the case with the phytek boards).

[miri64]

• If my everyday is working with say and esp32-wroom-32 and a samr21-xpro liek can be a lot easier if I get used to BOARD=3 make and BOARD=62 make rather than typing...

How would this numbering work? What criteria makes a board Number One? IMHO, this is something we can leave to the user, if they would put an order to board, As such, I'd say, once aliasing is in place, this should be done via some local aliasing and thus, a potential point for the wishlist for aliasing is "allow for user defined board names" ;-).

[chrysn]

a potential point for the wishlist for aliasing is "allow for user defined board names" ;-).

Briefly continuing out-of-scope: This could also be "third party defined names". Like, if someone came up with The Awesome Numerology of Boards, `BOARD=tanob:42` could become an alias to whichever name we use for that board.

[benpicco]

Should we also encode revision data in as well?

Maybe a bit off-topic, but we have

ifneq (, $(BOARD_VERSION))
  BOARD := $(BOARD)-v$(BOARD_VERSION)
  CFLAGS += -DBOARD_VERSION=$(BOARD_VERSION)
endif

I know BOARD_VERSION is currently used a bit different in upstream RIOT, but I'd say using it as an optional postfix could be useful in general.

[chrysn]

[oups, that was sitting unsent here while I've been replying via mail...]

typing

Aliases can help, and so will the known prefixes (which eventually might be handled by aliases). Yes it's more even to copy-paste, but especially when copying from documentation it also gives immediate information that helps match the value on screen with the box before you.

revision data

That's getting into "what is a board" (which is good but maybe going too far here). The way it is now (and unchanged through the RDM draft), a board is "everything that is built from setting that BOARD variable". If it so happens that the same code (possibly with runtime switches to detect whether a variant is the case) can serve many variants, the variant does not need to be encoded. Once a variant is relevant to the generated code (even in the linker script, see current blue/-blackpill boards), it becomes a different board.

Picking up benpicco's point -- that we can do, but we should be aware that this is something different than aliases. An alias would be resolved and then passed on in resolved form, it's two names for the same thing. If we allow this, we'd have different boards sharing a code base, so we can ifdef around things, rather than having two code bases where one just pulls in common components from the other. It may well make sense to do something like that, though.

matching a label on the board

That's nothing we can help with. With some boards, creators will be consistent between how they label the box / name the item they are selling and what they print on the board, with others, not. Once we have aliases, we can consider whether some labels on boards also make good aliases.

numbers

I'm not a big fan. On the user interface, it's inviting subtle errors (we're in the 3 digits already, and was it board 157 or 175?). On the management side, it'd need more coordination (can't handle numbers in conflicting PRs), and if we wanted to give protobuf style immutability guarantees, we'd need a way better understanding of what it means for a board to be compatible than we have now.

[MrKevinWeiss]

Good good, drop the numbers idea.

Other than that, it is nice to have some structure and there is backward compatibility so I give it my ACK.

[chrysn]

This has the necessary approvals, and as far as I've kept track, all concerns were addressed with resolutions accepted (implicitly assumed when following a suggestion in the concern) or claimed to be out-of-scope (in particular, board versioning and inheritence).

I've squashed to get green CI, and am leaving this for another 24h late review period before pushing the merge button.