# ESP_NET

**Repository Path**: NetADs/esp_net

## Basic Information

- **Project Name**: ESP_NET
- **Description**: ESP32S3-N16R8开发板中的wifiAP模式模块，STA模式模块，WebServer模块
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-09
- **Last Updated**: 2026-06-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ESP32 Network Tools

ESP-IDF WiFi 配网组件，提供 AP、STA 和 WebServer 三个模块。

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![ESP-IDF](https://img.shields.io/badge/ESP--IDF-v5.0+-green.svg)](https://docs.espressif.com/projects/esp-idf/en/latest/)

## 目录结构

```
esp_net_tools/
├── include/
│   ├── wifi_ap.h              # AP 模块头文件
│   ├── wifi_sta.h             # STA 模块头文件
│   └── webserver.h            # WebServer 模块头文件
├── src/
│   ├── wifi_ap.c              # AP 模块实现
│   ├── wifi_sta.c             # STA 模块实现
│   └── webserver.c            # WebServer 模块实现
├── examples/
│   ├── simple_connect/        # STA 连接示例
│   └── web_config/            # Web 配网示例
├── CMakeLists.txt
├── Kconfig
├── idf_component.yml
└── README.md
```

## 使用方式

### 方式 1：Git URL + Component Manager（推荐）

在项目的 `idf_component.yml` 中添加：

```yaml
dependencies:
  esp_net_tools:
    git: https://gitee.com/NetADs/esp_net.git
```

构建时自动下载和托管：

```bash
idf.py reconfigure
idf.py build
```

组件会自动托管到 `managed_components/` 目录，无需手动管理。

### 方式 2：Git 子模块

```bash
cd your_project
git submodule add https://gitee.com/NetADs/esp_net.git components/esp_net
```

CMakeLists.txt：
```cmake
set(EXTRA_COMPONENT_DIRS
    ${CMAKE_CURRENT_LIST_DIR}/components/esp_net)
```

### 方式 3：复制组件

```bash
cp -r esp_net_tools your_project/components/
```

## 快速开始

### 完整配网（AP + STA + WebServer）

```c
#include "wifi_ap.h"
#include "wifi_sta.h"
#include "webserver.h"
#include "esp_wifi.h"

// 扫描回调
static void wifi_scan_cb(char *buf, size_t size) {
    wifi_scan_config_t sc = {.show_hidden = false};
    if (esp_wifi_scan_start(&sc, true) != ESP_OK) { snprintf(buf, size, "{\"aps\":[]}"); return; }
    uint16_t n = 0;
    esp_wifi_scan_get_ap_num(&n);
    if (n == 0) { snprintf(buf, size, "{\"aps\":[]}"); return; }
    wifi_ap_record_t *aps = malloc(sizeof(wifi_ap_record_t) * n);
    esp_wifi_scan_get_ap_records(&n, aps);
    int off = snprintf(buf, size, "{\"aps\":[");
    for (int i = 0; i < n && off < (int)size - 80; i++) {
        if (i > 0) off += snprintf(buf + off, size - off, ",");
        off += snprintf(buf + off, size - off,
                "{\"ssid\":\"%s\",\"rssi\":%d,\"auth\":%d}",
                aps[i].ssid, aps[i].rssi, aps[i].authmode);
    }
    off += snprintf(buf + off, size - off, "]}");
    free(aps);
}

// AP 配置回调
static void ap_get_config_cb(char *buf, size_t size) {
    esp_net_ap_config_t cfg;
    esp_net_ap_get_config(&cfg);
    strncpy(buf, cfg.ssid, size - 1);
}

// STA 保存并连接回调
static void sta_save_cb(const char *ssid, const char *pass) {
    esp_net_sta_config_t cfg = {.retry_max = 5};
    strncpy(cfg.ssid, ssid, 31);
    strncpy(cfg.password, pass, 63);
    esp_net_sta_save_config(&cfg);
    esp_net_sta_init(&cfg);
    esp_net_sta_connect();
}

// STA 状态回调
static void sta_status_cb(bool *conn, char *ip, size_t size) {
    if (esp_net_sta_is_connected()) {
        esp_netif_ip_info_t info;
        esp_net_sta_get_ip_info(&info);
        snprintf(ip, size, IPSTR, IP2STR(&info.ip));
        *conn = true;
    } else {
        *conn = false;
    }
}

void app_main(void)
{
    // 初始化 AP
    esp_net_ap_init(NULL);
    esp_net_ap_start();

    // 初始化 WebServer
    esp_net_webserver_init(NULL);

    // 注册回调（顺序：扫描、AP配置、STA保存、STA状态）
    esp_net_set_wifi_callbacks(
        wifi_scan_cb,
        ap_get_config_cb,
        sta_save_cb,
        sta_status_cb
    );

    esp_net_webserver_start();
}
```

### 只使用 AP 模块

```c
#include "wifi_ap.h"

void app_main(void)
{
    esp_net_ap_init(NULL);
    esp_net_ap_start();
}
```

### 只使用 STA 模块

```c
#include "wifi_sta.h"

void app_main(void)
{
    esp_net_sta_config_t config = {
        .ssid = "MyWiFi",
        .password = "MyPassword",
        .retry_max = 5
    };

    esp_net_sta_init(&config);
    esp_net_sta_connect();
}
```

### 只使用 WebServer 模块

```c
#include "webserver.h"

void app_main(void)
{
    esp_net_webserver_init(NULL);
    esp_net_webserver_start();
}
```

## 示例项目

### simple_connect

简单 STA 连接示例：
```bash
cd examples/simple_connect
idf.py build flash monitor
```

### web_config

完整 Web 配网示例：
```bash
cd examples/web_config
idf.py build flash monitor
```

连接热点 `ESP32_Config`（密码：12345678），访问 http://192.168.4.1

## API 说明

### AP 模块 (`include/wifi_ap.h`)

```c
esp_net_ap_init(&config);       // 初始化
esp_net_ap_start();             // 启动
esp_net_ap_stop();              // 停止
esp_net_ap_get_config(&cfg);    // 获取配置
esp_net_ap_get_sta_num(&num);   // 获取连接数
```

### STA 模块 (`include/wifi_sta.h`)

```c
esp_net_sta_init(&config);         // 初始化
esp_net_sta_connect();             // 连接
esp_net_sta_disconnect();          // 断开
esp_net_sta_set_callback(cb, arg); // 设置回调
esp_net_sta_is_connected();        // 检查连接状态
esp_net_sta_get_ip_info(&info);    // 获取 IP 信息
esp_net_sta_save_config(&cfg);     // 保存到 NVS
esp_net_sta_load_config(&cfg);     // 从 NVS 加载
esp_net_sta_clear_config();        // 清除配置
```

### WebServer 模块 (`include/webserver.h`)

```c
esp_net_webserver_init(&config);         // 初始化
esp_net_webserver_start();               // 启动
esp_net_webserver_stop();                // 停止
esp_net_webserver_register_handler(...); // 注册自定义 API
esp_net_webserver_get_handle();          // 获取服务器句柄

// 设置 WiFi 回调（用于 Web API）
esp_net_set_wifi_callbacks(scan_cb, ap_cb, sta_save_cb, sta_status_cb);
```

> HTTP 服务器默认栈大小为 **8192 字节**（可通过 Kconfig 或 `esp_net_webserver_config_t.task_stack_size` 调整），请确保系统整体栈空间充裕，避免栈溢出。

## Web API 端点

| 方法 | 端点 | 说明 |
|------|------|------|
| GET | `/` | Web 配置页面（中文界面） |
| GET | `/api/scan` | 扫描附近 WiFi AP |
| POST | `/api/connect` | 连接 WiFi |
| GET | `/api/status` | 连接状态 |
| POST | `/api/reset` | 重启设备 |

## 配置选项

```bash
idf.py menuconfig → ESP Net Tools
```

| 类别 | 选项 | 默认值 | 说明 |
|------|------|--------|------|
| AP | SSID | ESP32_Config | 热点名称 |
| AP | Password | 12345678 | 热点密码 |
| AP | Channel | 1 | WiFi 信道 (1-11) |
| STA | Retry Max | 5 | 最大重试次数 (0-100) |
| STA | Authmode Threshold | WPA2 PSK | STA 最低认证模式阈值 |
| Common | Log Level | Info | 组件日志级别 |
| WebServer | HTTP Port | 80 | Web 服务端口 (1-65535) |
| WebServer | Task Stack Size | 8192 | HTTPD 任务栈大小 (4096-65536) |

## 更新组件

### Component Manager 方式

```bash
idf.py reconfigure  # 自动更新
```

### Git 子模块方式

```bash
cd components/esp_net
git pull origin master
```

## 许可证

MIT License