From 23c50fda078f23ce21cbd553db61535488b392ed Mon Sep 17 00:00:00 2001 From: Umberto Baldi <34278123+umbynos@users.noreply.github.com> Date: Thu, 1 Jul 2021 15:05:32 +0200 Subject: [PATCH] Enhance the documentation and rearrange `README.md` (#71) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * streamline `README.md` * moved old `README.md` in the docs folder * split `docs/README.md` in different markdown files * applied suggestions by @per1234 💚 * Update README.md Co-authored-by: per1234 Co-authored-by: per1234 --- README.md | 132 +++++++------------------------------------ docs/README.md | 1 - docs/index.md | 14 +++++ docs/installation.md | 17 ++++++ docs/usage.md | 60 ++++++++++++++++++++ mkdocs.yml | 4 +- 6 files changed, 114 insertions(+), 114 deletions(-) delete mode 120000 docs/README.md create mode 100644 docs/index.md create mode 100644 docs/installation.md create mode 100644 docs/usage.md diff --git a/README.md b/README.md index 17d60e8a..4e8fad33 100644 --- a/README.md +++ b/README.md @@ -1,124 +1,32 @@ -# Firmware/Certificates updater for WINC and NINA Wifi module +# Arduino Firmware Uploader -Use this tool to update the firmware and/or add SSL certificates for any WINC, NINA module. +The Arduino Firmware Uploader is a tool made to update the firmware and/or add SSL certificates for any Arduino board +equipped with WINC or NINA Wi-Fi module. -## Install +[![tests-badge]](https://github.com/arduino/arduino-fwuploader/actions/workflows/test.yaml) +[![docs-badge]](https://github.com/arduino/arduino-fwuploader/actions/workflows/publish-docs.yaml) -You can download the Firmware/Certificates updater here: +## Docs -https://github.com/arduino/arduino-fwuploader/releases/latest +For guidance on installation and development, see the [User documentation] -## Usage +## Quickstart -### Firmware Flashing - -Extract the zip file and, to update a mkr 1010, run: - -``` -./arduino-fwuploader firmware flash -b arduino:samd:mkrwifi1010 -a /dev/ttyACM0 -``` - -You just have to specify the fqbn (`-b` or `--fqbn`) of the board and the serial port (`-a` or `--address`) The firmware -uploader will take care of fetching everything is required to perform the update process. If no module and version are -specified **the latest version of the firmware** will be used. - -If you want to flash a specific version of a firmware you can use the `-m` or `--module` flag - -For example to flash a MKR1000 with 19.6.1 version of the firmware you can run something like: - -``` -./arduino-fwuploader firmware flash -b arduino:samd:mkr1000 -a /dev/ttyACM0 -m WINC1500@19.6.1 -``` - -There is also a retry mechanism bundled in the tool because the flashing process sometimes can be a bit unreliable. For -example to update a Nano RP2040 Connect with the retry set to 2 you can use: - -``` -./arduino-fwuploader firmware flash --fqbn arduino:mbed_nano:nanorp2040connect -a /dev/ttyACM0 --retries 2 -``` - -It's possible also to list the available firmwares for every board/module with: - -``` -./arduino-fwuploader firmware list -``` - -but you can also filter the results by specifying the `-b` or `--fqbn` flag - -The tool offers the ability to print output in json, with the `--format json` - -### Certificates - -The tool offers also the ability to flash SSL certificates to a board: - -``` -/arduino-fwuploader flash -b arduino:samd:nano_33_iot" -a COM10 -u arduino.cc:443 -u google.cc:443 -``` - -or you can specify a path to a file with `-f` - -### Command line options - -The full list of command line options can be obtained with the `-h` option: `./arduino-fwuploader -h` - -``` -Arduino Firmware Uploader (arduino-fwuploader). - -Usage: - arduino-fwuploader [command] - -Examples: - ./arduino-fwuploader [flags...] - -Available Commands: - certificates Commands to operate on certificates. - firmware Commands to operate on firmwares. - help Help about any command - version Shows version number of arduino-fwuploader. - -Flags: - --format string The output format, can be {text|json}. (default "text") - -h, --help help for arduino-fwuploader - --log-file string Path to the file where logs will be written - --log-format string The output format for the logs, can be {text|json}. - --log-level string Messages with this level and above will be logged. Valid levels are: trace, debug, info, warn, error, fatal, panic (default "info") - -v, --verbose Print the logs on the standard output. - -Use "arduino-fwuploader [command] --help" for more information about a command. -``` - -## How to build the tools from source file - -To build we use [task](https://taskfile.dev/) for simplicity. From the sources root directory run: - -``` -task dist:_ -``` - -Where could be one of: `macOS`,`Windows`,`Linux`. And : `32bit`, `64bit`, `ARM` or `ARM64` - -This will create the `arduino-fwuploader` executable. +1. [Install] the Arduino Firmware Uploader +2. Follow the [Usage] guide to check out what the tool can do +3. Browse the [Commands reference] to see all the available commands ## Security -If you think you found a vulnerability or other security-related bug in this project, please read our [security -policy][security-policy] and report the bug to our Security Team 🛡️ Thank you! +If you think you found a vulnerability or other security-related bug in this project, please read our [security policy] +and report the bug to our Security Team 🛡️ Thank you! e-mail contact: security@arduino.cc -## License - -Copyright (c) 2015-2021 Arduino LLC. All right reserved. - -This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public -License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later -version. - -This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied -warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more -details. - -You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the -Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA - -[security-policy]: https://github.com/arduino/arduino-fwuploader/security/policy +[tests-badge]: https://github.com/arduino/arduino-fwuploader/actions/workflows/test.yaml/badge.svg +[docs-badge]: https://github.com/arduino/arduino-fwuploader/actions/workflows/publish-docs.yaml/badge.svg +[security policy]: https://github.com/arduino/arduino-fwuploader/security/policy +[user documentation]: https://arduino.github.io/arduino-fwuploader/ +[install]: https://arduino.github.io/arduino-fwuploader/dev/installation +[usage]: https://arduino.github.io/arduino-fwuploader/dev/usage +[commands reference]: https://arduino.github.io/arduino-fwuploader/dev/commands/arduino-fwuploader/ diff --git a/docs/README.md b/docs/README.md deleted file mode 120000 index 32d46ee8..00000000 --- a/docs/README.md +++ /dev/null @@ -1 +0,0 @@ -../README.md \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..ccd49787 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,14 @@ +The Arduino Firmware Uploader is a tool made to update the firmware and/or add SSL certificates for any Arduino board +equipped with WINC or NINA Wi-Fi module. + +## Installation + +You have several options to install the latest version of the Arduino Firmware Uploader on your system, see the +[installation] page. + +## Getting started + +Follow the [Usage guide] to see how to use the most common CLI commands. + +[installation]: installation.md +[usage guide]: usage.md diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 00000000..f230ecb8 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,17 @@ +## Install + +You can download the Arduino Firmware Uploader directly from the GitHub release page: + +https://github.com/arduino/arduino-fwuploader/releases/latest + +### How to build the tools from source file + +To build we use [task](https://taskfile.dev/) for simplicity. From the sources root directory run: + +``` +task dist:_ +``` + +Where could be one of: `macOS`,`Windows`,`Linux`. And : `32bit`, `64bit`, `ARM` or `ARM64` + +This will create the `arduino-fwuploader` executable. diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 00000000..59cd7bc3 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,60 @@ +## Usage + +### Firmware Flashing + +First [install] the Arduino Firmware Uploader. Extract the zip file and, for example, to update the NINA module present +on the Arduino MKR WiFi 1010, run: + +``` +./arduino-fwuploader firmware flash -b arduino:samd:mkrwifi1010 -a /dev/ttyACM0 +``` + +You just have to specify the FQBN (`-b` or `--fqbn`) of the board and the serial port (`-a` or `--address`). The +firmware uploader will take care of fetching everything is required to perform the update process. If no module and +version are specified **the latest version of the firmware** will be used. + +If you want to flash a specific version of a firmware you can use the `-m` or `--module` flag + +For example to flash the WINC module present on the MKR 1000 with version 19.6.1 of the firmware you can run something +like: + +``` +./arduino-fwuploader firmware flash -b arduino:samd:mkr1000 -a /dev/ttyACM0 -m WINC1500@19.6.1 +``` + +There is a retry mechanism because the flashing process uses serial communication, which sometimes can be a bit +unreliable. The retry flag is set by default to 9 retries, but it's possible to overwrite it for whatever reason. For +example to update a Nano RP2040 Connect with the retry set to 2 you can use: + +``` +./arduino-fwuploader firmware flash --fqbn arduino:mbed_nano:nanorp2040connect -a /dev/ttyACM0 --retries 2 +``` + +It's possible to list the available firmwares for every board/module with: + +``` +./arduino-fwuploader firmware list +``` + +but you can also filter the results by specifying the `-b` or `--fqbn` flag + +The tool offers the ability to print output in JSON, with the `--format json` flag + +### Certificates + +The tool offers also the ability to flash SSL certificates to a module: + +``` +./arduino-fwuploader certificates flash -b arduino:samd:nano_33_iot" -a COM10 -u arduino.cc:443 -u google.cc:443 +``` + +or you can specify a path to a file with `-f` instead of the URL of the certificate + +### Command line options + +The full list of command line options can be obtained with the `-h` option: `./arduino-fwuploader -h` + +For further information you can use the [command reference] + +[install]: installation.md +[command reference]: commands/arduino-fwuploader.md diff --git a/mkdocs.yml b/mkdocs.yml index 3fd9bb64..60d96bdc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -61,7 +61,9 @@ extra: # Navigation nav: - - Documentation Home: README.md + - Documentation Home: index.md + - Installation: installation.md + - Usage: usage.md - Command reference: - arduino-fwuploader: commands/arduino-fwuploader.md - certificates: commands/arduino-fwuploader_certificates.md