Pro 4G Module content major update

TaddyHC · TaddyHC · commit 70147a72492e · 2024-10-02T18:33:45.000-06:00
diff --git a/content/hardware/04.pro/carriers/portenta-mid-carrier/tutorials/user-manual/content.md b/content/hardware/04.pro/carriers/portenta-mid-carrier/tutorials/user-manual/content.md
@@ -653,12 +653,12 @@ The Mini PCIe slot of the Portenta Mid Carrier has a dedicated breakout pin to c
 |       5        |         NC         |                     |            NC             |                      |
 |       6        |        GND         |       Ground        |                           |                      |
 
-To accommodate the power requirements and ensure reliable connectivity, jumper cables with appropriate electrical standards, such as ASTM B 258 standard, should be used to support a current of up to 2A. **Jumper cables with a cross-sectional area of 0.82 mm² to 1.3 mm² (approximately equivalent to AWG 18-16) should support 2.0 A of current**.
+To accommodate the power requirements and ensure reliable connectivity, jumper cables with appropriate electrical standards, such as ASTM B 258 standard, should be used to support a current of up to 2.0 A. **Jumper cables with a cross-sectional area of 0.82 mm² to 1.3 mm² (approximately equivalent to AWG 18-16) should support 2.0 A of current**.
 
 This precaution is necessary to prevent wire overheating and ensure reliable power transmission for the connected Mini PCIe-compatible module, such as Cat.4 modems. A minimum requirement to set the mini PCIe interface with the Portenta Mid Carrier consists of:
 
 - **3V3 PCIE** pin connected to **3V3 BUCK** pin
-- Properly inserted mini PCIe module, e.g., Pro 4G GNSS Module Global / Pro 4G EMEA Module
+- Properly inserted mini PCIe module, e.g., Pro 4G GNSS Module Global (EG25) / Pro 4G EMEA (EC200A-EU) Module
 
 ***Please use a 5.0 V external power source when using an Arduino Pro 4G Module (EMEA / GNSS Global) or any other mPCIe modules due to their high power consumption. This is important for maintaining a stable power supply to the Portenta SOM and the carrier, particularly for extended periods of use.***
 
@@ -2008,7 +2008,7 @@ It is available in two variants, **EMEA** and **Global (covering the US)**. This
 
 ![Arduino Pro 4G GNSS Module Global / Module EMEA](assets/portentaQuectel_overview.gif)
 
-***Make sure to attach external antennas to the Pro 4G Module to work correctly with wireless signals. There are three external antenna connectors: a main antenna connector, an Rx-diversity antenna connector, and a GNSS antenna connector. The impedance of the antenna connectors is 50 Ω.***
+***Make sure to attach external antennas to the Pro 4G Module to work correctly with wireless signals. There are three external antenna connectors: a main antenna connector, an Rx-diversity antenna connector, and a GNSS antenna connector. The impedance of the antenna connectors is **50 Ω**.***
 
 #### Setting Up Via Out-Of-The-Box Experience
 
@@ -2193,9 +2193,9 @@ systemctl stop ModemManager
 
 After stopping **ModemManager**, there will be a delay before the modem can be powered back on and detected by **mmcli**. The delay is around 20 seconds for appropriate initialization.
 
-Make sure the mini PCIe power configuration is configured as described in the [Mini PCIe Power Breakout Header](#mini-pcie-power-breakout-header-j9) section. The Portenta X8 requires the **PCIE Enable (GPIO5)** pin to be connected to a **VCC (3V3)** pin. This is a mandatory power setup for proper system operation.
+Make sure the mini PCIe power configuration is configured as described in the [Mini PCIe Power Breakout Header](#mini-pcie-power-breakout-header-j9) section. The Portenta X8 requires the **PCIE Enable (GPIO5)** pin to be connected to a **VCC (3V3)** pin. This is a required power setup for proper system operation.
 
-The modems may get stuck during operation, so managing power through software is recommended to allow modem rebooting when necessary. This method also helps to handle modem failures in case it happens.
+Modems may get stuck on certain occasions, so managing power through software is recommended to allow modem rebooting when necessary. This method also helps handle modem failures in case they happen.
 
 To adjust for modem initialization, an extended delay of **20 seconds** is required for the modem to power up properly.
 
@@ -2211,39 +2211,71 @@ nmcli c add type gsm ifname cdc-wdm0 con-name wwan0 apn hologram connection.auto
 
 This command establishes a GSM connection on the `cdc-wdm0` interface and automatically connects to the `hologram` APN.
 
-#### EU EC200A-EU Module
+#### Zero Interface Ban Implementation for Global EG25 Module
 
-The **EU EC200A-EU Module** is not directly supported by **ModemManager** out of the box and requires a compatibility patch. Once the patch is applied, you can connect to the network using:
+For the **Global EG25 Module**, it is important to consider a zero interface ban to prevent network conflicts. The zero interface (`cdc-wdm0` or similar) is often created automatically and can lead to connectivity issues. To avoid this, we can tell the system to ignore this interface when managing the modem.
+
+To implement a zero interface ban, you can create a custom `udev` rule that prevents the system from using this interface. The following steps show how to create this rule.
+
+Create a new `udev` rule in `/etc/udev/rules.d/` to ignore the zero interface.
+
+```bash
+sudo nano /etc/udev/rules.d/99-ban-zero-interface.rules
+```
+
+In the rule file, write the following line to ignore the `cdc-wdm0` interface (Change `cdc-wdm0` to the corresponding interface if the name differs in your case):
+
+```bash
+SUBSYSTEM=="net", ACTION=="add", KERNEL=="cdc-wdm0", ATTR{authorized}="0"
+```
+
+This tells the system to disable the interface automatically. Then, reload the `udev` rules with the following commands:
+
+```bash
+sudo udevadm control --reload-rules
+```
+
+```bash
+sudo udevadm trigger
+```
+
+This will prevent the **Global EG25 Module** from using the zero interface (`cdc-wdm0`) and ensure the system uses the correct network interface for establishing connections.
+
+#### EMEA EC200A-EU Module
+
+The **EMEA (EC200A-EU) Module** is not directly supported by **ModemManager** out of the box and requires a compatibility patch. Once the patch is applied, you can connect to the network using:
 
 ```bash
 mmcli -m 0 --simple-connect='apn=iot.1nce.net,ip-type=ipv4v6'
 ```
 
-The modem will create a USB `eth0` interface that will be remapped into `ec200aeu` by an udev rule.
+The modem will create a USB `eth0` interface that will be remapped into `ec200aeu` by an **udev** rule.
 
 #### Docker Environment and Power Management
 
-In a Docker environment, it may be helpful to disable **ModemManager** to avoid conflicts and instead control the modem using **qmicli**. You can disable **ModemManager** with the following command:
+In a Docker environment, it is often useful to disable **ModemManager** to avoid conflicts and instead control the modem using **qmicli**:
 
 ```bash
-systemctl stop ModemManager
+sudo systemctl stop ModemManager
 ```
 
-For modem power management, ensure that the Docker container has access to the GPIO device files by passing them into the container:
+For modem power management, the connection between the **PCIE Enable (GPIO5)** pin and **VCC (3V3)** pin is now required for a proper power setup. This bridge ensures proper hardware functionality when controlling the modem power. Moreover, you should manage power through software to allow the modem to be rebooted in case it becomes unresponsive.
+
+Ensure that the Docker container has access to the GPIO device files by passing them into the container:
 
 ```bash
 docker run --device /dev/gpiochip5 <docker-image>
 ```
 
-Inside the container, an **entrypoint.sh** script can control the modem's power via GPIO. To enable the 3.3V Buck Converter, the following command can be added to the script:
+Inside the container, an **entrypoint.sh** script can control the modem's power via GPIO, having the 3.3V Buck Converter line connected to **PCIE Enable (GPIO5)** pin, the following command can be added to the script:
 
 ```bash
 gpioset gpiochip5 5=1
 ```
 
-***It is mandatory to have **PCIE Enable (GPIO5)** pin connected to the **VCC (3V3)** pin to enable the 3.3V Buck Converter.***
+***It is required to have **PCIE Enable (GPIO5)** pin connected to the **VCC (3V3)** pin to secure power supply line.***
 
-This will enable the power to the modem, and add a delay for modem initialization:
+This will enable the power to the modem and add a delay for modem initialization:
 
 ```bash
 sleep 20
@@ -2275,6 +2307,8 @@ udhcpc -q -f -n -i wwan0
 
 ![Pro 4G Module - Dynamic IP Configuration](assets/portentaMIDcarrier_mpcie_dynamic.png)
 
+### Module Network Performance Test
+
 A speed test can be performed to test the speed and performance of the connection. It involves downloading the `speedtest-cli` script, converting it to an executable, and running it inside a Docker container:
 
 ```bash
@@ -2445,13 +2479,15 @@ AT commands, also known as Hayes commands, are instructions used to control mode
 
 This section explains how to use AT commands to interact with the Cat.4 modem, specifically addressing the differences between the **EG25 (Global)** and **EC200A-EU (EU)** modules. These instructions will guide you through setting up your environment, sending AT commands, and managing your modem effectively.
 
+***Before continuing, it is very important to have read all the [__Cat.4 Modem Cellular Connectivity__](#cat4-modem-cellular-connectivity) section. If you have not read it yet, please go through the section for a better understanding of the requirements and basic setup to use different variants of the Pro 4G Module.***
+
 ### Using Linux
 
 This subsection provides instructions on using **ModemManager**, **mmcli**, and **qmicli** to send AT commands to your Cat.4 modem with the Portenta X8.
 
 #### EG25 (Global) Module
 
-For the EG25 module, which is generally supported directly by NetworkManager, ModemManager handles most of the modem's operations. Begin by ensuring that the Pro 4G Module is properly mounted on the Portenta Mid Carrier and recognized by the Portenta X8.
+For the **GNSS Global (EG25)** module, which is generally supported directly by **NetworkManager**, **ModemManager** handles most of the modem's operations. Begin by ensuring that the Pro 4G Module is properly mounted on the Portenta Mid Carrier and recognized by the Portenta X8.
 
 You can verify the connection using the following command:
 
@@ -2461,7 +2497,7 @@ lsusb
 
 ***Please set up the Pro 4G Module referring to [this section](#using-linux-4). Otherwise, the __ModemManager__ service may not be recognized or working as intended.***
 
-If ModemManager is enabled, you can identify the modem with:
+If **ModemManager** is enabled, you can identify the modem with:
 
 ```bash
 mmcli -L
@@ -2521,34 +2557,40 @@ To configure the EG25 module with NetworkManager, you can use the following comm
 nmcli c add type gsm ifname cdc-wdm0 con-name wwan0 apn hologram connection.autoconnect yes
 ```
 
-#### EC200A-EU (EU) Module
+#### EMEA EC200A-EU Module
 
-The EC200A-EU module, unlike the EG25, is not officially supported by ModemManager and thus requires a different approach. After ensuring that the Pro 4G Module is properly mounted and recognized by the Portenta X8, you may find it presents as a USB Ethernet device (`eth0`). For appropriate configuration, you will need to remap it using an udev rule into an `ec200aeu` network device.
+The **EMEA (EC200A-EU)** module, unlike the EG25 module, is not officially supported by **ModemManager** and thus requires a different approach. After ensuring that the Pro 4G Module is properly mounted and recognized by the Portenta X8, you may find it presents as a USB Ethernet device (`eth0`). For appropriate configuration, you will need to remap it using an `udev` rule into an `ec200aeu` network device.
 
-The ModemManager requires a small compatibility patch for it to work with the module and to send configuration AT commands to the modem. Once patched, you can connect to the network using the following command for example:
+The **ModemManager** requires a small compatibility patch to work with the module and send configuration AT commands to the modem. Once patched, you can connect to the network using the following command for example:
 
 ```bash
 mmcli -m 0 --simple-connect='apn=iot.1nce.net,ip-type=ipv4v6'
 ```
 
-If ModemManager is disabled or if you prefer an alternative method, you can use `qmicli` to identify the modem and interact with it. For instance, you can retrieve the manufacturer information by running:
+If **ModemManager** is disabled or if you prefer an alternative method, you can use `qmicli` to identify the modem and interact with it. For instance, you can retrieve the manufacturer information by running:
 
 ```bash
 sudo qmicli -d /dev/cdc-wdm0 --dms-get-manufacturer
 ```
 
-Power management for the *EC200A-EU module* may require manual intervention, especially if **ModemManager** is disabled. You can power on the modem using a custom script that leverages the `gpiod` library. The script would include commands to set the GPIO pin high and then wait around 20 seconds for the modem to become available, for example: 
+Power management for the **EC200A-EU module** may require manual intervention, particularly if **ModemManager** is disabled or when using Docker. Make sure the mini PCIe power configuration is configured as described in the [Mini PCIe Power Breakout Header](#mini-pcie-power-breakout-header-j9) section. The Portenta X8 requires the **PCIE Enable (GPIO5)** pin to be connected to a **VCC (3V3)** pin. This is a required power setup for proper system operation.
+
+Additionally, sometimes the modem may become unresponsive, so it is recommended that you have a software based power control, which allows you to reboot the modem when necessary.
+
+You can create a custom script using the `gpiod` library to manage modem power via software. Ensure that the jumper connection mentioned previously is in place for this to work. The script can be used to power the modem and provide the required delay for proper initialization. A typical example is as follows:
 
 ```bash
-gpiod set-value <gpio-pin> 1
+gpioset gpiochip5 5=1 #PCIE 3V3 BUCK EN (stm32h7 PE10)
 ```
 
-Followed by:
+After powering on the modem, allow **20 seconds** for the modem to initialize properly:
 
 ```bash
 sleep 20
 ```
 
+This ensures the modem powers up correctly and becomes available for network operations. The software based power control also helps you reboot the modem if it becomes unresponsive, improving overall reliability and preventing manual resets.
+
 #### Docker Container Considerations
 
 Disable ModemManager to prevent conflicts with tools like `qmicli` when managing either modem within a Docker container. This can be done by using the following command:
@@ -2557,15 +2599,41 @@ Disable ModemManager to prevent conflicts with tools like `qmicli` when managing
 sudo systemctl stop ModemManager
 ```
 
-Inside the container, you will need to manage the modem’s power state manually. Use an `entrypoint.sh` script that includes commands to power on the modem with `gpiod`, followed by a short delay to allow the modem to initialize.
+Inside the container, you will need to manage the modem’s power as explained in this [**EC200A-EU**](#emea-ec200a-eu-module-1) section.
 
 To send AT commands, use `qmicli` within the Docker container. For example, you might use following command to interact with the modem:
 
 ```bash
 sudo qmicli -d /dev/cdc-wdm0 --dms-get-manufacturer
 ```
 
-If you are using the EG25 module, NetworkManager can manage the connection outside the container. For the EC200A-EU module, however, you will need to handle the connection using `qmicli` or similar tools within the container.
+If you are using the **GNSS Global (EG25)** module, **NetworkManager** can manage the connection outside the container. For the **EMEA (EC200A-EU)** module, however, you will need to handle the connection using `qmicli` or similar tools within the container.
+
+For example, to retrieve the modem’s manufacturer information:
+
+```bash
+sudo qmicli -d /dev/cdc-wdm0 --dms-get-manufacturer
+```
+
+To send AT commands, you can use `qmicli` directly. For example, to send the `ATI` command to retrieve basic information about the modem, you can use:
+
+```bash
+sudo qmicli -d /dev/cdc-wdm0 --device-open-proxy --dms-get-revision
+```
+
+Or if you want to send custom AT commands, such as `ATI`, you can use the following:
+
+```bash
+sudo qmicli -d /dev/cdc-wdm0 --device-open-proxy --dms-set-test-mode --dms-set-raw-at-command="ATI"
+```
+
+If **ModemManager** is disabled and you want to directly send AT commands to the **EC200A-EU** module using `qmicli`, an example command for sending AT commands is as follows:
+
+```bash
+sudo qmicli -d /dev/cdc-wdm0 --device-open-proxy --dms-set-raw-at-command="AT+CGMI"
+```
+
+This command sends the `AT+CGMI` command, which retrieves the manufacturer information from the modem.
 
 ### Using Arduino
 
