#ifndef WIFI_MONITOR_H #define WIFI_MONITOR_H #include "esp_wifi.h" #include "esp_wifi_types.h" #include #include #ifdef __cplusplus extern "C" { #endif /** * @brief 802.11 Frame Control field bits */ #define FRAME_CTRL_PROTOCOL_VERSION 0x0003 #define FRAME_CTRL_TYPE 0x000C #define FRAME_CTRL_SUBTYPE 0x00F0 #define FRAME_CTRL_TO_DS 0x0100 #define FRAME_CTRL_FROM_DS 0x0200 #define FRAME_CTRL_MORE_FRAG 0x0400 #define FRAME_CTRL_RETRY 0x0800 #define FRAME_CTRL_PWR_MGMT 0x1000 #define FRAME_CTRL_MORE_DATA 0x2000 #define FRAME_CTRL_PROTECTED 0x4000 #define FRAME_CTRL_ORDER 0x8000 /** * @brief 802.11 Frame Types */ typedef enum { FRAME_TYPE_MANAGEMENT = 0, FRAME_TYPE_CONTROL = 1, FRAME_TYPE_DATA = 2, FRAME_TYPE_RESERVED = 3 } wifi_frame_type_t; /** * @brief 802.11 Management Frame Subtypes */ typedef enum { MGMT_ASSOC_REQ = 0, MGMT_ASSOC_RESP = 1, MGMT_REASSOC_REQ = 2, MGMT_REASSOC_RESP = 3, MGMT_PROBE_REQ = 4, MGMT_PROBE_RESP = 5, MGMT_TIMING_ADV = 6, MGMT_BEACON = 8, MGMT_ATIM = 9, MGMT_DISASSOC = 10, MGMT_AUTH = 11, MGMT_DEAUTH = 12, MGMT_ACTION = 13 } wifi_mgmt_subtype_t; /** * @brief 802.11 Control Frame Subtypes */ typedef enum { CTRL_TRIGGER = 2, CTRL_BEAMFORMING_RPT = 4, CTRL_VHT_NDP_ANNOUNCE = 5, CTRL_CTRL_FRAME_EXT = 6, CTRL_CTRL_WRAPPER = 7, CTRL_BLOCK_ACK_REQ = 8, CTRL_BLOCK_ACK = 9, CTRL_PS_POLL = 10, CTRL_RTS = 11, CTRL_CTS = 12, CTRL_ACK = 13, CTRL_CF_END = 14, CTRL_CF_END_ACK = 15 } wifi_ctrl_subtype_t; /** * @brief 802.11 Data Frame Subtypes */ typedef enum { DATA_DATA = 0, DATA_DATA_CF_ACK = 1, DATA_DATA_CF_POLL = 2, DATA_DATA_CF_ACK_POLL = 3, DATA_NULL = 4, DATA_CF_ACK = 5, DATA_CF_POLL = 6, DATA_CF_ACK_POLL = 7, DATA_QOS_DATA = 8, DATA_QOS_DATA_CF_ACK = 9, DATA_QOS_DATA_CF_POLL = 10, DATA_QOS_DATA_CF_ACK_POLL = 11, DATA_QOS_NULL = 12, DATA_QOS_CF_POLL = 14, DATA_QOS_CF_ACK_POLL = 15 } wifi_data_subtype_t; /** * @brief Parsed 802.11 MAC header */ typedef struct { // Frame Control uint16_t frame_control; uint8_t protocol_version; uint8_t type; uint8_t subtype; bool to_ds; bool from_ds; bool more_frag; bool retry; bool pwr_mgmt; bool more_data; bool protected_frame; bool order; // Duration/ID (NAV) uint16_t duration_id; // MAC Addresses uint8_t addr1[6]; // Receiver address uint8_t addr2[6]; // Transmitter address uint8_t addr3[6]; // Filtering address (BSSID/SA/DA) // Sequence Control uint16_t seq_ctrl; uint16_t fragment_num; uint16_t sequence_num; // Optional: Address 4 (if To DS and From DS both set) uint8_t addr4[6]; bool has_addr4; // RX Info int8_t rssi; uint8_t channel; uint32_t timestamp; // PHY rate info uint8_t mcs; // MCS index (for HT/VHT frames) uint8_t rate; // Legacy rate or rate index uint8_t sig_mode; // Signal mode (0=legacy, 1=HT, 3=VHT) bool sgi; // Short Guard Interval uint8_t bandwidth; // 0=20MHz, 1=40MHz, 2=80MHz uint32_t phy_rate_kbps; // Calculated PHY rate in Kbps (uint32_t to handle >65 Mbps) // Frame size uint16_t frame_len; } wifi_frame_info_t; /** * @brief WiFi collapse detection statistics */ typedef struct { uint32_t total_frames; uint32_t retry_frames; uint32_t high_nav_frames; // NAV > 5000 us uint32_t rts_frames; uint32_t cts_frames; uint32_t ack_frames; uint32_t data_frames; uint32_t mgmt_frames; // Collapse indicators float retry_rate; // Percentage of retried frames uint16_t avg_nav; // Average NAV duration uint16_t max_nav; // Maximum NAV seen uint32_t collision_events; // Estimated collision count // Duration analysis uint32_t duration_mismatch_frames; // NAV >> expected uint32_t rate_fallback_frames; // PHY rate < 100 Mbps uint16_t avg_phy_rate_mbps; // Average PHY rate uint16_t min_phy_rate_mbps; // Minimum PHY rate seen uint16_t max_phy_rate_mbps; // Maximum PHY rate seen } wifi_collapse_stats_t; /** * @brief Callback function type for frame capture * * @param frame_info Parsed frame information * @param payload Raw frame payload (starts with MAC header) * @param len Frame length */ typedef void (*wifi_monitor_cb_t)(const wifi_frame_info_t *frame_info, const uint8_t *payload, uint16_t len); /** * @brief Initialize WiFi monitor mode * * @param channel WiFi channel to monitor (1-14 for 2.4GHz, 36+ for 5GHz) * @param callback Callback function for captured frames * @return esp_err_t ESP_OK on success */ esp_err_t wifi_monitor_init(uint8_t channel, wifi_monitor_cb_t callback); /** * @brief Start WiFi monitoring * * @return esp_err_t ESP_OK on success */ esp_err_t wifi_monitor_start(void); /** * @brief Stop WiFi monitoring * * @return esp_err_t ESP_OK on success */ esp_err_t wifi_monitor_stop(void); /** * @brief Set WiFi channel for monitoring * * @param channel WiFi channel (1-14 for 2.4GHz, 36+ for 5GHz) * @return esp_err_t ESP_OK on success */ esp_err_t wifi_monitor_set_channel(uint8_t channel); /** * @brief Parse 802.11 frame header * * @param payload Raw frame data * @param len Frame length * @param frame_info Output: parsed frame information * @return esp_err_t ESP_OK on success */ esp_err_t wifi_parse_frame(const uint8_t *payload, uint16_t len, wifi_frame_info_t *frame_info); /** * @brief Get WiFi collapse detection statistics * * @param stats Output: statistics structure * @return esp_err_t ESP_OK on success */ esp_err_t wifi_monitor_get_stats(wifi_collapse_stats_t *stats); /** * @brief Reset WiFi collapse detection statistics */ void wifi_monitor_reset_stats(void); /** * @brief Check if current conditions indicate WiFi collapse * * @return true if collapse is detected, false otherwise */ bool wifi_monitor_is_collapsed(void); /** * @brief Get string representation of frame type * * @param type Frame type * @param subtype Frame subtype * @return const char* String description */ const char* wifi_frame_type_str(uint8_t type, uint8_t subtype); #ifdef __cplusplus } #endif #endif // WIFI_MONITOR_H