Wi-Fi

组件注册表： espressif/brookesia_service_wifi
辅助头文件： #include "brookesia/service_helper/wifi.hpp"
辅助类： esp_brookesia::service::helper::Wifi

概述

brookesia_service_wifi 是为 ESP-Brookesia 生态系统提供的 WiFi 连接管理服务，提供：

状态机管理：通过状态机统一管理 WiFi 的初始化、启动、连接等生命周期状态
自动重连：支持自动连接历史 AP，并在断开后自动尝试重连
WiFi 扫描：支持周期性扫描周围 AP，并自动发现可连接的 AP
连接管理：管理目标 AP 和已连接 AP 列表，支持多 AP 历史记录
事件通知：提供丰富的事件通知机制，实时反馈 WiFi 状态变化
持久化存储：可选搭配 brookesia_service_nvs 服务持久化保存连接配置和其他参数

功能特性

状态机管理

WiFi 服务通过状态机统一管理 WiFi 的生命周期状态，确保状态转换的安全性和一致性。状态机包含 4 个核心状态：

状态	说明
`Idle`	WiFi 未初始化，系统初始状态
`Inited`	WiFi 已初始化，但未启动，可以配置参数
`Started`	WiFi 已启动，正在扫描或等待连接
`Connected`	WiFi 已成功连接到 AP，可以正常通信

状态转换通过触发相应的动作（Action）来实现：

正向流程：Idle → Inited（Init）→ Started（Start）→ Connected（Connect）
断开连接：Connected → Started（Disconnect）
停止流程：Started / Connected → Inited（Stop）
反初始化：Inited → Idle（Deinit）

状态转换图如下：

        stateDiagram-v2
  direction TB

  %% State Styles
  classDef Stable fill:#DEFFF8,stroke:#46EDC8,color:#378E7A,font-weight:bold;
  classDef Transient fill:#FFEFDB,stroke:#FBB35A,color:#8F632D,font-weight:bold;

  %% Initial State
  [*] --> Idle

  %% =====================
  %% Idle
  %% =====================
  Idle --> Initing: Init

  %% =====================
  %% Initing
  %% =====================
  state Initing {
    do_init() --> poll_until_inited()
  }

  Initing --> Inited: Success
  Initing --> Idle: Failure
  Initing --> Deiniting: Timeout

  %% =====================
  %% Inited
  %% =====================
  Inited --> Starting: Start
  Inited --> Deiniting: Deinit

  %% =====================
  %% Deiniting
  %% =====================
  state Deiniting {
    do_deinit() --> poll_until_deinited()
  }

  Deiniting --> Idle: Success / Failure / Timeout

  %% =====================
  %% Starting
  %% =====================
  state Starting {
    do_start() --> poll_until_started()
  }

  Starting --> Started: Success
  Starting --> Inited: Failure
  Starting --> Stopping: Timeout

  %% =====================
  %% Started
  %% =====================
  Started --> Connecting: Connect
  Started --> Stopping: Stop

  %% =====================
  %% Connecting
  %% =====================
  state Connecting {
    do_connect() --> poll_until_connected()
  }

  Connecting --> Connected: Success
  Connecting --> Started: Failure
  Connecting --> Disconnecting: Timeout

  %% =====================
  %% Connected
  %% =====================
  Connected --> Disconnecting: Disconnect
  Connected --> Stopping: Stop

  %% =====================
  %% Disconnecting
  %% =====================
  state Disconnecting {
    do_disconnect() --> poll_until_disconnected()
  }

  Disconnecting --> Started: Success / Failure / Timeout

  %% =====================
  %% Stopping
  %% =====================
  state Stopping {
    do_stop() --> poll_until_stopped()
  }

  Stopping --> Inited: Success / Failure / Timeout

  class Idle,Inited,Started,Connected Stable
  class Initing,Starting,Connecting,Disconnecting,Stopping,Deiniting Transient

自动重连机制

启动时自动连接：WiFi 启动后自动尝试连接历史可连接的 AP
断开后自动重连：检测到意外断开后，自动尝试连接历史可连接的 AP
扫描发现自动连接：扫描过程中发现目标 AP 或历史可连接 AP 时，自动触发连接

WiFi 扫描

周期性扫描：支持配置扫描间隔和超时时间
扫描结果通知：通过事件实时通知扫描到的 AP 信息
AP 信息：包含 SSID、信号强度等级、是否加密等信息

SoftAP 功能

参数设置：支持设置 SoftAP 的 SSID、密码、最大连接数和通道
最优通道选择：如果未设置通道，则会自动扫描附近 AP 并选择最佳通道
配网功能：支持启动 SoftAP 配网功能

服务接口

函数

`TriggerGeneralAction`

描述

Trigger a Wi-Fi general action.

执行要求

是否需要调度器: 需要

参数

Action
- 类型: String
- 是否必填: 必填
- 描述: General action. Allowed values: [Init, Deinit, Start, Stop, Connect, Disconnect]

Schema JSON

展开查看 JSON


{
  "name": "TriggerGeneralAction",
  "description": "Trigger a Wi-Fi general action.",
  "require_scheduler": true,
  "parameters": [
    {
      "name": "Action",
      "description": "General action. Allowed values: [Init, Deinit, Start, Stop, Connect, Disconnect]",
      "type": "String",
      "required": true,
      "default_value": null
    }
  ]
}

CLI 命令

svc_call Wifi TriggerGeneralAction {"Action":null}

`GetGeneralState`

描述

Get current general state. Return type: string. Allowed values: [Idle, Initing, Inited, Deiniting, Starting, Started, Stopping, Connecting, Connected, Disconnecting]. Example: “Connected”

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "GetGeneralState",
  "description": "Get current general state. Return type: string. Allowed values: [Idle, Initing, Inited, Deiniting, Starting, Started, Stopping, Connecting, Connected, Disconnecting]. Example: \"Connected\"",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Wifi GetGeneralState

`SetConnectAp`

描述

Set target AP credentials.

执行要求

是否需要调度器: 需要

参数

SSID
- 类型: String
- 是否必填: 必填
- 描述: AP SSID.
Password
- 类型: String
- 是否必填: 可选
- 默认值: ""
- 描述: AP password (optional).

Schema JSON

展开查看 JSON


{
  "name": "SetConnectAp",
  "description": "Set target AP credentials.",
  "require_scheduler": true,
  "parameters": [
    {
      "name": "SSID",
      "description": "AP SSID.",
      "type": "String",
      "required": true,
      "default_value": null
    },
    {
      "name": "Password",
      "description": "AP password (optional).",
      "type": "String",
      "required": false,
      "default_value": ""
    }
  ]
}

CLI 命令

svc_call Wifi SetConnectAp {"SSID":null,"Password":null}

`GetConnectAp`

描述

Get target AP. Return type: JSON object. Example: {“ssid”:”ssid1”,”password”:”password1”,”is_connectable”:true}

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "GetConnectAp",
  "description": "Get target AP. Return type: JSON object. Example: {\"ssid\":\"ssid1\",\"password\":\"password1\",\"is_connectable\":true}",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Wifi GetConnectAp

`GetConnectedAps`

描述

Get connected AP list. Return type: JSON array<object>. Example: [{“ssid”:”ssid1”,”password”:”password1”,”is_connectable”:true},{“ssid”:”ssid2”,”password”:”password2”,”is_connectable”:true}]

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "GetConnectedAps",
  "description": "Get connected AP list. Return type: JSON array<object>. Example: [{\"ssid\":\"ssid1\",\"password\":\"password1\",\"is_connectable\":true},{\"ssid\":\"ssid2\",\"password\":\"password2\",\"is_connectable\":true}]",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Wifi GetConnectedAps

`SetScanParams`

描述

Set scan parameters.

执行要求

是否需要调度器: 需要

参数

Param
- 类型: Object
- 是否必填: 必填
- 描述: Scan parameters as a JSON object. Example: {“ap_count”:20,”interval_ms”:10000,”timeout_ms”:60000}

Schema JSON

展开查看 JSON


{
  "name": "SetScanParams",
  "description": "Set scan parameters.",
  "require_scheduler": true,
  "parameters": [
    {
      "name": "Param",
      "description": "Scan parameters as a JSON object. Example: {\"ap_count\":20,\"interval_ms\":10000,\"timeout_ms\":60000}",
      "type": "Object",
      "required": true,
      "default_value": null
    }
  ]
}

CLI 命令

svc_call Wifi SetScanParams {"Param":null}

`TriggerScanStart`

描述

Start Wi-Fi scan.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "TriggerScanStart",
  "description": "Start Wi-Fi scan.",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Wifi TriggerScanStart

`TriggerScanStop`

描述

Stop Wi-Fi scan.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "TriggerScanStop",
  "description": "Stop Wi-Fi scan.",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Wifi TriggerScanStop

`SetSoftApParams`

描述

Set SoftAP parameters.

执行要求

是否需要调度器: 需要

参数

Param
- 类型: Object
- 是否必填: 必填
- 描述: SoftAP parameters as a JSON object. Example: {“ssid”:”ssid”,”password”:”password”,”max_connection”:4,”channel”:1}

Schema JSON

展开查看 JSON


{
  "name": "SetSoftApParams",
  "description": "Set SoftAP parameters.",
  "require_scheduler": true,
  "parameters": [
    {
      "name": "Param",
      "description": "SoftAP parameters as a JSON object. Example: {\"ssid\":\"ssid\",\"password\":\"password\",\"max_connection\":4,\"channel\":1}",
      "type": "Object",
      "required": true,
      "default_value": null
    }
  ]
}

CLI 命令

svc_call Wifi SetSoftApParams {"Param":null}

`GetSoftApParams`

描述

Get SoftAP parameters. Return type: JSON object. Example: {“ssid”:””,”password”:””,”max_connection”:4,”channel”:null}

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "GetSoftApParams",
  "description": "Get SoftAP parameters. Return type: JSON object. Example: {\"ssid\":\"\",\"password\":\"\",\"max_connection\":4,\"channel\":null}",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Wifi GetSoftApParams

`TriggerSoftApStart`

描述

Start SoftAP.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "TriggerSoftApStart",
  "description": "Start SoftAP.",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Wifi TriggerSoftApStart

`TriggerSoftApStop`

描述

Stop SoftAP.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "TriggerSoftApStop",
  "description": "Stop SoftAP.",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Wifi TriggerSoftApStop

`TriggerSoftApProvisionStart`

描述

Start SoftAP provisioning.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "TriggerSoftApProvisionStart",
  "description": "Start SoftAP provisioning.",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Wifi TriggerSoftApProvisionStart

`TriggerSoftApProvisionStop`

描述

Stop SoftAP provisioning.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "TriggerSoftApProvisionStop",
  "description": "Stop SoftAP provisioning.",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Wifi TriggerSoftApProvisionStop

`ResetData`

描述

Reset Wi-Fi data, including target AP, scan parameters, and connected APs. Also clears NVS data.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "ResetData",
  "description": "Reset Wi-Fi data, including target AP, scan parameters, and connected APs. Also clears NVS data.",
  "require_scheduler": true,
  "parameters": []
}

CLI 命令

svc_call Wifi ResetData

事件

`GeneralActionTriggered`

描述

Emitted when a general action is triggered.

执行要求

是否需要调度器: 需要

参数

Action
- 类型: String
- 描述: General action. Allowed values: [Init, Deinit, Start, Stop, Connect, Disconnect]

Schema JSON

展开查看 JSON


{
  "name": "GeneralActionTriggered",
  "description": "Emitted when a general action is triggered.",
  "require_scheduler": true,
  "items": [
    {
      "name": "Action",
      "description": "General action. Allowed values: [Init, Deinit, Start, Stop, Connect, Disconnect]",
      "type": "String"
    }
  ]
}

CLI 命令

svc_subscribe Wifi GeneralActionTriggered

`GeneralEventHappened`

描述

Emitted when a general event occurs.

执行要求

是否需要调度器: 需要

参数

Event
- 类型: String
- 描述: General event. Allowed values: [Deinited, Inited, Stopped, Started, Disconnected, Connected]
IsUnexpected
- 类型: Boolean
- 描述: Whether the event was unexpected.

Schema JSON

展开查看 JSON


{
  "name": "GeneralEventHappened",
  "description": "Emitted when a general event occurs.",
  "require_scheduler": true,
  "items": [
    {
      "name": "Event",
      "description": "General event. Allowed values: [Deinited, Inited, Stopped, Started, Disconnected, Connected]",
      "type": "String"
    },
    {
      "name": "IsUnexpected",
      "description": "Whether the event was unexpected.",
      "type": "Boolean"
    }
  ]
}

CLI 命令

svc_subscribe Wifi GeneralEventHappened

`ScanStateChanged`

描述

Emitted when scan state changes.

执行要求

是否需要调度器: 需要

参数

IsRunning
- 类型: Boolean
- 描述: Whether scanning is running.

Schema JSON

展开查看 JSON


{
  "name": "ScanStateChanged",
  "description": "Emitted when scan state changes.",
  "require_scheduler": true,
  "items": [
    {
      "name": "IsRunning",
      "description": "Whether scanning is running.",
      "type": "Boolean"
    }
  ]
}

CLI 命令

svc_subscribe Wifi ScanStateChanged

`ScanApInfosUpdated`

描述

Emitted when scan AP list is updated.

执行要求

是否需要调度器: 需要

参数

ApInfos
- 类型: Array
- 描述: Scanned AP list as a JSON array<object>. Example: [{“ssid”:”ssid1”,”password”:”password1”,”is_connectable”:true},{“ssid”:”ssid2”,”password”:”password2”,”is_connectable”:true}]

Schema JSON

展开查看 JSON


{
  "name": "ScanApInfosUpdated",
  "description": "Emitted when scan AP list is updated.",
  "require_scheduler": true,
  "items": [
    {
      "name": "ApInfos",
      "description": "Scanned AP list as a JSON array<object>. Example: [{\"ssid\":\"ssid1\",\"password\":\"password1\",\"is_connectable\":true},{\"ssid\":\"ssid2\",\"password\":\"password2\",\"is_connectable\":true}]",
      "type": "Array"
    }
  ]
}

CLI 命令

svc_subscribe Wifi ScanApInfosUpdated

`SoftApEventHappened`

描述

Emitted when a SoftAP event occurs.

执行要求

是否需要调度器: 需要

参数

Event
- 类型: String
- 描述: SoftAP event. Allowed values: [Started, Stopped]

Schema JSON

展开查看 JSON


{
  "name": "SoftApEventHappened",
  "description": "Emitted when a SoftAP event occurs.",
  "require_scheduler": true,
  "items": [
    {
      "name": "Event",
      "description": "SoftAP event. Allowed values: [Started, Stopped]",
      "type": "String"
    }
  ]
}

CLI 命令

svc_subscribe Wifi SoftApEventHappened

Wi-Fi

概述

功能特性

状态机管理

自动重连机制

WiFi 扫描

SoftAP 功能

服务接口

函数

TriggerGeneralAction

描述

执行要求

参数

Schema JSON

CLI 命令

GetGeneralState

描述

执行要求

参数

Schema JSON

CLI 命令

SetConnectAp

描述

执行要求

参数

Schema JSON

CLI 命令

GetConnectAp

描述

执行要求

参数

Schema JSON

CLI 命令

GetConnectedAps

描述

执行要求

参数

Schema JSON

CLI 命令

SetScanParams

描述

执行要求

参数

Schema JSON

CLI 命令

TriggerScanStart

描述

执行要求

参数

Schema JSON

CLI 命令

TriggerScanStop

描述

执行要求

参数

Schema JSON

CLI 命令

SetSoftApParams

描述

执行要求

参数

Schema JSON

CLI 命令

GetSoftApParams

描述

执行要求

参数

Schema JSON

CLI 命令

TriggerSoftApStart

描述

执行要求

参数

Schema JSON

CLI 命令

TriggerSoftApStop

描述

执行要求

参数

Schema JSON

`TriggerGeneralAction`

`GetGeneralState`

`SetConnectAp`

`GetConnectAp`

`GetConnectedAps`

`SetScanParams`

`TriggerScanStart`

`TriggerScanStop`

`SetSoftApParams`

`GetSoftApParams`

`TriggerSoftApStart`

`TriggerSoftApStop`

`TriggerSoftApProvisionStart`

`TriggerSoftApProvisionStop`

`ResetData`

`GeneralActionTriggered`

`GeneralEventHappened`

`ScanStateChanged`

`ScanApInfosUpdated`

`SoftApEventHappened`