Documentation: esp_wifi_set_promiscuous_filter() vs. esp_wifi_set_promiscuous_ctrl_filter() (IDFGH-9366)

[roger-]

Answers checklist.

• I have read the documentation ESP-IDF Programming Guide and the issue is not addressed there.
• I have updated my IDF branch (master or release) to the latest version and checked that the issue is present there.
• I have searched the issue tracker for a similar issue and not found a similar issue.

General issue report

The documentation on esp_wifi_set_promiscuous_filter() and esp_wifi_set_promiscuous_ctrl_filter() could use some improvement:

• what does "filter" mean? Block or pass? "Filter" by itself seems ambiguous.
• the relationship between the two functions is not clear. Does esp_wifi_set_promiscuous_filter() need to be called with the WIFI_PROMIS_FILTER_MASK_CTRL option before esp_wifi_set_promiscuous_ctrl_filter()?
• what happens if you just call esp_wifi_set_promiscuous_ctrl_filter()?

[zhangyanjiaoesp]

@roger-

what does "filter" mean? Block or pass? "Filter" by itself seems ambiguous.

The documentation already says "filter" means "pass".

If the sniffer mode is enabled, the following packets can be dumped to the application.

For frames that the sniffer can dump, the application can additionally decide which specific type of packets can be filtered to the application by using esp_wifi_set_promiscuous_filter() and esp_wifi_set_promiscuous_ctrl_filter().

https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/wifi.html#wi-fi-sniffer-mode

For the relationship between the two functions, we will update the documentation.