Merge branch 'feature/docs_wireshark_trubleshooting_guide' into 'master'

Added wireshark instruction to provide a common workflow for users submitting diagnostic data for Wi-Fi troubleshooting

See merge request idf/esp-idf!3497

docs/en/api-guides/wifi.rst

@@ -1632,7 +1632,7 @@ The following diagram shows how buffer is allocated/freed in the RX direction:
 
 Description:
 
- - The  Wi-Fi hardware receives a packet over the air and puts the packet content to the "Static Rx Buffer", which is also called "RX DMA Buffer".
+ - The Wi-Fi hardware receives a packet over the air and puts the packet content to the "Static Rx Buffer", which is also called "RX DMA Buffer".
  - The Wi-Fi driver allocates a "Dynamic Rx Buffer", makes a copy of the "Static Rx Buffer", and returns the "Static Rx Buffer" to hardware.
  - The Wi-Fi driver delivers the packet to the upper-layer (LwIP), and allocates a PBUF for holding the "Dynamic Rx Buffer".
  - The application receives data from LwIP.
@@ -1705,3 +1705,15 @@ If the Wi-Fi NVS flash is enabled, all Wi-Fi configurations set via the Wi-Fi AP
 Wi-Fi AMPDU
 +++++++++++++++++++++
 Generally, the AMPDU should be enabled, because it can greatly improve the Wi-Fi throughput. Disabling AMPDU is usually for debugging purposes. It may be removed from future releases.
+
+
+Troubleshooting
+---------------
+
+Please refer to a separate document with :doc:`wireshark-user-guide`.
+
+.. toctree::
+    :hidden:
+
+    wireshark-user-guide
+    

docs/en/api-guides/wireshark-user-guide.rst

@@ -0,0 +1,246 @@
+******************************
+Espressif Wireshark User Guide
+******************************
+:link_to_translation:`zh_CN:[中文]`
+
+===========
+1. Overview
+===========
+
+1.1 What is Wireshark?
+======================
+
+`Wireshark <https://www.wireshark.org>`_ (originally named "Ethereal") is a network packet analyzer that captures network packets and displays the packet data as detailed as possible. It uses WinPcap as its interface to directly capture network traffic going through a network interface controller (NIC).
+
+You could think of a network packet analyzer as a measuring device used to examine what is going on inside a network cable, just like a voltmeter is used by an electrician to examine what is going on inside an electric cable.
+
+In the past, such tools were either very expensive, proprietary, or both. However, with the advent of Wireshark, all that has changed.
+
+Wireshark is released under the terms of the GNU General Public License, which means you can use the software and the source code free of charge. It also allows you to modify and customize the source code. 
+
+Wireshark is, perhaps, one of the best open source packet analyzers available today. 
+
+
+1.2 Some Intended Purposes
+==========================
+
+Here are some examples of how Wireshark is typically used:
+
+* Network administrators use it to troubleshoot network problems.
+
+* Network security engineers use it to examine security problems.
+ 
+* Developers use it to debug protocol implementations.
+ 
+* People use it to learn more about network protocol internals.
+
+Beside these examples, Wireshark can be used for many other purposes.
+
+
+1.3 Features
+============
+
+The main features of Wireshark are as follows:
+
+* Available for UNIX and Windows  
+
+* Captures live packet data from a network interface 
+
+* Displays packets along with detailed protocol information
+
+* Opens/saves the captured packet data  
+
+* Imports/exports packets into a number of file formats, supported by other capture programs
+
+* Advanced packet filtering
+
+* Searches for packets based on multiple criteria  
+
+* Colorizes packets according to display filters
+
+* Calculates statistics
+
+* … and a lot more!
+
+
+1.4 Wireshark Can or Can't Do
+==============================
+
+* **Live capture from different network media**. 
+  
+  Wireshark can capture traffic from different network media, including wireless LAN. 
+
+* **Import files from many other capture programs**. 
+  
+  Wireshark can import data from a large number of file formats, supported by other capture programs.
+
+* **Export files for many other capture programs**. 
+  
+  Wireshark can export data into a large number of file formats, supported by other capture programs.
+
+* **Numerous protocol dissectors**.
+
+  Wireshark can dissect, or decode, a large number of protocols.
+
+* **Wireshark is not an intrusion detection system**.
+
+  It will not warn you if there are any suspicious activities on your network. However, if strange things happen, Wireshark might help you figure out what is really going on. 
+
+* **Wireshark does not manipulate processes on the network, it can only perform "measurements" within it**.
+
+  Wireshark does not send packets on the network or influence it in any other way, except for resolving names (converting numerical address values into a human readable format), but even that can be disabled. 
+
+
+==========================
+2. Where to Get Wireshark
+==========================
+
+You can get Wireshark from the official website: https://www.wireshark.org/download.html  
+
+Wireshark can run on various operating systems. Please download the correct version according to the operating system you are using.
+
+
+======================
+3. Step-by-step Guide
+======================
+
+**This demonstration uses Wireshark 2.2.6 on Linux.**
+
+
+**a) Start Wireshark**
+
+On Linux, you can run the shell script provided below. It starts Wireshark, then configures NIC and the channel for packet capture. 
+
+:: 
+
+  ifconfig $1 down
+  iwconfig $1 mode monitor
+  iwconfig $1 channel $2
+  ifconfig $1 up
+  Wireshark&
+
+In the above script, the parameter ``$1`` represents NIC and ``$2`` represents channel. For example, ``wlan0`` in ``./xxx.sh wlan0 6``, specifies the NIC for packet capture, and ``6`` identifies the channel of an AP or Soft-AP.
+
+
+**b) Run the Shell Script to Open Wireshark and Display Capture Interface**
+
+.. figure:: ../../_static/ws-capture-interface.jpeg
+    :align: center
+    :alt: Wireshark Capture Interface
+    :figclass: align-center
+    :width: 60%
+
+    Wireshark Capture Interface
+
+**c) Select the Interface to Start Packet Capture** 
+
+As the red markup shows in the picture above, many interfaces are available. The first one is a local NIC and the second one is a wireless NIC.
+
+Please select the NIC according to your requirements. This document will use the wireless NIC to demonstrate packet capture. 
+
+Double click *wlan0* to start packet capture.
+
+
+**d) Set up Filters**
+
+Since all packets in the channel will be captured, and many of them are not needed, you have to set up filters to get the packets that you need. 
+
+Please find the picture below with the red markup, indicating where the filters should be set up. 
+
+.. figure:: ../../_static/ws-setup-filters.png
+    :align: center
+    :alt: Setting up Filters in Wireshark
+    :figclass: align-center
+
+    Setting up Filters in Wireshark
+
+Click *Filter*, the top left blue button in the picture below. The *display filter* dialogue box will appear.
+
+.. figure:: ../../_static/ws-display-filter-dialogue-box.png
+    :align: center
+    :alt: *Display Filter* Dialogue Box
+    :figclass: align-center
+    :width: 60%
+
+    *Display Filter* Dialogue Box
+
+Click the *Expression* button to bring up the *Filter Expression* dialogue box and set the filter according to your requirements.
+
+.. figure:: ../../_static/ws-filter-expression.png
+    :align: center
+    :alt: *Filter Expression* Dialogue Box
+    :figclass: align-center
+    :width: 80%
+
+    *Filter Expression* Dialogue Box
+
+**The quickest way**: enter the filters directly in the toolbar.
+
+.. figure:: ../../_static/ws-filter-toolbar.png
+    :align: center
+    :alt: Filter Toolbar
+    :figclass: align-center
+
+    Filter Toolbar
+
+Click on this area to enter or modify the filters. If you enter a wrong or unfinished filter, the built-in syntax check turns the background red. As soon as the correct expression is entered, the background becomes green.
+
+The previously entered filters are automatically saved. You can access them anytime by opening the drop down list.
+
+For example, as shown in the picture below, enter two MAC addresses as the filters and click *Apply* (the blue arrow). In this case, only the packet data transmitted between these two MAC addresses will be captured.
+
+.. figure:: ../../_static/ws-filter-toolbar_green.png
+    :align: center
+    :alt: Example of MAC Addresses applied in the Filter Toolbar
+    :figclass: align-center
+
+    Example of MAC Addresses applied in the Filter Toolbar
+
+**e) Packet List**
+
+You can click any packet in the packet list and check the detailed information about it in the box below the list. For example, if you click the first packet, its details will appear in that box.
+
+.. figure:: ../../_static/ws-packet-list.png
+    :align: center
+    :alt: Example of Packet List Details
+    :figclass: align-center
+
+    Example of Packet List Details
+
+**f) Stop/Start Packet Capture**
+
+As shown in the picture below, click the red button to stop capturing the current packet.
+
+.. figure:: ../../_static/ws-stop-packet-capture.png
+    :align: center
+    :alt: Stopping Packets Capture
+    :figclass: align-center
+
+    Stopping Packet Capture
+
+Click the top left blue button to start or resume packet capture.
+
+.. figure:: ../../_static/ws-start-resume-packet-capture.png
+    :align: center
+    :alt: Starting or Resuming Packets Capture
+    :figclass: align-center
+    :width: 60%
+
+    Starting or Resuming the Packets Capture
+
+**g) Save the Current Packet**
+
+On Linux, go to *File* -> *Export Packet Dissections* -> *As Plain Text File* to save the packet.
+
+.. figure:: ../../_static/ws-save-packets.png
+    :align: center
+    :alt: Saving Captured Packets
+    :figclass: align-center
+    :width: 60%
+
+    Saving Captured Packets
+
+Please note that *All packets*, *Displayed* and *All expanded* must be selected.
+
+By default, Wireshark saves the captured packet in a libpcap file. You can also save the file in other formats, e.g. txt, to analyze it in other tools.
+

docs/zh_CN/api-guides/wireshark-user-guide.rst

@@ -0,0 +1,246 @@
+****************************
+乐鑫 Wireshark 使用指南
+****************************
+:link_to_translation:`en:[English]`
+
+===========
+1. 概述
+===========
+
+1.1 什么是 Wireshark？
+========================
+
+Wireshark（原称 Ethereal）是一个网络封包分析软件。网络封包分析软件的功能是撷取网络封包，并尽可能显示出最为详细的网络封包资料。Wireshark 使用 WinPCAP 作为接口，直接与网卡进行数据报文交换。
+
+网络封包分析软件的功能可想像成“电工技师使用电表来量测电流、电压、电阻” 的工作，只是将场景移植到网络上，并将电线替换成网线。
+
+在过去，网络封包分析软件是非常昂贵，或是专门属于营利用的软件。Wireshark 的出现改变了这一切。
+
+在 GNU GPL 通用许可证的保障范围下，使用者可以以免费的代价取得软件与其源代码，并拥有针对其源代码修改及客制化的权利。
+
+Wireshark 是目前全世界最广泛的网络封包分析软件之一。
+
+
+1.2 Wireshark 的主要应用
+===========================
+
+下面是 Wireshark 一些应用的举例：
+
+* 网络管理员用来解决网络问题 
+
+* 网络安全工程师用来检测安全隐患 
+
+* 开发人员用来测试协议执行情况 
+
+* 用来学习网络协议
+
+除了上面提到的，Wireshark 还可以用在其它许多场合。
+
+
+1.3 Wireshark 的特性
+========================
+
+* 支持 UNIX 和 Windows 平台  
+
+* 在接口实时捕捉包  
+
+* 能详细显示包的详细协议信息  
+
+* 可以打开/保存捕捉的包  
+
+* 可以导入导出其他捕捉程序支持的包数据格式 
+
+* 可以通过多种方式过滤包 
+
+* 多种方式查找包  
+
+* 通过过滤以多种色彩显示包 
+
+* 创建多种统计分析
+
+* 等等
+
+
+1.4 Wireshark 的“能”与“不能”？
+================================
+
+* **捕捉多种网络接口**  
+  
+  Wireshark 可以捕捉多种网络接口类型的包，哪怕是无线局域网接口。
+
+* **支持多种其它程序捕捉的文件**
+  
+  Wireshark 可以打开多种网络分析软件捕捉的包。
+
+* **支持多格式输出**
+  
+  Wireshark 可以将捕捉文件输出为多种其他捕捉软件支持的格式。
+
+* **对多种协议解码提供支持**
+  
+  Wireshark 可以支持许多协议的解码。
+
+* **Wireshark 不是入侵检测系统**
+  
+  如果您的网络中存在任何可疑活动，Wireshark 并不会主动发出警告。不过，当您希望对这些可疑活动一探究竟时，Wireshark 可以发挥作用。
+
+* **Wireshark 不会处理网络事务，它仅仅是“测量”（监视）网络**
+  
+  Wireshark 不会发送网络包或做其它交互性的事情（名称解析除外，但您也可以禁止解析）。
+
+
+========================
+2. 如何获取 Wireshark
+========================
+
+官网链接：https://www.wireshark.org/download.html  
+
+Wireshark 支持多种操作系统，请在下载安装文件时，注意选择与您所用操作系统匹配的安装文件。
+
+
+==============
+3. 使用步骤
+==============
+
+**本文档仅以 Linux 系统下的 Wireshark（版本号：2.2.6）为例**。
+
+**1) 启动 Wireshark** 
+
+Linux 下，可编写一个 Shell 脚本，运行该文件即可启动 Wireshark 配置抓包网卡和信道。Shell 脚本如下：
+
+:: 
+
+  ifconfig $1 down
+  iwconfig $1 mode monitor
+  iwconfig $1 channel $2
+  ifconfig $1 up
+  Wireshark&
+
+脚本中有两个参数：``$1`` 和 ``$2``，分别表示网卡和信道，例如，``./xxx.sh wlan0 6`` （此处，``wlan0`` 即为抓包使用的网卡，后面的数字 ``6`` 即为 AP 或 soft-AP 所在的 channel）。
+
+
+**2) 运行 Shell 脚本打开 Wireshark，会出现 Wireshark 抓包开始界面**
+
+.. figure:: ../../_static/ws-capture-interface.jpeg
+    :align: center
+    :alt: Wireshark 抓包界面
+    :figclass: align-center
+    :width: 60%
+
+    Wireshark 抓包界面
+
+
+**3) 选择接口，开始抓包**
+
+从上图红色框中可以看到有多个接口，第一个为本地网卡，第二个为无线网络。
+
+可根据自己的需求选取相应的网卡，本文是以利用无线网卡抓取空中包为例进行简单说明。
+
+双击 *wlan0* 即可开始抓包。
+
+
+**4) 设置过滤条件**
+
+抓包过程中会抓取到同信道所有的空中包，但其实很多都是我们不需要的，因此很多时候我们会设置抓包的过滤条件从而得到我们想要的包。
+
+下图中红色框内即为设置 filter 的位置。
+
+.. figure:: ../../_static/ws-setup-filters.png
+    :align: center
+    :alt: 设置 Wireshark 过滤条件
+    :figclass: align-center
+
+    设置 Wireshark 过滤条件
+
+点击 *Filter* 按钮（下图的左上角蓝色按钮）会弹出 *display filter* 对话框。
+
+.. figure:: ../../_static/ws-display-filter-dialogue-box.png
+    :align: center
+    :alt: *Display Filter* 对话框
+    :figclass: align-center
+    :width: 60%
+
+    *Display Filter* 对话框
+
+点击 *Expression* 按钮，会出现 *Filter Expression* 对话框，在此你可以根据需求进行 filter 的设置。
+
+.. figure:: ../../_static/ws-filter-expression.png
+    :align: center
+    :alt: *Filter Expression* 对话框
+    :figclass: align-center
+    :width: 80%
+
+    *Filter Expression* 对话框
+
+**最直接的方法** ：直接在工具栏上输入过滤条件。
+
+.. figure:: ../../_static/ws-filter-toolbar.png
+    :align: center
+    :alt: 过滤条件工具栏
+    :figclass: align-center
+
+    过滤条件工具栏
+
+点击在此区域输入或修改显示的过滤字符，在输入过程中会进行语法检查。如果您输入的格式不正确，或者未输入完成，则背景显示为红色。直到您输入合法的表达式，背景会变为绿色。你可以点击下拉列表选择您先前键入的过滤字符。列表会一直保留，即使您重新启动程序。
+
+例如：下图所示，直接输入 2 个 MAC 作为过滤条件，点击 *Apply* （即图中的蓝色箭头），则表示只抓取 2 个此 MAC 地址之间的交互的包。
+
+.. figure:: ../../_static/ws-filter-toolbar_green.png
+    :align: center
+    :alt: 在过滤条件工具栏中运用 MAC 地址过滤示例
+    :figclass: align-center
+
+    在过滤条件工具栏中运用 MAC 地址过滤示例
+
+
+**5) 封包列表**
+
+若想查看包的具体的信息只需要选中要查看的包，在界面的下方会显示出包的具体的格式和包的内容。
+
+.. figure:: ../../_static/ws-packet-list.png
+    :align: center
+    :alt: 封包列表具体信息示例
+    :figclass: align-center
+
+    封包列表具体信息示例
+
+如上图所示，我要查看第 1 个包，选中此包，图中红色框中即为包的具体内容。
+
+
+**6) 停止/开始包的捕捉**
+
+若要停止当前抓包，点击下图的红色按钮即可。
+
+.. figure:: ../../_static/ws-stop-packet-capture.png
+    :align: center
+    :alt: 停止包的捕捉
+    :figclass: align-center
+
+    停止包的捕捉
+
+若要重新开始抓包，点击下图左上角的蓝色按钮即可。
+
+.. figure:: ../../_static/ws-start-resume-packet-capture.png
+    :align: center
+    :alt: 开始或继续包的捕捉
+    :figclass: align-center
+    :width: 60%
+
+    开始或继续包的捕捉
+
+**7) 保存当前捕捉包**
+
+Linux 下，可以通过依次点击 "File" -> "Export Packet Dissections" -> "As Plain Text File" 进行保存。
+
+.. figure:: ../../_static/ws-save-packets.png
+    :align: center
+    :alt: 保存捕捉包
+    :figclass: align-center
+    :width: 60%
+
+    保存捕捉包
+
+上图中，需要注意的是，选择 *All packets*、*Displayed* 以及 *All expanded* 三项。
+
+Wireshark 捕捉的包可以保存为其原生格式文件（libpcap），也可以保存为其他格式（如.txt 文件）供其他工具进行读取分析。
+