API Reference-2 (Doxygen and Breathe)

struct ring_buf

Public Members

uint32_t head

uint32_t tail

uint32_t cap

uint32_t slot_size

uint8_t *slots

SemaphoreHandle_t lock

struct ring_slot_hdr_t

#include <ring_buf.h>

Metadata header stored immediately before each payload slot.

Upper layers reuse the magic value for integrity checks, and payload bytes follow this struct contiguously to keep DMA-friendly copies. Original inline comments remain for Korean context.

Public Members

uint32_t magic

uint16_t len

uint16_t _rsv

file cmd.c

#include <stdio.h>

#include <string.h>

#include <strings.h>

#include “esp_console.h”

#include “esp_err.h”

#include “esp_log.h”

#include “sdkconfig.h”

#include “cmd.h”

#include “wifi.h”

#include “sniffer.h”

UART console commands that control Wi-Fi modes and sniffer utilities.

Functions

static void print_usage(void)

Display available console commands and usage hints.

static int wifi_command(int argc, char **argv)

Handle the top-level wifi command and its subcommands.

매개변수:

• argc – Argument count.

• argv – Argument vector.

반환:

0 on success.

void command_init(void)

Initialise the ESP-IDF console REPL with the sniffer command set.

Start the UART REPL and register Wi-Fi sniffer console commands.

Variables

static const char *TAG = "ESP_CMD"

static esp_console_repl_t *s_repl = NULL

static bool s_initialized = false

file cmd.h

Functions

void command_init(void)

Start the UART REPL and register Wi-Fi sniffer console commands.

Start the UART REPL and register Wi-Fi sniffer console commands.

file ring_buf.c

#include “ring_buf.h”

#include <string.h>

#include “freertos/FreeRTOS.h”

#include “freertos/semphr.h”

#include “esp_heap_caps.h”

#include “esp_log.h”

Mutex-protected ring buffer implementation used by the Wi-Fi sniffer pipeline.

Functions

static inline uint32_t nxt(uint32_t i, uint32_t cap)

Calculate the next index in a circular manner.

매개변수:

• i – Current index.

• cap – Total capacity of the ring buffer.

esp_err_t ring_buf_create(ring_buf_t **out, uint32_t cap, uint32_t slot_size, bool try_psram)

void ring_buf_destroy(ring_buf_t *rb)

Destroy a ring buffer instance and free its resources.

매개변수:

rb – [in] Ring buffer handle to destroy.

bool ring_buf_push(ring_buf_t *rb, const ring_slot_hdr_t *hdr, const uint8_t *payload)

Push a payload into the next free slot.

Operates non-blocking and returns false when the buffer is full so callers can track drops.

매개변수:

• rb – [in] Ring buffer handle.

• hdr – [in] Pointer to the slot header metadata.

• payload – [in] Pointer to the payload data to store.

bool ring_buf_pop(ring_buf_t *rb, ring_slot_hdr_t *hdr, uint8_t *payload)

Pop the oldest slot into the supplied buffers.

Waits up to 1 ms while acquiring the internal mutex.

매개변수:

• rb – [in] Ring buffer handle.

• hdr – [out] Location to receive the slot header metadata.

• payload – [out] Location to receive the payload data.

uint32_t ring_buf_size(const ring_buf_t *rb)

Get the current number of occupied slots in the ring buffer.

매개변수:

rb – [in] Ring buffer handle.

반환:

Number of occupied slots.

uint32_t ring_buf_cap(const ring_buf_t *rb)

Get the total capacity of the ring buffer.

매개변수:

rb – [in] Ring buffer handle.

반환:

Total capacity of the ring buffer.

uint32_t ring_buf_free(const ring_buf_t *rb)

Get the number of free slots remaining in the ring buffer.

매개변수:

rb – [in] Ring buffer handle.

반환:

Number of free slots.

void ring_buf_reset(ring_buf_t *rb)

Reset head/tail indices to empty the buffer.

매개변수:

rb – [in] Ring buffer handle.

Variables

static const char *TAG = "RING_BUF"

file ring_buf.h

#include <stdint.h>

#include <stdbool.h>

#include “esp_err.h”

Typedefs

typedef struct ring_buf ring_buf_t

Functions

esp_err_t ring_buf_create(ring_buf_t **out, uint32_t cap, uint32_t slot_size, bool try_psram)

void ring_buf_destroy(ring_buf_t *rb)

Destroy a ring buffer instance and free its resources.

매개변수:

rb – [in] Ring buffer handle to destroy.

bool ring_buf_push(ring_buf_t *rb, const ring_slot_hdr_t *hdr, const uint8_t *payload)

Push a payload into the next free slot.

Operates non-blocking and returns false when the buffer is full so callers can track drops.

매개변수:

• rb – [in] Ring buffer handle.

• hdr – [in] Pointer to the slot header metadata.

• payload – [in] Pointer to the payload data to store.

bool ring_buf_pop(ring_buf_t *rb, ring_slot_hdr_t *hdr, uint8_t *payload)

Pop the oldest slot into the supplied buffers.

Waits up to 1 ms while acquiring the internal mutex.

매개변수:

• rb – [in] Ring buffer handle.

• hdr – [out] Location to receive the slot header metadata.

• payload – [out] Location to receive the payload data.

uint32_t ring_buf_size(const ring_buf_t *rb)

Get the current number of occupied slots in the ring buffer.

매개변수:

rb – [in] Ring buffer handle.

반환:

Number of occupied slots.

uint32_t ring_buf_cap(const ring_buf_t *rb)

Get the total capacity of the ring buffer.

매개변수:

rb – [in] Ring buffer handle.

반환:

Total capacity of the ring buffer.

uint32_t ring_buf_free(const ring_buf_t *rb)

Get the number of free slots remaining in the ring buffer.

매개변수:

rb – [in] Ring buffer handle.

반환:

Number of free slots.

void ring_buf_reset(ring_buf_t *rb)

Reset head/tail indices to empty the buffer.

매개변수:

rb – [in] Ring buffer handle.

file sniffer.c

#include <string.h>

#include <sys/time.h>

#include “esp_wifi.h”

#include “esp_event.h”

#include “esp_netif.h”

#include “esp_log.h”

#include “nvs_flash.h”

#include “freertos/FreeRTOS.h”

#include “freertos/task.h”

#include “esp_heap_caps.h”

#include “sniffer.h”

#include “ring_buf.h”

#include “usb_cdc.h”

Wi-Fi promiscuous capture pipeline that feeds frames into the USB CDC streamer.

Defines

SLOT_SIZE

Functions

static bool have_psram(void)

Detect whether SPIRAM is available for large ring allocations.

static void wifi_promiscuous_cb(void *buf, wifi_promiscuous_pkt_type_t type)

Wi-Fi promiscuous callback that copies frames into the ring buffer.

static void streamer_task(void *arg)

FreeRTOS task that drains the ring buffer and writes frames to the host.

void sniffer_init(void)

Configure buffer resources and start the USB streamer task.

Set up ring buffer and streamer task.

void sniffer_enable_promiscuous(void)

Enable promiscuous capture with the predefined filter set.

Enable promiscuous capture filters and callback.

void sniffer_ring_reset(void)

Reset ring indices and capture counters.

Reset ring buffer indices and statistics.

void sniffer_print_stats(void)

Print current ring usage and capture statistics.

Dump capture/drop counters and current ring usage.

Variables

static const char *TAG = "SNIF"

static ring_buf_t *g_rb = NULL

static uint32_t captured_count = 0

static uint32_t dropped_count = 0

file sniffer.h

#include <stdint.h>

#include “esp_err.h”

Defines

MAX_PACKET_SIZE

Maximum raw 802.11 payload length captured per frame.

RING_SLOTS_PSRAM

Number of ring slots when PSRAM is available.

RING_SLOTS_INTERNAL

Number of ring slots when limited to internal RAM.

SYNC_MAGIC

PACKET_HEADER_MAGIC

Functions

struct __attribute__ ((packed))

Metadata prepended to each frame written to the USB CDC stream.

void sniffer_init(void)

Set up ring buffer and streamer task.

Set up ring buffer and streamer task.

void sniffer_enable_promiscuous(void)

Enable promiscuous capture filters and callback.

Enable promiscuous capture filters and callback.

void sniffer_ring_reset(void)

Reset ring buffer indices and statistics.

Reset ring buffer indices and statistics.

void sniffer_print_stats(void)

Dump capture/drop counters and current ring usage.

Dump capture/drop counters and current ring usage.

file usb_cdc.c

#include “usb_cdc.h”

#include “tinyusb.h”

#include “tusb_cdc_acm.h”

#include “esp_log.h”

Thin wrapper around TinyUSB CDC-ACM for the Wi-Fi sniffer streamer.

Functions

static void line_state_changed_cb(int itf, cdcacm_event_t *event)

Track line state changes so we only stream when the host opens the port.

void usb_cdc_init(void)

Initialise the USB CDC-ACM driver and install callbacks.

bool usb_cdc_ready(void)

Check whether the host has opened the CDC port and asserted DTR.

반환:

true if the CDC port is ready for data transmission.

size_t usb_cdc_write(const uint8_t *data, size_t len)

Queue bytes for transmission to the host over the CDC endpoint.

매개변수:

• data – [in] Pointer to the data buffer to send.

• len – [in] Number of bytes to send from the data buffer.

반환:

Number of bytes successfully queued for transmission.

size_t usb_cdc_read(uint8_t *data, size_t len)

Read any pending bytes from the host.

매개변수:

• data – [out] Pointer to the buffer to receive incoming data.

• len – [in] Maximum number of bytes to read into the buffer.

반환:

Number of bytes actually read from the host.

void usb_cdc_flush(void)

Flush any queued bytes to the host over the CDC endpoint.

Variables

static const char *TAG = "USB_CDC"

static bool s_cdc_ready = false

file usb_cdc.h

#include <stddef.h>

#include <stdbool.h>

#include “esp_err.h”

Functions

void usb_cdc_init(void)

Initialise the USB CDC-ACM driver and install callbacks.

bool usb_cdc_ready(void)

Check whether the host has opened the CDC port and asserted DTR.

반환:

true if the CDC port is ready for data transmission.

size_t usb_cdc_write(const uint8_t *data, size_t len)

Queue bytes for transmission to the host over the CDC endpoint.

매개변수:

• data – [in] Pointer to the data buffer to send.

• len – [in] Number of bytes to send from the data buffer.

반환:

Number of bytes successfully queued for transmission.

size_t usb_cdc_read(uint8_t *data, size_t len)

Read any pending bytes from the host.

매개변수:

• data – [out] Pointer to the buffer to receive incoming data.

• len – [in] Maximum number of bytes to read into the buffer.

반환:

Number of bytes actually read from the host.

void usb_cdc_flush(void)

Flush any queued bytes to the host over the CDC endpoint.

file wifi.c

#include “wifi.h”

#include <string.h>

#include <stdio.h>

#include “esp_wifi.h”

#include “esp_log.h”

#include “sniffer.h”

Minimal Wi-Fi configuration manager backing the sniffer console commands.

Defines

WIFI_AP_DEFAULT_CHANNEL

Default SoftAP channel number.

WIFI_AP_DEFAULT_MAX_CONNECTION

WIFI_AP_DEFAULT_BEACON_INTERVAL

Functions

static void ensure_ap_defaults(void)

Ensure SoftAP configuration has sane defaults when unset.

static esp_err_t apply_wifi_mode_internal(wifi_mode_t mode)

Internal helper to reconfigure the driver and restart with cached parameters.

매개변수:

mode – Desired Wi-Fi mode to apply.

반환:

ESP_OK on success, or an error code on failure.

static esp_err_t update_sta_ssid(const char *ssid)

Store a new STA SSID and push it to the driver.

매개변수:

ssid – New STA SSID string.

반환:

ESP_OK on success, or an error code on failure.

static esp_err_t update_sta_password(const char *password)

Store a new STA password and push it to the driver.

매개변수:

password – New STA password string.

반환:

ESP_OK on success, or an error code on failure.

static esp_err_t update_ap_ssid(const char *ssid)

Store a new SoftAP SSID and push it to the driver.

매개변수:

ssid – New SoftAP SSID string.

반환:

ESP_OK on success, or an error code on failure.

static esp_err_t update_ap_password(const char *password)

Store a new SoftAP password (or open mode) and push it to the driver.

매개변수:

password – New SoftAP password string (empty for open mode).

반환:

ESP_OK on success, or an error code on failure.

const char *wifi_mgr_mode_to_string(wifi_mode_t mode)

Convert Wi-Fi mode enum to a short string for status printing.

Convert an enum mode to a short human-readable string.

매개변수:

mode – Wi-Fi mode enum value.

반환:

Short string representation of the Wi-Fi mode.

esp_err_t wifi_mgr_init(void)

Prime cached Wi-Fi configs and record the current mode.

Initialise Wi-Fi manager state by loading NVS-backed configs.

반환:

ESP_OK on success, or an error code on failure.

esp_err_t wifi_mgr_set_mode(wifi_mode_t mode)

Apply a specific Wi-Fi mode using stored STA/AP configurations.

Apply the requested Wi-Fi mode (NULL/AP/STA/APSTA).

매개변수:

mode – Desired Wi-Fi mode to set.

반환:

ESP_OK on success, or an error code on failure.

esp_err_t wifi_mgr_set_mode_str(const char *mode_str)

Parse a textual mode and forward to wifi_mgr_set_mode.

Helper that parses a string such as “sta” or “ap+sta” into wifi_mgr_set_mode.

매개변수:

mode_str – String representation of the desired mode (“null”, “sta”, “ap”, “apsta”).

반환:

ESP_OK on success, or an error code on failure.

esp_err_t wifi_mgr_set_sta_ssid(const char *ssid)

Update STA SSID and refresh promiscuous mode if already active.

Update the cached STA SSID and apply when appropriate.

매개변수:

ssid – New SSID string.

반환:

ESP_OK on success, or an error code on failure.

esp_err_t wifi_mgr_set_sta_password(const char *password)

Update STA password and refresh promiscuous mode if active.

Update the cached STA password and reapply when needed.

매개변수:

password – New password string.

반환:

ESP_OK on success, or an error code on failure.

esp_err_t wifi_mgr_set_ap_ssid(const char *ssid)

Update SoftAP SSID and refresh promiscuous mode if active.

Update the SoftAP SSID and reapply when needed.

매개변수:

ssid – New SSID string.

반환:

ESP_OK on success, or an error code on failure.

esp_err_t wifi_mgr_set_ap_password(const char *password)

Update SoftAP password (empty string toggles open auth) and refresh sniffer.

Update the SoftAP password (empty string forces open mode).

매개변수:

password – New password string.

반환:

ESP_OK on success, or an error code on failure.

esp_err_t wifi_mgr_set_channel(uint8_t primary)

Change the primary channel while respecting mode restrictions.

Change the primary channel while in NULL/AP mode for sniffing.

매개변수:

primary – Desired primary channel (1-13).

반환:

ESP_OK on success, or an error code on failure.

void wifi_mgr_print_status(void)

Print a snapshot of cached and runtime Wi-Fi configuration.

Print the current Wi-Fi configuration snapshot to the console.

Variables

static const char *TAG = "WIFI_MGR"

static wifi_config_t s_sta_config

static wifi_config_t s_ap_config

static wifi_mode_t s_current_mode = WIFI_MODE_NULL

static bool s_initialized = false

file wifi.h

#include “esp_err.h”

#include “esp_wifi.h”

Functions

esp_err_t wifi_mgr_init(void)

Initialise Wi-Fi manager state by loading NVS-backed configs.

NVS, netif, event loop, and Wifi driver setup are assumed to be done elsewhere.

Initialise Wi-Fi manager state by loading NVS-backed configs.

반환:

ESP_OK on success, or an error code on failure.

esp_err_t wifi_mgr_set_mode(wifi_mode_t mode)

Apply the requested Wi-Fi mode (NULL/AP/STA/APSTA).

Apply the requested Wi-Fi mode (NULL/AP/STA/APSTA).

매개변수:

mode – Desired Wi-Fi mode to set.

반환:

ESP_OK on success, or an error code on failure.

esp_err_t wifi_mgr_set_mode_str(const char *mode_str)

Helper that parses a string such as “sta” or “ap+sta” into wifi_mgr_set_mode.

Helper that parses a string such as “sta” or “ap+sta” into wifi_mgr_set_mode.

매개변수:

mode_str – String representation of the desired mode (“null”, “sta”, “ap”, “apsta”).

반환:

ESP_OK on success, or an error code on failure.

esp_err_t wifi_mgr_set_sta_ssid(const char *ssid)

Update the cached STA SSID and apply when appropriate.

Update the cached STA SSID and apply when appropriate.

매개변수:

ssid – New SSID string.

반환:

ESP_OK on success, or an error code on failure.

esp_err_t wifi_mgr_set_sta_password(const char *password)

Update the cached STA password and reapply when needed.

Update the cached STA password and reapply when needed.

매개변수:

password – New password string.

반환:

ESP_OK on success, or an error code on failure.

esp_err_t wifi_mgr_set_ap_ssid(const char *ssid)

Update the SoftAP SSID and reapply when needed.

Update the SoftAP SSID and reapply when needed.

매개변수:

ssid – New SSID string.

반환:

ESP_OK on success, or an error code on failure.

esp_err_t wifi_mgr_set_ap_password(const char *password)

Update the SoftAP password (empty string forces open mode).

Update the SoftAP password (empty string forces open mode).

매개변수:

password – New password string.

반환:

ESP_OK on success, or an error code on failure.

esp_err_t wifi_mgr_set_channel(uint8_t primary)

Change the primary channel while in NULL/AP mode for sniffing.

Change the primary channel while in NULL/AP mode for sniffing.

매개변수:

primary – Desired primary channel (1-13).

반환:

ESP_OK on success, or an error code on failure.

void wifi_mgr_print_status(void)

Print the current Wi-Fi configuration snapshot to the console.

Print the current Wi-Fi configuration snapshot to the console.

const char *wifi_mgr_mode_to_string(wifi_mode_t mode)

Convert an enum mode to a short human-readable string.

Convert an enum mode to a short human-readable string.

매개변수:

mode – Wi-Fi mode enum value.

반환:

Short string representation of the Wi-Fi mode.

file wifi_sniffer.c

#include <stdio.h>

#include “nvs_flash.h”

#include “esp_netif.h”

#include “esp_event.h”

#include “esp_wifi.h”

#include “esp_log.h”

#include “wifi.h”

#include “sniffer.h”

#include “cmd.h”

#include “usb_cdc.h”

Functions

void wifi_sniffer_init(void)

WIFI Sniffer Main (initialization function).

Variables

static const char *TAG = "WIFI_SNIF"

file wifi_sniffer.h

Functions

void wifi_sniffer_init(void)

WIFI Sniffer Main (initialization function).

file main.c

#include <stdio.h>

#include “nvs_flash.h”

#include “esp_netif.h”

#include “esp_event.h”

#include “esp_wifi.h”

#include “esp_log.h”

#include “wifi_sniffer.h”

ESP-IDF entry point that wires together USB, Wi-Fi, and sniffer subsystems.

Functions

void app_main(void)

Application entry point invoked by ESP-IDF.

Variables

static const char *TAG = "MAIN"

dir components

dir main

dir components/wifi_sniffer