wifi.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Chris Leishman
 
#pragma once
 
#include <idfxx/cpu>
#include <idfxx/error>
#include <idfxx/event>
#include <idfxx/flags>
#include <idfxx/mac>
#include <idfxx/netif>
 
#include <array>
#include <chrono>
#include <cstdint>
#include <electro/decibel>
#include <esp_idf_version.h>
#include <esp_wifi_types.h>
#include <optional>
#include <soc/soc_caps.h>
#include <span>
#include <string>
#include <string_view>
#include <vector>
 
namespace idfxx::wifi {
 
// =============================================================================
// Enumerations
// =============================================================================
 
enum class role : uint32_t {
    // clang-format off
    sta = 1, 
    ap  = 2, 
    // clang-format on
};
 
enum class auth_mode : int {
    // clang-format off
    open                 = 0,  
    wep                  = 1,  
    wpa_psk              = 2,  
    wpa2_psk             = 3,  
    wpa_wpa2_psk         = 4,  
    wpa2_enterprise      = 5,  
    wpa3_psk             = 6,  
    wpa2_wpa3_psk        = 7,  
    wapi_psk             = 8,  
    owe                  = 9,  
    wpa3_ent_192         = 10, 
    dpp                  = 13, 
    wpa3_enterprise      = 14, 
    wpa2_wpa3_enterprise = 15, 
    wpa_enterprise       = 16, 
    // clang-format on
};
 
enum class power_save : int {
    // clang-format off
    none      = 0, 
    min_modem = 1, 
    max_modem = 2, 
    // clang-format on
};
 
enum class bandwidth : int {
    // clang-format off
    ht20    = 1, 
    ht40    = 2, 
    bw80    = 3, 
    bw160   = 4, 
    bw80_80 = 5, 
    // clang-format on
};
 
enum class scan_type : int {
    // clang-format off
    active  = 0, 
    passive = 1, 
    // clang-format on
};
 
enum class second_channel : int {
    // clang-format off
    above = 1, 
    below = 2, 
    // clang-format on
};
 
enum class sort_method : int {
    // clang-format off
    by_rssi     = 0, 
    by_security = 1, 
    // clang-format on
};
 
enum class disconnect_reason : uint16_t {
    // clang-format off
    // IEEE 802.11 standard reasons
    unspecified                        = 1,   
    auth_expire                        = 2,   
    auth_leave                         = 3,   
    assoc_expire                       = 4,   
    assoc_toomany                      = 5,   
    not_authed                         = 6,   
    not_assoced                        = 7,   
    assoc_leave                        = 8,   
    assoc_not_authed                   = 9,   
    disassoc_pwrcap_bad                = 10,  
    disassoc_supchan_bad               = 11,  
    bss_transition_disassoc            = 12,  
    ie_invalid                         = 13,  
    mic_failure                        = 14,  
    fourway_handshake_timeout          = 15,  
    group_key_update_timeout           = 16,  
    ie_in_4way_differs                 = 17,  
    group_cipher_invalid               = 18,  
    pairwise_cipher_invalid            = 19,  
    akmp_invalid                       = 20,  
    unsupp_rsn_ie_version              = 21,  
    invalid_rsn_ie_cap                 = 22,  
    ieee_802_1x_auth_failed            = 23,  
    cipher_suite_rejected              = 24,  
    tdls_peer_unreachable              = 25,  
    tdls_unspecified                   = 26,  
    ssp_requested_disassoc             = 27,  
    no_ssp_roaming_agreement           = 28,  
    bad_cipher_or_akm                  = 29,  
    not_authorized_this_location       = 30,  
    service_change_precludes_ts        = 31,  
    unspecified_qos                    = 32,  
    not_enough_bandwidth               = 33,  
    missing_acks                       = 34,  
    exceeded_txop                      = 35,  
    sta_leaving                        = 36,  
    end_ba                             = 37,  
    unknown_ba                         = 38,  
    timeout                            = 39,  
    peer_initiated                     = 46,  
    ap_initiated                       = 47,  
    invalid_ft_action_frame_count      = 48,  
    invalid_pmkid                      = 49,  
    invalid_mde                        = 50,  
    invalid_fte                        = 51,  
    transmission_link_establish_failed = 67,  
    alterative_channel_occupied        = 68,  
    // Vendor-specific reasons (200+)
    beacon_timeout                     = 200, 
    no_ap_found                        = 201, 
    auth_fail                          = 202, 
    assoc_fail                         = 203, 
    handshake_timeout                  = 204, 
    connection_fail                    = 205, 
    ap_tsf_reset                       = 206, 
    roaming                            = 207, 
    assoc_comeback_time_too_long       = 208, 
    sa_query_timeout                   = 209, 
    no_ap_found_w_compatible_security  = 210, 
    no_ap_found_in_authmode_threshold  = 211, 
    no_ap_found_in_rssi_threshold      = 212, 
    // clang-format on
};
 
enum class cipher_type : int {
    // clang-format off
    none        = 0,  
    wep40       = 1,  
    wep104      = 2,  
    tkip        = 3,  
    ccmp        = 4,  
    tkip_ccmp   = 5,  
    aes_cmac128 = 6,  
    sms4        = 7,  
    gcmp        = 8,  
    gcmp256     = 9,  
    aes_gmac128 = 10, 
    aes_gmac256 = 11, 
    unknown     = 12, 
    // clang-format on
};
 
enum class phy_mode : int {
    // clang-format off
    lr    = 0, 
    b11b  = 1, 
    b11g  = 2, 
    b11a  = 3, 
    ht20  = 4, 
    ht40  = 5, 
    he20  = 6, 
    vht20 = 7, 
    // clang-format on
};
 
enum class band : int {
    // clang-format off
    ghz_2g = 1, 
    ghz_5g = 2, 
    // clang-format on
};
 
enum class band_mode : int {
    // clang-format off
    ghz_2g_only = 1, 
    ghz_5g_only = 2, 
    auto_mode   = 3, 
    // clang-format on
};
 
enum class channel_5g : uint32_t {
    // clang-format off
    ch36  = 1u << 1,  
    ch40  = 1u << 2,  
    ch44  = 1u << 3,  
    ch48  = 1u << 4,  
    ch52  = 1u << 5,  
    ch56  = 1u << 6,  
    ch60  = 1u << 7,  
    ch64  = 1u << 8,  
    ch100 = 1u << 9,  
    ch104 = 1u << 10, 
    ch108 = 1u << 11, 
    ch112 = 1u << 12, 
    ch116 = 1u << 13, 
    ch120 = 1u << 14, 
    ch124 = 1u << 15, 
    ch128 = 1u << 16, 
    ch132 = 1u << 17, 
    ch136 = 1u << 18, 
    ch140 = 1u << 19, 
    ch144 = 1u << 20, 
    ch149 = 1u << 21, 
    ch153 = 1u << 22, 
    ch157 = 1u << 23, 
    ch161 = 1u << 24, 
    ch165 = 1u << 25, 
    ch169 = 1u << 26, 
    ch173 = 1u << 27, 
    ch177 = 1u << 28, 
    all   = 0x1FFFFFFE, 
    // clang-format on
};
 
enum class storage : int {
    // clang-format off
    flash = 0, 
    ram   = 1, 
    // clang-format on
};
 
enum class country_policy : int {
    // clang-format off
    auto_policy = 0, 
    manual      = 1, 
    // clang-format on
};
 
enum class scan_method : int {
    // clang-format off
    fast        = 0, 
    all_channel = 1, 
    // clang-format on
};
 
enum class sae_pwe_method : int {
    // clang-format off
    hunt_and_peck   = 1, 
    hash_to_element = 2, 
    // clang-format on
};
 
enum class sae_pk_mode : int {
    // clang-format off
    automatic = 0, 
    only      = 1, 
    disabled  = 2, 
    // clang-format on
};
 
enum class protocol : uint8_t {
    // clang-format off
    b11b  = 0x01, 
    b11g  = 0x02, 
    b11n  = 0x04, 
    lr    = 0x08, 
    b11a  = 0x10, 
    b11ac = 0x20, 
    b11ax = 0x40, 
    // clang-format on
};
 
enum class promiscuous_pkt_type : int {
    // clang-format off
    mgmt = 0, 
    ctrl = 1, 
    data = 2, 
    misc = 3, 
    // clang-format on
};
 
enum class promiscuous_filter : uint32_t {
    // clang-format off
    all        = 0xFFFFFFFF, 
    mgmt       = 1u << 0,   
    ctrl       = 1u << 1,   
    data       = 1u << 2,   
    misc       = 1u << 3,   
    data_mpdu  = 1u << 4,   
    data_ampdu = 1u << 5,   
    fcsfail    = 1u << 6,   
    // clang-format on
};
 
enum class promiscuous_ctrl_filter : uint32_t {
    // clang-format off
    all     = 0xFF800000,  
    wrapper = 1u << 23,    
    bar     = 1u << 24,    
    ba      = 1u << 25,    
    pspoll  = 1u << 26,    
    rts     = 1u << 27,    
    cts     = 1u << 28,    
    ack     = 1u << 29,    
    cfend   = 1u << 30,    
    cfendack = 1u << 31,   
    // clang-format on
};
 
enum class event_mask : uint32_t {
    // clang-format off
    all              = 0xFFFFFFFF, 
    none             = 0,          
    ap_probe_req_rx  = 1u << 0,   
    // clang-format on
};
 
enum class statis_module : uint32_t {
    // clang-format off
    buffer = 1u << 0,      
    rxtx   = 1u << 1,      
    hw     = 1u << 2,      
    diag   = 1u << 3,      
    ps     = 1u << 4,      
    all    = 0xFFFFFFFF,   
    // clang-format on
};
 
enum class vendor_ie_type : int {
    // clang-format off
    beacon     = 0, 
    probe_req  = 1, 
    probe_resp = 2, 
    assoc_req  = 3, 
    assoc_resp = 4, 
    // clang-format on
};
 
enum class vendor_ie_id : int {
    // clang-format off
    id_0 = 0, 
    id_1 = 1, 
    // clang-format on
};
 
enum class ftm_status : int {
    // clang-format off
    success        = 0, 
    unsupported    = 1, 
    conf_rejected  = 2, 
    no_response    = 3, 
    fail           = 4, 
    no_valid_msmt  = 5, 
    user_term      = 6, 
    // clang-format on
};
 
enum class phy_rate : int {
    // clang-format off
    // 802.11b long preamble
    rate_1m_l  = 0x00, 
    rate_2m_l  = 0x01, 
    rate_5m_l  = 0x02, 
    rate_11m_l = 0x03, 
    // 802.11b short preamble
    rate_2m_s  = 0x05, 
    rate_5m_s  = 0x06, 
    rate_11m_s = 0x07, 
    // OFDM (802.11a/g)
    rate_48m = 0x08, 
    rate_24m = 0x09, 
    rate_12m = 0x0A, 
    rate_6m  = 0x0B, 
    rate_54m = 0x0C, 
    rate_36m = 0x0D, 
    rate_18m = 0x0E, 
    rate_9m  = 0x0F, 
    // HT (802.11n) long GI
    mcs0_lgi = 0x10, 
    mcs1_lgi = 0x11, 
    mcs2_lgi = 0x12, 
    mcs3_lgi = 0x13, 
    mcs4_lgi = 0x14, 
    mcs5_lgi = 0x15, 
    mcs6_lgi = 0x16, 
    mcs7_lgi = 0x17, 
#if SOC_WIFI_HE_SUPPORT
    mcs8_lgi = 0x18, 
    mcs9_lgi = 0x19, 
#endif
    // HT (802.11n) short GI
#if SOC_WIFI_HE_SUPPORT
    mcs0_sgi = 0x1A, 
#else
    mcs0_sgi = 0x18, 
#endif
    mcs1_sgi = mcs0_sgi + 1, 
    mcs2_sgi = mcs0_sgi + 2, 
    mcs3_sgi = mcs0_sgi + 3, 
    mcs4_sgi = mcs0_sgi + 4, 
    mcs5_sgi = mcs0_sgi + 5, 
    mcs6_sgi = mcs0_sgi + 6, 
    mcs7_sgi = mcs0_sgi + 7, 
#if SOC_WIFI_HE_SUPPORT
    mcs8_sgi = mcs0_sgi + 8, 
    mcs9_sgi = mcs0_sgi + 9, 
#endif
    // Long Range (Espressif proprietary)
    lora_250k = 0x29, 
    lora_500k = 0x2A, 
    // clang-format on
};
 
} // namespace idfxx::wifi
 
template<>
inline constexpr bool idfxx::enable_flags_operators<idfxx::wifi::role> = true;
template<>
inline constexpr bool idfxx::enable_flags_operators<idfxx::wifi::protocol> = true;
template<>
inline constexpr bool idfxx::enable_flags_operators<idfxx::wifi::promiscuous_filter> = true;
template<>
inline constexpr bool idfxx::enable_flags_operators<idfxx::wifi::promiscuous_ctrl_filter> = true;
template<>
inline constexpr bool idfxx::enable_flags_operators<idfxx::wifi::channel_5g> = true;
template<>
inline constexpr bool idfxx::enable_flags_operators<idfxx::wifi::event_mask> = true;
template<>
inline constexpr bool idfxx::enable_flags_operators<idfxx::wifi::sae_pwe_method> = true;
template<>
inline constexpr bool idfxx::enable_flags_operators<idfxx::wifi::statis_module> = true;
namespace idfxx::wifi {
 
// =============================================================================
// Error handling
// =============================================================================
 
enum class errc : esp_err_t {
    // clang-format off
    // ----- 0x3001..0x301C — ESP_ERR_WIFI_* aliases -----
    not_init            = 0x3001, 
    not_started         = 0x3002, 
    not_stopped         = 0x3003, 
    if_error            = 0x3004, 
    mode                = 0x3005, 
    state               = 0x3006, 
    conn                = 0x3007, 
    nvs                 = 0x3008, 
    mac                 = 0x3009, 
    ssid                = 0x300A, 
    password            = 0x300B, 
    timeout             = 0x300C, 
    wake_fail           = 0x300D, 
    would_block         = 0x300E, 
    not_connect         = 0x300F, 
    post                = 0x3012, 
    init_state          = 0x3013, 
    stop_state          = 0x3014, 
    not_assoc           = 0x3015, 
    tx_disallow         = 0x3016, 
    twt_full            = 0x3017, 
    twt_setup_timeout   = 0x3018, 
    twt_setup_txfail    = 0x3019, 
    twt_setup_reject    = 0x301A, 
    discard             = 0x301B, 
    roc_in_progress     = 0x301C, 
    // ----- idfxx-only validation codes (no ESP-IDF counterpart) -----
    value_too_large     = 1,      
    // clang-format on
};
 
class error_category : public std::error_category {
public:
    [[nodiscard]] const char* name() const noexcept override final;
 
    [[nodiscard]] std::string message(int ec) const override final;
 
    [[nodiscard]] bool equivalent(int code, const std::error_condition& condition) const noexcept override final;
};
 
// =============================================================================
// Data types
// =============================================================================
 
struct he_ap_info {
    uint8_t bss_color;       
    bool partial_bss_color;  
    bool bss_color_disabled; 
    uint8_t bssid_index;     
    [[nodiscard]] constexpr bool operator==(const he_ap_info&) const noexcept = default;
};
 
struct country_config {
    std::array<char, 3> cc = {'0', '1', '\0'};                
    uint8_t start_channel = 1;                                
    uint8_t num_channels = 11;                                
    electro::dbm max_tx_power{20};                            
    enum country_policy policy = country_policy::auto_policy; 
#if SOC_WIFI_SUPPORT_5G
    flags<channel_5g> channels_5g{}; 
#endif
 
    [[nodiscard]] constexpr bool operator==(const country_config&) const noexcept = default;
};
 
struct ap_record {
    mac_address bssid;                         
    std::string ssid;                          
    electro::dbm rssi;                         
    uint8_t primary_channel;                   
    std::optional<enum second_channel> second; 
    enum auth_mode authmode;                   
    enum cipher_type pairwise_cipher;          
    enum cipher_type group_cipher;             
    bool phy_11b;                              
    bool phy_11g;                              
    bool phy_11n;                              
    bool phy_lr;                               
    bool phy_11a;                              
    bool phy_11ac;                             
    bool phy_11ax;                             
    bool wps;                                  
    bool ftm_responder;                        
    bool ftm_initiator;                        
    struct country_config country;             
    struct he_ap_info he_ap;                   
    enum bandwidth bw;                         
    uint8_t vht_ch_freq1;                      
    uint8_t vht_ch_freq2;                      
    [[nodiscard]] bool operator==(const ap_record&) const = default;
};
 
struct sta_info {
    mac_address mac;   
    electro::dbm rssi; 
    bool phy_11b;      
    bool phy_11g;      
    bool phy_11n;      
    bool phy_lr;       
    bool phy_11a;      
    bool phy_11ac;     
    bool phy_11ax;     
    [[nodiscard]] constexpr bool operator==(const sta_info&) const noexcept = default;
};
 
struct ftm_report_entry {
    uint8_t dlog_token; 
    electro::dbm rssi;  
    uint32_t rtt;       
    uint64_t t1;        
    uint64_t t2;        
    uint64_t t3;        
    uint64_t t4;        
    [[nodiscard]] constexpr bool operator==(const ftm_report_entry&) const noexcept = default;
};
 
// =============================================================================
// Configuration structs
// =============================================================================
 
struct init_config {
    std::optional<unsigned int> static_rx_buf_num;  
    std::optional<unsigned int> dynamic_rx_buf_num; 
    std::optional<unsigned int> static_tx_buf_num;  
    std::optional<unsigned int> dynamic_tx_buf_num; 
    std::optional<unsigned int> cache_tx_buf_num;   
    std::optional<unsigned int> rx_ba_win;          
    std::optional<bool> ampdu_rx_enable;            
    std::optional<bool> ampdu_tx_enable;            
    std::optional<bool> nvs_enable;                 
    std::optional<core_id> wifi_task_core_id;       
    [[nodiscard]] constexpr bool operator==(const init_config&) const noexcept = default;
};
 
struct pmf_config {
    bool capable = false;  
    bool required = false; 
    [[nodiscard]] constexpr bool operator==(const pmf_config&) const noexcept = default;
};
 
struct sta_config {
    std::string ssid;                                      
    std::string password;                                  
    std::optional<mac_address> bssid = {};                 
    uint8_t channel = 0;                                   
    enum scan_method scan_method = scan_method::fast;      
    enum sort_method sort_method = sort_method::by_rssi;   
    enum auth_mode auth_threshold = auth_mode::open;       
    electro::dbm rssi_threshold{-127};                     
    struct pmf_config pmf = {};                            
    uint16_t listen_interval = 0;                          
    bool rm_enabled = false;                               
    bool btm_enabled = false;                              
    bool mbo_enabled = false;                              
    bool ft_enabled = false;                               
    bool owe_enabled = false;                              
    bool transition_disable = false;                       
    flags<sae_pwe_method> sae_pwe_h2e = {};                
    enum sae_pk_mode sae_pk_mode = sae_pk_mode::automatic; 
    uint8_t failure_retry_cnt = 0;                         
    [[nodiscard]] bool operator==(const sta_config&) const = default;
};
 
struct ap_config {
    std::string ssid;                                          
    std::string password;                                      
    uint8_t channel = 1;                                       
    enum auth_mode authmode = auth_mode::open;                 
    uint8_t ssid_hidden = 0;                                   
    uint8_t max_connection = 4;                                
    uint16_t beacon_interval = 100;                            
    enum cipher_type pairwise_cipher = cipher_type::tkip_ccmp; 
    bool ftm_responder = false;                                
    struct pmf_config pmf = {};                                
    flags<sae_pwe_method> sae_pwe_h2e = {};                    
    [[nodiscard]] bool operator==(const ap_config&) const = default;
};
 
struct scan_config {
    std::string ssid;                             
    uint8_t channel = 0;                          
    bool show_hidden = false;                     
    enum scan_type scan_type = scan_type::active; 
    [[nodiscard]] bool operator==(const scan_config&) const = default;
};
 
struct scan_default_params {
    std::chrono::milliseconds active_scan_min{0};       
    std::chrono::milliseconds active_scan_max{120};     
    std::chrono::milliseconds passive_scan{360};        
    std::chrono::milliseconds home_chan_dwell_time{30}; 
    [[nodiscard]] constexpr bool operator==(const scan_default_params&) const noexcept = default;
};
 
struct protocols_config {
    flags<protocol> ghz_2g; 
    flags<protocol> ghz_5g; 
    [[nodiscard]] constexpr bool operator==(const protocols_config&) const noexcept = default;
};
 
struct bandwidths_config {
    enum bandwidth ghz_2g = bandwidth::ht20; 
    enum bandwidth ghz_5g = bandwidth::ht20; 
    [[nodiscard]] constexpr bool operator==(const bandwidths_config&) const noexcept = default;
};
 
struct channel_info {
    uint8_t primary;                           
    std::optional<enum second_channel> second; 
    [[nodiscard]] constexpr bool operator==(const channel_info&) const noexcept = default;
};
 
struct ftm_initiator_config {
    mac_address resp_mac;    
    uint8_t channel = 0;     
    uint8_t frame_count = 0; 
    std::chrono::milliseconds burst_period{
        0
    }; 
#if ESP_IDF_VERSION < ESP_IDF_VERSION_VAL(6, 0, 0)
    bool use_get_report_api = false; 
#endif
 
    [[nodiscard]] constexpr bool operator==(const ftm_initiator_config&) const noexcept = default;
};
 
#if !SOC_WIFI_HE_SUPPORT
struct csi_config {
    bool lltf_en = true;           
    bool htltf_en = true;          
    bool stbc_htltf2_en = true;    
    bool ltf_merge_en = true;      
    bool channel_filter_en = true; 
    bool manu_scale = false;       
    uint8_t shift = 0;             
    bool dump_ack_en = false;      
    [[nodiscard]] constexpr bool operator==(const csi_config&) const noexcept = default;
};
#elif SOC_WIFI_MAC_VERSION_NUM == 3
struct csi_config {
    bool enable = false;                  
    bool acquire_csi_legacy = false;      
    bool acquire_csi_force_lltf = false;  
    bool acquire_csi_ht20 = false;        
    bool acquire_csi_ht40 = false;        
    bool acquire_csi_vht = false;         
    bool acquire_csi_su = false;          
    bool acquire_csi_mu = false;          
    bool acquire_csi_dcm = false;         
    bool acquire_csi_beamformed = false;  
    uint8_t acquire_csi_he_stbc_mode = 0; 
    uint8_t val_scale_cfg = 0;            
    bool dump_ack_en = false;             
    bool lltf_bit_mode = false;           
    [[nodiscard]] constexpr bool operator==(const csi_config&) const noexcept = default;
};
#else
struct csi_config {
    bool enable = false;                 
    bool acquire_csi_legacy = false;     
    bool acquire_csi_ht20 = false;       
    bool acquire_csi_ht40 = false;       
    bool acquire_csi_su = false;         
    bool acquire_csi_mu = false;         
    bool acquire_csi_dcm = false;        
    bool acquire_csi_beamformed = false; 
    uint8_t acquire_csi_he_stbc = 0;     
    uint8_t val_scale_cfg = 0;           
    bool dump_ack_en = false;            
    [[nodiscard]] constexpr bool operator==(const csi_config&) const noexcept = default;
};
#endif
 
// =============================================================================
// WiFi events
// =============================================================================
 
enum class event_id : int32_t {
    // clang-format off
    ready                                      = 0,  
    scan_done                                  = 1,  
    sta_start                                  = 2,  
    sta_stop                                   = 3,  
    sta_connected                              = 4,  
    sta_disconnected                           = 5,  
    sta_authmode_change                        = 6,  
    sta_wps_er_success                         = 7,  
    sta_wps_er_failed                          = 8,  
    sta_wps_er_timeout                         = 9,  
    sta_wps_er_pin                             = 10, 
    sta_wps_er_pbc_overlap                     = 11, 
    ap_start                                   = 12, 
    ap_stop                                    = 13, 
    ap_sta_connected                           = 14, 
    ap_sta_disconnected                        = 15, 
    ap_probe_req_received                      = 16, 
    ftm_report                                 = 17, 
    sta_bss_rssi_low                           = 18, 
    action_tx_status                           = 19, 
    roc_done                                   = 20, 
    sta_beacon_timeout                         = 21, 
    connectionless_module_wake_interval_start  = 22, 
    ap_wps_rg_success                          = 23, 
    ap_wps_rg_failed                           = 24, 
    ap_wps_rg_timeout                          = 25, 
    ap_wps_rg_pin                              = 26, 
    ap_wps_rg_pbc_overlap                      = 27, 
    itwt_setup                                 = 28, 
    itwt_teardown                              = 29, 
    itwt_probe                                 = 30, 
    itwt_suspend                               = 31, 
    twt_wakeup                                 = 32, 
    btwt_setup                                 = 33, 
    btwt_teardown                              = 34, 
    nan_started                                = 35, 
    nan_stopped                                = 36, 
    nan_svc_match                              = 37, 
    nan_replied                                = 38, 
    nan_receive                                = 39, 
    ndp_indication                             = 40, 
    ndp_confirm                                = 41, 
    ndp_terminated                             = 42, 
    home_channel_change                        = 43, 
    sta_neighbor_rep                           = 44, 
    ap_wrong_password                          = 45, 
    sta_beacon_offset_unstable                 = 46, 
    dpp_uri_ready                              = 47, 
    dpp_cfg_recvd                              = 48, 
    dpp_failed                                 = 49, 
    // clang-format on
};
 
extern const event_base<event_id> events;
 
inline event_base<event_id> idfxx_get_event_base(event_id*) {
    return events;
}
// =============================================================================
// Event data wrappers
// =============================================================================
 
struct connected_event_data {
    mac_address bssid;       
    std::string ssid;        
    uint8_t channel;         
    enum auth_mode authmode; 
    static connected_event_data from_opaque(const void* event_data);
 
    [[nodiscard]] bool operator==(const connected_event_data&) const = default;
};
 
struct disconnected_event_data {
    mac_address bssid;             
    std::string ssid;              
    enum disconnect_reason reason; 
    static disconnected_event_data from_opaque(const void* event_data);
 
    [[nodiscard]] bool operator==(const disconnected_event_data&) const = default;
};
 
struct scan_done_event_data {
    uint32_t status; 
    uint8_t number;  
    uint8_t scan_id; 
    static scan_done_event_data from_opaque(const void* event_data);
 
    [[nodiscard]] constexpr bool operator==(const scan_done_event_data&) const noexcept = default;
};
 
struct authmode_change_event_data {
    enum auth_mode old_mode; 
    enum auth_mode new_mode; 
    static authmode_change_event_data from_opaque(const void* event_data);
 
    [[nodiscard]] constexpr bool operator==(const authmode_change_event_data&) const noexcept = default;
};
 
struct ap_sta_connected_event_data {
    mac_address mac; 
    uint8_t aid;     
    static ap_sta_connected_event_data from_opaque(const void* event_data);
 
    [[nodiscard]] constexpr bool operator==(const ap_sta_connected_event_data&) const noexcept = default;
};
 
struct ap_sta_disconnected_event_data {
    mac_address mac;               
    uint8_t aid;                   
    enum disconnect_reason reason; 
    static ap_sta_disconnected_event_data from_opaque(const void* event_data);
 
    [[nodiscard]] constexpr bool operator==(const ap_sta_disconnected_event_data&) const noexcept = default;
};
 
struct ap_probe_req_event_data {
    electro::dbm rssi; 
    mac_address mac;   
    static ap_probe_req_event_data from_opaque(const void* event_data);
 
    [[nodiscard]] constexpr bool operator==(const ap_probe_req_event_data&) const noexcept = default;
};
 
struct bss_rssi_low_event_data {
    electro::dbm rssi; 
    static bss_rssi_low_event_data from_opaque(const void* event_data);
 
    [[nodiscard]] constexpr bool operator==(const bss_rssi_low_event_data&) const noexcept = default;
};
 
struct home_channel_change_event_data {
    uint8_t old_primary;                           
    std::optional<enum second_channel> old_second; 
    uint8_t new_primary;                           
    std::optional<enum second_channel> new_second; 
    static home_channel_change_event_data from_opaque(const void* event_data);
 
    [[nodiscard]] constexpr bool operator==(const home_channel_change_event_data&) const noexcept = default;
};
 
struct ftm_report_event_data {
    mac_address peer_mac;                  
    enum ftm_status status;                
    uint32_t rtt_raw;                      
    uint32_t rtt_est;                      
    uint32_t dist_est;                     
    std::vector<ftm_report_entry> entries; 
    static ftm_report_event_data from_opaque(const void* event_data);
 
    [[nodiscard]] bool operator==(const ftm_report_event_data&) const = default;
};
 
// =============================================================================
// Typed events
// =============================================================================
 
// WiFi events with data
inline constexpr idfxx::event<event_id, connected_event_data> sta_connected{event_id::sta_connected};
inline constexpr idfxx::event<event_id, disconnected_event_data> sta_disconnected{event_id::sta_disconnected};
inline constexpr idfxx::event<event_id, scan_done_event_data> scan_done{event_id::scan_done};
inline constexpr idfxx::event<event_id, authmode_change_event_data> sta_authmode_change{event_id::sta_authmode_change};
inline constexpr idfxx::event<event_id, ap_sta_connected_event_data> ap_sta_connected{event_id::ap_sta_connected};
inline constexpr idfxx::event<event_id, ap_sta_disconnected_event_data> ap_sta_disconnected{
    event_id::ap_sta_disconnected
};
inline constexpr idfxx::event<event_id, ap_probe_req_event_data> ap_probe_req_received{event_id::ap_probe_req_received};
inline constexpr idfxx::event<event_id, bss_rssi_low_event_data> sta_bss_rssi_low{event_id::sta_bss_rssi_low};
inline constexpr idfxx::event<event_id, home_channel_change_event_data> home_channel_change{
    event_id::home_channel_change
};
inline constexpr idfxx::event<event_id, ftm_report_event_data> ftm_report{event_id::ftm_report};
 
// WiFi events without data
inline constexpr idfxx::event<event_id> ready{event_id::ready};
inline constexpr idfxx::event<event_id> sta_start{event_id::sta_start};
inline constexpr idfxx::event<event_id> sta_stop{event_id::sta_stop};
inline constexpr idfxx::event<event_id> ap_start{event_id::ap_start};
inline constexpr idfxx::event<event_id> ap_stop{event_id::ap_stop};
inline constexpr idfxx::event<event_id> sta_beacon_timeout{event_id::sta_beacon_timeout};
inline constexpr idfxx::event<event_id> sta_wps_er_success{event_id::sta_wps_er_success};
inline constexpr idfxx::event<event_id> sta_wps_er_failed{event_id::sta_wps_er_failed};
inline constexpr idfxx::event<event_id> sta_wps_er_timeout{event_id::sta_wps_er_timeout};
inline constexpr idfxx::event<event_id> sta_wps_er_pin{event_id::sta_wps_er_pin};
inline constexpr idfxx::event<event_id> sta_wps_er_pbc_overlap{event_id::sta_wps_er_pbc_overlap};
inline constexpr idfxx::event<event_id> action_tx_status{event_id::action_tx_status};
inline constexpr idfxx::event<event_id> roc_done{event_id::roc_done};
inline constexpr idfxx::event<event_id> connectionless_module_wake_interval_start{
    event_id::connectionless_module_wake_interval_start
};
inline constexpr idfxx::event<event_id> ap_wps_rg_success{event_id::ap_wps_rg_success};
inline constexpr idfxx::event<event_id> ap_wps_rg_failed{event_id::ap_wps_rg_failed};
inline constexpr idfxx::event<event_id> ap_wps_rg_timeout{event_id::ap_wps_rg_timeout};
inline constexpr idfxx::event<event_id> ap_wps_rg_pin{event_id::ap_wps_rg_pin};
inline constexpr idfxx::event<event_id> ap_wps_rg_pbc_overlap{event_id::ap_wps_rg_pbc_overlap};
inline constexpr idfxx::event<event_id> itwt_setup{event_id::itwt_setup};
inline constexpr idfxx::event<event_id> itwt_teardown{event_id::itwt_teardown};
inline constexpr idfxx::event<event_id> itwt_probe{event_id::itwt_probe};
inline constexpr idfxx::event<event_id> itwt_suspend{event_id::itwt_suspend};
inline constexpr idfxx::event<event_id> twt_wakeup{event_id::twt_wakeup};
inline constexpr idfxx::event<event_id> btwt_setup{event_id::btwt_setup};
inline constexpr idfxx::event<event_id> btwt_teardown{event_id::btwt_teardown};
inline constexpr idfxx::event<event_id> nan_started{event_id::nan_started};
inline constexpr idfxx::event<event_id> nan_stopped{event_id::nan_stopped};
inline constexpr idfxx::event<event_id> nan_svc_match{event_id::nan_svc_match};
inline constexpr idfxx::event<event_id> nan_replied{event_id::nan_replied};
inline constexpr idfxx::event<event_id> nan_receive{event_id::nan_receive};
inline constexpr idfxx::event<event_id> ndp_indication{event_id::ndp_indication};
inline constexpr idfxx::event<event_id> ndp_confirm{event_id::ndp_confirm};
inline constexpr idfxx::event<event_id> ndp_terminated{event_id::ndp_terminated};
inline constexpr idfxx::event<event_id> sta_neighbor_rep{event_id::sta_neighbor_rep};
inline constexpr idfxx::event<event_id> ap_wrong_password{event_id::ap_wrong_password};
inline constexpr idfxx::event<event_id> sta_beacon_offset_unstable{event_id::sta_beacon_offset_unstable};
inline constexpr idfxx::event<event_id> dpp_uri_ready{event_id::dpp_uri_ready};
inline constexpr idfxx::event<event_id> dpp_cfg_recvd{event_id::dpp_cfg_recvd};
inline constexpr idfxx::event<event_id> dpp_failed{event_id::dpp_failed};
 
// =============================================================================
// Free function API — Lifecycle
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void init(const init_config& cfg = {});
 
void deinit();
 
void start();
 
void stop();
 
void restore();
#endif
 
[[nodiscard]] result<void> try_init(const init_config& cfg = {});
 
result<void> try_deinit();
 
[[nodiscard]] result<void> try_start();
 
result<void> try_stop();
 
[[nodiscard]] result<void> try_restore();
 
// =============================================================================
// Free function API — Roles
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void set_roles(flags<role> roles);
 
[[nodiscard]] flags<role> get_roles();
#endif
 
[[nodiscard]] result<void> try_set_roles(flags<role> roles);
 
[[nodiscard]] result<flags<role>> try_get_roles();
 
// =============================================================================
// Free function API — STA config
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void set_sta_config(const sta_config& cfg);
 
[[nodiscard]] sta_config get_sta_config();
#endif
 
[[nodiscard]] result<void> try_set_sta_config(const sta_config& cfg);
 
[[nodiscard]] result<sta_config> try_get_sta_config();
 
// =============================================================================
// Free function API — AP config
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void set_ap_config(const ap_config& cfg);
 
[[nodiscard]] ap_config get_ap_config();
 
void deauth_sta(uint16_t aid);
 
[[nodiscard]] std::vector<sta_info> get_sta_list();
 
[[nodiscard]] uint16_t ap_get_sta_aid(mac_address mac);
#endif
 
[[nodiscard]] result<void> try_set_ap_config(const ap_config& cfg);
 
[[nodiscard]] result<ap_config> try_get_ap_config();
 
[[nodiscard]] result<void> try_deauth_sta(uint16_t aid);
 
[[nodiscard]] result<std::vector<sta_info>> try_get_sta_list();
 
[[nodiscard]] result<uint16_t> try_ap_get_sta_aid(mac_address mac);
 
// =============================================================================
// Free function API — Connect / disconnect
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void connect();
 
template<typename Rep, typename Period>
[[nodiscard]] net::ipv4_info connect_sta(const sta_config& cfg, std::chrono::duration<Rep, Period> timeout);
 
void disconnect();
 
void clear_fast_connect();
 
[[nodiscard]] uint16_t sta_get_aid();
 
[[nodiscard]] enum phy_mode get_negotiated_phymode();
#endif
 
[[nodiscard]] result<void> try_connect();
 
[[nodiscard]] result<net::ipv4_info> try_connect_sta(const sta_config& cfg, std::chrono::milliseconds timeout);
 
template<typename Rep, typename Period>
[[nodiscard]] result<net::ipv4_info>
try_connect_sta(const sta_config& cfg, std::chrono::duration<Rep, Period> timeout) {
    return try_connect_sta(cfg, std::chrono::ceil<std::chrono::milliseconds>(timeout));
}
 
result<void> try_disconnect();
 
result<void> try_clear_fast_connect();
 
[[nodiscard]] result<uint16_t> try_sta_get_aid();
 
[[nodiscard]] result<enum phy_mode> try_get_negotiated_phymode();
 
// =============================================================================
// Free function API — Scanning
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
[[nodiscard]] std::vector<ap_record> scan(const scan_config& cfg = {});
 
void scan_start(const scan_config& cfg = {});
 
[[nodiscard]] std::vector<ap_record> scan_get_results();
 
void scan_stop();
 
[[nodiscard]] uint16_t scan_get_ap_num();
 
void clear_ap_list();
 
void set_scan_parameters(const scan_default_params& params);
 
[[nodiscard]] scan_default_params get_scan_parameters();
#endif
 
[[nodiscard]] result<std::vector<ap_record>> try_scan(const scan_config& cfg = {});
 
[[nodiscard]] result<void> try_scan_start(const scan_config& cfg = {});
 
[[nodiscard]] result<std::vector<ap_record>> try_scan_get_results();
 
result<void> try_scan_stop();
 
[[nodiscard]] result<uint16_t> try_scan_get_ap_num();
 
result<void> try_clear_ap_list();
 
[[nodiscard]] result<void> try_set_scan_parameters(const scan_default_params& params);
 
[[nodiscard]] result<scan_default_params> try_get_scan_parameters();
 
// =============================================================================
// Free function API — Power save
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void set_power_save(enum power_save ps);
 
[[nodiscard]] enum power_save get_power_save();
#endif
 
[[nodiscard]] result<void> try_set_power_save(enum power_save ps);
 
[[nodiscard]] result<enum power_save> try_get_power_save();
 
// =============================================================================
// Free function API — Bandwidth
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void set_bandwidth(enum role iface, enum bandwidth bw);
 
[[nodiscard]] enum bandwidth get_bandwidth(enum role iface);
 
void set_bandwidths(enum role iface, const bandwidths_config& bw);
 
[[nodiscard]] bandwidths_config get_bandwidths(enum role iface);
#endif
 
[[nodiscard]] result<void> try_set_bandwidth(enum role iface, enum bandwidth bw);
 
[[nodiscard]] result<enum bandwidth> try_get_bandwidth(enum role iface);
 
[[nodiscard]] result<void> try_set_bandwidths(enum role iface, const bandwidths_config& bw);
 
[[nodiscard]] result<bandwidths_config> try_get_bandwidths(enum role iface);
 
// =============================================================================
// Free function API — MAC
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void set_mac(enum role iface, mac_address mac);
 
[[nodiscard]] mac_address get_mac(enum role iface);
#endif
 
[[nodiscard]] result<void> try_set_mac(enum role iface, mac_address mac);
 
[[nodiscard]] result<mac_address> try_get_mac(enum role iface);
 
// =============================================================================
// Free function API — AP info
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
[[nodiscard]] ap_record get_ap_info();
#endif
 
[[nodiscard]] result<ap_record> try_get_ap_info();
 
// =============================================================================
// Free function API — Channel
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void set_channel(uint8_t primary, std::optional<enum second_channel> second = std::nullopt);
 
[[nodiscard]] channel_info get_channel();
#endif
 
[[nodiscard]] result<void> try_set_channel(uint8_t primary, std::optional<enum second_channel> second = std::nullopt);
 
[[nodiscard]] result<channel_info> try_get_channel();
 
// =============================================================================
// Free function API — Country
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void set_country(const country_config& cfg);
 
[[nodiscard]] country_config get_country();
 
void set_country_code(std::string_view cc, bool ieee80211d_enabled);
 
[[nodiscard]] std::string get_country_code();
#endif
 
[[nodiscard]] result<void> try_set_country(const country_config& cfg);
 
[[nodiscard]] result<country_config> try_get_country();
 
[[nodiscard]] result<void> try_set_country_code(std::string_view cc, bool ieee80211d_enabled);
 
[[nodiscard]] result<std::string> try_get_country_code();
 
// =============================================================================
// Free function API — TX power
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void set_max_tx_power(electro::centi_dbm power);
 
[[nodiscard]] electro::centi_dbm get_max_tx_power();
#endif
 
[[nodiscard]] result<void> try_set_max_tx_power(electro::centi_dbm power);
 
[[nodiscard]] result<electro::centi_dbm> try_get_max_tx_power();
 
// =============================================================================
// Free function API — RSSI
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void set_rssi_threshold(electro::dbm threshold);
 
[[nodiscard]] electro::dbm get_rssi();
#endif
 
[[nodiscard]] result<void> try_set_rssi_threshold(electro::dbm threshold);
 
[[nodiscard]] result<electro::dbm> try_get_rssi();
 
// =============================================================================
// Free function API — Protocol
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void set_protocol(enum role iface, flags<protocol> protos);
 
[[nodiscard]] flags<protocol> get_protocol(enum role iface);
 
void set_protocols(enum role iface, const protocols_config& cfg);
 
[[nodiscard]] protocols_config get_protocols(enum role iface);
#endif
 
[[nodiscard]] result<void> try_set_protocol(enum role iface, flags<protocol> protos);
 
[[nodiscard]] result<flags<protocol>> try_get_protocol(enum role iface);
 
[[nodiscard]] result<void> try_set_protocols(enum role iface, const protocols_config& cfg);
 
[[nodiscard]] result<protocols_config> try_get_protocols(enum role iface);
 
// =============================================================================
// Free function API — Band
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void set_band(enum band b);
 
[[nodiscard]] enum band get_band();
 
void set_band_mode(enum band_mode m);
 
[[nodiscard]] enum band_mode get_band_mode();
#endif
 
[[nodiscard]] result<void> try_set_band(enum band b);
 
[[nodiscard]] result<enum band> try_get_band();
 
[[nodiscard]] result<void> try_set_band_mode(enum band_mode m);
 
[[nodiscard]] result<enum band_mode> try_get_band_mode();
 
// =============================================================================
// Free function API — Storage
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void set_storage(enum storage s);
#endif
 
[[nodiscard]] result<void> try_set_storage(enum storage s);
 
// =============================================================================
// Free function API — Inactive time
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void set_inactive_time(enum role iface, std::chrono::seconds timeout);
 
[[nodiscard]] std::chrono::seconds get_inactive_time(enum role iface);
#endif
 
[[nodiscard]] result<void> try_set_inactive_time(enum role iface, std::chrono::seconds timeout);
 
[[nodiscard]] result<std::chrono::seconds> try_get_inactive_time(enum role iface);
 
// =============================================================================
// Free function API — Event mask
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void set_event_mask(flags<event_mask> mask);
 
[[nodiscard]] flags<event_mask> get_event_mask();
#endif
 
[[nodiscard]] result<void> try_set_event_mask(flags<event_mask> mask);
 
[[nodiscard]] result<flags<event_mask>> try_get_event_mask();
 
// =============================================================================
// Free function API — Force wakeup
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void force_wakeup_acquire();
 
void force_wakeup_release();
#endif
 
[[nodiscard]] result<void> try_force_wakeup_acquire();
 
result<void> try_force_wakeup_release();
 
// =============================================================================
// Free function API — Promiscuous mode
// =============================================================================
 
using promiscuous_rx_cb = void (*)(const wifi_promiscuous_pkt_t* pkt, promiscuous_pkt_type type);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void set_promiscuous(bool en);
 
[[nodiscard]] bool get_promiscuous();
 
void set_promiscuous_rx_cb(promiscuous_rx_cb cb);
 
void set_promiscuous_filter(flags<promiscuous_filter> filter);
 
[[nodiscard]] flags<promiscuous_filter> get_promiscuous_filter();
 
void set_promiscuous_ctrl_filter(flags<promiscuous_ctrl_filter> filter);
 
[[nodiscard]] flags<promiscuous_ctrl_filter> get_promiscuous_ctrl_filter();
#endif
 
[[nodiscard]] result<void> try_set_promiscuous(bool en);
 
[[nodiscard]] result<bool> try_get_promiscuous();
 
[[nodiscard]] result<void> try_set_promiscuous_rx_cb(promiscuous_rx_cb cb);
 
[[nodiscard]] result<void> try_set_promiscuous_filter(flags<promiscuous_filter> filter);
 
[[nodiscard]] result<flags<promiscuous_filter>> try_get_promiscuous_filter();
 
[[nodiscard]] result<void> try_set_promiscuous_ctrl_filter(flags<promiscuous_ctrl_filter> filter);
 
[[nodiscard]] result<flags<promiscuous_ctrl_filter>> try_get_promiscuous_ctrl_filter();
 
// =============================================================================
// Free function API — Raw 802.11
// =============================================================================
 
using tx_80211_done_cb = void (*)(const esp_80211_tx_info_t* tx_info);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void tx_80211(enum role iface, std::span<const uint8_t> buffer, bool en_sys_seq);
 
void register_80211_tx_cb(tx_80211_done_cb cb);
#endif
 
[[nodiscard]] result<void> try_tx_80211(enum role iface, std::span<const uint8_t> buffer, bool en_sys_seq);
 
[[nodiscard]] result<void> try_register_80211_tx_cb(tx_80211_done_cb cb);
 
// =============================================================================
// Free function API — Vendor IE
// =============================================================================
 
using vendor_ie_cb =
    void (*)(void* ctx, enum vendor_ie_type type, mac_address sa, const vendor_ie_data_t* ie, electro::dbm rssi);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void set_vendor_ie(bool enable, enum vendor_ie_type type, enum vendor_ie_id id, const void* vnd_ie);
 
void set_vendor_ie_cb(vendor_ie_cb cb, void* ctx);
#endif
 
[[nodiscard]] result<void>
try_set_vendor_ie(bool enable, enum vendor_ie_type type, enum vendor_ie_id id, const void* vnd_ie);
 
[[nodiscard]] result<void> try_set_vendor_ie_cb(vendor_ie_cb cb, void* ctx);
 
// =============================================================================
// Free function API — CSI
// =============================================================================
 
using csi_rx_cb = void (*)(void* ctx, const wifi_csi_info_t* info);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void set_csi(bool en);
 
void set_csi_config(const csi_config& cfg);
 
[[nodiscard]] csi_config get_csi_config();
 
void set_csi_rx_cb(csi_rx_cb cb, void* ctx);
#endif
 
[[nodiscard]] result<void> try_set_csi(bool en);
 
[[nodiscard]] result<void> try_set_csi_config(const csi_config& cfg);
 
[[nodiscard]] result<csi_config> try_get_csi_config();
 
[[nodiscard]] result<void> try_set_csi_rx_cb(csi_rx_cb cb, void* ctx);
 
// =============================================================================
// Free function API — FTM
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void ftm_initiate_session(const ftm_initiator_config& cfg);
 
void ftm_end_session();
 
void ftm_resp_set_offset(int16_t offset);
 
[[nodiscard]] std::vector<ftm_report_entry> ftm_get_report(size_t max_entries);
#endif
 
[[nodiscard]] result<void> try_ftm_initiate_session(const ftm_initiator_config& cfg);
 
result<void> try_ftm_end_session();
 
[[nodiscard]] result<void> try_ftm_resp_set_offset(int16_t offset);
 
[[nodiscard]] result<std::vector<ftm_report_entry>> try_ftm_get_report(size_t max_entries);
 
// =============================================================================
// Free function API — Miscellaneous
// =============================================================================
 
[[nodiscard]] int64_t get_tsf_time(enum role iface);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void statis_dump(flags<statis_module> modules);
 
void config_11b_rate(enum role iface, bool disable);
 
void config_80211_tx_rate(enum role iface, enum phy_rate rate);
 
void disable_pmf_config(enum role iface);
 
void set_dynamic_cs(bool enabled);
 
void connectionless_module_set_wake_interval(std::chrono::milliseconds interval);
#endif
 
[[nodiscard]] result<void> try_statis_dump(flags<statis_module> modules);
 
[[nodiscard]] result<void> try_config_11b_rate(enum role iface, bool disable);
 
[[nodiscard]] result<void> try_config_80211_tx_rate(enum role iface, enum phy_rate rate);
 
[[nodiscard]] result<void> try_disable_pmf_config(enum role iface);
 
[[nodiscard]] result<void> try_set_dynamic_cs(bool enabled);
 
[[nodiscard]] result<void> try_connectionless_module_set_wake_interval(std::chrono::milliseconds interval);
 
// =============================================================================
// Inline definitions — exception-based API
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
 
// Lifecycle
inline void init(const init_config& cfg) {
    unwrap(try_init(cfg));
}
inline void deinit() {
    unwrap(try_deinit());
}
inline void start() {
    unwrap(try_start());
}
inline void stop() {
    unwrap(try_stop());
}
inline void restore() {
    unwrap(try_restore());
}
 
// Roles
inline void set_roles(flags<role> roles) {
    unwrap(try_set_roles(roles));
}
inline flags<role> get_roles() {
    return unwrap(try_get_roles());
}
 
// STA config
inline void set_sta_config(const sta_config& cfg) {
    unwrap(try_set_sta_config(cfg));
}
inline sta_config get_sta_config() {
    return unwrap(try_get_sta_config());
}
 
// AP config
inline void set_ap_config(const ap_config& cfg) {
    unwrap(try_set_ap_config(cfg));
}
inline ap_config get_ap_config() {
    return unwrap(try_get_ap_config());
}
inline void deauth_sta(uint16_t aid) {
    unwrap(try_deauth_sta(aid));
}
inline std::vector<sta_info> get_sta_list() {
    return unwrap(try_get_sta_list());
}
inline uint16_t ap_get_sta_aid(mac_address mac) {
    return unwrap(try_ap_get_sta_aid(mac));
}
 
// Connect / disconnect
template<typename Rep, typename Period>
[[nodiscard]] net::ipv4_info connect_sta(const sta_config& cfg, std::chrono::duration<Rep, Period> timeout) {
    return unwrap(try_connect_sta(cfg, std::chrono::ceil<std::chrono::milliseconds>(timeout)));
}
inline void connect() {
    unwrap(try_connect());
}
inline void disconnect() {
    unwrap(try_disconnect());
}
inline void clear_fast_connect() {
    unwrap(try_clear_fast_connect());
}
inline uint16_t sta_get_aid() {
    return unwrap(try_sta_get_aid());
}
inline enum phy_mode get_negotiated_phymode() {
    return unwrap(try_get_negotiated_phymode());
}
 
// Scanning
inline std::vector<ap_record> scan(const scan_config& cfg) {
    return unwrap(try_scan(cfg));
}
inline void scan_start(const scan_config& cfg) {
    unwrap(try_scan_start(cfg));
}
inline std::vector<ap_record> scan_get_results() {
    return unwrap(try_scan_get_results());
}
inline void scan_stop() {
    unwrap(try_scan_stop());
}
inline uint16_t scan_get_ap_num() {
    return unwrap(try_scan_get_ap_num());
}
inline void clear_ap_list() {
    unwrap(try_clear_ap_list());
}
inline void set_scan_parameters(const scan_default_params& params) {
    unwrap(try_set_scan_parameters(params));
}
inline scan_default_params get_scan_parameters() {
    return unwrap(try_get_scan_parameters());
}
 
// Power save
inline void set_power_save(enum power_save ps) {
    unwrap(try_set_power_save(ps));
}
inline enum power_save get_power_save() {
    return unwrap(try_get_power_save());
}
 
// Bandwidth
inline void set_bandwidth(enum role iface, enum bandwidth bw) {
    unwrap(try_set_bandwidth(iface, bw));
}
inline enum bandwidth get_bandwidth(enum role iface) {
    return unwrap(try_get_bandwidth(iface));
}
inline void set_bandwidths(enum role iface, const bandwidths_config& bw) {
    unwrap(try_set_bandwidths(iface, bw));
}
inline bandwidths_config get_bandwidths(enum role iface) {
    return unwrap(try_get_bandwidths(iface));
}
 
// MAC
inline void set_mac(enum role iface, mac_address mac) {
    unwrap(try_set_mac(iface, mac));
}
inline mac_address get_mac(enum role iface) {
    return unwrap(try_get_mac(iface));
}
 
// AP info
inline ap_record get_ap_info() {
    return unwrap(try_get_ap_info());
}
 
// Channel
inline void set_channel(uint8_t primary, std::optional<enum second_channel> second) {
    unwrap(try_set_channel(primary, second));
}
inline channel_info get_channel() {
    return unwrap(try_get_channel());
}
 
// Country
inline void set_country(const country_config& cfg) {
    unwrap(try_set_country(cfg));
}
inline country_config get_country() {
    return unwrap(try_get_country());
}
inline void set_country_code(std::string_view cc, bool ieee80211d_enabled) {
    unwrap(try_set_country_code(cc, ieee80211d_enabled));
}
inline std::string get_country_code() {
    return unwrap(try_get_country_code());
}
 
// TX power
inline void set_max_tx_power(electro::centi_dbm power) {
    unwrap(try_set_max_tx_power(power));
}
inline electro::centi_dbm get_max_tx_power() {
    return unwrap(try_get_max_tx_power());
}
 
// RSSI
inline void set_rssi_threshold(electro::dbm threshold) {
    unwrap(try_set_rssi_threshold(threshold));
}
inline electro::dbm get_rssi() {
    return unwrap(try_get_rssi());
}
 
// Protocol
inline void set_protocol(enum role iface, flags<protocol> protos) {
    unwrap(try_set_protocol(iface, protos));
}
inline flags<protocol> get_protocol(enum role iface) {
    return unwrap(try_get_protocol(iface));
}
inline void set_protocols(enum role iface, const protocols_config& cfg) {
    unwrap(try_set_protocols(iface, cfg));
}
inline protocols_config get_protocols(enum role iface) {
    return unwrap(try_get_protocols(iface));
}
 
// Band
inline void set_band(enum band b) {
    unwrap(try_set_band(b));
}
inline enum band get_band() {
    return unwrap(try_get_band());
}
inline void set_band_mode(enum band_mode m) {
    unwrap(try_set_band_mode(m));
}
inline enum band_mode get_band_mode() {
    return unwrap(try_get_band_mode());
}
 
// Storage
inline void set_storage(enum storage s) {
    unwrap(try_set_storage(s));
}
 
// Inactive time
inline void set_inactive_time(enum role iface, std::chrono::seconds timeout) {
    unwrap(try_set_inactive_time(iface, timeout));
}
inline std::chrono::seconds get_inactive_time(enum role iface) {
    return unwrap(try_get_inactive_time(iface));
}
 
// Event mask
inline void set_event_mask(flags<event_mask> mask) {
    unwrap(try_set_event_mask(mask));
}
inline flags<event_mask> get_event_mask() {
    return unwrap(try_get_event_mask());
}
 
// Force wakeup
inline void force_wakeup_acquire() {
    unwrap(try_force_wakeup_acquire());
}
inline void force_wakeup_release() {
    unwrap(try_force_wakeup_release());
}
 
// Promiscuous mode
inline void set_promiscuous(bool en) {
    unwrap(try_set_promiscuous(en));
}
inline bool get_promiscuous() {
    return unwrap(try_get_promiscuous());
}
inline void set_promiscuous_rx_cb(promiscuous_rx_cb cb) {
    unwrap(try_set_promiscuous_rx_cb(cb));
}
inline void set_promiscuous_filter(flags<promiscuous_filter> filter) {
    unwrap(try_set_promiscuous_filter(filter));
}
inline flags<promiscuous_filter> get_promiscuous_filter() {
    return unwrap(try_get_promiscuous_filter());
}
inline void set_promiscuous_ctrl_filter(flags<promiscuous_ctrl_filter> filter) {
    unwrap(try_set_promiscuous_ctrl_filter(filter));
}
inline flags<promiscuous_ctrl_filter> get_promiscuous_ctrl_filter() {
    return unwrap(try_get_promiscuous_ctrl_filter());
}
 
// Raw 802.11
inline void tx_80211(enum role iface, std::span<const uint8_t> buffer, bool en_sys_seq) {
    unwrap(try_tx_80211(iface, buffer, en_sys_seq));
}
inline void register_80211_tx_cb(tx_80211_done_cb cb) {
    unwrap(try_register_80211_tx_cb(cb));
}
 
// Vendor IE
inline void set_vendor_ie(bool enable, enum vendor_ie_type type, enum vendor_ie_id id, const void* vnd_ie) {
    unwrap(try_set_vendor_ie(enable, type, id, vnd_ie));
}
inline void set_vendor_ie_cb(vendor_ie_cb cb, void* ctx) {
    unwrap(try_set_vendor_ie_cb(cb, ctx));
}
 
// CSI
inline void set_csi(bool en) {
    unwrap(try_set_csi(en));
}
inline void set_csi_config(const csi_config& cfg) {
    unwrap(try_set_csi_config(cfg));
}
inline csi_config get_csi_config() {
    return unwrap(try_get_csi_config());
}
inline void set_csi_rx_cb(csi_rx_cb cb, void* ctx) {
    unwrap(try_set_csi_rx_cb(cb, ctx));
}
 
// FTM
inline void ftm_initiate_session(const ftm_initiator_config& cfg) {
    unwrap(try_ftm_initiate_session(cfg));
}
inline void ftm_end_session() {
    unwrap(try_ftm_end_session());
}
inline void ftm_resp_set_offset(int16_t offset) {
    unwrap(try_ftm_resp_set_offset(offset));
}
inline std::vector<ftm_report_entry> ftm_get_report(size_t max_entries) {
    return unwrap(try_ftm_get_report(max_entries));
}
 
// Miscellaneous
inline void statis_dump(flags<statis_module> modules) {
    unwrap(try_statis_dump(modules));
}
inline void config_11b_rate(enum role iface, bool disable) {
    unwrap(try_config_11b_rate(iface, disable));
}
inline void config_80211_tx_rate(enum role iface, enum phy_rate rate) {
    unwrap(try_config_80211_tx_rate(iface, rate));
}
inline void disable_pmf_config(enum role iface) {
    unwrap(try_disable_pmf_config(iface));
}
inline void set_dynamic_cs(bool enabled) {
    unwrap(try_set_dynamic_cs(enabled));
}
inline void connectionless_module_set_wake_interval(std::chrono::milliseconds interval) {
    unwrap(try_connectionless_module_set_wake_interval(interval));
}
 
#endif // CONFIG_COMPILER_CXX_EXCEPTIONS
 
// =============================================================================
// Default netif creation helpers
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
netif::interface make_sta_netif();
 
netif::interface make_ap_netif();
#endif
 
[[nodiscard]] result<netif::interface> try_make_sta_netif();
 
[[nodiscard]] result<netif::interface> try_make_ap_netif();
 
} // namespace idfxx::wifi
 
namespace idfxx {
 
[[nodiscard]] const wifi::error_category& wifi_category() noexcept;
 
[[nodiscard]] std::unexpected<std::error_code> wifi_error(esp_err_t e);
 
// =============================================================================
// String conversion
// =============================================================================
 
[[nodiscard]] std::string to_string(flags<wifi::role> roles);
 
[[nodiscard]] std::string to_string(wifi::auth_mode m);
 
[[nodiscard]] std::string to_string(wifi::cipher_type c);
 
[[nodiscard]] std::string to_string(wifi::disconnect_reason r);
 
} // namespace idfxx
 
namespace idfxx::wifi {
 
[[nodiscard]] inline std::error_code make_error_code(errc e) noexcept {
    return {std::to_underlying(e), wifi_category()};
}
 
} // namespace idfxx::wifi
 
namespace std {
template<>
struct is_error_code_enum<idfxx::wifi::errc> : true_type {};
} // namespace std
#include "sdkconfig.h"
#ifdef CONFIG_IDFXX_STD_FORMAT
#include <algorithm>
#include <format>
namespace std {
 
template<>
struct formatter<idfxx::flags<idfxx::wifi::role>> {
    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
 
    template<typename FormatContext>
    auto format(idfxx::flags<idfxx::wifi::role> roles, FormatContext& ctx) const {
        auto s = idfxx::to_string(roles);
        return std::copy(s.begin(), s.end(), ctx.out());
    }
};
 
template<>
struct formatter<idfxx::wifi::auth_mode> {
    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
 
    template<typename FormatContext>
    auto format(idfxx::wifi::auth_mode m, FormatContext& ctx) const {
        auto s = idfxx::to_string(m);
        return std::copy(s.begin(), s.end(), ctx.out());
    }
};
 
template<>
struct formatter<idfxx::wifi::cipher_type> {
    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
 
    template<typename FormatContext>
    auto format(idfxx::wifi::cipher_type c, FormatContext& ctx) const {
        auto s = idfxx::to_string(c);
        return std::copy(s.begin(), s.end(), ctx.out());
    }
};
 
template<>
struct formatter<idfxx::wifi::disconnect_reason> {
    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
 
    template<typename FormatContext>
    auto format(idfxx::wifi::disconnect_reason r, FormatContext& ctx) const {
        auto s = idfxx::to_string(r);
        return std::copy(s.begin(), s.end(), ctx.out());
    }
};
 
} // namespace std
#endif // CONFIG_IDFXX_STD_FORMAT