Wi-Fi

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

概述

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

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

功能特性

状态机管理

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）

状态转换图如下：

flowchart TD
    A["**Idle**<br/>· 未初始化<br/>· 等待 Init"]
    B["**Inited**<br/>· 驱动和配置就绪<br/>· 可启动连接流程"]
    C["**Started**<br/>· Wi-Fi 已启动<br/>· 可发起连接"]
    D["**Connected**<br/>· 已连接 AP<br/>· 可提供网络能力"]

    A -->|"Init"| B
    B -->|"Start"| C
    C -->|"Connect"| D
    D -->|"Disconnect"| C
    C -->|"Stop"| B
    D -->|"Stop"| B
    B -->|"Deinit"| A

自动重连机制

启动时自动连接：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,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "Action",
      "description": "General action. Allowed values: [Init, Deinit, Start, Stop, Connect, Disconnect]",
      "type": "String",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": null
}

CLI 命令

svc_call Wifi TriggerGeneralAction {"Action":null}

`GetGeneralState`

描述

Get current general state.

执行要求

是否需要调度器: 需要

参数

无。

返回值

类型: 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.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": {
    "type": "String",
    "description": "Allowed values: [Idle, Initing, Inited, Deiniting, Starting, Started, Stopping, Connecting, Connected, Disconnecting]. Example: \"Connected\""
  }
}

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,
  "default_timeout_ms": null,
  "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": ""
    }
  ],
  "return_value": null
}

CLI 命令

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

`GetConnectAp`

描述

Get target AP.

执行要求

是否需要调度器: 需要

参数

无。

返回值

类型: Object
描述: Example: {"ssid":"ssid1","password":"password1","is_connectable":true}

Schema JSON

展开查看 JSON


{
  "name": "GetConnectAp",
  "description": "Get target AP.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": {
    "type": "Object",
    "description": "Example: {\"ssid\":\"ssid1\",\"password\":\"password1\",\"is_connectable\":true}"
  }
}

CLI 命令

svc_call Wifi GetConnectAp

`GetConnectedAps`

描述

Get connected AP list.

执行要求

是否需要调度器: 需要

参数

无。

返回值

类型: Array
描述: 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.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": {
    "type": "Array",
    "description": "Example: [{\"ssid\":\"ssid1\",\"password\":\"password1\",\"is_connectable\":true},{\"ssid\":\"ssid2\",\"password\":\"password2\",\"is_connectable\":true}]"
  }
}

CLI 命令

svc_call Wifi GetConnectedAps

`RemoveConnectedAp`

描述

Remove a saved AP from the connected AP list and persisted Wi-Fi data.

执行要求

是否需要调度器: 需要

参数

SSID
- 类型: String
- 是否必填: 必填
- 描述: Saved AP SSID to remove.

Schema JSON

展开查看 JSON


{
  "name": "RemoveConnectedAp",
  "description": "Remove a saved AP from the connected AP list and persisted Wi-Fi data.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "SSID",
      "description": "Saved AP SSID to remove.",
      "type": "String",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": null
}

CLI 命令

svc_call Wifi RemoveConnectedAp {"SSID":null}

`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,
  "default_timeout_ms": null,
  "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
    }
  ],
  "return_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,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": null
}

CLI 命令

svc_call Wifi TriggerScanStart

`TriggerScanStop`

描述

Stop Wi-Fi scan.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


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

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,
  "default_timeout_ms": null,
  "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
    }
  ],
  "return_value": null
}

CLI 命令

svc_call Wifi SetSoftApParams {"Param":null}

`GetSoftApParams`

描述

Get SoftAP parameters.

执行要求

是否需要调度器: 需要

参数

无。

返回值

类型: Object
描述: Example: {"ssid":"","password":"","max_connection":4,"channel":null}

Schema JSON

展开查看 JSON


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

CLI 命令

svc_call Wifi GetSoftApParams

`TriggerSoftApStart`

描述

Start SoftAP.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


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

CLI 命令

svc_call Wifi TriggerSoftApStart

`TriggerSoftApStop`

描述

Stop SoftAP.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


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

CLI 命令

svc_call Wifi TriggerSoftApStop

`TriggerSoftApProvisionStart`

描述

Start SoftAP provisioning.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


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

CLI 命令

svc_call Wifi TriggerSoftApProvisionStart

`TriggerSoftApProvisionStop`

描述

Stop SoftAP provisioning.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


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

CLI 命令

svc_call Wifi TriggerSoftApProvisionStop

`LoadData`

描述

Load persisted Wi-Fi data.

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


{
  "name": "LoadData",
  "description": "Load persisted Wi-Fi data.",
  "require_scheduler": true,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": null
}

CLI 命令

svc_call Wifi LoadData

`ResetData`

描述

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

执行要求

是否需要调度器: 需要

参数

无。

Schema JSON

展开查看 JSON


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

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","is_locked":true,"rssi":-45,"signal_level":"LEVEL_4","channel":1},{"ssid":"ssid2","is_locked":false,"rssi":-65,"signal_level":"LEVEL_2","channel":6}]

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\",\"is_locked\":true,\"rssi\":-45,\"signal_level\":\"LEVEL_4\",\"channel\":1},{\"ssid\":\"ssid2\",\"is_locked\":false,\"rssi\":-65,\"signal_level\":\"LEVEL_2\",\"channel\":6}]",
      "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 命令

RemoveConnectedAp

描述

执行要求

参数

Schema JSON

CLI 命令

SetScanParams

描述

执行要求

参数

Schema JSON

CLI 命令

TriggerScanStart

描述

执行要求

参数

Schema JSON

CLI 命令

TriggerScanStop

描述

执行要求

参数

Schema JSON

CLI 命令

SetSoftApParams

描述

执行要求

参数

Schema JSON

CLI 命令

GetSoftApParams

描述

执行要求

参数

返回值

Schema JSON

CLI 命令

TriggerSoftApStart

`TriggerGeneralAction`

`GetGeneralState`

`SetConnectAp`

`GetConnectAp`

`GetConnectedAps`

`RemoveConnectedAp`

`SetScanParams`

`TriggerScanStart`

`TriggerScanStop`

`SetSoftApParams`

`GetSoftApParams`

`TriggerSoftApStart`

`TriggerSoftApStop`

`TriggerSoftApProvisionStart`

`TriggerSoftApProvisionStop`

`LoadData`

`ResetData`

`GeneralActionTriggered`

`GeneralEventHappened`

`ScanStateChanged`

`ScanApInfosUpdated`

`SoftApEventHappened`