"Core" vs "platform"

[alranel]

Various help and error messages use the words "core" and "platform" interchangeably, as they are synonyms in the Arduino context. This might create confusion, so it would better to be consistent in all messages by choosing a single term.

[masci]

In some parts of the README you can spot few places where I wrote platform core instead of just core to highlight this interchangeability but it's a palliative. I will fully support any initiative to consolidate the terminology organically and across the whole codebase.

I think addressing the problem right now would be best because major version 0.x gives us a certain degree of freedom in changing user facing APIs.

[lorforlinux]

Hi, I think we should choose to use the term platform for referencing the software part used for the programming of the board, This Definition of the platform makes it clear.

Definition - What does Platform mean?
A platform is a group of technologies that are used as a base upon which other applications, processes or technologies are developed.

and we can spare the term core for the hardware core of our board.

[matthijskooijman]

I actually think (based on the terminology used in the Java IDE code - I have not looked at arduino-cli), that there are a few related but distinct concepts. For example, consider the regular Arduino core, which lives at: hardware/arduino/avr/cores/arduino (and is sometimes referred to as arduino:avr:arduino, though at least in a "core reference", the "avr" part is implied).

• "Package" is used to refer to the "hardware/arduino" directory above. A package groups related platforms/architectures, typically from the same vendor. Different packages would also usually indicate different vendors.
• "Platform" is used to refer to the "hardware/arduino/avr" directory above. Different platforms within the same package are intended for different architectures, and a single platform has a single architecture, so platform and architecture are sometimes use interchangeably, but I believe that "avr" is the architecture (which might also occur in different packages), but "arduino:avr" would be the platform.
• "Core" is used to refer to the "hardware/arduino/cores/arduino" directory. This directory contains the actual core files (e.g. the code that runs on the board, in addition to the sketch and libraries). Typically, a platform only has a single core named "arduino" (which indicates the core exposes the Arduino API), but sometimes a platform has multiple cores. Usecases that I can think of are:
  1. when within a single platform/architecture there are boards/microcontrollers that are distinct enough that a completely different implementation is warranted, such as the ATTinyCore that has a different core for the "modern" attinies
  2. when a core does not implement the Arduino API but something different. This is somewhat done by Cosa though that only implements the "cosa" core, not also the "arduino" core. Also this usecase does not really match, since the core to use is always specified by the board, so offering multiple cores for the same board means multiple entries in boards.txt (or a board-specific menu).

Since a platform typically only ships a single core, these two terms are often used interchangeably, but there is a technical difference.

I can imagine that changing the terminology could be useful, since these terms were chosen long ago when we did not really know how things would be used in practice. However, if we change things, we might need to settle for terms that are completely different (e.g. do not reuse core to refer to what used to be called platform), since that would highly complicate things. OTOH, if core and platform are already used interchangeably, reusing core for platform might not be so harmful after all.

Looking at the current terms:

• I do not really like "package", since it suggests that everything in a package is installed together, but in practice the unit-of-install is the platform. A package just groups together multiple platforms from, typically, the same vendor, so maybe "vendor" might be a better term?
• "platform" is vague (in general usage, I think that "platform" and "architecture" exist in the same space, e.g. "Arduino" could be a platform, but also "AVR", or "ARM", or "Mbed", etc.). In practice, this is the unit of install and what people refer to when they say "I installed a third-party core" (nobody actually says "platform", I think), so maybe this is what should be called "Core" (or is there a better word for this that is not ambiguous with old terminology)?
• "core" is technically correct, but not used like this in practice. I can imagine these would be called "subcore" (though that might imply that multiple subcores can be used at the same time), or "core implementation" maybe? Not sure here...

[lorforlinux]

if core and platform are already used interchangeably, reusing core for platform might not be so harmful after all.

@matthijskooijman I agree with you on this.

Since a platform typically only ships a single-core, these two terms are often used interchangeably, but there is a technical difference.

indeed! they are.

we are required to have more discussion before applying any patch for this one!

[thekunalsaini]

I think core is to be used.

[pra-dan]

I think, from the comments above, the first conclusion that can be made is:
We have a common understanding of the term core but platform is understood as architecture, arduino/avr as a family and the firmware (software for the board).

To limit the scope of discussion and to give it a direction. we should only focus on the platform part. Surprisingly, according to me, platform also meant the hardware. So, that's an addition to the problem :(

[matthijskooijman]

To limit the scope of discussion and to give it a direction. we should only focus on the platform part. Surprisingly, according to me, platform also meant the hardware. So, that's an addition to the problem :(

I'm not so sure. I guess the main problem is that the "official" terminology is package - platform - core. However, in practice people do not often refer to the package and core much, but only to the platform. However, when they refer to the platform, they often call it "core" or "board package" (the latter is actually encouraged by the fact that you can install them using the "boards manager"). Given that both terms ("core" and "package") are currently the official terms for other things, I suspect we also need to look at these other things (otherwise terms will become ambiguous...)

[pra-dan]

In response to the statement by @matthijskooijman,

"official" terminology is package - platform - core

A good instance of the use-case may be seen in issue #252

[cmaglie]

Let me recap the glossary with a bit of schematization.

To uniquely identify a board the official way is the FQBN, for example the Arduino UNO board is arduino:avr:uno.
In the FQBN arduino:avr:uno:

• arduino:avr is the Platform where:
  • arduino is the Package (or Packager or Vendor)
  • avr is the CPU Architecture
• uno is the Board Identifier (or just Board)

Inside the Platform there is a boards.txt definitions file that specifies, for each board, a build.core property that tells which Core to use for that particular Board. For example uno.build.core=arduino, in this case:

• arduino is the Core used by the uno board.

So in conclusion, we have that:

• FQBNs maps 1:1 with Boards.
• a Platform is a container of Boards.
• a Platform is a container of Cores.
• each Board uses a Core.
• a Packager is a container of Platforms

Just to give some examples of the above:

• arduino is a Packager
• arduino:avr or arduino:samd are Platforms
• arduino:avr contains a Core named arduino
• arduino:avr contains many Boards, for example arduino:avr:uno ("Arduino UNO") or arduino:avr:mega ("Arduino Mega 2560")
• arduino:avr:uno uses the arduino Core
• arduino:avr:mega uses the arduino Core

now, given the above, I think we can just use the term "Platform" without ambiguities.

The cons that I can see is are that:

• we already used core in the arduino-cli core subcommands, so we have

  arduino-cli core install arduino:samd
  arduino-cli core search Uno
  arduino-cli core uninstall arduino:avr
  

  and it should really be changed to

  arduino-cli platform install arduino:samd
  arduino-cli platform search Uno
  arduino-cli platform uninstall arduino:avr
  

• people are used to use Core and Platform as synonims. IMHO this can still be tolerated, since the term Core in the real world is used basically only as a synonim of Platform, BTW we must start to deprecate the usage of "core" and stick to Platform from now on.

[matthijskooijman]

Great summary. Some more additions:

• In practice, the term "Board package" is also used to refer to platforms, I think (board because the end user does not care about cores or platforms, they just want "support for their board" and "package" because it is the unit of installation).
• It is interesting to observe that some platforms are really just "board packages" (they contain a boards.txt but refer to the core from another platform). Some platforms have both: The define boards and ship their own boards. I guess there are no platforms that ship a core but define no boards, though that is technically possible.
• A con of the term "platform" to refer to platforms, is that the term is used for a lot of other things in other contexts (e.g. the web is a platform, x86 is a platform, Windows is a platform, etc.), so it does not really apply that well to the platforms we are talking about here. This is probably also why in practice people (including us developers) are not using "platform" much, and instead fall back to "core" or "board package".
• We can say "Platform is the correct term, so everybody should use that" and be done with it, but I am doubtful that people are actually going to start changing their terminology. Renaming the arduino-cli command, and maybe also updating the Boards Manager (Platform Manager?) UI in the IDE would help here, but do we really want to do that? Or should we adapt the terminology to match the mental model people have of this?

[cmaglie]

Let me clarify a bit: I suggested to change the cli command and to start using the correct terms in the documentation / discussions and nothing else :-) so the GUI of the various IDE will remain the same.

We need to take apart users from developers I think:

• the Arduino user, doesn't care about internals (platforms / cores / architectures etc.), he just want to use his board. The only term that has a meaning for him is the board name, the phisical object he has in his hands, so it makes perfectly sense to continue to call the GUI "Board Manager" and allow the user to search using the board name and find the "package" he needs to install (again it doesn't matter if the "package" content is a platform a core or whatever, there is the concept of "package to install" that is general enough and sufficient).

• the Arduino developer on the other hand should have a better understanding of the internals, so it makes sense to start using the term platform in the correct place instead of core. Moreover:

  • the experienced developers already uses core and platform interchangeably, probably they uses core more often, but they already knows the difference, so I don't see any problem for them to swtich
  • all the others instead may only benefit from using the correct terms from the beginning.

[pra-dan]

With the user and developer point of view considered, what else can we expect out of this thread/discussion ?
Is there any scope for more?

[alranel]

So, according to what @cmaglie says, we should rename the ArduinoCore-* repositories to ArduinoPlatform-*.

E.g. the ArduinoCore-samd repository is actually a platform, which contains several boards (or, maybe better, board definitions?) and one core (arduino) referenced by such board definitions. I'm really concerned about clarity and cleanness because that impacts the overall feeling beyond functionality.

(To my taste, platform is a very generic word that may sound vague in some contexts. Arduino in its entirety is known as a development platform :) Ideally we would use something like platform package or platform implementation whenever possible in documentation. For the same reason, I'd suggest board definition.)

Let's try to draft definitions to see whether we're all on the same track:

• A platform package or platform implementation (sometimes referred to as Board Support Package) is a component that allows the Arduino tools to compile and upload sketches to a given set of boards, as well as performing other operations such as burning bootloaders or additional firmwares. A platform implementation is named according to the vendor:architecture schema (e.g. arduino:avr) and usually groups boards based on the same CPU architecture although any grouping criteria can be used by vendors.
• A core is the actual Arduino API implementation included in a platform. Usually all boards defined within a platform share the same core, but it's possible to include multiple cores in a single platform to be referenced by different boards. The core names are scoped locally within each platform and they are not supposed to be referenced anywhere outside it.

Basically I would hide core as much as possible, except when describing the internals of a platform.
Regarding package, I would replace it as much as possible with vendor which is more clear (also because as @matthijskooijman was saying, that's not the installation unit).

How does this sound to you?

[matthijskooijman]

(To my taste, platform is a very generic word that may sound vague in some contexts. Arduino in its entirety is known as a development platform :) Ideally we would use something like platform package or platform implementation whenever possible in documentation. For the same reason, I'd suggest board definition.)

I guess that in "arduino:avr:arduino", "avr" is actually the platform, while "arduino:avr" (or really the ArduinoCoreAVR repo) would be the "Platform implementation" (or "Arduino implementation by "arduino" for the platform "avr").

Regarding package, I would replace it as much as possible with vendor which is more clear (also because as @matthijskooijman was saying, that's not the installation unit).

But "package" and "vendor" are different things? I can't say "I'll install the Arduino AVR vendor", right (but I can say "install the Arduino AVR package")?

and usually groups boards based on the same CPU architecture although any grouping criteria can be used by vendors.

Other grouping can be used, but the second level is not completely free-form, but actually expected to be the "architecture" (aka platform), i.e. it can be specified in a list of supported architectures in a library and when creating derived cores/platforms, this value should match the parent platform exactly.

Let's try to draft definitions to see whether we're all on the same track:

Your definitions seem ok to me.

[matthijskooijman]

(To my taste, platform is a very generic word that may sound vague in some contexts. Arduino in its entirety is known as a development platform :) Ideally we would use something like platform package or platform implementation whenever possible in documentation. For the same reason, I'd suggest board definition.)

I guess that in "arduino:avr:arduino", "avr" is actually the platform, while "arduino:avr" (or really the ArduinoCoreAVR repo) would be the "Platform implementation" (or "Arduino implementation by "arduino" for the platform "avr").

Regarding package, I would replace it as much as possible with vendor which is more clear (also because as @matthijskooijman was saying, that's not the installation unit).

But "package" and "vendor" are different things? I can't say "I'll install the Arduino AVR vendor", right (but I can say "install the Arduino AVR package")?

and usually groups boards based on the same CPU architecture although any grouping criteria can be used by vendors.

Other grouping can be used, but the second level is not completely free-form, but actually expected to be the "architecture" (aka platform), i.e. it can be specified in a list of supported architectures in a library and when creating derived cores/platforms, this value should match the parent platform exactly.

Let's try to draft definitions to see whether we're all on the same track:

Your definitions seem ok to me.

[per1234]

A platform package or platform implementation (sometimes referred to as Board Support Package)

Please, let's only have one single term.There is no benefit to having three new terms. My preference is "boards platform". I have been finding that this works well in practice. For example:

This is defined in the Arduino AVR Boards platform

The commonly used platform names often end in "boards", so the "boards platform" term evolved naturally from that.

But I'm happy with anything other than "core".

Adafruit uses "Board Support Package", but my research indicated that the original meaning of "Board Support Package" is not quite the same as an Arduino boards platform.

The core names are scoped locally within each platform and they are not supposed to be referenced anywhere outside it.

Almost certainly irrelevant to this discussion, but core libraries can be referenced by other platforms:
https://arduino.github.io/arduino-cli/dev/platform-specification/#core-reference

Basically I would hide core as much as possible, except when describing the internals of a platform.

My suggestion is that we augment the term to help differentiate the new specific usage of the term "core" from the old ambiguous use of it, and never again use the term "core" alone. Something like "core library".

[WestfW]

I guess there are no platforms that ship a core but define no boards

I'm late, but I'd argue that the popular MCUDude and SpenceKonde "cores" (MegaCore, ATtinycore, etc) do not define "boards." (they have boards.txt entries, but they're mostly for generic pinouts of individual CHIPs rather than productized boards.)