Merge pull request #2668 from arduino/karlsoderby/add-linux-note-flasher

[PXCT-1499] Add instructions for fixing qcserial issue on linux (arduino-flasher-cli)

Author: karlsoderby

content/hardware/02.uno/boards/uno-q/tutorials/04.update-image/assets/flashing-tool.gif

@@ -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