Skip to content

Commit 23c50fd

Browse files
umbynosper1234
umbynos
and
per1234
authored
Enhance the documentation and rearrange README.md (#71)
* 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 <accounts@perglass.com> Co-authored-by: per1234 <accounts@perglass.com>
1 parent 5d7d398 commit 23c50fd

File tree

6 files changed

+114
-114
lines changed

6 files changed

+114
-114
lines changed

‎README.md‎

Lines changed: 20 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -1,124 +1,32 @@
1-
# Firmware/Certificates updater for WINC and NINA Wifi module
1+
# Arduino Firmware Uploader
22

3-
Use this tool to update the firmware and/or add SSL certificates for any WINC, NINA module.
3+
The Arduino Firmware Uploader is a tool made to update the firmware and/or add SSL certificates for any Arduino board
4+
equipped with WINC or NINA Wi-Fi module.
45

5-
## Install
6+
[![tests-badge]](https://github.com/arduino/arduino-fwuploader/actions/workflows/test.yaml)
7+
[![docs-badge]](https://github.com/arduino/arduino-fwuploader/actions/workflows/publish-docs.yaml)
68

7-
You can download the Firmware/Certificates updater here:
9+
## Docs
810

9-
https://github.com/arduino/arduino-fwuploader/releases/latest
11+
For guidance on installation and development, see the [User documentation]
1012

11-
## Usage
13+
## Quickstart
1214

13-
### Firmware Flashing
14-
15-
Extract the zip file and, to update a mkr 1010, run:
16-
17-
```
18-
./arduino-fwuploader firmware flash -b arduino:samd:mkrwifi1010 -a /dev/ttyACM0
19-
```
20-
21-
You just have to specify the fqbn (`-b` or `--fqbn`) of the board and the serial port (`-a` or `--address`) The firmware
22-
uploader will take care of fetching everything is required to perform the update process. If no module and version are
23-
specified **the latest version of the firmware** will be used.
24-
25-
If you want to flash a specific version of a firmware you can use the `-m` or `--module` flag
26-
27-
For example to flash a MKR1000 with 19.6.1 version of the firmware you can run something like:
28-
29-
```
30-
./arduino-fwuploader firmware flash -b arduino:samd:mkr1000 -a /dev/ttyACM0 -m WINC1500@19.6.1
31-
```
32-
33-
There is also a retry mechanism bundled in the tool because the flashing process sometimes can be a bit unreliable. For
34-
example to update a Nano RP2040 Connect with the retry set to 2 you can use:
35-
36-
```
37-
./arduino-fwuploader firmware flash --fqbn arduino:mbed_nano:nanorp2040connect -a /dev/ttyACM0 --retries 2
38-
```
39-
40-
It's possible also to list the available firmwares for every board/module with:
41-
42-
```
43-
./arduino-fwuploader firmware list
44-
```
45-
46-
but you can also filter the results by specifying the `-b` or `--fqbn` flag
47-
48-
The tool offers the ability to print output in json, with the `--format json`
49-
50-
### Certificates
51-
52-
The tool offers also the ability to flash SSL certificates to a board:
53-
54-
```
55-
/arduino-fwuploader flash -b arduino:samd:nano_33_iot" -a COM10 -u arduino.cc:443 -u google.cc:443
56-
```
57-
58-
or you can specify a path to a file with `-f`
59-
60-
### Command line options
61-
62-
The full list of command line options can be obtained with the `-h` option: `./arduino-fwuploader -h`
63-
64-
```
65-
Arduino Firmware Uploader (arduino-fwuploader).
66-
67-
Usage:
68-
arduino-fwuploader [command]
69-
70-
Examples:
71-
./arduino-fwuploader <command> [flags...]
72-
73-
Available Commands:
74-
certificates Commands to operate on certificates.
75-
firmware Commands to operate on firmwares.
76-
help Help about any command
77-
version Shows version number of arduino-fwuploader.
78-
79-
Flags:
80-
--format string The output format, can be {text|json}. (default "text")
81-
-h, --help help for arduino-fwuploader
82-
--log-file string Path to the file where logs will be written
83-
--log-format string The output format for the logs, can be {text|json}.
84-
--log-level string Messages with this level and above will be logged. Valid levels are: trace, debug, info, warn, error, fatal, panic (default "info")
85-
-v, --verbose Print the logs on the standard output.
86-
87-
Use "arduino-fwuploader [command] --help" for more information about a command.
88-
```
89-
90-
## How to build the tools from source file
91-
92-
To build we use [task](https://taskfile.dev/) for simplicity. From the sources root directory run:
93-
94-
```
95-
task dist:<OS>_<ARCH>
96-
```
97-
98-
Where <OS> could be one of: `macOS`,`Windows`,`Linux`. And <ARCH>: `32bit`, `64bit`, `ARM` or `ARM64`
99-
100-
This will create the `arduino-fwuploader` executable.
15+
1. [Install] the Arduino Firmware Uploader
16+
2. Follow the [Usage] guide to check out what the tool can do
17+
3. Browse the [Commands reference] to see all the available commands
10118

10219
## Security
10320

104-
If you think you found a vulnerability or other security-related bug in this project, please read our [security
105-
policy][security-policy] and report the bug to our Security Team 🛡️ Thank you!
21+
If you think you found a vulnerability or other security-related bug in this project, please read our [security policy]
22+
and report the bug to our Security Team 🛡️ Thank you!
10623

10724
e-mail contact: security@arduino.cc
10825

109-
## License
110-
111-
Copyright (c) 2015-2021 Arduino LLC. All right reserved.
112-
113-
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public
114-
License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later
115-
version.
116-
117-
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
118-
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
119-
details.
120-
121-
You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the
122-
Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
123-
124-
[security-policy]: https://github.com/arduino/arduino-fwuploader/security/policy
26+
[tests-badge]: https://github.com/arduino/arduino-fwuploader/actions/workflows/test.yaml/badge.svg
27+
[docs-badge]: https://github.com/arduino/arduino-fwuploader/actions/workflows/publish-docs.yaml/badge.svg
28+
[security policy]: https://github.com/arduino/arduino-fwuploader/security/policy
29+
[user documentation]: https://arduino.github.io/arduino-fwuploader/
30+
[install]: https://arduino.github.io/arduino-fwuploader/dev/installation
31+
[usage]: https://arduino.github.io/arduino-fwuploader/dev/usage
32+
[commands reference]: https://arduino.github.io/arduino-fwuploader/dev/commands/arduino-fwuploader/

‎docs/README.md‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎docs/index.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
The Arduino Firmware Uploader is a tool made to update the firmware and/or add SSL certificates for any Arduino board
2+
equipped with WINC or NINA Wi-Fi module.
3+
4+
## Installation
5+
6+
You have several options to install the latest version of the Arduino Firmware Uploader on your system, see the
7+
[installation] page.
8+
9+
## Getting started
10+
11+
Follow the [Usage guide] to see how to use the most common CLI commands.
12+
13+
[installation]: installation.md
14+
[usage guide]: usage.md

‎docs/installation.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
## Install
2+
3+
You can download the Arduino Firmware Uploader directly from the GitHub release page:
4+
5+
https://github.com/arduino/arduino-fwuploader/releases/latest
6+
7+
### How to build the tools from source file
8+
9+
To build we use [task](https://taskfile.dev/) for simplicity. From the sources root directory run:
10+
11+
```
12+
task dist:<OS>_<ARCH>
13+
```
14+
15+
Where <OS> could be one of: `macOS`,`Windows`,`Linux`. And <ARCH>: `32bit`, `64bit`, `ARM` or `ARM64`
16+
17+
This will create the `arduino-fwuploader` executable.

‎docs/usage.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
## Usage
2+
3+
### Firmware Flashing
4+
5+
First [install] the Arduino Firmware Uploader. Extract the zip file and, for example, to update the NINA module present
6+
on the Arduino MKR WiFi 1010, run:
7+
8+
```
9+
./arduino-fwuploader firmware flash -b arduino:samd:mkrwifi1010 -a /dev/ttyACM0
10+
```
11+
12+
You just have to specify the FQBN (`-b` or `--fqbn`) of the board and the serial port (`-a` or `--address`). The
13+
firmware uploader will take care of fetching everything is required to perform the update process. If no module and
14+
version are specified **the latest version of the firmware** will be used.
15+
16+
If you want to flash a specific version of a firmware you can use the `-m` or `--module` flag
17+
18+
For example to flash the WINC module present on the MKR 1000 with version 19.6.1 of the firmware you can run something
19+
like:
20+
21+
```
22+
./arduino-fwuploader firmware flash -b arduino:samd:mkr1000 -a /dev/ttyACM0 -m WINC1500@19.6.1
23+
```
24+
25+
There is a retry mechanism because the flashing process uses serial communication, which sometimes can be a bit
26+
unreliable. The retry flag is set by default to 9 retries, but it's possible to overwrite it for whatever reason. For
27+
example to update a Nano RP2040 Connect with the retry set to 2 you can use:
28+
29+
```
30+
./arduino-fwuploader firmware flash --fqbn arduino:mbed_nano:nanorp2040connect -a /dev/ttyACM0 --retries 2
31+
```
32+
33+
It's possible to list the available firmwares for every board/module with:
34+
35+
```
36+
./arduino-fwuploader firmware list
37+
```
38+
39+
but you can also filter the results by specifying the `-b` or `--fqbn` flag
40+
41+
The tool offers the ability to print output in JSON, with the `--format json` flag
42+
43+
### Certificates
44+
45+
The tool offers also the ability to flash SSL certificates to a module:
46+
47+
```
48+
./arduino-fwuploader certificates flash -b arduino:samd:nano_33_iot" -a COM10 -u arduino.cc:443 -u google.cc:443
49+
```
50+
51+
or you can specify a path to a file with `-f` instead of the URL of the certificate
52+
53+
### Command line options
54+
55+
The full list of command line options can be obtained with the `-h` option: `./arduino-fwuploader -h`
56+
57+
For further information you can use the [command reference]
58+
59+
[install]: installation.md
60+
[command reference]: commands/arduino-fwuploader.md

‎mkdocs.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,9 @@ extra:
6161

6262
# Navigation
6363
nav:
64-
- Documentation Home: README.md
64+
- Documentation Home: index.md
65+
- Installation: installation.md
66+
- Usage: usage.md
6567
- Command reference:
6668
- arduino-fwuploader: commands/arduino-fwuploader.md
6769
- certificates: commands/arduino-fwuploader_certificates.md

0 commit comments

Comments
 (0)