From 5e4e7f9b30c15e18e87535b5646c44079880111f Mon Sep 17 00:00:00 2001 From: per1234 Date: Sat, 4 Jul 2020 23:53:42 -0700 Subject: [PATCH 1/4] [skip ci] Update statement re: prevalence of usb to serial chip on Arduino boards It's no longer true that "most" Arduino boards have a dedicated USB to serial chip (and becoming increasingly less so). --- docs/platform-specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platform-specification.md b/docs/platform-specification.md index 513ecb91199..6b6ec61dd9d 100644 --- a/docs/platform-specification.md +++ b/docs/platform-specification.md @@ -456,7 +456,7 @@ Most **{upload.XXXX}** variables are used later in the avrdude upload recipe in [.....] #### 1200 bps bootloader reset -Most Arduino boards use a dedicated USB-to-serial chip, that takes care of restarting the main MCU (starting the bootloader) when the serial port is opened. However, boards that have a native USB connection (such as the Leonardo or Zero) will have to disconnect from USB when rebooting into the bootloader (after which the bootloader reconnects to USB and offers a new serial port for uploading). After the upload is complete, the bootloader disconnects from USB again, starts the sketch, which then reconnects to USB. Because of these reconnections, the standard restart-on-serial open will not work, since that would cause the serial port to disappear and be closed again. Instead, the sketch running on these boards interprets a bitrate of 1200 bps as a signal the bootloader should be started. +Some Arduino boards use a dedicated USB-to-serial chip, that takes care of restarting the main MCU (starting the bootloader) when the serial port is opened. However, boards that have a native USB connection (such as the Leonardo or Zero) will have to disconnect from USB when rebooting into the bootloader (after which the bootloader reconnects to USB and offers a new serial port for uploading). After the upload is complete, the bootloader disconnects from USB again, starts the sketch, which then reconnects to USB. Because of these reconnections, the standard restart-on-serial open will not work, since that would cause the serial port to disappear and be closed again. Instead, the sketch running on these boards interprets a bitrate of 1200 bps as a signal the bootloader should be started. To let the Arduino development software perform these steps, two board parameters can be set: From 8fb0b4b504b7751d1928ed7fdee8145c8784880a Mon Sep 17 00:00:00 2001 From: per1234 Date: Sun, 5 Jul 2020 00:03:19 -0700 Subject: [PATCH 2/4] [skip ci] Update documentation for sketch size regex properties The platform specification was outdated in regard to the sketch size determination regular expression properties. - Document recipe.size.regex.data - Update Arduino AVR Boards' recipe.size.regex value --- docs/platform-specification.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/platform-specification.md b/docs/platform-specification.md index 6b6ec61dd9d..51ab98090d5 100644 --- a/docs/platform-specification.md +++ b/docs/platform-specification.md @@ -193,7 +193,10 @@ A full example for the AVR platform can be: #### Recipes to compute binary sketch size -At the end of the build the Arduino development software shows the final binary sketch size to the user. The size is calculated using the recipe **recipe.size.pattern**. The output of the command executed using the recipe is parsed through the regular expression set in the property **recipe.size.regex**. The regular expression must match the sketch size. +At the end of the build the Arduino development software shows the final binary sketch size to the user. The size is calculated using the recipe **recipe.size.pattern**. The output of the command executed using the recipe is parsed through the regular expressions set in the properties: + +* **recipe.size.regex**: Program storage space used. +* **recipe.size.regex.data**: Dynamic memory used by global variables. For AVR we have: @@ -201,7 +204,8 @@ For AVR we have: [....] ## Compute size recipe.size.pattern="{compiler.path}{compiler.size.cmd}" -A "{build.path}/{build.project_name}.hex" - recipe.size.regex=Total\s+([0-9]+).* + recipe.size.regex=^(?:\.text|\.data|\.bootloader)\s+([0-9]+).* + recipe.size.regex.data=^(?:\.data|\.bss|\.noinit)\s+([0-9]+).* #### Recipes to export compiled binary From 2ee04d09eb58edae8d7ce26473e345fb5358bdac Mon Sep 17 00:00:00 2001 From: per1234 Date: Sun, 5 Jul 2020 00:10:36 -0700 Subject: [PATCH 3/4] [skip ci] Update docs re: platform.local.txt location Previously, the location specified by the platform specification applied only to the folder structure of manually installed platforms. When a platform is installed via Boards Manager, there is an additional version folder level and it is under this folder the platform.local.txt must be placed. The documentation now applies equally well to either platform installation type. --- docs/platform-specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platform-specification.md b/docs/platform-specification.md index 51ab98090d5..6f02a17d5fe 100644 --- a/docs/platform-specification.md +++ b/docs/platform-specification.md @@ -279,7 +279,7 @@ Properties defined in a platform.txt created in the **hardware** subfolder of th ## platform.local.txt -Introduced in Arduino IDE 1.5.7. This file can be used to override properties defined in platform.txt or define new properties without modifying platform.txt (e.g. when platform.txt is tracked by a version control system). It should be placed in the architecture folder. +Introduced in Arduino IDE 1.5.7. This file can be used to override properties defined in platform.txt or define new properties without modifying platform.txt (e.g. when platform.txt is tracked by a version control system). It should be placed in the same folder as the platform.txt it supplements. ## boards.txt From 576518170f7bf33b25266e7e023d076dd12459b2 Mon Sep 17 00:00:00 2001 From: per1234 Date: Sun, 5 Jul 2020 00:14:58 -0700 Subject: [PATCH 4/4] [skip ci] Modernize statement re: upload tools The statement was written at a time when there was only two Arduino platforms. Although still correct, it had a decidedly outdated feel that was fixed by a minor rewording. --- docs/platform-specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platform-specification.md b/docs/platform-specification.md index 6f02a17d5fe..7ab970690e2 100644 --- a/docs/platform-specification.md +++ b/docs/platform-specification.md @@ -371,7 +371,7 @@ The parameter **build.variant.path** is automatically generated. ## Tools -The Arduino development software uses external command line tools to upload the compiled sketch to the board or to burn bootloaders using external programmers. Currently *avrdude* is used for AVR based boards and *bossac* for SAM based boards, but there is no limit, any command line executable can be used. The command line parameters are specified using **recipes** in the same way used for platform build process. +The Arduino development software uses external command line tools to upload the compiled sketch to the board or to burn bootloaders using external programmers. For example, *avrdude* is used for AVR based boards and *bossac* for SAM based boards, but there is no limit, any command line executable can be used. The command line parameters are specified using **recipes** in the same way used for platform build process. Tools are configured inside the platform.txt file. Every Tool is identified by a short name, the Tool ID. A tool can be used for different purposes: