diff --git a/doc/memos/rdm0003.md b/doc/memos/rdm0003.md new file mode 100644 index 000000000000..0be8b1705f24 --- /dev/null +++ b/doc/memos/rdm0003.md @@ -0,0 +1,167 @@ +- RDM: 3 +- Title: Board names for RIOT boards +- Author: Christian Amsüss +- Status: Active +- Type: Design +- Created: 2022-09 + +## Abstract + +This memo describes how boards are assigned names in RIOT. + +## Status + +This document is a draft and reflects the author's opinion. + +## Terminology + +This document does not attempt to define what "board" means within RIOT; +for the purpose of this document, +a "board" is the name for the group of devices built with the same `BOARD` variable. +A board's "technical name" is the corresponding value of the `BOARD` variable; +its "friendly name" is the text by which it is shown in documentation. + +A board's "defining representative" is a distinct piece of hardware +which the maintainers of that board picked. +This distinction is only relevant for boards containing devices created by multiple vendors; +typically, the other boards are (unauthorized) clones +or forks (of Open Hardware boards) +of the defining representative. + +# 1. Introduction + +In order to facilitate discovery of boards, +and to avoid confusion disappointment with advertised boards, +this memo describes the structured naming of boards. + +It makes recommendations as to which information is to be included in documentation +where it comes to naming, +but does not influence how boards should generally be documented, +or which boards are acceptable for inclusion. + +The memo describes a state of RIOT that is not immediately attained +when it becomes a consensus document; +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. + +# 2. Board naming + +The friendly and the technical name are for boards are derived +from a designation assigned by the vendor of the defining representative. +They are composed from the vendor's name and the name chosen by the vendor, +unless the vendor uses a well known prefix for the board. + +When vendor names contain components that are common in names but uncommon in use, +these are removed. +For example, "Microchip Technology Inc." is rendered as "Microchip", +Vendors that primarily use a particular shortened form of their name +are addressed by that name ("MikroElektronika d.o.o." uses "MIKROE"). + +As vendors commonly use multiple names for themselves or products +(eg. "Thunderboard", "Thunderboard Sense" and "SLTB001A"), +it is up to the board's maintainer to select pick a name +that is likely to be usable for a long term. +Marketing names are often unsuitable, +as vendors (such as "Galaxy A7") might release later revisions without a clear name distinction. + +For the **friendly name**, +the vendor's name and the product name are taken verbatim from the vendor, +including stylization and capitalization, as far as that is possible within Unicode: +Examples are "Arduino", "PHYTEC", "micro:bit" and "TRÅDFRI". + +A list of vendor names, along with their well known prefixes, +is maintained as part of the RIOT documentation. + +For the **technical name**, +the friendly names are reduced to the set of lowercase ASCII characters, digits and the dash (`-`) character. +As a general rule, whitespace in the name is replaced with a dash. +The precise conversion is left to the maintainer; +they are encouraged to consider the source language's and ecosystem's conventions. +For example, "TRÅDFRI" becomes "tradfri" +and "micro:bit" becomes "microbit" +(both because that's what the respective vendors use in their URIs). + +The vendor and product name are concatenated +by a space (` `) to form the friendly name, +and by a dash (`-`) to form the technical name. +If the product name uses a prefix out of the well known prefix list, +the vendor name and concatenating character are left out from both names. +In the context of the vendor, +the friendly name may be used without the vendor part, +for example when listing all boards from one vendor. + +Note that names can not be reliably split into the vendor and product name; +such a split can only be performed through inspecting metadata of the board, +if such are defined. + +## Unstructured vendors + +Some boards do not have a clear vendor, +but just "pop up" on online stores. +Examples are the "bluepill" series, +and the boards [documented as "nRF52 DK" at the time of writing](https://web.archive.org/web/20211015201641/https://doc.riot-os.org/group__boards__nrf52dk.html). + +Unless and until a well-structured vendor of a defining representative is found, +these are filed under the "Generic" (technical name: "generic") vendor. +The product name is assigned by the maintainer based on any common term for the boards. + +For such boards, +it may be useful to document links to typical sources, +preferably as Wayback Machine snapshots (given that sources may be volatile). + +# 3. Examples + +* The "Adafruit PyBadge" uses the technical name "adafruit-pybadge". + + There are other devices currently covered by this board + (the PyBadge LC and the EdgeBadge), + but the PyBadge is the defining representative. + +* The "Silicon Labs EFM32GG-STK3700" uses the technical name `silabs-efm32gg-stk3700`. + + The technical name for Silicon Labs is `silabs` as used in their web site. + +* The "STM32F7508-DK" uses the technical name "stm32f7508-dk". + + STM is a well-known prefix of STMicroelectronics. + +* The "BBC micro:bit v2" uses the technical name "bbc-microbit-v2". + + "BBC" is the well known prefix the Micro:bit Educational Foundation uses for their boards. + (The development stems from a project led by BBC Education, which explains the name's presence.) + +* The "Generic nRF52 DK" uses the technical name "generic-nrf52-dk". + + It is thus clearly distinguished from the nRF52-DK product from Nordic Semiconductor, + which is named "nRF52 DK" ("nrf52-dk") based on the vendor's well-known prefix. + +# 4. Aliases + +Aliases for board names may be used as a transition mechanism, +to address cloned / forked boards under their new vendor's name, +to remove the need for the "well-known prefixes" rule, +or when renames are necessary. + +A mechanism for such aliases is out of scope of this memo. + +## Acknowledgements + +Thanks to +Kaspar Schleiser, +Alexandre Abadie, +Marian Buschsieweke, +Koen Zandberg, +Martine Lenders +and Benjamin Valentin +for their comments, suggestions and review. + +## Revision + +- Rev0: initial document + +## Contact + +The author of this memo can be contacted via email at .