"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?