Skip to content

[skip changelog] Document the programmers system of Arduino platforms #925

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Aug 31, 2020
Merged

[skip changelog] Document the programmers system of Arduino platforms #925

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
fc25182
Document the programmers.txt configuration file of the Arduino platfo…
per1234 Aug 26, 2020
283c3c4
Document the "Upload Using Programmer" configuration system of Arduin…
per1234 Aug 26, 2020
68cd2f9
Document the "Burn Bootloader" configuration system for Arduino platf…
per1234 Aug 26, 2020
8a5b4f5
Document programmer inheritance from referenced core platforms
per1234 Aug 26, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 88 additions & 2 deletions docs/platform-specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <programmer ID>`](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
Expand Down Expand Up @@ -701,11 +739,54 @@ The file component of the port's path (e.g., `ttyACM0`) is available as the conf

### Upload using an external programmer

**TODO...**<br> 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 <programmer ID>`](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

**TODO...**<br> 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

Expand Down Expand Up @@ -833,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**:
Expand Down