embedded_networking_esp32

General Description

Abstract

This component implements basic networking functionality using the WiFi capabilities of ESP-IDF in pure C.

It is meant to be reusable and provides a very minimal (public) interface for integration in different ESP32 projects.

It establishes and maintains the connection to a WiFi network, provides an internal access point for fallback purposes, integrates into a project’s http server implementation and exposes most of its configuration options by ESP-IDF’s menuconfig or by using the web interface while running.

WiFi Provisioning

The component stores the credentials for the WiFi to be used on the ESP32’s internal non-volatile storage (NVS).

If the specified network is not reachable (with a configurable number of retries), the component launches an internal access point (with configurable credentials) to make the configuration interface available.

If there are no credentials found, the access point is started immediatly.

Please note The component does not include an HTTP server implementation. The project has to provide this functionality (e.g. by another component) in order to make the web interface accessible.

Developer’s Note

This component is implemented as ESP-IDF component while developing a web radio player based on the ESP32, KrachkisteESP32.

It is meant to be as pluggable as possible, but most likely it will require some hacking to integrate it with other ESP32-based projects.

Public API

Component Configuration

The component’s configuration is implemented as #define statements in the main header file. Most of these configuration values can be adjusted / modified by using ESP-IDF’s menuconfig tool. However, some are only adjustable by modifying the actual header file mnet32.h

MNET32_NVS_NAMESPACE

The namespace to store component-specific values in the non-volatile storage.

The component will store some internal configuration values (e.g. the actual SSID and PSK of the configured WiFi network) to the non-volatile storage (NVS) of the ESP32.

The component uses a dedicated namespace by default to ensure that there are no conflicts of the actual key names.

This is part of the component’s configuration and can be adjusted using ESP-IDF’s menuconfig or editing the sdkconfig file.

MNET32_TASK_PRIORITY

The freeRTOS-specific priority for the component’s task.

The component launches a dedicated task with the given priority to establish and maintain the network connectivity. The default value is suitable for general purposes, but may be adjusted for specific projects.

This is part of the component’s configuration, but can only be adjusted by modifying the actual header file mnet32.h.

Todo:

Determine a sane (default) value for this! Evaluate other (built-in) task priorities.

MNET32_TASK_MONITOR_FREQUENCY

The component will automatically provide status information to other components with this frequency.

The value is given in milliseconds.

This is part of the component’s configuration and can be adjusted using ESP-IDF’s menuconfig or editing the sdkconfig file.

MNET32_WEB_URL_CONFIG

The URI to serve the component’s web interface from.

This is part of the component’s configuration and can be adjusted using ESP-IDF’s menuconfig or editing the sdkconfig file.

MNET32_WIFI_AP_CHANNEL

The channel to be used while providing the project-specific access point.

This is part of the component’s configuration and can be adjusted using ESP-IDF’s menuconfig or editing the sdkconfig file.

MNET32_WIFI_AP_MAX_CONNS

The maximum number of allowed clients while providing the project-specific access point.

This is part of the component’s configuration and can be adjusted using ESP-IDF’s menuconfig or editing the sdkconfig file.

MNET32_WIFI_AP_LIFETIME

Timespan to keep the project-specific access point available.

The value is given in milliseconds.

This is part of the component’s configuration and can be adjusted using ESP-IDF’s menuconfig or editing the sdkconfig file.

MNET32_WIFI_AP_PSK

The password to access the project-specific access point.

The component esp_wifi requires the password to be at least 8 characters! It fails badly otherwise. The (internal) function mnet32_wifi_ap_init does handle this.

This is part of the component’s configuration and can be adjusted using ESP-IDF’s menuconfig or editing the sdkconfig file.

MNET32_WIFI_AP_SSID

The actual SSID of the project-specific access point.

This is part of the component’s configuration and can be adjusted using ESP-IDF’s menuconfig or editing the sdkconfig file.

MNET32_WIFI_STA_MAX_CONNECTION_ATTEMPTS

The maximum number of connection attempts for station mode.

After this number is reached, the component will launch the access point.

This is part of the component’s configuration and can be adjusted using ESP-IDF’s menuconfig or editing the sdkconfig file.

MNET32_WIFI_STA_THRESHOLD_AUTH

Set a minimum required WiFi security while scanning for networks.

This has to be a valid value of wifi_auth_mode_t, as specified in ESP-IDF’s esp_wifi_types.h:

  • WIFI_AUTH_OPEN

  • WIFI_AUTH_WEP

  • WIFI_AUTH_WPA_PSK

  • WIFI_AUTH_WPA2_PSK

  • WIFI_AUTH_WPA_WPA2_PSK

  • WIFI_AUTH_WPA2_ENTERPRISE

  • WIFI_AUTH_WPA3_PSK

  • WIFI_AUTH_WPA2_WPA3_PSK

  • WIFI_AUTH_WAPI_PSK

  • WIFI_AUTH_MAX

This is part of the component’s configuration, but can only be adjusted by modifying the actual header file mnet32.h.

MNET32_WIFI_STA_THRESHOLD_RSSI

Set a minimum required WiFi signal strength while scanning for networks.

Internally, ESP-IDF handle the RSSI as a signed int8, so -127 is the minimally available signal quality.

This is part of the component’s configuration, but can only be adjusted by modifying the actual header file mnet32.h.

Events

The component emits several specific events to ESP-IDF’s default event loop. The component’s event base is MNET32_EVENTS and the following events are defined:

enum mnet32_events

Define the actual component-specific events that will be emitted.

Values:

enumerator MNET32_EVENT_UNAVAILABLE

Emitted before the component terminates the network connectivity.

This event is emitted without event-specific data.

enumerator MNET32_EVENT_READY

Emitted when network connectivity is available.

The event is emitted in the following cases:

  • the component could successfully establish a connection to a WiFi network;

  • the component has successfully started its internal access point.

Functions

esp_err_t mnet32_start(void)

The component’s entry point.

This function is meant to be called from the actual application and will take care of setting up the network, depending on configuration values.

Internally, the component will launch a dedicated task, which is meant to establish and maintain network connectivity or provide a fallback, providing an access point to keep the configuration web interface accessible.

Returns

esp_err_t ESP_OK if the network could be initialized, ESP_FAIL in all other cases.

esp_err_t mnet32_stop(void)

Stop all networking and free resources.

Returns

esp_err_t Always returns ESP_OK.

void mnet32_web_attach_handlers(void *arg, esp_event_base_t event_base, int32_t event_id, void *event_data)

Handle the event, that the http server is ready to accept further URI handlers.

This is a specific handler, that does not actually parse or verify the event, that triggered its execution.

This requires the calling code, or more specifically, the code that connects this handler with events, to specifically select the events, that should make this component register its specific URI handlers.

Parameters

  • arg – Generic arguments.

  • event_base – esp_event’s EVENT_BASE. Every event is specified by the EVENT_BASE and its EVENT_ID.

  • event_id – esp_event’s EVENT_ID. Every event is specified by the EVENT_BASE and its EVENT_ID.

  • event_data – Events might provide a pointer to additional, event-related data. This handler assumes, that the provided arg is an actual http_handle_t* to the http server instance.

Internal API

Internally, the component is split into several modules (combinations of source and internal header files).

All of these modules are documented in the source code.