From 2e8693bf0cf0200143cba771b7a2da79cc85cfc5 Mon Sep 17 00:00:00 2001 From: "zhen.guo" Date: Fri, 22 Nov 2024 17:20:06 +0800 Subject: [PATCH] =?UTF-8?q?=E5=88=A0=E9=99=A4=E8=8B=B1=E6=96=87=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E4=B8=AD=E5=8E=9F=E5=8E=82=E5=B7=A5=E5=85=B7=E4=BB=8B?= =?UTF-8?q?=E7=BB=8D=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../en/dev-tools/LogTool/ASR.md | 261 ------------ .../en/dev-tools/LogTool/Qualcomm.md | 203 ---------- .../en/dev-tools/LogTool/README.md | 38 -- .../en/dev-tools/LogTool/UNISOC8910.md | 371 ------------------ docs/Application_guide/en/dev-tools/README.md | 1 - 5 files changed, 874 deletions(-) delete mode 100644 docs/Application_guide/en/dev-tools/LogTool/ASR.md delete mode 100644 docs/Application_guide/en/dev-tools/LogTool/Qualcomm.md delete mode 100644 docs/Application_guide/en/dev-tools/LogTool/README.md delete mode 100644 docs/Application_guide/en/dev-tools/LogTool/UNISOC8910.md diff --git a/docs/Application_guide/en/dev-tools/LogTool/ASR.md b/docs/Application_guide/en/dev-tools/LogTool/ASR.md deleted file mode 100644 index a6f0fdcb..00000000 --- a/docs/Application_guide/en/dev-tools/LogTool/ASR.md +++ /dev/null @@ -1,261 +0,0 @@ -# ASR Platform Log Tool User Guide - -This document introduces how to use the log tools *CATStudio* and *QWinLog* to capture AP and CP logs on the ASR platform. It also explains how to use *CATStudio* to export dump files and pcap files. - -## Overview - -### Tool Introduction - -*CATStudio* is a software tool used for real-time monitoring and capturing ASR series module logs. It has rich functionality, and the most commonly used features for users are capturing AP/CP logs, exporting dump files, and exporting pcap files. - -*QWinLog* is a tool specifically designed for log capturing. It currently supports capturing AP/CP logs of Qualcomm and ASR platforms. - -### Software Installation - -Either *CATStudio* or *QWinLog* is a portable software tool, so you only need to depress the tool's zip to a directory on your computer. Please note that the decompression path cannot contain any Chinese characters, otherwise, the tool cannot run properly. - -### System Requirements - -*CATStudio* is compatible with Windows XP/7/10 system, with a minimum of 512 MB RAM and a dual-core processor. - -*QWinLog* is compatible with the Windows 7/10 system. - -## Hardware Connection - -Before capturing logs, please make the following preparations: - -* Install the USB driver for the ASR series modules. - -* Connect the module to the computer using a USB data cable. - -* Power on the module. - -Go to the "Device Manager" interface on your computer. If the USB driver is loaded correctly, you should see several ports as shown in the following figure. - -![](../../media/dev-tools/LogTool/ASR-USB-port.png) - -The functions of the ports are as follows: - -* Quectel USB AT Port: Used for sending AT commands. - -* Quectel USB DIAG Port: Used for capturing logs. - -* Quectel USB REPL Port: For QuecPython firmware, this port is the REPL port for Python, where you can execute Python codes. Please note that the REPL port name may vary on different platforms. If you are unsure which port is the Python REPL port, you can contact Quectel Technical Support for confirmation. - -The ports highlighted in red in the above figure are the ones you need to use when capturing logs using *CATStudio*. - -## User Guide - -After preparing the hardware environment, follow the steps below to proceed. - -### Capture AP and CP Logs - -#### Using *CATStudio* - -**Step 1: Select Configuration File** - -Open *CATStudio*, and the following window will pop up by default. Select "**Generic Target Online**" and click "**OK**". - -![](../../media/dev-tools/LogTool/CatStudio-1.png) - -**Step 2: Select and Configure Communication Port** - -After finishing "Step 1", you will enter the following interface. Click "**Device Communication**" in the lower right corner to open the corresponding configuration window. By default, select "**Device 0**" and click "**Settings**". - -
Description 1 Description 2
- -In the following interface, select "**Serial**" and click the drop-down button of the "Serial Port" selection box. Choose "**Quectel USB DIAG Port**", and leave the baud rate as default. Click "**OK**", and you can see the window start outputting logs. - -![](../../media/dev-tools/LogTool/CatStudio-4.png) - -> If the main window of *CATStudio* does not output any logs after this step, you may need to restart your computer and reopen *CATStudio*. - -**Step 3: Match DB Files** - -When no DB file is matched, many logs on the *CATStudio* interface will remain undecoded. To better view logs, you can match the DB file corresponding to the module firmware. DB files are usually contained in the corresponding firmware package, as shown below. - -![](../../media/dev-tools/LogTool/ASR-DB-files.png) - -> If the *DBG* directory is not available in your firmware package, you can provide the firmware version number to Quectel Technical Support to obtain the corresponding DB file. - -If there is no matched DB file, you will see a red indicator light on the tool interface, as shown in the following figure. - -![](../../media/dev-tools/LogTool/CatStudio-5.png) - -Click "**Update**" next to the red indicator light to enter the following interface, and then follow the steps below. - -* Select "**TEXT**" at position ①. - -* Click "**...**" at position ②, and in the file selection window, navigate to the path where the module firmware package is located, and then go to the *DBG* directory in the firmware package to select the corresponding DB file. - -* Click "**Update**" at position ③. If the selected DB file matches the firmware in the module, you will see the indicator light on the right side of the CP section turn green. -* After successfully matching the DB file, click "**Close**" at position ④ to return to the log output interface. At this point, the indicator light for Device 0 should also turn green. - -![](../../media/dev-tools/LogTool/CatStudio-6.png) - -> It is not necessary for you to match the DB file. If you only need to capture logs and provide them to Quectel Technical Support for analysis, "Step 3" can be skipped. Quectel Technical Support will match the DB file itself. - -**Step 4: Export Log Files** - -After capturing logs, you need to export the log file and provide it to Quectel Technical Support or software engineers for analysis. Follow the steps below to export the log file. - -* Click "**Log**" in the menu bar, and then click "**Export Log-File**" in the drop-down list to open the "ExportLog" window. - -* In the "ExportLog" window, click "**Select Path(P)**" to choose the path for saving logs. - -* Click "**Output**" and wait for the log file to be exported. - -![](../../media/dev-tools/LogTool/CatStudio-7.png) - -The exported log file contains both AP and CP logs. If you need any assistance in analyzing related issues, please provide the exported log file to Quectel Technical Support or software engineers. - -#### Using *QWinLog* - -**Step 1: Open *QWinLog*** - -Navigate to the root directory of *QWinLog*, double click *QWinLog.exe* to open the tool, and you will see the interface as shown in the figure below. - -![](../../media/dev-tools/LogTool/QWinLog-main-ui.png) - -**Step 2: Configure Parameters** - -Since you are using *QWinLog* to capture logs of the ASR platform, you only need to configure parameters related to the ASR platform, as shown in the figure below. - -![](../../media/dev-tools/LogTool/QWinLog-ASR-param-config.png) - -Follow the steps below. - -- Tick "**QASR log**" at position ①. - -- Select "**USB Port**" at position ②. - -- Click the drop-down button of the "Port" selection box at position ③ and choose "**Quectel USB DIAG Port**," which is the port for capturing AP and CP logs on the ASR platform. - -- "Config file" is the configuration file used by *QWinLog* for log capture. You can use the default configuration file provided by the tool or contact Quectel Technical Support for the configuration file. - -- "Log path" is the path where the captured logs will be saved. You can keep the default setting or modify it as needed. - -**Step 3: Capture Logs** - -Click "**Start**" on the *QWinLog* interface to start capturing logs. Click "**Stop**" to stop capturing logs. - -**Step 4: Package Log Files** - -After capturing the required logs, click "**Stop**" to stop capturing, and then you can find the saved log files in the directory specified in the "Log path" option, as shown in the figure below. - -![](../../media/dev-tools/LogTool/QWinLog-ASR-sdl-log-file.png) - -You only need to compress these log files into a zip and send it to Quectel Technical Support or software engineers. - - - -### Export Dump Files - -If you encounter dump issues while using the ASR platform modules, you can export dump files using *CATStudio* and then send the dump files to Quectel software engineers for analysis. - -**Step 1: Configure Dump Mode** - -By default, ASR platform modules will reboot when a dump occurs, making it impossible to export dump files. To export dump files, you need to configure the module's dump mode by sending the following AT commands when the module runs normally to ensure the module will not reboot automatically when a dump occurs but stays in dump status. - -``` -AT+QDUMPCFG=0,0 -AT+QDUMPCFG=2,1 -AT+log=19,1 -``` - -While the module is running normally, you need to open *QPYcom*, select "**Quectel USB AT Port**" for "COM Port," and click "**Open port**". Then, send the three AT commands above one by one, as shown in the figure below. - -![](../../media/dev-tools/LogTool/QPYcom-ASR-dump-config.png) - - - -**Step 2: Reproduce Dump Issue** - -After finishing "Step 1" to configure the dump mode and sending the AT commands, you need to reproduce the issue that led to the dump. When the dump issue occurs, you will see a dump port in your computer's device manager, as shown below. - -![](../../media/dev-tools/LogTool/dump-port.png) - - - -**Step 3: Select Configuration File** - -Open *CATStudio*, and the following window will pop up by default. Select **"Log-Only Online**" and click "**OK**". - -![](../../media/dev-tools/LogTool/CatStudio-online.png) - - - -**Step 4: Configure Parameters and Export Dump Files** - -After following "Step 3", a window will pop up as shown below. Click "**Dump**" at position ① to open the dump export page, and configure the parameters as indicated by the numbers in the figure. - -![](../../media/dev-tools/LogTool/CatStudio-dump-export-1.png) - -- Select "**YModem**" at position ②. -- Click the drop-down button at position ③ and select the dump port you identified in "Step 2". -- Click "**Open**" at position ④ to open the corresponding port. -- Click "**Browse**" at position ⑤ to select the path where you want to save the dump file. -- Click "**Receive**" at position ⑥ to start exporting the dump file. Until the export is completed, a window will pop up, and you can click "**OK**." - -![](../../media/dev-tools/LogTool/CatStudio-dump-export-2.png) - -After executing these steps, the dump files have been successfully exported. You can compress the exported dump files into a single zip and provide it to Quectel Technical Support or software engineers for analysis. - - - -### Export Pcap Files - -Pcap files are commonly used for storing network data and are typically used with popular network analysis tools like Wireshark and tcpdump to monitor and analyze issues related to network applications, such as data transmission over MQTT and HTTP. - -*CATStudio* supports the export of pcap files. Follow the steps below to export pcap files using *CATStudio*. - -**Step 1: Export AP and CP Logs** - -Follow the steps in the [Capture AP and CP Logs](./ASR.html#Capture AP and CP Logs) section to export log files for later use. - -**Step 2: Select Configuration File** - -Open *CATStudio*, and the following window will pop up by default. Select "**Generic Target Offline**" and click "**OK**". - -![](../../media/dev-tools/LogTool/CatStudio-offline.png) - -> Please note that in this case, you should select "Generic Target Offline". In the *Capture AP and CP Logs* section, you should select "Generic Target Offline". - -**Step 3: Load Log Files** - -After entering the *CATStudio* main interface, click "**Open ZIP/ICL...**" in the upper right corner. In the pop-up window, select the log file zip you exported earlier and wait for the zip to be decompressed and loaded. - -![](../../media/dev-tools/LogTool/CatStudio-load-zip-log.png) - -If, during the file loading process, you see the window below, it means that the selected log file zip is relatively large and exceeds the default file size limit. In this case, click "**Cancel (Load whole file)**," which means loading the whole file. - -![](../../media/dev-tools/LogTool/CatStudio-load-whole-file.png) - -**Step 4: Match DB Files** - -If you have already matched DB files during the log export process, you can skip this step and proceed directly to "Step 5". Otherwise, follow the instructions provided earlier to match DB files. - -**Step 5: Export Pcap Files** - -Click "**Action**" in the menu bar, then select "**Export SN Trace to pcap file**" from the drop-down list. A window will pop up as shown below. - -![](../../media/dev-tools/LogTool/CatStudio-export-pcap-file.png) - -In this window, select the location where you want to save the export file, then click "**OK**". Until the export is completed, a window will pop up, and you can click "**OK**." - -![](../../media/dev-tools/LogTool/CatStudio-export-pcap-file-finish.png) - - - -## FAQ - -**Q1**: Why did I fail to capture logs using *QWinLog* with a window like the one shown below popped up? - -![](../../media/dev-tools/LogTool/QWinLog-open-port-failed.png) - -There may be two reasons: - -**Reason 1:** Another program occupies "Quectel USB DIAG Port". You can check whether the port is occupied. If the port is occupied, close the program occupying the port and try to capture logs again. - -**Reason 2:** The USB driver has loaded abnormally. You can disconnect the module from the computer, and then reconnect the module with the computer via a USB cable, or power cycle the module. If the issue still exists, restart your computer. - diff --git a/docs/Application_guide/en/dev-tools/LogTool/Qualcomm.md b/docs/Application_guide/en/dev-tools/LogTool/Qualcomm.md deleted file mode 100644 index 2d373138..00000000 --- a/docs/Application_guide/en/dev-tools/LogTool/Qualcomm.md +++ /dev/null @@ -1,203 +0,0 @@ -# Qualcomm Platform Log Tool User Guide - -*QWinLog* is used to capture the AP and CP logs of Qualcomm platform modules. *QPST* is used to export dump files. *QCAT* is used to export pcap files. - -## Overview - -### Tool Introduction - -*QWinLog* is a tool specifically designed for log capturing. It currently supports capturing AP/CP logs of Qualcomm platform modules. - -### Software Installation - -*QWinLog* is a portable software tool, so you only need to depress the tool's zip to a directory on your computer. Please note that the decompression path cannot contain any Chinese characters, otherwise, the tool cannot run properly. - -### System Requirement - -*QWinLog* is compatible with the Windows 7/10 system. - - - -## Hardware Connection - -Before capturing logs, please make the following preparations: - -* Install the USB driver for the Qualcomm series modules. - -* Connect the module to the computer using a USB data cable. - -* Power on the module. - -Go to the "Device Manager" interface on your computer. If the USB driver is loaded correctly, you should see several ports as shown in the following figure. - -![](../../media/dev-tools/LogTool/Qualcomm-USB-port-1.png) - -![](../../media/dev-tools/LogTool/Qualcomm-USB-port-2.png) - -The functions of the ports are as follows: - -* Quectel USB DM Port: Used for AP and CP log output. -* Quectel USB Modem: Used for sending AT commands. -* Quectel USB REPL Port: For QuecPython firmware, this port is the REPL port for Python, where you can execute Python codes. Please note that the REPL port name may vary on different platforms. If you are unsure which port is the Python REPL port, you can contact Quectel Technical Support for confirmation. - - - -## User Guide - -Please make sure that the device has been connected to the PC and all USB ports are enumerated successfully, and then you can configure and use the software tool. - -### Capture AP and CP Logs - -**Step 1: Open *QWinLog*** - -Navigate to the root directory of *QWinLog*, double click *QWinLog.exe* to open the tool, and you will see the interface as shown in the figure below. - -![](../../media/dev-tools/LogTool/QWinLog-main-ui.png) - - - -**Step 2: Configure Parameters** - -Since you are using *QWinLog* to capture logs of the Qualcomm platform, you only need to configure parameters related to the Qualcomm platform, as shown in the figure below. - -![](../../media/dev-tools/LogTool/QWinLog-QXDM-param-config.png) - -Follow the steps below. - -- Tick "**QXDM log**" at position ①. After the tool is opened, this option will generally be ticked by default, if not, please tick it manually. - -- Select "**USB&TCP Port**" at position ②. - -- Click the drop-down button of the "Port" selection box at position ③ and choose "**Quectel USB DM Port**. - -- "Config file" is the configuration file used by *QWinLog* for log capture. You can use the default configuration file provided by the tool or contact Quectel Technical Support for the configuration file. - -- "Log path" is the path where the captured logs will be saved. You can keep the default setting or modify it as needed. - - - -**Step 3: Capture Logs** - -Click "**Start**" on the *QWinLog* interface to start capturing logs. Click "**Stop**" to stop capturing logs. - - - -**Step 4: Package Log Files** - -After capturing the required logs, click "**Stop**" to stop capturing, and then you can find the saved log files in the directory specified in the "Log path" option, as shown in the figure below. - -![](../../media/dev-tools/LogTool/QWinLog-ASR-sdl-log-file.png) - -You only need to compress these log files into a zip and send it to Quectel Technical Support or software engineers. - - - -### Export Dump Files - -To capture and export dump files of Qualcomm platform, you need to use *QPST* (Qualcomm Product Support Tools). If *QPST* is not installed on your computer, please contact Quectel Technical Support to obtain the corresponding tool installation package and install it. *QPST* can automatically capture and export dump files with simple configuration. - -**Step 1: Configure Dump Mode** - -Here is how to configure dump mode for Qualcomm platform modules with AT command. - -```plaintext -AT+QCFGEXT="dump",1 -``` - -Open *QPYcom*, select "**Quectel USB Modem**" for "COM Port," and click "**Open port**". Then, send the AT command above. - -![](../../media/dev-tools/LogTool/Qualcomm-dump-config.png) - -> Note: The AT command takes effect immediately and the configuration is automatically saved after the module is rebooted. - - - -**Step 2: Open *QPST*** - -After *QPST* is installed, navigate to the "*bin*" folder in the installation directory and double click the "*QPSTServer.exe*" file to open *QPST*. You will see the main interface shown below. - -![](../../media/dev-tools/LogTool/QPST-UI-1.png) - -If you don't see the main window of the tool, you can double click the earth icon in the bottom-right corner of your computer, as shown below. - -![](../../media/dev-tools/LogTool/QPST-UI-2.png) - - - -**Step 3: Add Port** - -In the *QPST* main window, click "**Ports**" at position ①. - -![](../../media/dev-tools/LogTool/QPST-param-config-1.png) - -Then, click "**Add New Port**" at position ②. In the pop-up window, select the "**Serial/USB Ports**" tab, select "**Quectel USB DM Port**" and click "**OK**". - -![](../../media/dev-tools/LogTool/QPST-param-config-2.png) - -After you click "**OK**", *QPST* will automatically open and connect to "**Quectel USB DM Port**". - - - -**Step 4: Reproduce Dump Issue** - -With *QPST* configured, you can reproduce the dump issue. When the dump issue occurs, *QPST* will automatically recognize it and capture and save the dump files. - - - -**Step 5: Package Dump Files** - -After *QPST* has automatically captured and saved the dump files, click "**Help**" → "**Open Log File Directory**" in the menu bar to open the directory where the dump files are saved. *QPST* will create a sub-folder with the name "Port_COMx" under the *Sahara* directory to store the dump files, as shown in the figure below. - -![](../../media/dev-tools/LogTool/QPST-dump-files-dir.png) - -You can compress the dump files automatically captured and saved by *QPST* into a single zip and provide it to Quectel Technical Support or software engineers for analysis. - - - -### Export pcap Files - -To export pcap files of Qualcomm platform, you need to use *QCAT*. If *QCAT* is not installed on your computer, please contact Quectel Technical Support to obtain the corresponding tool installation package and install it. - -**Step 1: Capture AP and CP Logs** - -To export pcap files on the Qualcomm platform, you first need to capture log files in *.bin* format using *QWinLog*, following the steps stated in the "Capture AP and CP Logs" section. - - - -**Step 2: Modify Log File Extension** - -Navigate to the directory where the log files in *.bin* format are saved. Make a copy of the log files and change the file extension of the copied file to *.qmdl*, as shown below. - -![](../../media/dev-tools/LogTool/bin-to-qmdl.png) - - - -**Step 3: Open *QCAT*** - -After *QCAT* is installed, navigate to the "*bin*" folder in the installation directory and double click the "*QCAT.exe*" file to open *QCAT*. You will see the main interface shown below. - -![](../../media/dev-tools/LogTool/QCAT-UI-1.png) - - - -**Step 4: Import Files** - -In the *QCAT* main window, click the button as shown in the figure below. In the pop-up window, navigate to the directory where the *.qmdl* file is located, select the *.qmdl* file, and wait for the file to be imported. - -![](../../media/dev-tools/LogTool/QCAT-UI-2.png) - - - -> Users can also directly drag and drop the .qmdl file into the QCAT main window to import the file. - - - -**Step 5: Export pcap Files** - -Click "**Tools**" → "**Convert log to PCAP/TXT**" to open the following window. - -![](../../media/dev-tools/LogTool/QCAT-export-pcap-1.png) - -In this window, you can see the path of the input file and the path where the exported pcap file will be saved, which is usually the same directory as the input file. Click "**Run**" in the above figure to start exporting the pcap file. After the export is completed, go back to the directory where the *.qmdl* file is located, and you will see the exported pcap file, as shown in the following figure. - -![](../../media/dev-tools/LogTool/QCAT-export-pcap-2.png) diff --git a/docs/Application_guide/en/dev-tools/LogTool/README.md b/docs/Application_guide/en/dev-tools/LogTool/README.md deleted file mode 100644 index 305a7567..00000000 --- a/docs/Application_guide/en/dev-tools/LogTool/README.md +++ /dev/null @@ -1,38 +0,0 @@ -# Log Tool User Guide - -This document introduces the usage of log capture tools for different QuecPython platforms, including ASR, UNISOC8910 and Qualcomm. - -## Purpose of Module Log - -During the use of the module, you may encounter various issues. In order to identify the cause of the problem and the running status of the module code, it is usually necessary to capture the running logs of the module. These logs can help you analyze and locate problems, as well as determine whether the operation of certain functions meets expectations. - -## Module Log Types - -Module logs are generally classified into AP logs, CP logs, pcap logs, and dump files. - -* AP logs: Logs output by the SDK and Apps. AP logs are mainly used to confirm the running status of the system software and can be used to locate software bugs. - -* CP logs: Logs related to the wireless protocol stack output by the Modem, such as air interface logs. CP logs are mainly used to locate the bugs related to wireless networks, such as module network registration problems and abnormal network disconnections. To locate the device's network registration problem, you need to capture the CP logs during the device's boot stage or the CP logs containing the CFUN0/1 switching process. - - > CFUN0/1 switching refers to calling `net.setModemFun(0)` to switch the device to mode 0 (minimum functionality mode), and then calling `net.setModemFun(1)` to switch the device to mode 1 (full functionality mode). The purpose is to make the device initiate the network registration process again. If you did not capture the CP logs during the device's boot stage, you can also capture the CP logs containing the CFUN0/1 switching process and provide them to Quectel software engineers for analysis. - -* pcap logs: pcap logs can be used to analyze and debug network traffic. Through pcap logs, you can know the working status of the device or application at the network level to identify performance issues or faults. By analyzing pcap logs, you can view the details of network communication, such as the process of establishing connections, the format of transmitted packets, and the parameters of requests and responses. For example, when analyzing TCP/IP, MQTT, HTTP/HTTPS issues, pcap logs are often used. You can use *Wireshark* to open pcap files. -* dump files: When some unrecoverable errors have occurred in the operating system or application, it will save certain parts of the memory as files to record the status and other relevant information at that time. These files are called dump files. For example, program crashes, illegal memory access, memory exhaustion, stack overflow, and other abnormal issues may cause the module program to crash and reboot abnormally. If you encounter situations where the module reboots abnormally, it is likely that a dump problem has occurred. At this time, it is necessary to capture and export the dump file and provide it to Quectel software engineers for problem localization and analysis. - -## Log Tools for Each Platform - -Below are the tools used to capture AP/CP logs, pcap logs, and dump files for each platform. - -| Platform | Module Model | AP Log | CP Log | pcap Log | Dump File | Icon | -| ---------- | --------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | --------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------ | -| ASR | EG915N | [CATStudio](./ASR.html#UsingCATStudiotoCaptureLogs)
[QWinLog](./ASR.html#UsingQWinLogtoCaptureLogs) | [CATStudio](./ASR.html#UsingCATStudiotoCaptureLogs)
[QWinLog](./ASR.html#UsingQWinLogtoCaptureLogs) | [CATStudio](./ASR.html#ExportingPcapFiles) | [CATStudio](./ASR.html#ExportingDumpFiles) | ![](../../media/dev-tools/LogTool/CatStudio.png)![](../../media/dev-tools/LogTool/QWinLog.png) | -| UNISOC8910 | EC200U/EG912U/
EG915U | [coolwatcher](./UNISOC8910.html#CapturingAPLogs) | [ArmTracer](./UNISOC8910.html#CapturingCPLogs) | [coolwatcher](./UNISOC8910.html#ExportingPcapFiles) | [coolwatcher](./UNISOC8910.html#ExportingDumpFiles) | ![](../../media/dev-tools/LogTool/cooltools.png) ![](../../media/dev-tools/LogTool/ArmTracer.png) | -| Qualcomm | BG95M1/BG95M3/
BG95M6/BG95M8/BG95M9 | [QWinLog](./Qualcomm.html#CapturingAPandCPLogs) | [QWinLog](./Qualcomm.html#CapturingAPandCPLogs) | [QCAT](./Qualcomm.html#ExportingPcapFiles) | [QPST](./Qualcomm.html#ExportingDumpFiles) | ![](../../media/dev-tools/LogTool/QWinLog.png)![](../../media/dev-tools/LogTool/QCAT.png) | - -## Table of Contents - -[ASR Platform Log Tool User Guide](./ASR.md) - -[Qualcomm Platform Log Tool User Guide](./Qualcomm.md) - -[UNISOC8910 Platform Log Tool User Guide](./UNISOC8910.md) \ No newline at end of file diff --git a/docs/Application_guide/en/dev-tools/LogTool/UNISOC8910.md b/docs/Application_guide/en/dev-tools/LogTool/UNISOC8910.md deleted file mode 100644 index 83c9d0e4..00000000 --- a/docs/Application_guide/en/dev-tools/LogTool/UNISOC8910.md +++ /dev/null @@ -1,371 +0,0 @@ -# UNISOC8910 Platform Log Tool User Guide - -This document introduces how to use *coolwatcher* and *ArmTracer* to capture AP and CP logs, as well as export dump files. - -## Overview - -### Tool Introduction - -*coolwatcher* is a software tool used to capture AP logs on the UNISOC8910 platform module. It also supports exporting dump files. - -*ArmTracer* is a software tool used to capture CP logs on the UNISOC8910 platform module. It is used to analyze module network registration-related issues. - -### Software Installation - -Either *CATStudio* or *QWinLog* is a portable software tool, so you only need to depress the tool's zip to a directory on your computer. Please note that the decompression path cannot contain any Chinese characters, otherwise, the tool cannot run properly. - -### System Requirements - -*coolwatcher* is compatible with Windows XP/7/10 system, with a minimum of 4 GB RAM and a dual-core processor. - -*ArmTracer* is compatible with Windows XP or later versions. If *ArmTracer* fails to run properly, try running it as an administrator or in XP SP3 compatibility mode. - -## Hardware Connection - -Before capturing logs, make sure to: - -* Install the USB driver for the UNISOC8910 platform module. - -* Connect the module to the computer using a USB data cable. - -* Power on the module. - -Go to the "Device Manager" interface on your computer. If the USB driver is loaded correctly, you should see several ports as shown in the following figure. - -![](../../media/dev-tools/LogTool/UNISOC8910-USB-port.png) - -The functions of the ports are as follows: - -* Quectel Modem: Used for PPP data calls and sending AT commands. However, AT commands are seldom sent through this port but from a dedicated AT port. - -* Quectel USB AP Log Port: Used for capturing AP logs. - -* Quectel USB AT Port: The dedicated AT port for sending AT commands. - -* Quectel USB CP Log Port: Used for capturing CP logs. - -* Quectel USB Diag Port: Reserved. - -* Quectel USB MOS Port: Reserved. - -* Quectel USB REPL Port: For QuecPython firmware, this port is the REPL port for Python, where you can execute Python codes. Please note that the REPL port name may vary on different platforms. If you are unsure which port is the Python REPL port, you can contact Quectel Technical Support for confirmation. - - - -## User Guide - -Please make sure that the device has been connected to the PC and all USB ports are enumerated successfully, and then you can configure and use the software tool. - -### Capture AP Logs - -**Step 1: Open *cooltools*** - -Decompress the *cooltools* zip to a directory on your computer. Please note that the path to *cooltools* should not contain any Chinese characters. After decompression, navigate to the root directory of *cooltools*. - -![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-root-dir.png) - -Double click *coolwatcher_usb.exe* to open the tool. The following configuration window will pop up. The left side is the module model selection area, and the right side is the configuration options for the selected model. - -* Click "**8910**" at position ① to enter the configuration interface for the corresponding platform. - -* Confirm that the model at position ② is "8910". - -* In the input box at position ③, enter the port number corresponding to "Quectel USB AP Log Port". Click "**OK**". - -![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-1.png) - - - -**Step 2: Wait for the Tool to Successfully Connect to the Module** - -After configuring the port in "Step 1" and clicking "**OK**", *coolwatcher* will automatically open the "Quectel USB AP Log Port" and establish a connection with the module. Once the connection is successfully established, the following interface will pop up. There will be several green prompt messages on the left side, and the last message will be "[COM OPEN OK]". - -![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-2.png) - -The above figure shows the main interface of *coolwatcher*. The "Trace tool" window on the right side is where the AP logs are displayed. The buttons at position ① control the AP logs, and below are the function descriptions of several commonly used buttons. - -| Button | Function | -| ------------------------------------------------------------ | ------------------------------------------------------------ | -| ![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-start.png) | Start: Click to start outputting AP logs in the trace window. | -| ![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-stop.png) | Stop: Click to stop outputting AP logs in the trace window. | -| ![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-clear.png) | Clear: Click to clear all AP logs in the trace window. | -| ![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-set.png) | Set: Click to open the settings window, where you can configure auto-saving, file types, save path, size of a single file and pcap file saving. | -| ![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-save.png) | Save: Click to save the logs immediately. You can configure auto-saving through the "Set" button, so manual saving is not required. | - -The box at position ② in the figure is the keyword input box for the AP log filtering criteria. You can enter a keyword in the input box as a filter, and then *coolwatcher* will list all AP logs that contain the keyword. - -If, after the port configuration in "Step 1", the Trace tool window on the right side of the above figure does not pop up, but the following window pops up instead, it means that the software version you are using is not the latest. - -![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-old-ver-1.png) - -In this case, follow the steps below: - -Click "**Plugins**", and in the drop-down window, click "**Activate Tracer**" to display the Trace tool window. - -![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-old-ver-2.png) - -![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-old-ver-3.png) - - - -**Step 3: Configure Parameters** - -Click the "**Set**" icon in the "Trace tool" window toolbar to open the "Set Trace Levels" window. You only need to pay attention to and set the parts marked in the figure. - -* ① Auto Save Trace: It is ticked by default. If it is not ticked, you are recommended to tick this option. - -* ② Log file type: Two types, Bin and trc, with trc being the default. *Bin* files can only be viewed with *coolwatcher*, while *trc* files are plain text files. - -* ③ Split Size: When the log size exceeds this value, it will be automatically saved to a new file. - -* ④ Directory: You can set the directory to save log files according to your needs. The default directory is the *logs* directory under *coolwatcher* root directory. - -* ⑤ Save Pcap: This option is not ticked by default. You are recommended to tick this option. When this option is ticked, *coolwatcher* will automatically capture and save pcap files. - -After configuring parameters as the above instructions, click "**OK**" to save the configuration. - -![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-config.png) - - - -**Step 4: Capture Logs** - -Click the "**Start**" icon in the "Trace tool" window to start outputting logs, as shown in the following figure. - -![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-start-trace.png) - - - -**Step 5: Package Log Files** - -When the required AP logs have been captured, click the "**Stop**" icon in the "Trace tool" window. Go to the custom directory for saving logs. If you have not customized it, logs will be saved to the *logs* folder under the *coolwatcher* root directory by default. After entering the directory for saving AP logs, package and compress all the files in the *logs* directory, and then send them to Quectel Technical Support or software engineers for problem analysis. - -![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-log-dir.png) - -> It is recommended to delete the historical log files in the default log-saving path before each log capture. - -### Capture CP Logs - -To capture CP logs of the UNISOC8910 platform modules, you need to use *ArmTracer*. The following will explain how to use *ArmTracer* to capture the CP logs of a module. - -**Step 1: Open *ArmTracer*** - -Decompress the *ArmTracer* zip to a directory on your computer. Please note that the path to *ArmTracer* should not contain any Chinese characters. After decompression, navigate to the root directory of *ArmTracer*. Double click *ArmTracer.exe* to open the tool. The main interface window will pop up. - -![](../../media/dev-tools/LogTool/UNISOC8910-armtracer-ui-1.png) - -In the above figure, ① is the "**Configure Parameter**" icon, ② is the "**Start**" icon, ③ is the "**Stop**" button, and ④ is the "**Set Log-saving Path**" icon. - - - -**Step 2: Configure Port Parameters** - -Click the "**Configure Parameter**" icon on the toolbar to open the following window. Since the USB port is used, you only need to select the port number, and other parameters are generally kept as default. Click the drop-down button in the "Device Port" option box and select the port number corresponding to the "Quectel USB CP Log Port". Then click "**OK**". - -![](../../media/dev-tools/LogTool/UNISOC8910-armtracer-port-config.png) - - - -**Step 3: Set the Log Save Path** - -Click the "**Set Log-saving Path**" icon on the toolbar to open the following setting window. "Saved Path" is the path of saving the CP logs, and you can set it according to your needs. "Filename" is the name of the log file. *ArmTracer* will combine this name with a timestamp to form the final log file name. After setting the log file saving path and file name, click "**OK**". - -![](../../media/dev-tools/LogTool/UNISOC8910-armtracer-log-save-setting.png) - - - -**Step 4: Capture CP Logs** - -Click the "**Start**" icon on the toolbar. At this time, the "log setting" window in "Step 3" may pop up automatically. Just click "**OK**". If the hardware connection is normal and the tool is configured correctly, the tool window should start outputting log information, as shown in the following figure. - -![](../../media/dev-tools/LogTool/UNISOC8910-armtracer-ui-2.png) - - - -**Step 5: Package and Save Log Files** - -When the required logs are captured, click the "**Stop**" icon on the *ArmTracer* toolbar, and the log will be automatically saved to the directory previously customized. You can package and compress all the latest *.tra* files in the log-saving directory into one zip, and send it to Quectel Technical Support. - -![](../../media/dev-tools/LogTool/UNISOC8910-armtracer-log-file.png) - - - -#### Configure Automatic Log Capture - -The purpose of capturing CP logs is to analyze wireless network-related issues of the device, such as device network registration failure. The device's network registration process is automatically performed during the boot stage, so to analyze network registration failure and related issues, it is necessary to capture the CP logs during the device boot stage. To capture CP logs during the device boot stage, you can configure *ArmTracer* to automatically detect the CP log port and capture the logs. The following explains how to configure this feature. - -> To analyze the network registration failure of the module only, you can also choose not to configure this feature and manually capture the CP logs that include the CFUN0/1 switching process. - - - -**Step 1: Open Configuration File** - -Go to the root directory of *ArmTracer* and find the configuration file, *ArmTracer.ini*, as shown in the following figure. - -![](../../media/dev-tools/LogTool/UNISOC8910-armtracer-config-file.png) - -Open *ArmTracer.ini* in a text editor. Find the "[USBDevice]" section, as shown in the following figure. - -![](../../media/dev-tools/LogTool/UNISOC8910-armtracer-USBDevice-1.png) - - - -**Step 2: Modify Configuration File** - -After finding the "[USBDevice]" section, you need to add "Quectel USB CP Log Port" to the "`DeviceList`" and change the value of "`DeviceSel`" to "Quectel USB CP Log Port", as shown below. - -![](../../media/dev-tools/LogTool/UNISOC8910-armtracer-USBDevice-2.png) - -After modification, save and exit. - - - -**Step 3: Select Automatic Detection of CP Port** - -If *ArmTracer* has been already opened before you modify the configuration file, you need to close *ArmTracer* and reopen it for the configuration to take effect. After opening *ArmTracer*, enter the following main interface. - -![](../../media/dev-tools/LogTool/UNISOC8910-armtracer-ui-3.png) - -Click the icon pointed by the arrow in the figure, and the "Software Setting" window will pop up. You can see that the value corresponding to "USB Device Description" is already set to "Quectel USB CP Log Port". Tick "**Automatic Detect CP Port**" and click "**OK**". - -![](../../media/dev-tools/LogTool/UNISOC8910-armtracer-software-setting.png) - -If the configuration is correct, theoretically, after you click "**OK**", the tool will automatically detect the CP log port and start capturing logs. You can see the CP logs output as shown below. - -![](../../media/dev-tools/LogTool/UNISOC8910-armtracer-log-output.png) - -To further verify if the configuration is correct, restart the device and observe if *ArmTracer* can automatically detect the CP log port and start outputting logs. If you can see continuous log output in the log output window, it means the configuration is effective. Then you can start capturing CP logs. - - - -### Export Dump Files - -*coolwatcher* supports exporting dump files. When the module encounters a crash dump, you can use *coolwatcher* to export the dump files, and then compress them into a zip and send the zip to Quectel software engineers for analysis. The following describes how to use *coolwatcher* to export dump files. - -**Step 1: Configure Dump Mode** - -By default, ASR platform modules will reboot when a dump occurs, making it impossible to export dump files. To export dump files, you need to configure the module's dump mode by sending the following AT commands when the module runs normally to ensure the module will not reboot automatically when a dump occurs but stays in dump status. - -The following is the AT command that needs to be sent to configure the dump mode for the UNISOC8910 platform modules. - -``` -AT+QDBGCFG="DUMPCFG",0 -``` - -Open *QPYcom*, select "**Quectel USB AT Port**" for "COM Port," and click "**Open port**". Then, send the AT command above. - -![](../../media/dev-tools/LogTool/UNISOC8850-dump-config.png) - ->The AT command takes effect immediately but the configuration is not saved. If the module is rebooted, you need to send the command again. - -**Step 2: Reproduce Dump Issue** - -After sending the AT command in "Step 1", you can reproduce the dump issue. When the module encounters a dump issue, you can see the following log information from the *coolwatcher* log output window. - -![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-dump.png) - - - -**Step 3: Export Dump Files** - -Click "**Tools**" → "**Blue Screen Dump**", as shown in the following figure。 - -![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-dump-export-1.png) - -After clicking, the "Blue Screen Dump" window will pop up, as shown in the following figure。 - -![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-dump-export-2.png) - -In the window shown above, you need to perform the following operations. - -* "Mode": Select "**8910 (FreeRTOS)**". - -* "XML file name": Select the file shown in the figure, which is generally the default file. - -* "Elf file name": Select the *elf* file corresponding to the firmware currently used by the module, which can generally be found directly in the firmware package, as shown in the figure below. If it is not available in the firmware package, you can contact Quectel Technical Support to obtain the corresponding *elf* file for the firmware. - -![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-elf-file.png) - ->If you are using the latest version of *coolwatcher*, when exporting the dump file, you do not need to select the *elf* file, that is, in the "Bule Screen Dump" window above, the "Elf file name" option is disabled. If the "Elf file name" option is selectable, you can select the corresponding *elf* file according to the above instructions. - -* "Output Directory": Select the directory to save the dump file. Please note that the selected directory should not contain any Chinese characters or spaces. - -After configuring the parameters according to the above instructions, click the "**Start**" icon to start exporting the dump file and wait for the dump file export to complete, as shown in the following figure. - -![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-dump-export-3.png) - -Go to the directory to save the dump file, compress all the dump files, and send them to Quectel Technical Support or software engineers for analysis. - -![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-dump-export-4.png) - -### Export Pcap Files - -*coolwatcher* supports the automatic saving of pcap files, but this function is not enabled by default. The method to enable the automatic saving of pcap files has been mentioned in "Step 3" of the [Capture AP Logs](./UNISOC8910.html#Capture AP Logs). That is, click the "Set" icon in the "Trace tool" window toolbar, and the following settings window will pop up. Tick "**Save Pcap**" at position ⑤ in the figure, and click "**OK**". - -![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-config.png) - -After ticking this function, *coolwatcher* will automatically capture and save pcap files. The path to save pcap files is the "cap" subdirectory under the directory set at position ④ in the figure. The "cap" directory is automatically created by *coolwatcher*, so you do not need to create this folder. - -![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-pcap-file.png) - -If you need any assistance in analyzing network application-related issues, you can compress the AP log files and pcap files together and send them to Quectel Technical Support. - -## FAQ - -**Q1**: The dump export failed. - -There are multiple reasons for the failure of dump export. The common reasons are as follows. - -Scenario 1: - -![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-dump-export-failed-1.png) - -If the error message for the export failure is similar to the figure above, the possible reasons are: - -* The USB data cable connecting the module and the computer is too long. You can try a shorter USB data cable. - -* The module and the computer are not directly connected via a USB cable but through a hub. This situation can easily lead to dump export failure. It is recommended to directly connect the module to the computer via a USB data cable. - -Scenario 2: - -![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-dump-export-failed-2.png) - -![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-dump-export-failed-3.png) - -If the error message for export failure is similar to the above two figures, it is likely that the selected *elf* file does not match the firmware currently used by the module. In this case, you need to select an *elf* file that matches the firmware currently used by the module. - -If you have followed the above troubleshooting steps and still cannot export dump files, please contact Quectel Technical Support for assistance. - -**Q2**: After opening *coolwatcher* as instructed earlier and clicking the "**Start**" icon, there is no AP log output in the "Trace tool" window. - -AP logs are normally output from the USB port, which, for *coolwatcher*, is the "Quectel USB AP Log Port". If you have previously switched the AP log output to the physical debug port with AT commands, clicking the "Start" icon will result in no AP log output in the "Trace tool" window. In this case, you can follow the steps below. - -Step 1: Confirm the current AP log output port. - -Send the following AT command to query the current AP log output port. - -``` -at+qdbgcfg="tracecfg" -``` - -Open *QPYcom*, select "**Quectel USB AT Port**" for "COM Port," and click "**Open port**". Then, send the AT command above. - -![](../../media/dev-tools/LogTool/at-qdbgcfg-tracecfg-1.png) - -If the query result is as shown in the above figure, with the last two digits being 0 and 1, it means that the current AP log output port is the physical debug port. - -In this case, you can send the following AT command to switch the AP log output port to the USB port. - -``` -at+qdbgcfg="tracecfg",0,2 -``` - -![](../../media/dev-tools/LogTool/at-qdbgcfg-tracecfg-2.png) - -Since the above AT command takes effect after the module is rebooted, after sending the above AT command, reboot the module. Then go back to the *coolwatcher* interface, click the "**Start**" icon again, and you should see the log output. - -**Q3**: If the following information is shown, is something wrong with the system? - -![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-invalid-tdb.png) - -The information shown in the above figure is not an indication of abnormal module functionality, but rather because the version of *coolwatcher* being used is old and cannot recognize and parse certain logs. You can contact Quectel Technical Support to request the latest version of *coolwatcher*. \ No newline at end of file diff --git a/docs/Application_guide/en/dev-tools/README.md b/docs/Application_guide/en/dev-tools/README.md index f0ea4604..cb451db0 100644 --- a/docs/Application_guide/en/dev-tools/README.md +++ b/docs/Application_guide/en/dev-tools/README.md @@ -8,6 +8,5 @@ This series of documents will introduce the use of QuecPython tools, including t - [Thonny IDE User Guide](./Thonny/README.md) - [DTU Tool User Guide](./DTU-Tool/README.md) - [Factory Tool User Guide](./FactoryTool/README.md) -- [Log Tool User Guide](./LogTool/README.md) - [VSCode Plugin User Guide](./VSCode-Plugin-quecpython/README.md) - [Multi-port User Guide](./QMulti-DL/README.md) -- Gitee