From 57c1ce7d9b7296438ddad764e0509867db839904 Mon Sep 17 00:00:00 2001 From: "zhen.guo" Date: Wed, 4 Dec 2024 13:40:44 +0800 Subject: [PATCH] add LogTool --- docs/Application_guide/en/README.md | 1 + .../en/dev-tools/LogTool/ASR.md | 261 ++++++++++++ .../en/dev-tools/LogTool/README.md | 35 ++ .../en/dev-tools/LogTool/UNISOC8910.md | 371 +++++++++++++++++ docs/Application_guide/en/dev-tools/README.md | 1 + docs/Application_guide/en/sidebar.yaml | 7 + docs/Application_guide/zh/README.md | 1 + .../zh/dev-tools/LogTool/ASR.md | 308 ++++++++++++++ .../zh/dev-tools/LogTool/EIGEN.md | 189 +++++++++ .../zh/dev-tools/LogTool/README.md | 47 +++ .../zh/dev-tools/LogTool/UNISOC8850.md | 247 +++++++++++ .../zh/dev-tools/LogTool/UNISOC8910.md | 392 ++++++++++++++++++ docs/Application_guide/zh/dev-tools/README.md | 1 + docs/Application_guide/zh/sidebar.yaml | 11 + 14 files changed, 1872 insertions(+) create mode 100644 docs/Application_guide/en/dev-tools/LogTool/ASR.md create mode 100644 docs/Application_guide/en/dev-tools/LogTool/README.md create mode 100644 docs/Application_guide/en/dev-tools/LogTool/UNISOC8910.md create mode 100644 docs/Application_guide/zh/dev-tools/LogTool/ASR.md create mode 100644 docs/Application_guide/zh/dev-tools/LogTool/EIGEN.md create mode 100644 docs/Application_guide/zh/dev-tools/LogTool/README.md create mode 100644 docs/Application_guide/zh/dev-tools/LogTool/UNISOC8850.md create mode 100644 docs/Application_guide/zh/dev-tools/LogTool/UNISOC8910.md diff --git a/docs/Application_guide/en/README.md b/docs/Application_guide/en/README.md index bb8908fe..3ca1c9b0 100644 --- a/docs/Application_guide/en/README.md +++ b/docs/Application_guide/en/README.md @@ -87,6 +87,7 @@ QuecPython Application Guide is a guide on how to use the commonly used function - [Thonny IDE User Guide](dev-tools/Thonny/README.md) - [DTU Tool User Guide](dev-tools/DTU-Tool/README.md) - [Factory Tool User Guide](dev-tools/FactoryTool/README.md) +- [Log Tool User Guide](dev-tools/LogTool/README.md) - [VSCode Plugin User Guide](dev-tools/VSCode-Plugin-quecpython/README.md) diff --git a/docs/Application_guide/en/dev-tools/LogTool/ASR.md b/docs/Application_guide/en/dev-tools/LogTool/ASR.md new file mode 100644 index 00000000..4d40d3b4 --- /dev/null +++ b/docs/Application_guide/en/dev-tools/LogTool/ASR.md @@ -0,0 +1,261 @@ +# 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/README.md b/docs/Application_guide/en/dev-tools/LogTool/README.md new file mode 100644 index 00000000..dd39e88b --- /dev/null +++ b/docs/Application_guide/en/dev-tools/LogTool/README.md @@ -0,0 +1,35 @@ +# Log Tool User Guide + +This document introduces the usage of log capture tools for different QuecPython platforms, including ASR and UNISOC8910. + +## 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) | + +## Table of Contents + +[ASR Platform Log Tool User Guide](./ASR.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 new file mode 100644 index 00000000..a9e3da34 --- /dev/null +++ b/docs/Application_guide/en/dev-tools/LogTool/UNISOC8910.md @@ -0,0 +1,371 @@ +# 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 cb451db0..f0ea4604 100644 --- a/docs/Application_guide/en/dev-tools/README.md +++ b/docs/Application_guide/en/dev-tools/README.md @@ -8,5 +8,6 @@ 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) diff --git a/docs/Application_guide/en/sidebar.yaml b/docs/Application_guide/en/sidebar.yaml index 62ee3db0..b35ce4f0 100644 --- a/docs/Application_guide/en/sidebar.yaml +++ b/docs/Application_guide/en/sidebar.yaml @@ -248,6 +248,13 @@ items: file: dev-tools/DTU-Tool/README.md - label: Factory Tool User Guide file: dev-tools/FactoryTool/README.md + - label: Log Tools User Guide + file: dev-tools/LogTool/README.md + items: + - label: ASR Platform + file: dev-tools/LogTool/ASR.md + - label: UNISOC8910 Platform + file: dev-tools/LogTool/UNISOC8910.md - label: VSCode Plugin User Guide file: dev-tools/VSCode-Plugin-quecpython/README.md - label: QMulti-DL User Guide diff --git a/docs/Application_guide/zh/README.md b/docs/Application_guide/zh/README.md index d2e84059..e3d032de 100644 --- a/docs/Application_guide/zh/README.md +++ b/docs/Application_guide/zh/README.md @@ -76,6 +76,7 @@ QuecPython 应用指导，是对QuecPython常用功能模块如何使用的指 - [Thonny IDE 使用教程](dev-tools/Thonny/README.md) - [DTU Tool 使用教程](dev-tools/DTU-Tool/README.md) - [产测工具使用教程](dev-tools/FactoryTool/README.md) +- [各平台Log工具使用教程](dev-tools/LogTool/README.md) - [VSCode 插件使用教程](dev-tools/VSCode-Plugin-quecpython/README.md) diff --git a/docs/Application_guide/zh/dev-tools/LogTool/ASR.md b/docs/Application_guide/zh/dev-tools/LogTool/ASR.md new file mode 100644 index 00000000..c896d0d5 --- /dev/null +++ b/docs/Application_guide/zh/dev-tools/LogTool/ASR.md @@ -0,0 +1,308 @@ +# ASR平台Log工具使用说明 + +ASR平台AP和CP的Log抓取，既可以使用CATStudio工具，也可以使用QWinLog工具，本文将介绍如何使用这两种工具来抓取AP和CP的Log。同时也将说明如何使用CATStudio工具来导出dump文件和pcap文件。 + +## 概述 + +### 工具简介 + +CATStudio是用于实时监控和抓取ASR平台模组log的软件工具，功能非常丰富，对于用户来说，最常用的就是抓取设备的AP/CP log、dump文件导出和pcap文件导出。 + +QWinLog是专门用来进行log抓取的工具，目前支持高通和ASR平台AP/CP log的抓取，使用非常简单。 + +### 软件安装 + +CATStudio和QWinLog工具均为免安装软件，只需要将工具压缩包解压到电脑某个目录下即可。需要注意，解压路径中，不要包含中文字符，否则可能导致工具无法正常运行。 + +### 运行环境 + +CATStudio支持在Windows XP/7/10 系统上运行，计算机内存应在512M以上，处理器双核以上。 + +QWinLog工具支持在Windows 7/10系统上运行。 + + + +## 硬件连接 + +抓取log之前，用户应做如下准备： + +* 确认计算机已经安装ASR平台模组的USB驱动程序。 + +* 使用USB数据线连接模组和计算机。 + +* 模组上电运行。 + +进入计算机的设备管理器界面，如果USB驱动程序加载正常，应该可以看到下图所示的几个端口： + +![](../../media/dev-tools/LogTool/ASR-USB-port.png) + + + +几个端口的作用如下： + +* Quectel USB AT Port：该端口用于发送AT指令。 + +* Quectel USB DIAG Port：该端口用于抓取Log。 + +* Quectel USB REPL Port：对于QuecPython固件而言，该端口是python的REPL端口，用户可通过该端口执行一些python代码。 需要注意的是，不同的平台，python的REPL端口名称可能是不同的。如果用户不清楚哪个端口是python的REPL端口，可以咨询我司的FAE进行确认。 + +上图中红框标注的端口，就是接下来我们使用CATStudio抓取Log时需要使用的端口。 + + + +## 使用指南 + +硬件环境准备完成后，按照下面的步骤来操作。 + +### AP和CP日志抓取 + +#### 使用CATStudio抓取 + +**步骤1：选择功能类型** + +打开CATStudio软件，默认会弹出下图所示界面，选择“在线解析日志”选项，并点击“OK”。 + +![](../../media/dev-tools/LogTool/CatStudio-1.png) + + + +**步骤2：通信端口选择与配置** + +经过步骤1后会进入如下界面，点击右下角的“Device Communication”选项，弹出对应配置界面后，默认选择“Device 0”，点击“Settings”。 + +
描述1 描述2
+ + 进入如下界面，选中“Serial”，点击“Serial Port”选择框的下拉按钮，选择“Quectel USB DIAG Port”端口，波特率保持默认即可，点击“OK”，之后应该就能看到工具窗口开始输出Log信息了。 + +![](../../media/dev-tools/LogTool/CatStudio-4.png) + + + +> 如果经过这一步骤后，CATStudio主窗口无Log信息输出，需要重启电脑，然后重新打开CATStudio软件工具。 + + + +**步骤3：匹配DB文件** + +如果没有匹配DB文件，CatStudio工具界面上很多Log都是处于未解码的状态。为了方便看Log信息，用户可以选择匹配模组当前使用固件所对应的DB文件。DB文件一般都在对应固件包中，如下所示： + +![](../../media/dev-tools/LogTool/ASR-DB-files.png) + + + +> 如果用户的固件包中没有DBG目录，可以将使用的固件版本号提供给我司FAE，让FAE提供对应固件的DB文件。 + + + +如果没有匹配DB文件，从工具界面上，可以看到如下图所示的红色指示灯： + +![](../../media/dev-tools/LogTool/CatStudio-5.png) + + + +点击红色指示灯边上的“Update”按钮，进入下面的界面，然后按照下面步骤设置： + +* 选择①处的“TEXT”。 + +* 点击②处的按钮，在弹出的文件选择窗口中，切换到模组固件包所在路径，然后进入固件包中的DBG目录下，选择对应的DB文件。 + +* 点击③处的“Update”按钮，如果选择的DB文件与模组中的固件是匹配的，则可以看到图中右边CP部分的指示灯变成绿色。 +* DB文件匹配成功后，点击④处的“Close”按钮，重新回到Log输出界面，此时应该可以看到上图中Device 0的指示灯也变成绿色。 + +![](../../media/dev-tools/LogTool/CatStudio-6.png) + + + +> 对于用户来说，匹配DB文件这一步骤并不是必须的，如果客户仅需要抓取Log并提供给我司研发人员分析，也可以省略该步骤，由我司研发人员自行匹配DB文件。 + + + +**步骤4：Log文件导出** + +当Log抓取结束后，需要将Log文件导出，然后提供给我司FAE或者研发人员，用于分析相关问题。用户可按照如下操作导出Log文件： + +* 点击菜单栏的“Log”选项，在弹出的下拉框中，继续点击“Export Log-File”选项，弹出ExportLog窗口。 + +* 在ExportLog窗口中，点击“Select Path(P)”，选择Log保存路径。 + +* 点击“Output”按钮，等待Log文件导出结束。 + +![](../../media/dev-tools/LogTool/CatStudio-7.png) + + + +导出的Log文件，同时包含了AP和CP的Log，用户如需我司协助分析相关问题，需要将导出的Log文件提供给我司FAE或者研发人员。 + + + +#### 使用QWinLog抓取 + +**步骤1：打开QWinLog** + +将QWinLog工具的压缩包解压到电脑某个路径下，注意路径中不要包含中文字符。进入到QWinLog工具根目录下，双击QWinLog.exe打开工具后，进入下图所示的界面： + +![](../../media/dev-tools/LogTool/QWinLog-main-ui.png) + + + +**步骤2：参数配置** + +由于是使用QWinLog抓取ASR平台的log，因此只需要配置QWinLog工具界面中和ASR平台相关的参数即可，如下图所示： + +![](../../media/dev-tools/LogTool/QWinLog-ASR-param-config.png) + +具体配置说明如下： + +* 首先勾选①处的“QASR log”选项。 + +* 选中②处的“USB Port”。 + +* 点击图中③处端口选择窗口后面下拉按钮，选择“Quectel USB DIAG Port”端口。该端口是ASR平台抓取AP和CP log的端口。 + +* “Config file”是QWinLog抓取log所使用的配置文件，用户可以使用工具默认的配置文件或者联系我司FAE提供相关配置文件。 + +* “Log path”为抓取的log保存路径，一般保持默认即可，用户也可根据需要修改。 + + + +**步骤3：开始Log抓取** + +点击QWinLog界面的“Start”按钮开始抓取log，点击“Stop”按钮则停止log抓取。 + + + +**步骤4：Log文件打包** + +当需要的log抓取完成，点击“Stop”按钮停止后，进入到“Log path”选项中设置的路径下，就可以看到保存的log文件，如下图所示： + +![](../../media/dev-tools/LogTool/QWinLog-ASR-sdl-log-file.png) + +用户只需要将这些log文件打包压缩后，发送给我司FAE或者研发人员即可。 + + + +### Dump文件导出 + +当用户使用ASR平台模组过程中，遇到dump问题时，可以通过CATStudio工具来导出dump文件，然后将dump文件发送给我司研发人员进行分析。 + +**步骤1：配置dump模式** + +模组在默认情况下，如果发生dump，会直接重启，这种情况下，无法导出dump文件。因此，我们需要在模组正常运行时，先发送AT指令来配置模组的dump模式，确保发生dump时不会自动重启，而是一直停在dump状态，等待用户导出dump文件。下面是ASR平台模组配置dump模式，需要发送的AT指令。 + +``` +AT+QDUMPCFG=0,0 +AT+QDUMPCFG=2,1 +AT+log=19,1 +``` + +在模组正常运行时，打开QPYcom工具，“COM Port”选择“Quectel USB AT Port”，然后点击“Open port”。依次发送上述3条AT，如下所示： + +![](../../media/dev-tools/LogTool/QPYcom-ASR-dump-config.png) + + + +**步骤2：复现dump问题** + +按照步骤1中的说明，确定所使用的模组型号并发送了对应的AT指令后，按照之前测试出现dump问题的方法步骤重新测试，等待dump问题复现。当出现dump问题时，从电脑的设备管理器中，可以看到出现如下所示的dump端口： + +![](../../media/dev-tools/LogTool/dump-port.png) + + + +**步骤3：选择功能类型** + +打开CATStudio软件，默认会弹出下图所示界面，选择“专门抓取日志”选项，并点击“OK”。 + +![](../../media/dev-tools/LogTool/CatStudio-online.png) + + + +**步骤4：参数设置与dump文件导出** + +按照步骤3操作后，会弹出下面的窗口，我们先点击①处的“Dump”，切换到dump导出标签页，依次按照下图标号进行参数设置即可： + +![](../../media/dev-tools/LogTool/CatStudio-dump-export-1.png) + +* 选择YModem模式，如图中②处所示； + +* 图中③处，点击下拉按钮，选择步骤2中dump端口； + +* 点击图中④处的“open”按钮，打开对应端口； + +* 点击图中⑤处的“Browse”按钮，选择dump文件保存的路径； + +* 点击图中的⑥处的“Receive”按钮，开始dump文件的导出，并等待dump文件导出结束。当文件导出结束时，会弹出窗口提示用户，用户点击“确定”即可。如下图所示： + +![](../../media/dev-tools/LogTool/CatStudio-dump-export-2.png) + + + +经过这些步骤后，dump文件就已经导出完成，可将导出的dump文件打包压缩为一个文件，提供给我司FAE或者研发人员进行分析。 + + + +### Pcap文件导出 + +pcap文件是一种常见的网络数据存储文件，通常与Wireshark、Tcpdump等流行的网络分析工具一起使用，用来监控和分析与网络应用相关的问题。比如像MQTT和HTTP等应用协议的数据传输问题。 + +CATStudio工具支持导出pacp文件，下面说明如何通过CATStudio工具来导出pacp文件。 + +**步骤1：导出AP和CP Log** + +先按照前面[AP和CP日志抓取](./ASR.html#AP和CP日志抓取)章节的步骤，将Log文件导出备用。 + +**步骤2：选择功能类型** + +重新打开CATStudio软件，默认会弹出下图所示界面，选择“离线解析日志”选项，并点击“OK”。 + +![](../../media/dev-tools/LogTool/CatStudio-offline.png) + + + +> 这里需要注意，是选择“离线解析日志”，前面《AP和CP日志抓取》章节中，选择的是“在线解析日志”。 + + + +**步骤3：加载Log文件** + +进入CATStudio主界面后，点击右上角的“Open ZIP/ICL ...”按钮，在弹出的窗口中选择之前导出Log压缩文件，等待文件解压并加载完成。 + +![](../../media/dev-tools/LogTool/CatStudio-load-zip-log.png) + +如果加载文件过程中，弹出如下窗口，说明选择的Log文件比较大，超过了默认的文件大小限制。这种情况我们直接选择“Cancel（Load whole file）”选项，即选择加载整个文件。 + +![](../../media/dev-tools/LogTool/CatStudio-load-whole-file.png) + + + +**步骤4：匹配DB文件** + +如果用户在导出Log文件的步骤中，已经按照说明匹配过了DB文件，则可以省略该步骤，直接进行步骤5，否则需要按照前面的说明匹配DB文件。 + + + +**步骤5：导出pacp文件** + +点击菜单栏的“Action”选项，在弹出的下来框中，选择“Export SN Trace to pacp file”选项，弹出如下窗口： + +![](../../media/dev-tools/LogTool/CatStudio-export-pcap-file.png) + + + +在弹出的窗口中，选择导出文件的保存路径，然后点击“OK”，等待导出完成，会弹出如下提示窗口，点击“确定”即可。 + +![](../../media/dev-tools/LogTool/CatStudio-export-pcap-file-finish.png) + + + +## 常见问题 + +**问题1：**使用QWinLog工具抓取log失败，并弹出如下窗口，是什么原因？ + +![](../../media/dev-tools/LogTool/QWinLog-open-port-failed.png) + +这种情况可能有两种原因导致： + +原因1：有其他程序占用了“Quectel USB DIAG Port”端口，可以检查是否存在这种情况，如果有，请先关闭占用该端口的软件，然后重新尝试。 + +原因2：USB驱动程序加载异常。可以先尝试断开模组和计算机的USB连接再重新接上，或者将模组断电后再重新上电，如果仍然不能正常使用，则需要重启计算机。 \ No newline at end of file diff --git a/docs/Application_guide/zh/dev-tools/LogTool/EIGEN.md b/docs/Application_guide/zh/dev-tools/LogTool/EIGEN.md new file mode 100644 index 00000000..f9591516 --- /dev/null +++ b/docs/Application_guide/zh/dev-tools/LogTool/EIGEN.md @@ -0,0 +1,189 @@ +# EIGEN平台Log工具使用说明 + +EIGEN平台AP、CP Log的抓取和dump文件的导出，都是使用EPAT工具。本文将介绍如何使用ArmLogel工具来抓取AP和CP Log，以及如何导出dump文件。 + +## 概述 + +### 工具简介 + +EPAT是用于抓取和分析EIGEN平台模组log的工具，可在线实时抓取分析，也可以离线分析。同时支持pcap和dump文件的导出功能。 + +### 软件安装 + +EPAT为绿色免安装软件，只需要将工具压缩包解压到电脑某个目录下即可。需要注意，解压路径中，不要包含中文字符，否则可能导致工具无法正常运行。解压后，进入到工具的Bin目录下，执行EPAT.exe 即可打开该工具。 + + + +> EPAT需要VC MFC DLLs，如果第一次运行EPAT失败，请安装执行Bin目录下的vc_redist.x86.exe文件。 + + + +### 运行环境 + +EPAT支持在Windows7/8/10系统上运行，计算机内存应在2G以上，处理器建议酷睿i3以上。 + + + +## 硬件连接 + +抓取log之前，用户应做如下准备： + +* 确认已经安装EPAT平台模组的USB驱动程序。 + +* 使用USB数据线连接模组和计算机。 + +* 模组上电运行。 + +进入计算机的设备管理器界面，如果USB驱动程序加载正常，应该可以看到下图所示的几个端口： + +![](../../media/dev-tools/LogTool/EPAT-USB-port.png) + +图中几个端口的作用如下： + +* Quectel USB AT Port：该端口用于发送AT指令，是专用AT端口。 +* Quectel USB Diag Port：该端口用于AP/CP log的抓取以及dump文件的导出。 +* USB 串行设备：对于QuecPython固件而言，该端口是python的REPL端口，用户可通过该端口执行一些python代码。 需要注意的是，不同的平台，python的REPL端口名称可能是不同的。如果用户不清楚哪个端口是python的REPL端口，可以咨询我司的FAE进行确认。 + + + +## 使用指南 + +确认设备与PC硬件连接正常，并且所有USB端口枚举成功，接下来就可以进行软件工具的配置和使用。 + +### AP和CP日志抓取 + +**步骤1：打开AP Log工具** + +进入EPAT工具的根目录，双击EPAT.exe，打开EPAT工具： + +![](../../media/dev-tools/LogTool/EPAT-root-dir.png) + +打开EPAT工具后，会先弹出如下窗口，让用户选择在线还是离线模式： + +* Serial Device：该选项表示在线模式，即直接从串口设备上实时抓取。 + +* Select From Local Files：该选项表示离线模式，即从计算机本地加载log文件。 + +这里我们选择第一个“Serial Device”模式，然后点击“OK”。 + +![](../../media/dev-tools/LogTool/EPAT-UI-1.png) + + + +**步骤2：端口参数配置** + +点击工具栏的如下图中①处的按钮，弹出“Device Selection”窗口。 + +点击②处的“Setting”按钮，弹出“Communications Settings”窗口。 + +点击③处选择“Quectel USB DIAG Port”端口。然后依次点击④和⑤处的“OK”按钮。 + +![](../../media/dev-tools/LogTool/EPAT-port-config.png) + + + +**步骤3：DB匹配** + +步骤2中端口参数配置完成后，工具会自动打开并连接USB端口，此时应该可以看到工具窗口中有log开始输出，如下图所示： + +![](../../media/dev-tools/LogTool/EPAT-UI-2.png) + +因为没有匹配DB文件，所以输出的log基本都是处于未解码的状态，为了看到解码后的明文log，我们需要先匹配DB文件，具体操作如下： + +点击图中①处的按钮，弹出“State”窗口。 + +点击“State”窗口中②处的“Update”按钮，弹出“CheckVersion”窗口。 + +点击“CheckVersion”窗口中③处的按钮，在弹出的窗口中选择模组当前固件所对应的DB文件，如④处所示。选中后点击“打开”。 + +点击“CheckVersion”窗口中⑥处的“Update”按钮，然后点击⑦处的“Close”按钮。如果匹配成功，应该可以看到“State”窗口中的指示灯变成绿色。 + +点击“State”窗口中⑧处的“Close”按钮。到此DB文件就匹配完成了，此时应该可以看到log输出窗口输出的都是明文信息。 + +![](../../media/dev-tools/LogTool/EPAT-DB.png) + + + +**步骤4：重启设备并开始log抓取** + +DB文件匹配完成后，我们重启设备，EPAT工具会自动识别端口并开始抓取log。 + + + +**步骤5：log文件保存** + +需要的log抓取完成后，点击工具栏的保存按钮，选择目录保存导出的log文件，确认后等待文件保存完成。默认保存的log是zip压缩文件。 + +
描述1 描述2
+ +文件保存完成后，打开log保存目录，将对应的log压缩文件发送给我司FAE。 + + + +### Dump文件导出 + +EPAT支持dump文件导出，当模组发生dump死机问题时，EPAT工具会自动抓取dump文件并导出。 + +**步骤1：配置dump模式** + +模组在默认情况下，如果发生dump，会直接重启。这种情况下，无法导出dump文件。因此，我们需要在模组正常运行时，先发送AT指令来配置模组的dump模式，确保发生dump时不会自动重启。 + +下面是EIGEN平台模组配置dump模式，需要发送的AT指令: + +``` +AT+ECPCFG="faultAction",0 +``` + +打开QPYcom工具，“COM Port”选择“Quectel USB AT Port”端口，点击“Open Port”，然后发送上面的AT指令： + +![](../../media/dev-tools/LogTool/EIGEN-dump-config.png) + + + +>上述AT发送后立即生效，并且配置掉电保存。 + + + +**步骤2：复现dump问题** + +按照步骤1发送相关AT指令后，就可以去复现相关的dump问题。 + + + +**步骤3：dump文件保存** + +当模组出现dump问题时，EPAT工具会自动检测并开始dump文件的导出。dump文件导出完成时，会弹出如下窗口，此时dump文件已经导出并保存到计算机本地，默认保存在工具根目录下的Bin\RamDump目录中。用户可以直接点击图中①处的按钮关闭“RamDump”窗口。 + +![](../../media/dev-tools/LogTool/EPAT-auto-save-dump.png) + +进入到EPAT工具根目录下的`Bin\RamDump`目录，即可看到dump文件。将该文件打包压缩后发送给我司FAE即可。 + +![](../../media/dev-tools/LogTool/EPAT-dump-file.png) + + + +### Pcap文件导出 + +当用户需要导出pcap文件来分析MQTT/HTTP/HTTPS等网络问题时，可以按照如下步骤进行操作。 + +* 点击图中①处的“SigLogger”标签。 + +* 点击图中②处的暂停按钮。 + +* 点击菜单栏的“SigLog”选项，在弹出的下拉窗口中，选择“Export As pcap file”选项。 + +* 在弹出的窗口中，选择pcap文件保存目录并设置文件名，确认后即可导出pcap文件。 + +![](../../media/dev-tools/LogTool/EPAT-export-pcap-1.png) + +![](../../media/dev-tools/LogTool/EPAT-export-pcap-2.png) + + + +## 常见问题 + +**问题1：**使用EPAT工具连接模组后，为什么log输出窗口中看到的几乎都是一些十六进制的数据？ + +这是因为没有匹配DB文件导致的，此时输出的log信息大致如下，log是处于未解码的状态，需要匹配正确的DB文件才能看到明文log。 + +![](../../media/dev-tools/LogTool/EPAT-UI-2.png) \ No newline at end of file diff --git a/docs/Application_guide/zh/dev-tools/LogTool/README.md b/docs/Application_guide/zh/dev-tools/LogTool/README.md new file mode 100644 index 00000000..e66fd170 --- /dev/null +++ b/docs/Application_guide/zh/dev-tools/LogTool/README.md @@ -0,0 +1,47 @@ +# 平台Log工具使用说明 + +本文主要介绍QuecPython各个平台log抓取工具的使用，包括ASR、UNISOC8850、UNISOC8910和EIGEN平台。 + +## 模组log的作用 + +用户在使用模组的过程中，经常会遇到各种问题，为了确认问题的原因和模组代码运行的情况，我们通常需要抓取模组运行的日志。通过这些日志，可以帮助研发人员分析和定位问题，以及判断一些功能的运行是否符合预期。 + + + +## 模组Log分类 + +模组的Log一般分为AP log、CP log、pcap log和dump文件。 + +* AP log：一般是SDK以及APP输出的日志文件。AP log主要用于确认系统软件运行情况，可用于定位一些软件BUG。 + +* CP log：一般是Modem输出的无线协议栈相关的日志，比如我们经常说的空口log。CP log主要用于定位确认和无线网络相关的问题，比如模组网络注册问题、网络异常断开问题等。如果是确认设备的网络注册问题，一般需要抓取设备开机阶段的CP log，或者抓取包含CFUN0/1切换过程的CP log。 + + > CFUN0/1切换是指通过`net.setModemFun(0)`方法先将设备切换到模式0（最小功能模式），然后再通过`net.setModemFun(1)`方法将设备切换到模式1（全功能模式），目的是为了让设备重新发起网络注册流程。如果用户没有抓到设备开机时的CP log，也可以抓取包含CFUN0/1切换过程的CP log提供给我司研发人员分析问题。 + +* pcap log：pcap日志文件可用于网络流量分析和调试。使用pcap日志文件可以了解设备或应用在网络层面的工作情况，以找出性能问题或故障。通过分析pcap日志，可以查看网络通信的细节，如连接建立的过程、传输的报文格式、请求和响应的参数等。比如分析TCP/IP、MQTT、HTTP/HTTPS等问题时，可能会经常用到pcap日志。用户一般可使用Wireshark软件工具来打开pcap文件。 +* dump文件：当操作系统或应用程序遇到某些不可恢复的错误时，为了记录当时的状态和其他相关信息，它会将内存中的某些部分保存为文件，这些文件称为dump文件。比如程序崩溃、非法内存访问、内存耗尽、栈溢出等异常问题都可能导致模组程序崩溃，从而异常重启。如果用户遇到模组异常重启的情况，很可能是发生dump问题了，此时需要抓取并导出dump文件，提供给我司研发人员进行问题定位和分析。 + + + +## 各平台Log工具 + +下面是各个平台抓取AP/CP log、pcap log以及dump文件所使用的工具： + +| 平台 | 模组型号 | AP Log | CP Log | pcap Log | Dump | 图标 | +| ---------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | --------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------ | +| ASR | EC100Y/EC200N/EC600S/
EC600N/EG915N/EC600M/
EC800M/EG810M/EC200A/
UC200A | [CATStudio](./ASR.html#使用CATStudio抓取)
[QWinLog](./ASR.html#使用QWinLog抓取) | [CATStudio](./ASR.html#使用CATStudio抓取)
[QWinLog](./ASR.html#使用QWinLog抓取) | [CATStudio](./ASR.html#Pcap文件导出) | [CATStudio](./ASR.html#Dump文件导出) | ![](../../media/dev-tools/LogTool/CatStudio.png)![](../../media/dev-tools/LogTool/QWinLog.png) | +| UNISOC8850 | EC600G/EC800G | [ArmLogel](./UNISOC8850.html#AP和CP日志抓取) | [ArmLogel](./UNISOC8850.html#AP和CP日志抓取) | [ArmLogel](./UNISOC8850.html#Pcap文件导出) | [DTools](./UNISOC8850.html#Dump文件导出) | ![](../../media/dev-tools/LogTool/ArmLogel.png)![](../../media/dev-tools/LogTool/DTools.png) | +| UNISOC8910 | EC200U/EC600U/EG912U/
EG915U | [coolwatcher](./UNISOC8910.html#AP日志抓取) | [ArmTracer](./UNISOC8910.html#CP日志抓取) | [coolwatcher](./UNISOC8910.html#Pcap文件导出) | [coolwatcher](./UNISOC8910.html#Dump文件导出) | ![](../../media/dev-tools/LogTool/cooltools.png) ![](../../media/dev-tools/LogTool/ArmTracer.png) | +| EIGEN | EC600E/EC800E | [EPAT](./EIGEN.html#AP和CP日志抓取) | [EPAT](./EIGEN.html#AP和CP日志抓取) | [EPAT](./EIGEN.html#Pcap文件导出) | [EPAT](./EIGEN.html#Dump文件导出) | ![](../../media/dev-tools/LogTool/EPAT.png) | + + + +## 目录 + +[ASR平台Log工具使用说明](./ASR.md) + +[EIGEN平台Log工具使用说明](./EIGEN.md) + +[UNISOC8850平台Log工具使用说明](./UNISOC8850.md) + +[UNISOC8910平台Log工具使用说明](./UNISOC8910.md) \ No newline at end of file diff --git a/docs/Application_guide/zh/dev-tools/LogTool/UNISOC8850.md b/docs/Application_guide/zh/dev-tools/LogTool/UNISOC8850.md new file mode 100644 index 00000000..a5ec930e --- /dev/null +++ b/docs/Application_guide/zh/dev-tools/LogTool/UNISOC8850.md @@ -0,0 +1,247 @@ +# UNISOC8850平台Log工具使用说明 + +UNISOC8850平台AP和CP Log的抓取，都是使用ArmLogel工具，而dump文件的导出则需要使用dtools_win工具。本文将介绍如何使用ArmLogel工具来抓取AP和CP的Log，以及使用dtools_win工具导出dump文件。 + +## 概述 + +### 工具简介 + +ArmLogel是一个用来实时监控并抓取UNISOC8850平台模组的内部消息、空中消息、系统消息的测试工具。它可以将来自每个任务的消息分层显示，并提供了对消息结构和数据的解析功能。 + +### 软件安装 + +ArmLogel工具为免安装软件，只需要将工具压缩包解压到电脑某个目录下即可。需要注意，解压路径中，不要包含中文字符，否则可能导致工具无法正常运行。 + +### 运行环境 + +ArmLogel工具支持在Windows XP/7/10系统上运行，计算机内存应在8G以上，处理器至少双核。 + + + +## 硬件连接 + +抓取log之前，用户应做如下准备： + +* 确认已经安装UNISOC8850平台模组的USB驱动程序。 + +* 使用USB数据线连接模组和计算机。 + +* 模组上电运行。 + +进入计算机的设备管理器界面，如果USB驱动程序加载正常，应该可以看到下图所示的几个端口： + +![](../../media/dev-tools/LogTool/UNISOC8850-USB-port.png) + +几个端口的作用如下： + +* Quectel USB AT Port：该端口用于发送AT指令。 +* Quectel USB CP Port：该端口用于抓取CP Log。 +* Quectel USB Debug Port：在USB连接下，该端口保留，用户可忽略。 + +* Quectel USB DIAG Port：该端口用于抓取AP Log。 + +* Quectel USB REPL Port：对于QuecPython固件而言，该端口是python的REPL端口，用户可通过该端口执行一些python代码。需要注意的是，不同的平台，python的REPL端口名称可能是不同的。如果用户不清楚哪个端口是python的REPL端口，可以咨询我们公司的FAE进行确认。 + + + +## 使用指南 + +确认设备与计算机硬件连接正常，并且所有USB端口枚举成功，接下来就可以进行软件工具的配置和使用。 + +### AP和CP日志抓取 + +**步骤1：打开ArmLogel工具** + +将ArmLogel工具的压缩包解压到电脑某个路径下，注意路径中不要包含中文字符。进入到ArmLogel工具根目录下，双击Logel.exe打开ArmLogel工具后，进入下图所示的界面，其中的“Traces”窗口就是AP Log的输出窗口。CP Log的输出窗口一般默认不直接打开，而是在用户配置好参数并连接设备成功后，会自动弹出。 + +![](../../media/dev-tools/LogTool/ArmLogel-1.png) + + + +**步骤2：参数配置** + +点击菜单栏的设置按钮，如下图所示： + +![](../../media/dev-tools/LogTool/ArmLogel-2.png) + +弹出如下所示的参数设置窗口，在该窗口中，用户需要设置Log的保存路径以及USB端口相关的参数。当用户设置好这些参数，并开始Log的抓取时，ArmLogel工具会自动保存AP和CP Log到用户设置的目录中。 + +![](../../media/dev-tools/LogTool/ArmLogel-3.png) + +具体的参数设置说明如下： + +* 在①处设置Log的保存路径。 + +* ②处的“Type”选择“Uart”。 + +* ③处的“Diag Port”选择“Quectel USB DIAG Port”，后面波特率输入框填写2000000即可。 + +* ④处的“Log Port”选择“Quectel USB CP Port”，后面波特率输入框填写8000000即可。 + +* 点击⑤处的“OK”按钮确认。 + +按照上述步骤配置之后，参数配置就完成了。 + + + +**步骤3：开始Log抓取** + +点击菜单栏的“Capture Log”按钮开始抓取Log： + +![](../../media/dev-tools/LogTool/ArmLogel-4.png) + +当“Capture Log”按钮变成绿色，并且“Traces”窗口能看到Log输出，说明硬件连接正常，并且工具参数配置也正确。当工具开始输出Log时，还会弹出几个新的窗口，比如“CP All Message”、"CP Lay3 Message"和“Neighbour Cell Info”窗口，这些窗口输出的是CP Log相关的信息。 + +![](../../media/dev-tools/LogTool/ArmLogel-5.png) + + + +**步骤4：Log文件打包保存** + +当需要的Log抓取完成时，点击ArmLogel工具菜单栏的停止按钮，Log会自动保存到之前设置的目录下。 + +![](../../media/dev-tools/LogTool/ArmLogel-6.png) + +进入之前设置的Log保存路径下，该目录下就是ArmLogel工具自动保存的所有Log文件，用户需要将这些文件打包压缩后，发送给我司FAE或者研发，用于分析问题。 + +![](../../media/dev-tools/LogTool/ArmLogel-log-files.png) + + + +> 由于ArmLogel工具每次打开时，默认都会按照用户之前设置的路径来保存，所以会导致保存Log文件的目录下有大量历史Log文件。因此，建议用户在每次使用ArmLogel工具抓取Log之前，先将历史Log文件都删除，这样可以确保该目录下保存的文件是最新的。 + + + +### Dump文件导出 + +UNISOC8850平台模组抓取dump文件，需要使用dtools_win工具，且需要结合ArmLogel工具来使用。下面将说明如何使用ArmLogel工具合dtools_win工具来导出模组的dump文件。 + +**步骤1：配置dump模式** + +模组在默认情况下，如果发生dump，会直接重启。这种情况下，无法导出dump文件。因此，我们需要在模组正常运行时，先发送AT指令来配置模组的dump模式，确保发生dump时不会自动重启，而是一直停在dump状态，等待用户导出dump文件。 + +下面是UNISOC8850平台模组配置dump模式，需要发送的AT指令: + +``` +AT+QDBGCFG="DUMPCFG",0 +``` + +打开QPYcom工具，“COM Port”选择“Quectel USB AT Port”端口，点击“Open Port”，然后发送上面的AT指令： + +![](../../media/dev-tools/LogTool/UNISOC8850-dump-config.png) + + + +>上述AT发送后立即生效，但是掉电不保存，如果重启设备了，就需要重新发送一次。 + + + +**步骤2：复现dump问题** + +按照步骤1发送相关AT指令后，就可以去复现相关的dump问题，当模组出现dump问题时，ArmLogel工具会弹出如下所示的Assert Information窗口： + +![](../../media/dev-tools/LogTool/ArmLogel-dump-1.png) + +并且Traces窗口中会列出模组当前所有Task的基本信息： + +![](../../media/dev-tools/LogTool/ArmLogel-dump-2.png) + + + +**步骤3：停止ArmLogel工具的Log抓取** + +由于接下来需要使用dtools_win工具来导出dump文件。dtools_win工具导出dump时使用的也是模组的USB端口，如果不先停止ArmLogel工具，会导致模组的USB端口一直被ArmLogel工具占用，dtools_win工具则无法再使用模组的USB端口。 + +当模组确认发生dump，并出现步骤2中的现象时，用户需要点击ArmLogel工具菜单栏的停止按钮，停止成功后，该按钮会变成红色。 + +![](../../media/dev-tools/LogTool/ArmLogel-6.png) + + + +**步骤4：打开dtools_win工具** + +双击打开dtools_win工具，进入该工具的主界面，具体如下所示： + +![](../../media/dev-tools/LogTool/dtools_win.png) + + + +**步骤5：端口参数配置** + +点击下图中①处的图标，弹出端口参数配置窗口，如下所示： + +![](../../media/dev-tools/LogTool/dtools-port-config.png) + +在弹出的端口参数配置窗口中，依次按照下面的步骤进行配置： + +* 图中②处的Chip Type类型，选择8850。 + +* 选择图中③处的Diag Port，并且后面的端口号选择"Quectel USB DIAG Port"所对应的端口号。 + +* 最后点击图中④处的“Confirm”按钮。 + + + +**步骤6：dump文件导出** + +在dtools_win工具的主界面上，先点击下图①处的“Blue Screen Dump”标签，进入对应的标签页： + +![](../../media/dev-tools/LogTool/dtools-dump-export.png) + +在“Blue Screen Dump”标签页中，依次按照如下步骤进行操作： + +* 图中②处的Chip类型需要选择8850，如果步骤5中配置正确，此处应该默认就是8850。 + +* 图中③处是dump文件导出后的保存路径，用户可以点击输入框后面的按钮选择指定的目录来保存dump文件。 + +* 点击图中④处的按钮，开始dump文件的导出。下方⑤处会有dump文件导出的进度显示，当导出进度显示为100%时，表示dump文件导出已经完成。 + +我们可以点击“Open Dump Folder”按钮，直接打开dump文件保存目录，然后将dump文件打包压缩为一个文件后，发送给我司FAE或者研发进行dump问题的分析。 + + + +### Pcap文件导出 + +ArmLogel工具会自动抓取并保存pcap文件，并将pcap文件保存在用户设置的Log保存路径下，用户只需要按照前面[AP和CP日志抓取](./UNISOC8850.html#AP和CP日志抓取)章节的步骤设置即可，无需单独设置其他参数。 + +模组开机后，如果没有进行过任何网络数据业务，则Log保存路径下不会有pcap文件存在；只有当模组进行进行socket、mqtt以及http等业务时，ArmLogel工具才会抓取并保存pacp文件。 + +![](../../media/dev-tools/LogTool/ArmLogel-pcap-files.png) + + + +## 常见问题 + +**问题1：**ArmLogel工具打开后，没有看到“Traces”窗口。 + +如果用户打开ArmLogel工具后，没有看到“Traces”窗口，可以手动打开。点击菜单栏的“View”选项，在弹出的下拉窗口中，依次点击“Common”——>"Traces"，即可显示“Traces”窗口。 + + + +**问题2：**点击菜单栏的“Capture Log”按钮后，该按钮已经变成绿色，但是“Traces”窗口看不到任何的AP Log输出。 + +AP Log默认是从USB端口输出，对于ArmLogel工具来说，即从"Quectel USB DIAG Port"端口输出。如果用户之前通过相关AT将AP Log输出切换到了物理串口的Debug串口，就会出现“Capture Log”按钮已经变成绿色，但是“Traces”窗口看不到任何的AP Log输出的现象。此时，用户可以按照下面步骤进行操作： + +步骤1：确认当前AP Log输出端口。 + +发送如下AT，查询当前的AP Log输出端口： + +``` +at+qdbgcfg="tracecfg" +``` + +打开QPYcom工具，“COM Port”选择“Quectel USB AT Port”端口，点击“Open Port”，然后发送上面的AT指令： + +![](../../media/dev-tools/LogTool/at-qdbgcfg-tracecfg-1.png) + +如果AT指令查询结果如上图所示，最后两位数字是0和1，说明当前AP Log的输出端口是物理串口Debug口。 + +此时，用户可以发送如下AT命令，来将AP Log输出端口切换到USB端口： + +``` +at+qdbgcfg="tracecfg",0,2 +``` + +![](../../media/dev-tools/LogTool/at-qdbgcfg-tracecfg-2.png) + +由于上述AT指令需要重启才能生效，所以发送上述AT指令后，重启模组。然后回到ArmLogel工具界面，应该就可以看到有Log输出了。 \ No newline at end of file diff --git a/docs/Application_guide/zh/dev-tools/LogTool/UNISOC8910.md b/docs/Application_guide/zh/dev-tools/LogTool/UNISOC8910.md new file mode 100644 index 00000000..b0f051e5 --- /dev/null +++ b/docs/Application_guide/zh/dev-tools/LogTool/UNISOC8910.md @@ -0,0 +1,392 @@ +# UNISOC8910平台Log工具使用说明 + +本文将介绍如何使用coolwatcher和ArmTracer这两种工具来进行AP和CP Log的抓取，以及dump文件的导出。 + +## 概述 + +### 工具简介 + +coolwatcher是用来抓取UNISOC8910平台模组AP Log的软件工具，同时支持dump文件导出。 + +ArmTracer是用来抓取UNISOC8910平台模组CP Log的软件工具，用于分析模组网络注册相关的问题。 + +### 软件安装 + +coolwatcher和ArmTracer工具均为免安装软件，只需要将工具压缩包解压到电脑某个目录下即可。需要注意，解压路径中，不要包含中文字符，否则可能导致工具无法正常运行。 + +### 运行环境 + +coolwatcher支持在Windows XP/7/10 系统上运行，计算机内存应在4G以上，处理器双核以上。 + +ArmTracer运行于 Windows XP 以上的系统版本，如果软件无法正常运行，可尝试以管理员身份运行或者以XP SP3兼容模式来运行。 + + + +## 硬件连接 + +抓取log之前，用户应做如下准备： + +* 确认已经安装UNISOC8910平台模组的USB驱动程序。 + +* 使用USB数据线连接模组和计算机。 + +* 模组上电运行。 + +进入计算机的设备管理器界面，如果USB驱动程序加载正常，应该可以看到下图所示的几个端口： + +![](../../media/dev-tools/LogTool/UNISOC8910-USB-port.png) + +图中几个端口的作用如下： + +* Quectel Modem：该端口主要用于ppp拨号，也可用于发送AT，但是一般不用该端口发送AT，而是使用专用AT端口。 + +* Quectel USB AP Log Port：该端口用于抓取AP Log。 + +* Quectel USB AT Port：该端口用于发送AT指令，是专用AT端口。 + +* Quectel USB CP Log Port：该端口用于抓取CP Log。 + +* Quectel USB Diag Port：该端口保留。 + +* Quectel USB MOS Port：该端口保留。 + +* Quectel USB REPL Port：对于QuecPython固件而言，该端口是python的REPL端口，用户可通过该端口执行一些python代码。需要注意的是，不同的平台，python的REPL端口名称可能是不同的。如果用户不清楚哪个端口是python的REPL端口，可以咨询我们公司的FAE进行确认。 + + + +## 使用指南 + +确认设备与PC硬件连接正常，并且所有USB端口枚举成功，接下来就可以进行软件工具的配置和使用。 + +### AP日志抓取 + +**步骤1：打开AP Log工具** + +将cooltools软件工具压缩包解压到电脑某个目录下，需要注意，cooltools工具所在路径中，不要包含中文路径。解压完成后，进入到工具根目录下： + +![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-root-dir.png) + +双击coolwatcher_usb.exe文件打开工具，弹出如下配置窗口，窗口左侧为模块型号选择区，右侧为对应型号的配置项： + +* 点击①处的8910，进入对应项目的配置界面。 + +* 确认②处型号为8910。 + +* 在③处的输入框中，填写“Quectel USB AP Log Port”所对应的端口号。点击“OK”按钮。 + +![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-1.png) + + + +**步骤2：等待工具连接模组成功** + +步骤1中，端口参数配置完成，点击“OK”后，coolwatcher工具会自动打开“Quectel USB AP Log Port”端口，并与模组进行通信，建立连接。当连接建立成功后，会出现下图所示的界面，左边会有几条绿色提示信息，并且最后会出现“[COM OPEN OK]”的提示信息。 + +![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-2.png) + +上图就是我们打开coolwatcher工具进入的主界面。其中右边的Trace tool窗口就是AP Log的输出窗口，图中①处是控制AP Log的一些按钮，下面是几个常用按钮功能的介绍： + +| 按钮 | 功能 | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| ![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-start.png) | 开始，点击后trace窗口开始输出AP Log。 | +| ![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-stop.png) | 停止，点击后trace窗口停止输出AP Log。 | +| ![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-clear.png) | 清空，点击后会清空trace窗口的所有AP Log。 | +| ![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-set.png) | 设置，点击后会弹出设置窗口，可设置自动保存、保存的文件类型、保存路径、单个文件大小、pcap保存等。 | +| ![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-save.png) | 保存，点击后立即保存，实际可以通过“设置”按钮来配置自动保存，无需手动保存。 | + +图种②处是AP Log过滤功能的关键字输入框，用户可以在该输入框中输入某个字符串作为关键字并按键盘的回车键确认，工具会把包含该关键字的所有AP Log条目都列举出来。 + +如果用户在步骤1中，端口参数配置完成，点击“OK”后，没有弹出上面图中右边的Trace tool窗口，而是进入下面的窗口，说明用户使用的软件版本不是最新的。 + +![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-old-ver-1.png) + +此时按照下面步骤操作即可： + +点击菜单栏的“Plugins”，在弹出的下拉窗口中，点击“Activate Tracer”，即可出现Trace tool窗口。 + +![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-old-ver-2.png) + +![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-old-ver-3.png) + + + +**步骤3：参数设置** + +点击Trace tool窗口工具栏里面的“设置”按钮，弹出如下设置窗口，用户需要关注和设置的即图中标注的部分： + +* ①自动保存，默认是勾选的，如果没有勾选，建议用户勾选该功能。 + +* ②保存的Log文件类型，支持Bin和trc两种类型，默认是trc。Bin类型的文件需要coolwatcher才能查看，trc为普通文本文件。 + +* ③单个Log文件大小，当文件大小超过该值时，会自动保存到下一个新的文件中。 + +* ④Log文件保存路径，用户可根据需要来设置，默认是保存到coolwatcher工具根目录的logs目录下。 + +* ⑤是否保存pcap文件，默认不保存。建议用户勾选该选项，勾选后，coolwatcher工具会自动抓取并保存pcap文件。 + +按照上述说明设置完成后，点击“OK”按钮保存。 + + ![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-config.png) + + + +**步骤4：开始Log抓取** + +点击Trace tool窗口的“开始”按钮，即可看到下方的窗口开始输出Log信息。如下图所示： + +![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-start-trace.png) + + + +**步骤5：Log文件打包** + +当需要的AP Log已经抓取完成时，点击Trace tool窗口的“停止”按钮，进入用户设置的Log保存目录下，如果用户没有设置过，则默认保存到coolwatcher工具根目录下的logs文件夹。进入AP Log保存目录后，将logs目录下的所有文件都打包压缩，然后发送给我司FAE或者研发人员，用于分析问题。 + +![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-log-dir.png) + +> 建议用户在每次抓取log之前，先将默认的log保存路径下的历史log文件删除。 + + + +### CP日志抓取 + +UNISOC8910平台模组CP Log的抓取，需要使用ArmTracer工具，下面将说明如何使用ArmTracer工具来抓取模组CP Log。 + +#### 抓取步骤 + +**步骤1：打开ArmTracer工具** + +将ArmTracer工具的压缩包解压到电脑某个路径下，注意路径中不要包含中文字符。进入到ArmTracer工具根目录下，双击ArmTracer.exe文件打开该工具，进入如下所示主界面： + +![](../../media/dev-tools/LogTool/UNISOC8910-armtracer-ui-1.png) + +上图中①处是端口参数设置按钮，②处是开始按钮，③处是停止按钮，④处是log保存路径设置按钮。 + + + +**步骤2：端口参数配置** + +点击工具栏的端口参数设置按钮，弹出如下设置窗口。由于使用的是USB端口，因此只需要选择端口号即可，其他参数一般保持默认。点击“Device Port”选项输入框的下拉按钮，选择“Quectel USB CP Log Port”端口对应的端口号，然后点击“OK”。 + +![](../../media/dev-tools/LogTool/UNISOC8910-armtracer-port-config.png) + + + +**步骤3：设置log保存路径** + +点击工具栏的log保存路径设置按钮，弹出如下设置窗口。“Saved Path”是CP log的保存路径，用户根据需要去设置。“Filename”是log文件的名称，ArmTracer工具会使用该名称和时间戳组合为最终的log文件名称。设置好log文件保存路径和文件名称后，点击“OK”。 + +![](../../media/dev-tools/LogTool/UNISOC8910-armtracer-log-save-setting.png) + + + +**步骤4：开始CP log抓取** + +点击工具栏的开始按钮，此时可能会自动弹出步骤3中的“log setting”窗口，直接点击“OK”。如果硬件连接正常，工具配置正确，应该可以看到工具窗口开始输出log信息，如下图所示： + +![](../../media/dev-tools/LogTool/UNISOC8910-armtracer-ui-2.png) + + + +**步骤5：Log文件打包保存** + +当需要的Log抓取完成了，点击ArmTracer工具栏的停止按钮，log会自动保存到之前设置的目录下。将log保存目录下的最新生成的.tra文件都打包压缩为一个文件，发送给我司FAE即可。 + +![](../../media/dev-tools/LogTool/UNISOC8910-armtracer-log-file.png) + + + +#### 配置工具自动抓取 + +抓取CP Log的目的是为了分析设备的无线网络相关的问题，比如设备网络注册失败问题。而设备的网络注册过程是在开机阶段就自动进行的，所以分析网络注册失败这一类问题，一般都需要抓设备开机阶段的CP Log。为了方便抓取设备开机阶段的CP log，我们可以配置ArmTracer工具自动检测CP log端口并抓取log。下面将说明如何配置该功能。 + +> 如果仅仅是分析模组网络注册失败问题，也可以不配置该功能，采用手动抓取的方式，抓取包含CFUN0/1切换过程的CP log。 + + + +**步骤1：打开配置文件** + +进入到ArmTracer工具根目录下，找到ArmTracer.ini配置文件，如下图所示： + +![](../../media/dev-tools/LogTool/UNISOC8910-armtracer-config-file.png) + +以文本的方式打开该配置文件，找到[USBDevice]配置项，如下图所示： + +![](../../media/dev-tools/LogTool/UNISOC8910-armtracer-USBDevice-1.png) + + + +**步骤2：修改配置文件** + +找到[USBDevice]配置项后，我们需要在`DeviceList`中增加“Quectel USB CP Log Port”端口，并将`DeviceSel`的值改为“Quectel USB CP Log Port”，修改后如下： + +![](../../media/dev-tools/LogTool/UNISOC8910-armtracer-USBDevice-2.png) + +修改完成后，保存退出。 + + + +**步骤3：选择自动检测CP端口** + +如果修改配置文件之前，ArmTracer工具就已经处于打开状态，在修改配置文件之后，需要关闭ArmTracer工具并重新打开，配置才会生效。打开ArmTracer工具后，进入下图所示主界面： + +![](../../media/dev-tools/LogTool/UNISOC8910-armtracer-ui-3.png) + +点击图中箭头所指的图标，会弹出“Software Setting”窗口，可以看到此时“USB Device Description”对应的值已经是我们前面配置的“Quectel USB CP Log Port”，勾选“Automatic Detect CP Port”功能，点击“OK”。 + +![](../../media/dev-tools/LogTool/UNISOC8910-armtracer-software-setting.png) + +如果配置正确，理论上在点击“OK”后，工具就会自动检测CP log端口并开始抓取log，可以看到CP log输出，如下所示： + +![](../../media/dev-tools/LogTool/UNISOC8910-armtracer-log-output.png) + +为了进一步验证配置是否正常，我们重启设备，观察ArmTracer工具是否可以自动检测CP log端口并自动开始输出log，如果能观察到ArmTracer工具log输出窗口不断有log输出，说明配置是生效的。就可以开始正式抓取CP log了。 + + + + + +### Dump文件导出 + +coolwatcher支持dump文件导出，当模组发生dump死机问题时，可以通过coolwatcher导出dump文件，然后将其打包压缩后发送给我司研发分析。下面介绍如何使用coolwatcher工具来导出dump文件。 + +**步骤1：配置dump模式** + +模组在默认情况下，如果发生dump，会直接重启。这种情况下，无法导出dump文件。因此，我们需要在模组正常运行时，先发送AT指令来配置模组的dump模式，确保发生dump时不会自动重启，而是一直停在dump状态，等待用户导出dump文件。 + +下面是UNISOC8910平台模组配置dump模式，需要发送的AT指令: + +``` +AT+QDBGCFG="DUMPCFG",0 +``` + +打开QPYcom工具，“COM Port”选择“Quectel USB AT Port”端口，点击“Open Port”，然后发送上面的AT指令： + +![](../../media/dev-tools/LogTool/UNISOC8850-dump-config.png) + + + +>上述AT发送后立即生效，但是掉电不保存，如果重启设备了，就需要重新发送一次。 + + + +**步骤2：复现dump问题** + +按照步骤1发送相关AT指令后，就可以去复现相关的dump问题，当模组出现dump问题时，从coolwatcher的log输出窗口可以看到如下log信息： + +![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-dump.png) + + + +**步骤3：导出dump文件** + +依次点击菜单栏的“Tools”——>“Blue Screen Dump”，如下图所示： + +![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-dump-export-1.png) + +点击之后会弹出dump导出设置窗口，如下图所示： + +![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-dump-export-2.png) + +在上图所示窗口中，用户需要进行的操作如下： + +* “Mode”：选择“8910 (FreeRTOS)”选项。 + +* “XML file name”：选择图中所示的文件，一般默认就是该文件。 + +* “Elf file name”：选择模组当前使用的固件所对应的elf文件，一般可直接在固件包中找到，如下图所示。如果固件包中没有，可以联系我司FAE获取对应固件的elf文件。 + +![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-elf-file.png) + +> 如果用户使用的coolwatcher工具版本较新，在导出dump文件时，是不需要选择elf文件的，即上面的“Bule Screen Dump”窗口中，“Elf file name”选项是处于无法操作的状态。如果“Elf file name”选项处于可选择的状态，用户按照上述说明选择对应elf文件即可。 + +* “Output Directory”：选择dump文件保存目录。需要注意选择的路径中不要包含任何中文字符以及空格等。 + +按照上述说明配置后，点击“start”按钮开始dump文件的导出并等待dump文件导出完成，如下图所示： + +![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-dump-export-3.png) + +进入到dump文件保存目录下，将所有的dump文件打包压缩后，发送给我司FAE或者研发人员进行问题定位和分析。 + +![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-dump-export-4.png) + + + +### Pcap文件导出 + +coolwatcher工具支持自动保存pcap文件，但是该功能默认没有开启。开启方式在前面[AP日志抓取](./UNISOC8910.html#AP日志抓取)章节的步骤3中其实已经提到，即点击Trace tool窗口工具栏里面的“设置”按钮，弹出如下设置窗口，勾选图中⑤处的“Save Pcap”功能，点击“OK”。 + +![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-config.png) + +勾选该功能后，工具就会自动抓取并保存pcap文件，保存的路径为上图④处设置的路径下的cap子目录，cap目录为工具自动创建，无需用户新建该文件夹。 + +![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-pcap-file.png) + +如需要我司FAE或者研发协助分析网络应用相关的问题，可以将AP Log文件和这些pcap文件一起打包压缩后，发送给我司FAE。 + + + +## 常见问题 + +**问题1：**dump导出失败了。 + +dump导出失败的原因有多种，一般常见的原因有下面这些。 + +情况1： + +![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-dump-export-failed-1.png) + +如果导出失败的提示信息类似上图这种，那么可能的原因有： + +* 连接模组和电脑的USB数据线太长，用户可尝试换一根较短的USB数据线。 + +* 模组和电脑之间不是通过USB直连，而是经过了HUB集线器。这种情况很容易导致dump导出失败，建议用户使用USB数据线直连模组和电脑。 + +情况2： + +![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-dump-export-failed-2.png) + +![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-dump-export-failed-3.png) + +如果导出失败的提示信息类似上述两种情况，那很可能是选择的elf文件和模组当前使用的固件不匹配导致。这种情况需要用户选择和模组当前使用的固件相匹配的elf文件。 + +如果用户按照上述几种情况排查后，仍然无法导出，可以联系我司FAE进行协助。 + + + +**问题2：**按照前文说明打开配置coolwatcher工具后，点击“开始”按钮后，trace窗口无AP Log输出。 + +AP Log默认是从USB端口输出，对于coolwatcher工具来说，即从"Quectel USB AP Log Port"端口输出。如果用户之前通过相关AT将AP Log输出切换到了物理串口的Debug串口，就会出现点击“开始”按钮后，trace窗口无AP Log输出的现象。此时，用户可以按照下面步骤进行操作： + +步骤1：确认当前AP Log输出端口。 + +发送如下AT，查询当前的AP Log输出端口： + +``` +at+qdbgcfg="tracecfg" +``` + +打开QPYcom工具，“COM Port”选择“Quectel USB AT Port”端口，点击“Open Port”，然后发送上面的AT指令： + +![](../../media/dev-tools/LogTool/at-qdbgcfg-tracecfg-1.png) + +如果AT指令查询结果如上图所示，最后两位数字是0和1，说明当前AP Log的输出端口是物理串口Debug口。 + +此时，用户可以发送如下AT命令，来将AP Log输出端口切换到USB端口： + +``` +at+qdbgcfg="tracecfg",0,2 +``` + +![](../../media/dev-tools/LogTool/at-qdbgcfg-tracecfg-2.png) + +由于上述AT指令需要重启才能生效，所以发送上述AT指令后，重启模组。然后回到coolwatcher工具界面，重新点击“开始”按钮，应该就可以看到有Log输出了。 + + + +**问题3：**log中看到如下这种信息，是系统某些功能运行异常吗？ + +![](../../media/dev-tools/LogTool/UNISOC8910-cooltools-invalid-tdb.png) + +上图中这些信息并不是模组功能运行异常，而是因为使用的coolwatcher工具版本比较旧，工具无法识别解析一些log。用户可联系我司FAE申请最新版本的coolwatcher工具。 + diff --git a/docs/Application_guide/zh/dev-tools/README.md b/docs/Application_guide/zh/dev-tools/README.md index d7e17df5..37a58877 100644 --- a/docs/Application_guide/zh/dev-tools/README.md +++ b/docs/Application_guide/zh/dev-tools/README.md @@ -8,5 +8,6 @@ - [Thonny IDE 使用教程](./Thonny/README.md) - [DTU Tool 使用教程](./DTU-Tool/README.md) - [产测工具使用教程](./FactoryTool/README.md) +- [各平台Log工具使用教程](./LogTool/README.md) - [VSCode 插件使用教程](./VSCode-Plugin-quecpython/README.md) - [QMulti_DL 批量烧录工具使用教程](./QMulti-DL/README.md) diff --git a/docs/Application_guide/zh/sidebar.yaml b/docs/Application_guide/zh/sidebar.yaml index a12c8d2f..8c7c4b53 100644 --- a/docs/Application_guide/zh/sidebar.yaml +++ b/docs/Application_guide/zh/sidebar.yaml @@ -247,6 +247,17 @@ items: file: dev-tools/DTU-Tool/README.md - label: 产测工具使用教程 file: dev-tools/FactoryTool/README.md + - label: 各平台Log工具使用教程 + file: dev-tools/LogTool/README.md + items: + - label: ASR平台 + file: dev-tools/LogTool/ASR.md + - label: EIGEN平台 + file: dev-tools/LogTool/EIGEN.md + - label: UNISOC8850平台 + file: dev-tools/LogTool/UNISOC8850.md + - label: UNISOC8910平台 + file: dev-tools/LogTool/UNISOC8910.md - label: VSCode 插件使用教程 file: dev-tools/VSCode-Plugin-quecpython/README.md - label: QMulti_DL 批量烧录工具使用教程 -- Gitee