Skip to content

Commit c051517

Browse files
Update README (#15)
1 parent 0f63928 commit c051517

File tree

2 files changed

+123
-4
lines changed

2 files changed

+123
-4
lines changed

README.md

Lines changed: 122 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,127 @@
1212
[![Check Workflows status](https://github.com/arduino/uno-r4-wifi-fwuploader-plugin/actions/workflows/check-workflows-task.yml/badge.svg)](https://github.com/arduino/uno-r4-wifi-fwuploader-plugin/actions/workflows/check-workflows-task.yml)
1313
[![Codecov](https://codecov.io/gh/arduino/uno-r4-wifi-fwuploader-plugin/branch/main/graph/badge.svg)](https://codecov.io/gh/arduino/uno-r4-wifi-fwuploader-plugin)
1414

15-
Be sure to have `libudev-dev` installed
15+
The `uno-r4-wifi-fwuploader-plugin` is a core component of the [arduino-fwuploader](https://github.com/arduino/arduino-fwuploader). The purpose of this plugin is to abstract all the
16+
business logic needed to update firmware and certificates for the [uno r4 wifi](https://docs.arduino.cc/hardware/uno-r4-wifi) board.
1617

17-
### Ubuntu:
18+
## How to contribute
19+
20+
Contributions are welcome!
21+
22+
:sparkles: Thanks to all our [contributors]! :sparkles:
23+
24+
### Requirements
25+
26+
1. [Go](https://go.dev/) version 1.20 or later
27+
1. [Task](https://taskfile.dev/) to help you run the most common tasks from the command line
28+
1. The [uno r4 wifi](https://docs.arduino.cc/hardware/uno-r4-wifi) board to test the core parts.
29+
30+
## Development
31+
32+
When running only the plugin without the fwuploader, the required tools are downloaded by the fwuploader. If you run only the plugin, you must provide them by hand.
33+
Therefore be sure to place the `espflash` and `bossac` binaries in the correct folders like the following:
34+
35+
```bash
36+
.
37+
├── bossac
38+
│   └── 1.9.1-arduino5
39+
│   └── bossac
40+
├── espflash
41+
│   └── 2.0.0
42+
│   └── espflash
43+
└── uno-r4-wifi-fwuploader-plugin_linux_amd64
44+
└── bin
45+
└── uno-r4-wifi-fwuploader-plugin
46+
```
47+
48+
**Commands**
49+
50+
- `uno-r4-wifi-fwuploader-plugin cert flash -p /dev/ttyACM0 ./certificate/testdata/portenta.pem`
51+
- `uno-r4-wifi-fwuploader-plugin firmware get-version -p /dev/ttyACM0`
52+
- `uno-r4-wifi-fwuploader-plugin firmware flash -p /dev/ttyACM0 ~/Documents/fw0.2.0.bin`
53+
54+
55+
## Known problems:
56+
57+
### Espflash panic `UnknownModel`
58+
59+
On some arm64 Linux distros, version 2.0.0 of [espflash](https://github.com/esp-rs/espflash/) might panic with the following error:
60+
61+
```
62+
Error: × Main thread panicked.
63+
├─▶ at espflash/src/interface.rs:70:33
64+
╰─▶ called `Result::unwrap()` on an `Err` value: UnknownModel
65+
help: set the `RUST_BACKTRACE=1` environment variable to display a
66+
backtrace.
67+
```
68+
69+
### The esp32 module does not go into download mode
70+
71+
On Linux, the uno r4 must be plugged into a **hub usb** to make the flash process work. Otherwise, it won’t be able to reboot in download mode.
72+
73+
```bash
74+
$ arduino-fwuploader firmware flash -b arduino:renesas_uno:unor4wifi -a /dev/ttyACM0 -v --log-level debug
75+
76+
Done in 0.001 seconds
77+
Write 46588 bytes to flash (12 pages)
78+
[==============================] 100% (12/12 pages)
79+
Done in 3.106 seconds
80+
81+
Waiting to flash the binary...
82+
time=2023-07-18T14:50:10.492+02:00 level=INFO msg="getting firmware version"
83+
time=2023-07-18T14:50:10.509+02:00 level=INFO msg="firmware version is > 0.1.0 using sketch"
84+
time=2023-07-18T14:50:10.511+02:00 level=INFO msg="check if serial port has changed"
85+
[2023-07-18T12:50:20Z INFO ] 🚀 A new version of espflash is available: v2.0.1
86+
[2023-07-18T12:50:20Z INFO ] Serial port: '/dev/ttyACM0'
87+
[2023-07-18T12:50:20Z INFO ] Connecting...
88+
[2023-07-18T12:50:20Z INFO ] Unable to connect, retrying with extra delay...
89+
[2023-07-18T12:50:21Z INFO ] Unable to connect, retrying with default delay...
90+
[2023-07-18T12:50:21Z INFO ] Unable to connect, retrying with extra delay...
91+
[2023-07-18T12:50:21Z INFO ] Unable to connect, retrying with default delay...
92+
[2023-07-18T12:50:21Z INFO ] Unable to connect, retrying with extra delay...
93+
[2023-07-18T12:50:21Z INFO ] Unable to connect, retrying with default delay...
94+
[2023-07-18T12:50:21Z INFO ] Unable to connect, retrying with extra delay...
95+
Error: espflash::connection_failed
96+
97+
× Error while connecting to device
98+
╰─▶ Failed to connect to the device
99+
help: Ensure that the device is connected and the reset and boot pins are
100+
not being held down
101+
102+
Error: exit status 1
103+
ERRO[0021] couldn't update firmware: exit status 3
104+
INFO[0021] Waiting 1 second before retrying...
105+
INFO[0022] Uploading firmware (try 2 of 9)
106+
time=2023-07-18T14:50:22.229+02:00 level=INFO msg=upload_command_sketch
107+
time=2023-07-18T14:50:22.230+02:00 level=INFO msg="sending serial reset"
108+
Error: reboot mode: upload commands sketch: setting DTR to OFF
109+
...
110+
```
111+
112+
### I flashed the certificates, but I am unable to reach the host
113+
114+
The **whole certificate chain** is needed to make it work. Using `-u` flags (ex: `-u www.arduino.cc:443`) won’t work because it
115+
only downloads the root certificates. The solution is to use only the `-f` flag and provide a pem certificate containing the whole chain.
116+
117+
### My antivirus says that `espflash` is a threat
118+
119+
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,
120+
and it's possible to double-check the md5 hashes of the binary and the source code.
121+
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.
122+
123+
## Security
124+
125+
If you think you found a vulnerability or other security-related bug in the uno-r4-wifi-fwuploader-plugin, please read our [security
126+
policy] and report the bug to our Security Team 🛡️ Thank you!
127+
128+
e-mail contact: [email protected]
129+
130+
## License
131+
132+
uno-r4-wifi-fwuploader-plugin is licensed under the [AGPL 3.0](LICENSE.txt) license.
133+
134+
You can be released from the requirements of the above license by purchasing a commercial license. Buying such a license
135+
is mandatory if you want to modify or otherwise use the software for commercial activities involving the Arduino
136+
software without disclosing the source code of your own applications. To purchase a commercial license, send an email to
137+
18138

19-
`sudo apt install libudev-dev`

package-lock.json

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)