diff --git a/content/hardware/02.uno/boards/uno-q/tutorials/04.update-image/assets/flashing-tool.gif b/content/hardware/02.uno/boards/uno-q/tutorials/04.update-image/assets/flashing-tool.gif new file mode 100644 index 0000000000..8d5b1995f8 Binary files /dev/null and b/content/hardware/02.uno/boards/uno-q/tutorials/04.update-image/assets/flashing-tool.gif differ diff --git a/content/hardware/02.uno/boards/uno-q/tutorials/04.update-image/update-image.md b/content/hardware/02.uno/boards/uno-q/tutorials/04.update-image/update-image.md index 90f8df964a..f059702c08 100644 --- a/content/hardware/02.uno/boards/uno-q/tutorials/04.update-image/update-image.md +++ b/content/hardware/02.uno/boards/uno-q/tutorials/04.update-image/update-image.md @@ -52,6 +52,21 @@ You should see something like: This means it is working, and we can proceed to [flashing the board](#flash-image-to-the-board). + +#### Windows + +Navigate to the unzipped folder (e.g. `arduino-flasher-cli-x.x.x-darwin-arm64`), and run the following command: + +``` +arduino-flasher-cli +``` + +A new window should appear, prompting you to install the driver. Install it, and run `arduino-flasher-cli` again in the terminal. + +![Output from testing tool (Windows)](assets/windows.png) + +This means it is working, and we can proceed to [flashing the board](#flash-image-to-the-board). + #### Linux Navigate to the unzipped folder (e.g. `arduino-flasher-cli-x.x.x-darwin-arm64`), and run the following command: @@ -66,19 +81,41 @@ You should see something like: This means it is working, and we can proceed to [flashing the board](#flash-image-to-the-board). -#### Windows +***Note: in some Linux systems, the `arduino-flasher-cli` could exit with an error right before flashing. This may occur if the kernel module `qcserial` is loaded. A workaround solution to fix this is in place (see section below).*** -Navigate to the unzipped folder (e.g. `arduino-flasher-cli-x.x.x-darwin-arm64`), and run the following command: +#### Fixing `qcserial` Issue (Linux Only) + +Open a terminal, and check if `qcserial` is present by running `lsmod | grep qcse` + +If present, it will return: ``` -arduino-flasher-cli +> lsmod | grep qcse +qcserial 24576 0 +usb_wwan 24576 1 qcserial +usbserial 69632 2 qcserial,usb_wwan ``` -A new window should appear, prompting you to install the driver. Install it, and run `arduino-flasher-cli` again in the terminal. +Then, check if `qcserial` is locking the serial port `ttyUSB0`, by running `sudo dmesg`: -![Output from testing tool (Windows)](assets/windows.png) +``` +> sudo dmesg +[31633.372270] qcserial ttyUSB0: Qualcomm USB modem converter now disconnected from ttyUSB0 +[31633.372308] qcserial 3-3:1.0: device disconnected +``` -This means it is working, and we can proceed to [flashing the board](#flash-image-to-the-board). +This issue can be fixed by disabling (or blacklisting), the `qcserial` kernel module on the Linux system. + +1. Create or edit a configuration file named `blacklist-modem.conf` inside the `/etc/modprobe.d/` directory: + ```sh + sudo nano /etc/modprobe.d/blacklist-modem.conf + ``` +2. Inside this file, we need to blacklist the `qcserial` module: + + ```sh + blacklist qcserial + ``` +3. Save the file and restart the system for the configuration to take effect. ## Preparing the Hardware @@ -89,20 +126,19 @@ To prepare the hardware for flashing, follow the instructions below: ![Short the two pins](assets/flash-uno-q.png) -3. Do **not** connect the board to the computer yet. This will need to be timed in the next step. - ## Flash Image to the Board In this step, we will upload the new image to the board using the Arduino Flasher CLI. -1. Open a terminal and navigate to the directory where you unzipped the Arduino Flasher CLI (normally `/Downloads`). -2. Type the following command in the terminal: `./arduino-flasher-cli flash latest` **but do not press Enter yet** -3. **Connect the board to the computer**, and press **Enter** to run the command **during the boot animations** on the LED matrix (immediately after plugging in). You only need the jumper to force recovery at plug-in; **you may remove it after you run the command**. +1. Connect the board to your computer, using a USB-C® type cable. +2. Open a terminal and navigate to the directory where you unzipped the Arduino Flasher CLI (normally `cd /Downloads`). +3. Run the following command in the terminal: `./arduino-flasher-cli flash latest`. 4. A download sequence will begin (the image is >1 GB). Once the download is complete, it will flash the board with the new image. **Please note:** this will take several minutes. Do **not** disconnect the USB cable during this process. -5. Once flashing completes and the tool reports success, **power-cycle** the board (unplug and re-plug USB) so it boots the new OS. (Ensure the jumper is removed before the power-cycle.) +5. Once flashing completes and the tool reports success, **power-cycle** the board (unplug and re-plug USB) so it boots the new OS. -***It is important to run the flashing command ONLY when the board is booting up; it does not work once the OS has finished booting.*** +The steps above are summarized in the graphic below: +![Flashing the UNO Q](assets/flashing-tool.gif) ## Troubleshooting