ESP32 Wi-Fi 客户端实现 / ESP32 Wi-Fi client implementation. More...

#include <esp_wifi_client.hpp>

Inheritance diagram for LibXR::ESP32WifiClient:

Collaboration diagram for LibXR::ESP32WifiClient:

Public Member Functions
bool	Enable () override
	启用网络接口（WiFi） / Enable the network interface

void	Disable () override
	禁用网络接口（WiFi） / Disable the network interface

WifiError	Connect (const Config &config) override
	连接到指定 WiFi 网络 / Connect to a WiFi network

WifiError	Disconnect () override
	断开当前 WiFi 连接 / Disconnect from the WiFi network

bool	IsConnected () const override
	检查是否已连接 / Check if currently connected

IPAddressRaw	GetIPAddress () const override
	获取当前 IP 地址 / Get current IP address

MACAddressRaw	GetMACAddress () const override
	获取当前 MAC 地址 / Get MAC address

WifiError	Scan (ScanResult *out_list, size_t max_count, size_t &out_found) override
	扫描可用网络 / Scan for available WiFi networks

int	GetRSSI () const override
	获取当前 WiFi 信号强度（RSSI） / Get current signal strength

Public Member Functions inherited from LibXR::WifiClient
virtual	~WifiClient ()=default
	析构函数 / Destructor

Public Member Functions inherited from LibXR::NetworkInterface

Private Member Functions
bool	RegisterHandlers ()

void	UnregisterHandlers ()

void	ResetConnectionState ()

void	DrainEvents ()

Static Private Member Functions
static void	EventHandler (void arg, esp_event_base_t event_base, int32_t event_id, void event_data)
	事件处理回调 / Event handler callback

Private Attributes
bool	init_ok_ = false

bool	enabled_ = false
	是否启用 / Whether WiFi is enabled

bool	handlers_registered_ = false

bool	connected_ = false
	是否连接 / Whether WiFi is connected

bool	got_ip_ = false
	是否获取 IP / Whether IP is acquired

char	ip_str_ [16] = {}
	当前 IP 字符串 / Current IP string

esp_event_handler_instance_t	wifi_connected_handler_ = nullptr

esp_event_handler_instance_t	wifi_disconnected_handler_ = nullptr

esp_event_handler_instance_t	got_ip_handler_ = nullptr

esp_event_handler_instance_t	lost_ip_handler_ = nullptr

LibXR::Semaphore	semaphore_
	状态同步信号量 / Event wait semaphore

Static Private Attributes
static bool	is_initialized_
	ESP 网络是否已初始化 / Netif initialized.

static esp_netif_t *	netif_ = nullptr
	ESP 默认 netif 对象 / Default netif.

Additional Inherited Members
Public Types inherited from LibXR::WifiClient
enum class	WifiError { NONE , ALREADY_ENABLED , NOT_ENABLED , CONNECTION_TIMEOUT , AUTHENTICATION_FAILED , DHCP_FAILED , SSID_NOT_FOUND , INVALID_CONFIG , HARDWARE_FAILURE , SCAN_FAILED , UNKNOWN }
	WiFi 错误码 / Enumeration of WiFi error codes. More...

enum class	Security { OPEN , WPA2_PSK , WPA2_ENTERPRISE , UNKNOWN }
	WiFi 安全类型 / WiFi security types. More...

using	WifiCallback = LibXR::Callback<WifiError>
	WiFi 状态回调类型 / Callback type for WiFi status.

Detailed Description

ESP32 Wi-Fi 客户端实现 / ESP32 Wi-Fi client implementation.

基于 ESP-IDF 提供连接、断开、扫描、RSSI 查询等接口。 Provides connect/disconnect/scan/RSSI operations via ESP-IDF.

Definition at line 19 of file esp_wifi_client.hpp.

Constructor & Destructor Documentation

◆ ESP32WifiClient()

LibXR::ESP32WifiClient::ESP32WifiClient ( )

Definition at line 92 of file esp_wifi_client.cpp.

{
  if (is_initialized_)
  {
    init_ok_ = true;
    return;
  }
 
  esp_err_t err = nvs_flash_init();
  if ((err == ESP_ERR_NVS_NO_FREE_PAGES) || (err == ESP_ERR_NVS_NEW_VERSION_FOUND))
  {
    if (nvs_flash_erase() != ESP_OK)
    {
      return;
    }
    err = nvs_flash_init();
  }
  if (err != ESP_OK)
  {
    return;
  }
 
  err = esp_netif_init();
  if ((err != ESP_OK) && (err != ESP_ERR_INVALID_STATE))
  {
    return;
  }
 
  err = esp_event_loop_create_default();
  if ((err != ESP_OK) && (err != ESP_ERR_INVALID_STATE))
  {
    return;
  }
 
  netif_ = esp_netif_create_default_wifi_sta();
  if (netif_ == nullptr)
  {
    return;
  }
 
  wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
  err = esp_wifi_init(&cfg);
  if ((err != ESP_OK) && (err != ESP_ERR_INVALID_STATE))
  {
    return;
  }
 
  is_initialized_ = true;
  init_ok_ = true;
}

Member Function Documentation

◆ Connect()

WifiClient::WifiError LibXR::ESP32WifiClient::Connect ( const Config & config )

overridevirtual

连接到指定 WiFi 网络 / Connect to a WiFi network

Parameters

[in] config WiFi 连接配置 / Configuration parameters

Returns: WifiError 连接结果 / Error code

Implements LibXR::WifiClient.

Definition at line 184 of file esp_wifi_client.cpp.

{
  if (!enabled_) return WifiError::NOT_ENABLED;
 
  ResetConnectionState();
  DrainEvents();
 
  wifi_config_t wifi_config{};
  CopyToWifiField(wifi_config.sta.ssid, sizeof(wifi_config.sta.ssid), config.ssid);
  CopyToWifiField(wifi_config.sta.password, sizeof(wifi_config.sta.password),
                  config.password);
  if (esp_wifi_set_config(WIFI_IF_STA, &wifi_config) != ESP_OK)
  {
    return WifiError::INVALID_CONFIG;
  }
  if (esp_wifi_connect() != ESP_OK)
  {
    return WifiError::HARDWARE_FAILURE;
  }
 
  if (!WaitForPredicate(semaphore_, kWifiConnectTimeoutMs, [&]() { return connected_; }))
  {
    return WifiError::CONNECTION_TIMEOUT;
  }
 
  if (!WaitForPredicate(semaphore_, kWifiDhcpTimeoutMs,
                        [&]() { return got_ip_ || !connected_; }))
  {
    return WifiError::DHCP_FAILED;
  }
  if (!connected_) return WifiError::CONNECTION_TIMEOUT;
  if (!got_ip_) return WifiError::DHCP_FAILED;
 
  return WifiError::NONE;
}

◆ Disable()

void LibXR::ESP32WifiClient::Disable ( )

overridevirtual

禁用网络接口（WiFi） / Disable the network interface

Implements LibXR::WifiClient.

Definition at line 174 of file esp_wifi_client.cpp.

{
  if (!enabled_) return;
 
  (void)esp_wifi_stop();
  enabled_ = false;
  ResetConnectionState();
  UnregisterHandlers();
}

◆ Disconnect()

WifiClient::WifiError LibXR::ESP32WifiClient::Disconnect ( )

overridevirtual

断开当前 WiFi 连接 / Disconnect from the WiFi network

Returns: WifiError 断开结果 / Error code

Implements LibXR::WifiClient.

Definition at line 220 of file esp_wifi_client.cpp.

{
  if (!enabled_) return WifiError::NOT_ENABLED;
  if (!connected_) return WifiError::NONE;
 
  DrainEvents();
  if (esp_wifi_disconnect() != ESP_OK)
  {
    return WifiError::HARDWARE_FAILURE;
  }
 
  if (!WaitForPredicate(semaphore_, kWifiDisconnectTimeoutMs,
                        [&]() { return !connected_; }))
  {
    return WifiError::UNKNOWN;
  }
 
  return WifiError::NONE;
}

◆ DrainEvents()

void LibXR::ESP32WifiClient::DrainEvents ( )

private

Definition at line 441 of file esp_wifi_client.cpp.

{
  while (semaphore_.Wait(0) == ErrorCode::OK)
  {
  }
}

◆ Enable()

bool LibXR::ESP32WifiClient::Enable ( )

overridevirtual

启用网络接口（WiFi） / Enable the network interface

Returns: true 表示成功 / true if enabled successfully

Implements LibXR::WifiClient.

Definition at line 143 of file esp_wifi_client.cpp.

{
  if (enabled_) return true;
 
  if (!init_ok_)
  {
    return false;
  }
 
  if (!RegisterHandlers())
  {
    return false;
  }
 
  if (esp_wifi_set_mode(WIFI_MODE_STA) != ESP_OK)
  {
    UnregisterHandlers();
    return false;
  }
 
  ResetConnectionState();
  DrainEvents();
  if (esp_wifi_start() != ESP_OK)
  {
    UnregisterHandlers();
    return false;
  }
  enabled_ = true;
  return true;
}

◆ EventHandler()

void LibXR::ESP32WifiClient::EventHandler	(	void *	arg,
		esp_event_base_t	event_base,
		int32_t	event_id,
		void *	event_data )

staticprivate

事件处理回调 / Event handler callback

Parameters

arg	用户数据 / User pointer
event_base	事件域 / Event base type
event_id	事件编号 / Event ID
event_data	附加数据 / Event payload

Definition at line 313 of file esp_wifi_client.cpp.

{
  auto* self = static_cast<ESP32WifiClient*>(arg);
 
  if (event_base == WIFI_EVENT)
  {
    switch (event_id)
    {
      case WIFI_EVENT_STA_CONNECTED:
        self->connected_ = true;
        self->semaphore_.Post();
        break;
      case WIFI_EVENT_STA_DISCONNECTED:
        self->connected_ = false;
        self->got_ip_ = false;
        self->ip_str_[0] = '\0';
        self->semaphore_.Post();
        break;
      default:
        break;
    }
  }
 
  if (event_base == IP_EVENT)
  {
    switch (event_id)
    {
      case IP_EVENT_STA_GOT_IP:
      {
        ip_event_got_ip_t* event = reinterpret_cast<ip_event_got_ip_t*>(event_data);
        self->got_ip_ = true;
        esp_ip4addr_ntoa(&event->ip_info.ip, self->ip_str_, sizeof(self->ip_str_));
        self->semaphore_.Post();
        break;
      }
      case IP_EVENT_STA_LOST_IP:
        self->got_ip_ = false;
        self->ip_str_[0] = '\0';
        self->semaphore_.Post();
        break;
      default:
        break;
    }
  }
}

◆ GetIPAddress()

IPAddressRaw LibXR::ESP32WifiClient::GetIPAddress ( ) const

overridevirtual

获取当前 IP 地址 / Get current IP address

Returns: 当前 IP 地址（结构形式） / Current IP address in raw form

Implements LibXR::WifiClient.

Definition at line 242 of file esp_wifi_client.cpp.

{
  return IPAddressRaw::FromString(ip_str_);
}

◆ GetMACAddress()

MACAddressRaw LibXR::ESP32WifiClient::GetMACAddress ( ) const

overridevirtual

获取当前 MAC 地址 / Get MAC address

Returns: 当前 MAC 地址（结构形式） / Current MAC address in raw form

Implements LibXR::WifiClient.

Definition at line 247 of file esp_wifi_client.cpp.

{
  uint8_t mac[6] = {};
  esp_wifi_get_mac(WIFI_IF_STA, mac);
  MACAddressRaw result;
  std::memcpy(result.bytes, mac, 6);
  return result;
}

◆ GetRSSI()

int LibXR::ESP32WifiClient::GetRSSI ( ) const

overridevirtual

获取当前 WiFi 信号强度（RSSI） / Get current signal strength

Returns: 信号强度（dBm） / Signal strength in dBm

Implements LibXR::WifiClient.

Definition at line 360 of file esp_wifi_client.cpp.

{
  if (!connected_) return -127;
 
  wifi_ap_record_t ap_info;
  if (esp_wifi_sta_get_ap_info(&ap_info) == ESP_OK)
  {
    return ap_info.rssi;
  }
  return -127;
}

◆ IsConnected()

bool LibXR::ESP32WifiClient::IsConnected ( ) const

overridevirtual

检查是否已连接 / Check if currently connected

Returns: true 如果连接上了 / true if connected

Implements LibXR::WifiClient.

Definition at line 240 of file esp_wifi_client.cpp.

240{ return connected_; }

◆ RegisterHandlers()

bool LibXR::ESP32WifiClient::RegisterHandlers ( )

private

Definition at line 372 of file esp_wifi_client.cpp.

{
  if (handlers_registered_)
  {
    return true;
  }
 
  if ((esp_event_handler_instance_register(WIFI_EVENT, WIFI_EVENT_STA_CONNECTED,
                                           &EventHandler, this,
                                           &wifi_connected_handler_) != ESP_OK) ||
      (esp_event_handler_instance_register(WIFI_EVENT, WIFI_EVENT_STA_DISCONNECTED,
                                           &EventHandler, this,
                                           &wifi_disconnected_handler_) != ESP_OK) ||
      (esp_event_handler_instance_register(IP_EVENT, IP_EVENT_STA_GOT_IP, &EventHandler,
                                           this, &got_ip_handler_) != ESP_OK) ||
      (esp_event_handler_instance_register(IP_EVENT, IP_EVENT_STA_LOST_IP, &EventHandler,
                                           this, &lost_ip_handler_) != ESP_OK))
  {
    UnregisterHandlers();
    return false;
  }
 
  handlers_registered_ = true;
  return true;
}

◆ ResetConnectionState()

void LibXR::ESP32WifiClient::ResetConnectionState ( )

private

Definition at line 434 of file esp_wifi_client.cpp.

{
  connected_ = false;
  got_ip_ = false;
  ip_str_[0] = '\0';
}

◆ Scan()

WifiClient::WifiError LibXR::ESP32WifiClient::Scan	(	ScanResult *	out_list,
		size_t	max_count,
		size_t &	out_found )

overridevirtual

扫描可用网络 / Scan for available WiFi networks

Parameters

[out]	out_list	扫描结果数组 / Output list buffer
[in]	max_count	最大可填入数量 / Max result count
[out]	out_found	实际找到数量 / Number found

Returns: WifiError 错误码 / Scan result code

Implements LibXR::WifiClient.

Definition at line 256 of file esp_wifi_client.cpp.

{
  out_found = 0;
  if (!enabled_)
  {
    return WifiError::NOT_ENABLED;
  }
  if ((out_list == nullptr) && (max_count != 0U))
  {
    return WifiError::INVALID_CONFIG;
  }
 
  wifi_scan_config_t scan_config = {};
  if (esp_wifi_scan_start(&scan_config, true) != ESP_OK)
  {
    return WifiError::SCAN_FAILED;
  }
 
  uint16_t ap_num = 0;
  if (esp_wifi_scan_get_ap_num(&ap_num) != ESP_OK)
  {
    return WifiError::SCAN_FAILED;
  }
 
  uint16_t copy_count = ap_num;
  if (copy_count > max_count)
  {
    copy_count = static_cast<uint16_t>(max_count);
  }
  if (copy_count > kMaxScanResults)
  {
    copy_count = kMaxScanResults;
  }
 
  wifi_ap_record_t ap_records[kMaxScanResults] = {};
  if ((copy_count > 0U) &&
      (esp_wifi_scan_get_ap_records(&copy_count, ap_records) != ESP_OK))
  {
    return WifiError::SCAN_FAILED;
  }
 
  out_found = copy_count;
  for (uint16_t i = 0; i < copy_count; ++i)
  {
    CopyToCharField(out_list[i].ssid, sizeof(out_list[i].ssid),
                    reinterpret_cast<const char*>(ap_records[i].ssid));
    out_list[i].rssi = ap_records[i].rssi;
    out_list[i].security = (ap_records[i].authmode == WIFI_AUTH_OPEN) ? Security::OPEN
                           : (ap_records[i].authmode == WIFI_AUTH_WPA2_PSK)
                               ? Security::WPA2_PSK
                               : Security::UNKNOWN;
  }
 
  return WifiError::NONE;
}

◆ UnregisterHandlers()

void LibXR::ESP32WifiClient::UnregisterHandlers ( )

private

Definition at line 398 of file esp_wifi_client.cpp.

{
  if ((wifi_connected_handler_ == nullptr) && (wifi_disconnected_handler_ == nullptr) &&
      (got_ip_handler_ == nullptr) && (lost_ip_handler_ == nullptr))
  {
    handlers_registered_ = false;
    return;
  }
 
  if (wifi_connected_handler_ != nullptr)
  {
    (void)esp_event_handler_instance_unregister(WIFI_EVENT, WIFI_EVENT_STA_CONNECTED,
                                                wifi_connected_handler_);
    wifi_connected_handler_ = nullptr;
  }
  if (wifi_disconnected_handler_ != nullptr)
  {
    (void)esp_event_handler_instance_unregister(WIFI_EVENT, WIFI_EVENT_STA_DISCONNECTED,
                                                wifi_disconnected_handler_);
    wifi_disconnected_handler_ = nullptr;
  }
  if (got_ip_handler_ != nullptr)
  {
    (void)esp_event_handler_instance_unregister(IP_EVENT, IP_EVENT_STA_GOT_IP,
                                                got_ip_handler_);
    got_ip_handler_ = nullptr;
  }
  if (lost_ip_handler_ != nullptr)
  {
    (void)esp_event_handler_instance_unregister(IP_EVENT, IP_EVENT_STA_LOST_IP,
                                                lost_ip_handler_);
    lost_ip_handler_ = nullptr;
  }
  handlers_registered_ = false;
}

Field Documentation

◆ connected_

bool LibXR::ESP32WifiClient::connected_ = false

private

是否连接 / Whether WiFi is connected

Definition at line 66 of file esp_wifi_client.hpp.

◆ enabled_

bool LibXR::ESP32WifiClient::enabled_ = false

private

是否启用 / Whether WiFi is enabled

Definition at line 64 of file esp_wifi_client.hpp.

◆ got_ip_

bool LibXR::ESP32WifiClient::got_ip_ = false

private

是否获取 IP / Whether IP is acquired

Definition at line 67 of file esp_wifi_client.hpp.

◆ got_ip_handler_

esp_event_handler_instance_t LibXR::ESP32WifiClient::got_ip_handler_ = nullptr

private

Definition at line 71 of file esp_wifi_client.hpp.

◆ handlers_registered_

bool LibXR::ESP32WifiClient::handlers_registered_ = false

private

Definition at line 65 of file esp_wifi_client.hpp.

◆ init_ok_

bool LibXR::ESP32WifiClient::init_ok_ = false

private

Definition at line 63 of file esp_wifi_client.hpp.

◆ ip_str_

char LibXR::ESP32WifiClient::ip_str_[16] = {}

private

当前 IP 字符串 / Current IP string

Definition at line 68 of file esp_wifi_client.hpp.

68{};

◆ is_initialized_

bool LibXR::ESP32WifiClient::is_initialized_

inlinestaticprivate

Initial value:

=

false

ESP 网络是否已初始化 / Netif initialized.

Definition at line 59 of file esp_wifi_client.hpp.

◆ lost_ip_handler_

esp_event_handler_instance_t LibXR::ESP32WifiClient::lost_ip_handler_ = nullptr

private

Definition at line 72 of file esp_wifi_client.hpp.

◆ netif_

esp_netif_t* LibXR::ESP32WifiClient::netif_ = nullptr

inlinestaticprivate

ESP 默认 netif 对象 / Default netif.

Definition at line 61 of file esp_wifi_client.hpp.

◆ semaphore_

LibXR::Semaphore LibXR::ESP32WifiClient::semaphore_

private

状态同步信号量 / Event wait semaphore

Definition at line 74 of file esp_wifi_client.hpp.

◆ wifi_connected_handler_

esp_event_handler_instance_t LibXR::ESP32WifiClient::wifi_connected_handler_ = nullptr

private

Definition at line 69 of file esp_wifi_client.hpp.

◆ wifi_disconnected_handler_

esp_event_handler_instance_t LibXR::ESP32WifiClient::wifi_disconnected_handler_ = nullptr

private

Definition at line 70 of file esp_wifi_client.hpp.

The documentation for this class was generated from the following files:

driver/esp/esp_wifi_client.hpp
driver/esp/esp_wifi_client.cpp

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ESP32WifiClient()

Member Function Documentation

◆ Connect()

◆ Disable()

◆ Disconnect()

◆ DrainEvents()

◆ Enable()

◆ EventHandler()

◆ GetIPAddress()

◆ GetMACAddress()

◆ GetRSSI()

◆ IsConnected()

◆ RegisterHandlers()

◆ ResetConnectionState()

◆ Scan()

◆ UnregisterHandlers()

Field Documentation

◆ connected_

◆ enabled_

◆ got_ip_

◆ got_ip_handler_

◆ handlers_registered_

◆ init_ok_

◆ ip_str_

◆ is_initialized_

◆ lost_ip_handler_

◆ netif_

◆ semaphore_

◆ wifi_connected_handler_

◆ wifi_disconnected_handler_