Wi-Fi

Component registry: espressif/brookesia_service_wifi
Helper header: #include "brookesia/service_helper/wifi.hpp"
Helper class: esp_brookesia::service::helper::Wifi

Overview

brookesia_service_wifi manages Wi-Fi connectivity:

State machine: Init, start, connect, and related lifecycle states.
Auto reconnect: Reconnect to known APs after drops.
Scanning: Periodic scans and discovery of connectable APs.
Connection management: Target AP and connected-AP lists with history.
Events: Rich notifications for state changes.
Persistence: Optional brookesia_service_nvs for credentials and parameters.

Features

State Machine

The Wi-Fi service manages lifecycle states in a state machine for safe, consistent transitions. The state machine has four core states:

State	Description
`Idle`	Wi-Fi not initialized (initial state).
`Inited`	Initialized but not started; parameters can be configured.
`Started`	Started; scanning or waiting to connect.
`Connected`	Associated with an AP and ready for traffic.

Transitions use actions:

Forward: Idle → Inited (Init) → Started (Start) → Connected (Connect)
Disconnect: Connected → Started (Disconnect)
Stop: Started / Connected → Inited (Stop)
Deinit: Inited → Idle (Deinit)

State transition diagram:

        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

Auto Reconnect

Connect to historical APs after start.
Reconnect after unexpected disconnects.
Auto-connect when a target or historical AP appears during scan.

Wi-Fi Scanning

Configurable interval and timeout.
Events with SSID, signal level, security, etc.

SoftAP

SSID, password, max clients, channel.
Optional automatic best-channel selection.
SoftAP provisioning mode.

Standard Include / Helper Class

Standard include: #include \"brookesia/service_helper/wifi.hpp\"
Helper class: esp_brookesia::service::helper::Wifi

Service Interfaces

Functions

`TriggerGeneralAction`

Description

Trigger a Wi-Fi general action.

Execution

Requires scheduler: Required

Parameters

Action
- Type: String
- Required: required
- Description: General action. Allowed values: [Init, Deinit, Start, Stop, Connect, Disconnect]

Schema JSON

Show raw 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 Command

svc_call Wifi TriggerGeneralAction {"Action":null}

`GetGeneralState`

Description

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

Execution

Requires scheduler: Required

Parameters

No parameters.

Schema JSON

Show raw 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 Command

svc_call Wifi GetGeneralState

`SetConnectAp`

Description

Set target AP credentials.

Execution

Requires scheduler: Required

Parameters

SSID
- Type: String
- Required: required
- Description: AP SSID.
Password
- Type: String
- Required: optional
- Default: ""
- Description: AP password (optional).

Schema JSON

Show raw 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 Command

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

`GetConnectAp`

Description

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

Execution

Requires scheduler: Required

Parameters

No parameters.

Schema JSON

Show raw JSON


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

CLI Command

svc_call Wifi GetConnectAp

`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}]

Execution

Requires scheduler: Required

Parameters

No parameters.

Schema JSON

Show raw 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 Command

svc_call Wifi GetConnectedAps

`SetScanParams`

Description

Set scan parameters.

Execution

Requires scheduler: Required

Parameters

Param
- Type: Object
- Required: required
- Description: Scan parameters as a JSON object. Example: {“ap_count”:20,”interval_ms”:10000,”timeout_ms”:60000}

Schema JSON

Show raw 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 Command

svc_call Wifi SetScanParams {"Param":null}

`TriggerScanStart`

Description

Start Wi-Fi scan.

Execution

Requires scheduler: Required

Parameters

No parameters.

Schema JSON

Show raw JSON


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

CLI Command

svc_call Wifi TriggerScanStart

`TriggerScanStop`

Description

Stop Wi-Fi scan.

Execution

Requires scheduler: Required

Parameters

No parameters.

Schema JSON

Show raw JSON


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

CLI Command

svc_call Wifi TriggerScanStop

`SetSoftApParams`

Description

Set SoftAP parameters.

Execution

Requires scheduler: Required

Parameters

Param
- Type: Object
- Required: required
- Description: SoftAP parameters as a JSON object. Example: {“ssid”:”ssid”,”password”:”password”,”max_connection”:4,”channel”:1}

Schema JSON

Show raw 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 Command

svc_call Wifi SetSoftApParams {"Param":null}

`GetSoftApParams`

Description

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

Execution

Requires scheduler: Required

Parameters

No parameters.

Schema JSON

Show raw JSON


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

CLI Command

svc_call Wifi GetSoftApParams

`TriggerSoftApStart`

Description

Start SoftAP.

Execution

Requires scheduler: Required

Parameters

No parameters.

Schema JSON

Show raw JSON


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

CLI Command

svc_call Wifi TriggerSoftApStart

`TriggerSoftApStop`

Description

Stop SoftAP.

Execution

Requires scheduler: Required

Parameters

No parameters.

Schema JSON

Show raw JSON


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

CLI Command

svc_call Wifi TriggerSoftApStop

`TriggerSoftApProvisionStart`

Description

Start SoftAP provisioning.

Execution

Requires scheduler: Required

Parameters

No parameters.

Schema JSON

Show raw JSON


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

CLI Command

svc_call Wifi TriggerSoftApProvisionStart

`TriggerSoftApProvisionStop`

Description

Stop SoftAP provisioning.

Execution

Requires scheduler: Required

Parameters

No parameters.

Schema JSON

Show raw JSON


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

CLI Command

svc_call Wifi TriggerSoftApProvisionStop

`ResetData`

Description

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

Execution

Requires scheduler: Required

Parameters

No parameters.

Schema JSON

Show raw 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 Command

svc_call Wifi ResetData

Events

`GeneralActionTriggered`

Description

Emitted when a general action is triggered.

Execution

Requires scheduler: Required

Items

Action
- Type: String
- Description: General action. Allowed values: [Init, Deinit, Start, Stop, Connect, Disconnect]

Schema JSON

Show raw 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 Command

svc_subscribe Wifi GeneralActionTriggered

`GeneralEventHappened`

Description

Emitted when a general event occurs.

Execution

Requires scheduler: Required

Items

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

Schema JSON

Show raw 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 Command

svc_subscribe Wifi GeneralEventHappened

`ScanStateChanged`

Description

Emitted when scan state changes.

Execution

Requires scheduler: Required

Items

IsRunning
- Type: Boolean
- Description: Whether scanning is running.

Schema JSON

Show raw JSON


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

CLI Command

svc_subscribe Wifi ScanStateChanged

`ScanApInfosUpdated`

Description

Emitted when scan AP list is updated.

Execution

Requires scheduler: Required

Items

ApInfos
- Type: Array
- Description: 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

Show raw 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 Command

svc_subscribe Wifi ScanApInfosUpdated

`SoftApEventHappened`

Description

Emitted when a SoftAP event occurs.

Execution

Requires scheduler: Required

Items

Event
- Type: String
- Description: SoftAP event. Allowed values: [Started, Stopped]

Schema JSON

Show raw 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 Command

svc_subscribe Wifi SoftApEventHappened

Wi-Fi

Overview

Features

State Machine

Auto Reconnect

Wi-Fi Scanning

SoftAP

Standard Include / Helper Class

Service Interfaces

Functions

TriggerGeneralAction

Description

Execution

Parameters

Schema JSON

CLI Command

GetGeneralState

Description

Execution

Parameters

Schema JSON

CLI Command

SetConnectAp

Description

Execution

Parameters

Schema JSON

CLI Command

GetConnectAp

Description

Execution

Parameters

Schema JSON

CLI Command

GetConnectedAps

Description

Execution

Parameters

Schema JSON

CLI Command

SetScanParams

Description

Execution

Parameters

Schema JSON

CLI Command

TriggerScanStart

Description

Execution

Parameters

Schema JSON

CLI Command

TriggerScanStop

Description

Execution

Parameters

Schema JSON

CLI Command

SetSoftApParams

Description

Execution

Parameters

Schema JSON

CLI Command

GetSoftApParams

Description

Execution

Parameters

Schema JSON

CLI Command

TriggerSoftApStart

Description

Execution

Parameters

Schema JSON

CLI Command

TriggerSoftApStop

Description

Execution

Parameters

`TriggerGeneralAction`

`GetGeneralState`

`SetConnectAp`

`GetConnectAp`

`GetConnectedAps`

`SetScanParams`

`TriggerScanStart`

`TriggerScanStop`

`SetSoftApParams`

`GetSoftApParams`

`TriggerSoftApStart`

`TriggerSoftApStop`

`TriggerSoftApProvisionStart`

`TriggerSoftApProvisionStop`

`ResetData`

`GeneralActionTriggered`

`GeneralEventHappened`

`ScanStateChanged`

`ScanApInfosUpdated`

`SoftApEventHappened`