RIOT/doc/memos/rdm0003.md

- 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 <mailto:chrysn@fsfe.org>.