From bac1d051b67b509e741818e688530d46a68a0c88 Mon Sep 17 00:00:00 2001 From: Alessio Perugini Date: Thu, 20 Jul 2023 12:39:00 +0200 Subject: [PATCH] Add documentation on the new plugin system (#179) * Add documentation on the new plugin system (#178) * Apply Code Review suggestions --------- Co-authored-by: MatteoPologruto <109663225+MatteoPologruto@users.noreply.github.com> --- docs/index.md | 5 +++ docs/plugins.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 106 insertions(+) create mode 100644 docs/plugins.md diff --git a/docs/index.md b/docs/index.md index ccd49787..02a69311 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,5 +10,10 @@ You have several options to install the latest version of the Arduino Firmware U Follow the [Usage guide] to see how to use the most common CLI commands. +## Plugins + +Read the [plugins] section to learn more on the topic. + [installation]: installation.md [usage guide]: usage.md +[plugins]: plugins.md diff --git a/docs/plugins.md b/docs/plugins.md new file mode 100644 index 00000000..fcd05c42 --- /dev/null +++ b/docs/plugins.md @@ -0,0 +1,101 @@ +# Plugins + +A new plugin-system has been implemented in the Arduino Firmware Uploader. A plugin is basically another +executable/tool, specifically tailored for a board/family of boards, but with a well-defined user interface. Inside the +plugin, there is all the business logic to support a board/family of boards. Every plugin implements the +[interface](https://pkg.go.dev/github.com/arduino/fwuploader-plugin-helper#Plugin) contained in the +[fwuploader-plugin-helper](https://github.com/arduino/fwuploader-plugin-helper) repository. + +The fwuploader is still responsible for downloading the files required for the plugin to work: + +- plugins/tools +- certificates +- firmware + +The new information is hosted in the +[plugin_firmware_index.json](https://downloads.arduino.cc/arduino-fwuploader/boards/plugin_firmware_index.json), which +is generated by `generator.py`. + +## uno-r4-wifi-plugin + +The source code can be found [here](https://github.com/arduino/uno-r4-wifi-fwuploader-plugin). + +### Known issues + +#### Espflash panic `UnknownModel` + +On some arm64 Linux distros, version 2.0.0 of [espflash](https://github.com/esp-rs/espflash/) might panic with the +following error: + +``` +Error: × Main thread panicked. + ├─▶ at espflash/src/interface.rs:70:33 + ╰─▶ called `Result::unwrap()` on an `Err` value: UnknownModel + help: set the `RUST_BACKTRACE=1` environment variable to display a + backtrace. +``` + +#### The ESP32 module does not go into download mode + +On Linux, the UNO R4 WiFi must be plugged into a **USB hub** to make the flash process work. Otherwise, it won’t be able +to reboot in download mode. + +```bash +$ arduino-fwuploader firmware flash -b arduino:renesas_uno:unor4wifi -a /dev/ttyACM0 -v --log-level debug + +Done in 0.001 seconds +Write 46588 bytes to flash (12 pages) +[==============================] 100% (12/12 pages) +Done in 3.106 seconds + +Waiting to flash the binary... +time=2023-07-18T14:50:10.492+02:00 level=INFO msg="getting firmware version" +time=2023-07-18T14:50:10.509+02:00 level=INFO msg="firmware version is > 0.1.0 using sketch" +time=2023-07-18T14:50:10.511+02:00 level=INFO msg="check if serial port has changed" +[2023-07-18T12:50:20Z INFO ] 🚀 A new version of espflash is available: v2.0.1 +[2023-07-18T12:50:20Z INFO ] Serial port: '/dev/ttyACM0' +[2023-07-18T12:50:20Z INFO ] Connecting... +[2023-07-18T12:50:20Z INFO ] Unable to connect, retrying with extra delay... +[2023-07-18T12:50:21Z INFO ] Unable to connect, retrying with default delay... +[2023-07-18T12:50:21Z INFO ] Unable to connect, retrying with extra delay... +[2023-07-18T12:50:21Z INFO ] Unable to connect, retrying with default delay... +[2023-07-18T12:50:21Z INFO ] Unable to connect, retrying with extra delay... +[2023-07-18T12:50:21Z INFO ] Unable to connect, retrying with default delay... +[2023-07-18T12:50:21Z INFO ] Unable to connect, retrying with extra delay... +Error: espflash::connection_failed + + × Error while connecting to device + ╰─▶ Failed to connect to the device + help: Ensure that the device is connected and the reset and boot pins are + not being held down + +Error: exit status 1 +ERRO[0021] couldn't update firmware: exit status 3 +INFO[0021] Waiting 1 second before retrying... +INFO[0022] Uploading firmware (try 2 of 9) +time=2023-07-18T14:50:22.229+02:00 level=INFO msg=upload_command_sketch +time=2023-07-18T14:50:22.230+02:00 level=INFO msg="sending serial reset" +Error: reboot mode: upload commands sketch: setting DTR to OFF +... +``` + +#### I flashed the certificates, but I am unable to reach the host + +The **whole certificate chain** is needed to make it work. Using +[`-u` flags](commands/arduino-fwuploader_certificates_flash.md#options) (ex: `-u www.arduino.cc:443`) won’t work because +it only downloads the root certificates. The solution is to use only the +[`-f` flag](commands/arduino-fwuploader_certificates_flash.md#options) and provide a pem certificate containing the +whole chain. + +#### My antivirus says that `espflash` is a threat + +The binary is not signed [#348](https://github.com/esp-rs/espflash/issues/348), and some antiviruses might complain. If +still doubtful, https://github.com/esp-rs/espflash is open source, and it's possible to double-check the md5 hashes of +the binary and the source code. For more information, you can follow +[this](https://forum.arduino.cc/t/radio-module-firmware-version-0-2-0-is-now-available/1147361/11) forum thread. + +#### Not running on armv7 + +At the moment, we are always downloading the armv6 binaries. Since they are dynamically linked, most likely they are not +going to run on armv7. More infos on the topic: +[here](https://developer.arm.com/documentation/ddi0419/c/Appendices/ARMv7-M-Differences/ARMv6-M-and-ARMv7-M-compatibility).