From fc251822564ad704974cb38fad33aec07a8c54eb Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 26 Aug 2020 08:02:14 -0700 Subject: [PATCH 1/4] Document the programmers.txt configuration file of the Arduino platform system This file is used to define external programmer configurations to be used for burning bootloaders and programming Arduino boards. NOTE: the example programmer snippet is missing some of the properties that are defined in the real programmer definition in the Arduino AVR Boards platform. After a lot of investigation, experimentation, and even consulting with the original author of the code, I was still unable to find any use of these properties in the current or any past IDE version that supported the 1.5 platform format. If these properties have no purpose, they they only represent a source of confusion and maintenance burden for platform developers. --- docs/platform-specification.md | 38 ++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/docs/platform-specification.md b/docs/platform-specification.md index a4044164b4c..628ce9aedae 100644 --- a/docs/platform-specification.md +++ b/docs/platform-specification.md @@ -529,6 +529,44 @@ Adding a **hide** property to a board definition causes it to not be shown in th The value of the property is ignored; it's the presence or absence of the property that controls the board's visibility. +## programmers.txt + +This file contains definitions for external programmers. These programmers are used by: + +- The [**Tools > Burn Bootloader**](#burn-bootloader) feature of the IDEs and + [`arduino-cli burn-bootloader`](commands/arduino-cli_burn-bootloader.md) +- The [**Sketch > Upload Using Programmer**](#upload-using-an-external-programmer) feature of the IDEs and + [`arduino-cli upload --programmer `](commands/arduino-cli_upload.md#options) + +programmers.txt works similarly to [boards.txt](#boardstxt). Programmers are referenced by their short name: the +programmer ID. The settings for a programmer are defined through a set of properties with keys that use the programmer +ID as prefix. + +For example, the programmer ID chosen for the +["Arduino as ISP" programmer](https://www.arduino.cc/en/Tutorial/ArduinoISP) is "arduinoasisp". The definition of this +programmer in programmers.txt looks like: + + [......] + arduinoasisp.name=Arduino as ISP + arduinoasisp.protocol=stk500v1 + arduinoasisp.program.speed=19200 + arduinoasisp.program.tool=avrdude + arduinoasisp.program.extra_params=-P{serial.port} -b{program.speed} + [......] + +These properties can only be used in the recipes of the actions that use the programmer (`erase`, `bootloader`, and +`program`). + +The **arduinoasisp.name** property defines the human-friendly name of the programmer. This is shown in the **Tools > +Programmer** menu of the IDEs and the output of [`arduino-cli upload --programmer list`](commands/arduino-cli_upload.md) +and [`arduino-cli burn-bootloader --programmer list`](commands/arduino-cli_burn-bootloader.md). + +In Arduino IDE 1.8.12 and older, all programmers of all installed platforms were made available for use. Starting with +Arduino IDE 1.8.13 (and in all relevant versions of other Arduino development tools), only the programmers defined by +the [board and core platform](#platform-terminology) of the currently selected board are available. For this reason, +platforms may now need to define copies of the programmers that were previously assumed to be provided by another +platform. + ## Tools The Arduino development software uses external command line tools to upload the compiled sketch to the board or to burn From 283c3c43b661895415566710fcae33ef75e003b6 Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 26 Aug 2020 08:03:14 -0700 Subject: [PATCH 2/4] Document the "Upload Using Programmer" configuration system of Arduino platforms --- docs/platform-specification.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/platform-specification.md b/docs/platform-specification.md index 628ce9aedae..5dd548caf08 100644 --- a/docs/platform-specification.md +++ b/docs/platform-specification.md @@ -739,7 +739,27 @@ The file component of the port's path (e.g., `ttyACM0`) is available as the conf ### Upload using an external programmer -**TODO...**
The platform.txt associated with the selected programmer will be used. +The `program` action is triggered via the **Sketch > Upload Using Programmer** feature of the IDEs or +[`arduino-cli upload --programmer `](commands/arduino-cli_upload.md). This action is used to transfer a +compiled sketch to a board using an external programmer. + +The **program.tool** property determines the tool to be used for this action. This property is typically defined for +each programmer in [programmers.txt](#programmerstxt): + + [......] + usbasp.program.tool=avrdude + [......] + arduinoasisp.program.tool=avrdude + [......] + +This action can use the same [upload verification preference system](#upload-verification) as the `upload` action, via +the **program.verify** property. + +When using the Arduino IDE, if the selected programmer is from a different platform than the board, the `program` recipe +defined in the programmer's platform is used without overrides from the properties defined in the +[platform.txt](#platformtxt) of the [board platform](#platform-terminology). When using Arduino development software +other than the Arduino IDE, the handling of properties is the same as when doing a +[standard Upload](#sketch-upload-configuration). ### Burn Bootloader From 68cd2f94f64eb7fa7cb02236af8c77fd3bca50ec Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 26 Aug 2020 08:03:56 -0700 Subject: [PATCH 3/4] Document the "Burn Bootloader" configuration system for Arduino platforms --- docs/platform-specification.md | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/docs/platform-specification.md b/docs/platform-specification.md index 5dd548caf08..3a2e1eb818b 100644 --- a/docs/platform-specification.md +++ b/docs/platform-specification.md @@ -763,7 +763,30 @@ other than the Arduino IDE, the handling of properties is the same as when doing ### Burn Bootloader -**TODO...**
The platform.txt associated with the selected board will be used. +The `erase` and `bootloader` actions are triggered via the **Tools > Burn Bootloader** feature of the Arduino IDE or +[`arduino-cli burn-bootloader`](commands/arduino-cli_burn-bootloader.md). This action is used to flash a bootloader to +the board. + +"Burn Bootloader" is unique in that it uses two actions, which are executed in sequence: + +1. `erase` is typically used to erase the microcontroller's flash memory and set the configuration fuses according to + the properties defined in the [board definition](#boardstxt) +1. `bootloader` is used to flash the bootloader to the board + +The **bootloader.tool** property determines the tool to be used for the `erase` and `bootloader` actions both. This +property is typically defined for each board in boards.txt: + + [......] + uno.bootloader.tool=avrdude + [......] + leonardo.bootloader.tool=avrdude + [......] + +When using the Arduino IDE, if the board uses a +[core reference](https://arduino.github.io/arduino-cli/dev/platform-specification/#core-reference), the platform.txt of +the [core platform](#platform-terminology) is not used at all in defining the recipes for `erase` and `bootloader` +actions. When using Arduino development software other than the Arduino IDE, the handling of properties from the core +platform's platform.txt is done as usual. ### Sketch debugging configuration From 8a5b4f5c6a08f78d0ba69277923dcc19478b49e4 Mon Sep 17 00:00:00 2001 From: per1234 Date: Wed, 26 Aug 2020 08:09:10 -0700 Subject: [PATCH 4/4] Document programmer inheritance from referenced core platforms Previously, all programmers of all platforms of the same architecture could be used. The behavior of the Arduino IDE was changed in the 1.8.13 release in this matter, and Arduino CLI and Arduino Pro IDE followed the same behavior from the initial introduction of support for programmers. This means it's now important to document programmer inheritance. --- docs/platform-specification.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/platform-specification.md b/docs/platform-specification.md index 3a2e1eb818b..fa740cd7417 100644 --- a/docs/platform-specification.md +++ b/docs/platform-specification.md @@ -914,6 +914,11 @@ The [bundled libraries](#platform-bundled-libraries) from the referenced platfor the referencing platform to bundle those libraries. If libraries are provided, the list of available libraries is the sum of the two libraries, where the referencing platform has priority over the referenced platform. +The [programmers](#programmerstxt) from the referenced platform are made available, thus there is no need for the +referencing platform to define those programmers. If the referencing platform does provide its own programmer +definitions, the list of available programmer is the sum of the programmers of the two platforms. In Arduino IDE 1.8.12 +and older, all programmers of all installed platforms were made available. + ### Variant reference In the same way we can use a variant defined on another platform using the syntax **VENDOR_ID:VARIANT_ID**: