APROVISIONAMIENTO

1. PROTOCOLO DE COMUNICACIÓN

1.1 Descripción General

El componente protocomm (Protocol Communication) administra las sesiones de

manera segura y proporciona un marco de trabajo para múltiples transportes. La
aplicación también puede usar la capa de protocomm directamente para tener
extensiones específicas de la aplicación para los casos de uso de aprovisionamiento
(o no aprovisionamiento).

Las siguientes características están disponibles para el aprovisionamiento:

 Seguridad de la comunicación a nivel de aplicación.

o protocomm_security0 (sin seguridad).
o protocomm_security1 (curve25519 Intercambio de Claves + Cifrado AES-
CTR).
 Proof-of-possession (Soporte solo con protocomm_security1).

Protocomm utiliza internamente protobuf (protocol buffers, en español búferes de

protocolo) para el establecimiento seguro de sesiones. Aunque los usuarios pueden
implementar su propia seguridad (incluso sin usar protobuf). Incluso se puede usar
protocomm sin ninguna capa de seguridad.

Protocomm proporciona un marco de trabajo para varios transportes: WiFi (SoftAP +

HTTPD), BLE y consola (en cuyo caso la invocación del controlador se realiza
automáticamente en el lado del dispositivo).

Tenga en cuenta que el cliente necesita establecer la sesión (solo para

protocomm_security1) realizando el apretón de manos bidireccional. Consulte
Aprovisionamiento Unificado para obtener más información sobre la lógica de
protocolo de enlace seguro.

1.2 Ejemplo de Transporte (SoftAP + HTTP) con Seguridad 1

1.3 Ejemplo de Transporte (BLE) con Seguridad 0

1.4 Referencia de la API

2. APROVISIONAMIENTO UNIFICADO

2.1 Descripción General

El soporte de aprovisionamiento unificado en ESP-IDF proporciona un mecanismo

extensible a los desarrolladores para configurar el dispositivo con las credenciales de
Wi-Fi y/u otra configuración personalizada utilizando varios transportes y diferentes
esquemas de seguridad. Dependiendo del caso de uso, proporciona una solución
completa y lista para el aprovisionamiento de redes Wi-Fi junto con aplicaciones de
ejemplo para iOS y Android. O bien, los desarrolladores pueden ampliar las
implementaciones del lado del dispositivo y del lado de la aplicación telefónica para
adaptarse a sus requisitos para enviar datos de configuración adicionales.

Las siguientes son las características importantes de esta implementación:

1. Protocolo Extensible: El protocolo es completamente flexible y ofrece la
capacidad para que los desarrolladores envíen una configuración personalizada
en el proceso de aprovisionamiento. La representación de datos también se deja
a la aplicación para que decida.
2. Flexibilidad de Transporte: El protocolo puede funcionar en Wi-Fi (softap +
Servidor HTTP) o en BLE como protocolo de transporte. El marco de trabajo
proporciona la capacidad de agregar soporte para cualquier otro transporte
fácilmente, siempre y cuando el comportamiento de comando-respuesta se
pueda admitir en el transporte.
3. Flexibilidad del Esquema de Seguridad: Se entiende que cada caso de uso puede
requerir un esquema de seguridad diferente para proteger los datos que se
intercambian en el proceso de aprovisionamiento. Algunas aplicaciones pueden
funcionar con SoftAP que está protegido por WPA2 o BLE con seguridad "just-
works". O bien, las aplicaciones pueden considerar que el transporte es inseguro
y pueden querer seguridad a nivel de aplicación. El marco de aprovisionamiento
unificado permite a la aplicación elegir la seguridad que considere adecuada.
4. Representación de datos compacta: el protocolo utiliza “Google Protobufs” como
representación de datos para la configuración de sesiones y el aprovisionamiento
de Wi-Fi. Proporcionan una representación de datos compacta y la capacidad de
analizar los datos en múltiples lenguajes de programación en formato nativo.
Tenga en cuenta que esta representación de datos no se aplica a los datos
específicos de la aplicación y los desarrolladores pueden elegir la representación
de su elección.

2.2 Proceso de Aprovisionamiento Típico

 Figura 1: Proceso de Aprovisionamiento Típico

2.3 Decidir sobre el Transporte

El subsistema de aprovisionamiento unificado admite esquemas de transporte Wi-Fi
(SoftAP + HTTP Server) y BLE (basado en GATT). Los siguientes puntos deben
tenerse en cuenta al seleccionar el mejor transporte posible para el
aprovisionamiento.

1. El transporte basado en BLE tiene la ventaja de que en el proceso de

aprovisionamiento, el canal de comunicación BLE permanece intacto entre el
dispositivo y el cliente. Eso proporciona retroalimentación de aprovisionamiento
confiable.
2. La implementación de aprovisionamiento basada en BLE hace que la experiencia
del usuario sea mejor desde las aplicaciones del teléfono, ya que en Android e
iOS, la aplicación del teléfono puede descubrir y conectarse al dispositivo sin
necesidad de que el usuario salga de la aplicación del teléfono
3. Sin embargo, el transporte BLE consume aproximadamente 110 KB de memoria
en tiempo de ejecución. Si el producto no utiliza la funcionalidad BLE o BT
después de realizar el aprovisionamiento, casi toda la memoria se puede
recuperar y se puede agregar al montón.
4. El transporte basado en SoftAP es altamente interoperable; sin embargo, como la
misma radio se comparte entre las interfaces SoftAP y Station, el transporte no es
confiable en la fase en que se intenta la conexión Wi-Fi a un AP externo.
Además, el cliente puede volver a una red diferente cuando el SoftAP cambia el
canal en el momento de la conexión de la Station.
5. El transporte SoftAP no requiere mucha memoria adicional para los casos de uso
de Wi-Fi
6. El aprovisionamiento basado en SoftAP requiere que el usuario de la aplicación
telefónica vaya a "Configuración del sistema" para conectarse a la red Wi-Fi
alojada por el dispositivo en caso de iOS. La API de descubrimiento (escaneo) y
conexión no están disponibles para las aplicaciones de iOS.
2.4 Decidir sobre la Seguridad

Dependiendo del transporte y otras restricciones, los desarrolladores de la aplicación

deben seleccionar el esquema de seguridad. Se deben tener en cuenta las
siguientes consideraciones desde la perspectiva de la seguridad de
aprovisionamiento:

 Los datos de configuración enviados desde el cliente al dispositivo y la respuesta

deben estar protegidos.
 El cliente debe autenticar el dispositivo al que está conectado.
 El fabricante del dispositivo puede elegir proof-of-possession (una clave secreta
única por dispositivo que se introducirá en el cliente de aprovisionamiento como
medida de seguridad para asegurarse de que el usuario pueda aprovisionar el
dispositivo en posesión).

Hay dos niveles de esquemas de seguridad. El desarrollador puede seleccionar uno

o una combinación dependiendo de los requisitos.

1. Seguridad de Transporte: El aprovisionamiento de SoftAP puede elegir la

seguridad protegida WPA2 con una frase de contraseña única por dispositivo. La
frase de contraseña única por dispositivo también puede actuar como una proof-
of-possession. Para BLE, la seguridad "just-works" se puede utilizar como una
seguridad de nivel de transporte después de comprender el nivel de seguridad
que proporciona.
2. Seguridad de la Aplicación: El subsistema de aprovisionamiento unificado
proporciona seguridad de nivel de aplicación (seguridad1) que proporciona
protección de datos y autenticación (mediante proof-of-possession) si la
aplicación no utiliza la seguridad de nivel de transporte o si la seguridad de nivel
de transporte no es suficiente para el caso de uso.
2.5 Detección de Dispositivos

El anuncio y el descubrimiento del dispositivo se dejan a la aplicación y,

dependiendo del protocolo elegido, las aplicaciones del teléfono y la aplicación del
firmware del dispositivo pueden elegir el método apropiado para anunciar y
descubrir.

Para el transporte SoftAP + HTTP, normalmente se puede utilizar el SSID (nombre

de red) del AP hospedado por el dispositivo para la detección.

Para el dispositivo de transporte BLE, el nombre o el servicio principal incluido en el

anuncio o la combinación de ambos se puede utilizar para la detección.

2.6 Arquitectura

El siguiente diagrama muestra la arquitectura del aprovisionamiento unificado.

Figura 2: Arquitectura de Aprovisionamiento Unificado

Se basa en la capa base llamada protocomm (Protocolo de Comunicación) que

proporciona un marco de trabajo para esquemas de seguridad y mecanismos de
transporte. La capa de aprovisionamiento de Wi-Fi utiliza Protocomm para
proporcionar devoluciones de llamada simples a la aplicación para establecer la
configuración y obtener el estado de Wi-Fi. La aplicación tiene control sobre la
implementación de estas devoluciones de llamada. Además, la aplicación puede
usar directamente protocomm para registrar controladores personalizados.

La aplicación crea una instancia de protocomm que se asigna a un transporte

específico y un esquema de seguridad específico. Cada transporte en protocomm
tiene un concepto de "punto final" que corresponde al canal lógico de comunicación
para un tipo específico de información. Por ejemplo, el protocolo de enlace de
seguridad ocurre en un punto de conexión diferente al punto de conexión de
configuración de Wi-Fi. Cada punto final se identifica mediante una cadena y,
dependiendo de la representación interna de transporte del punto final, cambia. En el
caso del transporte SoftAP+HTTP, el punto final corresponde a URI, mientras que en
el caso de BLE, el punto final corresponde a la característica GATT con UUID
específico. Los desarrolladores pueden crear puntos finales personalizados e
implementar controladores para los datos que se reciben o envían a través del
mismo punto final.

2.7 Esquemas de Seguridad

En la actualidad, el aprovisionamiento unificado admite dos esquemas de seguridad:

1. Seguridad0: Sin seguridad (sin cifrado).

2. Seguridad1: Intercambio de claves basado en Curve25519, derivación de clave
compartida y cifrado de los datos en modo AES256-CTR.

Soporta dos modos:

Soporta dos modos:

 Autorizado: cadena de prueba de posesión (PoP) utilizada para autorizar la
sesión y derivar la clave compartida.
 Sin autenticación (PoP nulo): clave compartida derivada solo a través del
intercambio de claves.

Los detalles del esquema Security1 se muestran en el siguiente diagrama de

secuencia.

Figura 3: Security1
2.8 Código de Ejemplo

Consulte Protocolo de Comunicación y Aprovisionamiento de Wi-Fi para obtener

guías de la API y fragmentos de código sobre el uso de ejemplos.

La implementación de aplicaciones se puede encontrar como ejemplo en:

“esp-idf/examples/provisioning”

2.9 Herramientas de Aprovisionamiento

Las aplicaciones de aprovisionamiento están disponibles para varias plataformas,

junto con el código fuente:

Android:

 BLE Provisioning app on Play Store.

 SoftAP Provisioning app on Play Store.
 Source code on GitHub: esp-idf-provisioning-android.

iOS:

 BLE Provisioning app on app store.

 SoftAP Provisioning app on app Store.
 Source code on GitHub: esp-idf-provisioning-ios.

Linux/MacOS/Windows: tools/esp_prov (Una herramienta de línea de comandos

basada en Python para el aprovisionamiento)

Las aplicaciones de teléfono ofrecen una interfaz de usuario simple y, por lo tanto,
más centrada en el usuario, mientras que la aplicación de línea de comandos es útil
como herramienta de depuración para los desarrolladores.
3. APROVISIONAMIENTO DE WI-FI

3.1 Descripción General

Este componente proporciona APIs que controlan el servicio de aprovisionamiento

de Wi-Fi para recibir y configurar credenciales de Wi-Fi a través del transporte
SoftAP o BLE a través de sesiones seguras de protocomm. Las API wifi_prov_mgr_
ayuda a implementar rápidamente un servicio de aprovisionamiento que tiene las
características necesarias con una cantidad mínima de código y suficiente
flexibilidad.

3.1.1 Inicialización

Para configurar e inicializar el administrador de aprovisionamiento se utiliza la API

wifi_prov_mgr_init(), por lo tanto, se debe llamar a este antes de invocar cualquier
otra API wifi_prov_mgr_. Tenga en cuenta que el administrador se basa en otros
componentes de IDF, a saber, NVS, TCP/IP, Event Loop y Wi-Fi (y opcionalmente
mDNS), por lo tanto, estos deben inicializarse de antemano. El administrador puede
ser cancelar la inicialización en cualquier momento haciendo una llamada a la API
wifi_prov_mgr_deinit().

wifi_prov_mgr_config_t config = {

.scheme = wifi_prov_scheme_ble,

.scheme_event_handler = WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BTDM

};

ESP_ERROR_CHECK( wifi_prov_mgr_init(config) );

La estructura de configuración wifi_prov_mgr_config_t tiene algunos campos para

especificar el comportamiento deseado del administrador.

Scheme
Esto se utiliza para especificar el esquema de aprovisionamiento. Cada esquema
corresponde a uno de los modos de transporte soportados por protocomm. Por lo
tanto, tenemos tres opciones:

 wifi_prov_scheme_ble
 wifi_prov_scheme_softap
 wifi_prov_scheme_console

scheme_event_handler

Un controlador de eventos definido junto con el esquema. La elección del controlador

de eventos específico del esquema adecuado permite al administrador ocuparse de
ciertos asuntos automáticamente. Actualmente, esto no se utiliza para el
aprovisionamiento basado en SoftAP o consola, pero es muy conveniente para BLE.
Para entender cómo, debemos recordar que Bluetooth requiere bastante cantidad de
memoria para funcionar y una vez finalizado el aprovisionamiento, la aplicación
principal puede querer recuperar esta memoria (o parte de ella, si necesita usar BLE
o BT clásico). Además, en cada reinicio futuro de un dispositivo aprovisionado, esta
recuperación de memoria debe realizarse nuevamente. Para reducir esta
complicación en el uso de wifi_prov_scheme_ble, se han definido los controladores
específicos del esquema y, dependiendo del controlador elegido, la memoria BLE /
BT clásica / BTDM se liberará automáticamente cuando se desinicie el administrador
de aprovisionamiento. Las opciones disponibles son:

WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BTDM: Memoria BT y BLE

clásica (BTDM) libre. Se utiliza cuando la aplicación principal no requiere Bluetooth
en absoluto.

WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BLE: Memoria BLE

gratuita. Se utiliza cuando la aplicación principal requiere BT clásico.
WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BT: BT clásico gratuito. Se
utiliza cuando la aplicación principal requiere BLE. En este caso, la liberación ocurre
justo cuando se inicializa el administrador.

WIFI_PROV_EVENT_HANDLER_NONE: No utilice ningún controlador específico del

esquema. Se utiliza cuando el esquema de aprovisionamiento no es BLE (es decir,
SoftAP o Consola), o cuando la aplicación principal quiere manejar la recuperación
de memoria por sí sola, o necesita tanto BLE como BT clásico para funcionar.

app_event_handler (Obsoleto)

Ahora se recomienda capturar WIFI_PROV_EVENT que se emite al controlador de

bucle de eventos predeterminado. Consulte la enumeración
wifi_prov_cb_event_t para obtener la lista de eventos generados por el servicio de
aprovisionamiento. Aquí hay un extracto que muestra algunos de los eventos de
aprovisionamiento:

static void event_handler(void *arg, esp_event_base_t event_base,

                          int event_id, void *event_data)
{
    if (event_base == WIFI_PROV_EVENT)
    {
        switch (event_id)
        {
        case WIFI_PROV_START:
            ESP_LOGI(TAG, " Inicio del Aprovisionamiento");
            break;
        case WIFI_PROV_CRED_RECV:
        {
            wifi_sta_config_t *wifi_sta_cfg = (wifi_sta_config_t *)event_data;
            ESP_LOGI(TAG, "Received Wi-Fi credentials"
                          "\n\tSSID     : %s\n\tPassword : %s",
                     (const char *)wifi_sta_cfg->ssid,
                     (const char *)wifi_sta_cfg->password);
            break;
        }
        case WIFI_PROV_CRED_FAIL:
        {
            wifi_prov_sta_fail_reason_t *reason = (wifi_prov_sta_fail_reason_t
*)event_data;
            ESP_LOGE(TAG, "Provisioning failed!\n\tReason : %s"
                          "\n\tPlease reset to factory and retry
provisioning",
                     (*reason == WIFI_PROV_STA_AUTH_ERROR) ? "Wi-Fi station
authentication failed" : "Wi-Fi access-point not found");
            break;
        }
        case WIFI_PROV_CRED_SUCCESS:
            ESP_LOGI(TAG, "Provisioning successful");
            break;
        case WIFI_PROV_END:
            /* De-initialize manager once provisioning is finished */
            wifi_prov_mgr_deinit();
            break;
        default:
            break;
        }
    }
}

El administrador puede cancelar la inicialización en cualquier momento haciendo una

llamada a wifi_prov_mgr_deinit().

3.1.2 Comprobación del Estado de Aprovisionamiento

Si el dispositivo está aprovisionado o no, se puede comprobar en tiempo de

ejecución llamando a la API wifi_prov_mgr_is_provisioned(). Esto comprueba
internamente si las credenciales de Wi-Fi están almacenadas en NVS.

Tenga en cuenta que actualmente el administrador no tiene su propio espacio de

nombres NVS para el almacenamiento de credenciales de Wi-Fi, sino que se basa
en las API de esp_wifi_ para establecer y obtener las credenciales almacenadas en
NVS desde la ubicación predeterminada.

Si es necesario restablecer el estado de aprovisionamiento, se puede adoptar

cualquiera de los siguientes métodos:
 La parte asociada de la partición NVS debe borrarse manualmente.
 La aplicación principal debe implementar alguna lógica para llamar a la API
esp_wifi_ para borrar las credenciales en tiempo de ejecución.
 La aplicación principal debe implementar alguna lógica para forzar el inicio del
aprovisionamiento, independientemente del estado de aprovisionamiento.

bool provisioned = false;

ESP_ERROR_CHECK(wifi_prov_mgr_is_provisioned(&provisioned));

3.1.3 Iniciar el Servicio de Aprovisionamiento

En el momento de iniciar el aprovisionamiento necesitamos especificar un nombre de

servicio y la clave correspondiente. Estos se traducen en:

 wifi_prov_scheme_softap: SSID y contraseña.

 wifi_prov_scheme_ble: Nombre del dispositivo BLE (se omite la clave de
servicio).

Además, dado que internamente el gestor utiliza protocomm, tenemos la opción de

elegir una de las características de seguridad que nos proporciona:

 La seguridad 1 es una comunicación segura que consiste en un apretón de

manos previo que involucra el intercambio de claves X25519 junto con la
autenticación utilizando POP, seguida de AES-CTR para el cifrado/descifrado de
mensajes posteriores.
 La seguridad 0 es simplemente comunicación de texto sin formato. En este caso,
el POP simplemente se ignora.

Consulte Aprovisionamiento Unificado para obtener más información sobre las

características de seguridad.
const char *service_name = "my_device";
const char *service_key = "password";

wifi_prov_security_t security = WIFI_PROV_SECURITY_1;

const char *pop = "abcd1234";

ESP_ERROR_CHECK(wifi_prov_mgr_start_provisioning(security,
                                                 pop,
                                                 service_name,
                                                 service_key));

El servicio de aprovisionamiento finalizará automáticamente solo si recibe

credenciales válidas de Wi-Fi AP seguidas de la conexión correcta del dispositivo al
AP (IP obtenida). Independientemente de eso, el servicio de aprovisionamiento se
puede detener en cualquier momento haciendo una llamada a la API
wifi_prov_mgr_stop_provisioning().

Nota: Si el dispositivo no se conecta con las credenciales proporcionadas, ya no

aceptará nuevas credenciales, pero el servicio de aprovisionamiento seguirá
ejecutándose (solo para transmitir el error al cliente), hasta que se reinicie el
dispositivo. Al reiniciar, el estado de aprovisionamiento resultará ser verdadero esta
vez (ya que las credenciales se encontrarán en NVS), pero el dispositivo volverá a
no conectarse con esas mismas credenciales (a menos que un AP con las
credenciales coincidentes de alguna manera esté disponible). Esta situación se
puede solucionar restableciendo las credenciales en NVS o forzando el inicio del
servicio de aprovisionamiento. Esto se ha explicado anteriormente en Comprobación
del Estado de Aprovisionamiento.

3.1.4 Espera de Finalización

Normalmente, la aplicación principal esperará a que finalice el aprovisionamiento,

luego des inicializará el administrador para liberar recursos y finalmente comenzará a
ejecutar su propia lógica. Hay dos maneras de hacer esto posible.
La forma más sencilla es usar una llamada de bloqueo como la API
wifi_prov_mgr_wait():

// Iniciar el servicio de aprovisionamiento

ESP_ERROR_CHECK(wifi_prov_mgr_start_provisioning(
    security, pop,
    service_name,
    service_key));

// Espere a que se complete el servicio

wifi_prov_mgr_wait();

// Finalmente desinicializar el gestor

wifi_prov_mgr_deinit();

La otra forma es usar el controlador de bucle de eventos predeterminado para

capturar WIFI_PROV_EVENT y ejecutar la API wifi_prov_mgr_deinit(), solo si el
identificador del evento es ''WIFI_PROV_END:

static void event_handler(void *arg,

                          esp_event_base_t event_base,
                          int event_id,
                          void *event_data)
{
    if (event_base == WIFI_PROV_EVENT && event_id == WIFI_PROV_END)
    {
        /* De-initialize manager once provisioning is finished */
        wifi_prov_mgr_deinit();
    }
}

3.1.5 Puntos Finales Adicionales

En caso de que los usuarios quieran tener algunos puntos finales de protocomm
adicionales personalizados según sus requisitos, esto se hace en dos pasos. El
primero es la creación de un punto de enlace con un nombre específico, y el
segundo paso es el registro de un controlador para este punto de enlace. Consulte
protocomm para la firma de función de un controlador de extremo. Se debe crear un
extremo personalizado después de la inicialización y antes de iniciar el servicio de
aprovisionamiento. Mientras que, el controlador de protocomm se registra para este
extremo solo después de iniciar el servicio de aprovisionamiento.

3.2 Referencia de la API

3.2.1 Archivo de Encabezado

components/wifi_provisioning/include/wifi_provisioning/manager.h

3.2.2 Funciones

esp_err_t wifi_prov_mgr_init (wifi_prov_mgr_config_t config)

Inicialice la instancia del administrador de aprovisionamiento. Configura el gestor y

asigna recursos internos. La configuración especifica el esquema de
aprovisionamiento (transporte) y los controladores de eventos. Se emite el evento
WIFI_PROV_INIT justo después de que se completa la inicialización.

Return:

 ESP_OK : Success
 ESP_FAIL : Fail

Parámetros:

 [in] config: Estructura de Configuración.

void wifi_prov_mgr_deinit (void)

Stop provisioning (if running) and release resource used by the manager.

Detiene el aprovisionamiento (si se está ejecutando) y libera los recursos utilizados

por el gestor.
El evento WIFI_PROV_DEINIT se emite inmediatamente después de finalizar la
cancelación de la inicialización.

Si el servicio de aprovisionamiento sigue activo cuando se llama a esta API, primero

detiene el servicio, por lo tanto, emite el evento WIFI_PROV_END y, a continuación,
realiza cancelación de la inicialización.

esp_err_t wifi_prov_mgr_is_provisioned (bool *provisioned)

Comprueba si el dispositivo está aprovisionado.

Esto comprueba si las credenciales de Wi-Fi están presentes en el NVS.

Se supone que las credenciales de Wi-Fi se mantienen en el mismo espacio de

nombres NVS que usa el componente esp_wifi.

Si se llamara a esp_wifi_set_config() directamente en lugar de pasar por el proceso

de aprovisionamiento, esta función seguirá siendo verdadera (es decir, se encontrará
que el dispositivo está aprovisionado)

Nota: Llamar a la API wifi_prov_mgr_start_provisioning() restablece

automáticamente el estado de la provisión, independientemente de cuál era el
estado antes de realizar la llamada.

Return:

 ESP_OK: Estado de aprovisionamiento recuperado correctamente.

 ESP_FAIL: Wi-Fi no inicializado.
 ESP_ERR_INVALID_ARG: Argumento nulo proporcionado.
 ESP_ERR_INVALID_STATE: Administrador no inicializado.

Parámetros:

[out] provisioned: True si se aprovisiona, de lo contrario false.

esp_err_t wifi_prov_mgr_start_provisioning (
wifi_prov_security_t security,
const char *pop,
const char *service_name,
const char *service_key
)

Esta API inicia el servicio de aprovisionamiento de acuerdo con el esquema

configurado en el momento de la inicialización. Para el esquema:

 wifi_prov_scheme_ble: Esto inicia protocomm_ble, que inicializa internamente el

transporte BLE e inicia el servidor GATT para controlar las solicitudes de
aprovisionamiento.
 wifi_prov_scheme_softap: Esto activa el modo SoftAP de Wi-Fi e inicia
protocomm_httpd, que internamente inicia un servidor HTTP para manejar las
solicitudes de aprovisionamiento (si mDNS está activo, también inicia el servicio
de publicidad con el tipo _esp_wifi_prov._tcp).

El evento WIFI_PROV_START se emite inmediatamente después de que se inicia el

aprovisionamiento sin errores.

Nota: Esta API comenzará a aprovisionar el servicio incluso si se descubre que el

dispositivo ya está aprovisionado, es decir, wifi_prov_mgr_is_provisioned() produce
true.

Return:

 ESP_OK: El aprovisionamiento comenzó correctamente.

 ESP_FAIL: Error al iniciar el servicio de aprovisionamiento.
 ESP_ERR_INVALID_STATE: Administrador de aprovisionamiento no
inicializado o ya iniciado.

Parámetros:

[in] security: Especifica el esquema de seguridad de protocomm a utilizar.

 WIFI_PROV_SECURITY_0: Sin seguridad.

 WIFI_PROV_SECURITY_1: Protocolo de enlace seguro x25519 para el
establecimiento de sesiones seguido de cifrado AES-CTR de mensajes de
 aprovisionamiento.

[in] pop: Puntero a la cadena de prueba de posesión (NULL si no es necesario).

Esto es relevante solo para protocomm security 1, en cuyo caso se utiliza para
autenticar una sesión segura.

[in] service_name: Nombre único del servicio. Esto se traduce en Wi-Fi SSID
cuando el modo de aprovisionamiento es softAP o en el nombre del dispositivo
cuando el modo de aprovisionamiento es BLE.

[in] service_key: Clave requerida por el cliente para acceder al servicio (NULL si no
es necesario). Esto se traduce en la contraseña de Wi-Fi cuando el modo de
aprovisionamiento es softAP y se ignora cuando el modo de aprovisionamiento es
BLE.

void wifi_prov_mgr_stop_provisioning (void)

Detiene el servicio de aprovisionamiento.

Si el servicio de aprovisionamiento está activo, esta API iniciará un proceso para

detener el servicio y retornar. Una vez que el servicio se detenga realmente, se
emitirá el evento WIFI_PROV_END.

Si se llama a la API wifi_prov_mgr_deinit() sin llamar primero a esta API, detendrá

automáticamente el servicio de aprovisionamiento y emitirá el evento
WIFI_PROV_END, seguido del evento WIFI_PROV_DEINIT, antes de regresar.

Esta API se usa generalmente junto con la API wifi_prov_mgr_disable_auto_stop()

en el escenario en que la aplicación principal haya registrado sus propios puntos de
conexión y desee que el servicio de aprovisionamiento se detenga solo cuando se
reciba algún comando de protocomm de la aplicación del lado cliente.

Llamar a esta API dentro de un controlador de punto final, con suficiente

cleanup_delay, permitirá que la respuesta/confirmación se envíe correctamente
antes de que se detenga el servicio protocomm subyacente.

Cleaup_delay se establece al llamar a wifi_prov_mgr_disable_auto_stop(). Si no

se especifica, el valor predeterminado es 1000ms.

Para casos sencillos, el uso de esta API generalmente no es necesario, ya que el

aprovisionamiento se detiene automáticamente una vez que se emite
WIFI_PROV_CRED_SUCCESS. La detención se retrasa (máximo 30 segundos), lo
que permite que la aplicación del lado del cliente consulte el estado de Wi-Fi, es
decir, después de recibir la primera consulta y enviar la respuesta conectada al
estado de Wi-Fi, el servicio se detiene inmediatamente.

void wifi_prov_mgr_wait (void)

Espere a que finalice el servicio de aprovisionamiento. Llamar esta API bloqueará las
demás tareas hasta que se detenga el servicio de aprovisionamiento, es decir, hasta
que se emita el evento WIFI_PROV_END. Esto no bloqueará las demás tareas si el
aprovisionamiento no se inicia o no se inicializa.

3.2.3 Estructuras

struct wifi_prov_mgr_config_t

Estructura para especificar la configuración del administrador.

Miembros Públicos:

wifi_prov_scheme_t scheme
Esquema de aprovisionamiento a utilizar. Los siguientes esquemas ya están
disponibles:

1. wifi_prov_scheme_ble: Aprovisionamiento a través del transporte BLE + servidor

GATT.
2. wifi_prov_scheme_softap: Aprovisionamiento a través del transporte SoftAP +
Servidor HTTP + mDNS (opcional)
3. wifi_prov_scheme_console: Aprovisionamiento a través del transporte serial
UART + Consola (para la depuración).

wifi_prov_event_handler_t scheme_event_handler

Manipulador de eventos requerido por el esquema para incorporar el

comportamiento específico del esquema mientras se ejecuta el administrador de
aprovisionamiento. El esquema puede proporcionar varias opciones para establecer
este campo. Use WIFI_PROV_EVENT_HANDLER_NONE cuando no se use.
Cuando se utilize el esquema wifi_prov_scheme_ble, están disponibles las
siguientes opciones:

1. WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BTDM
2. WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BLE
3. WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BT

wifi_prov_event_handler_t app_event_handler

Manipulador de eventos que se puede establecer con el fin de incorporar el

comportamiento específico de la aplicación. Use
WIFI_PROV_EVENT_HANDLER_NONE cuando no se use.
4. CONFIGURACIÓN INTELIGENTE

5. WI-FI EASY CONNECTTM (DPP)

6. GLOSARIO

Proof-of-possession (POP, en español Prueba de Posesión) es un medio para probar

que una parte que envía un mensaje está en posesión de una clave criptográfica en
particular. Esto se utiliza como prueba de que la parte correcta está enviando el
mensaje, bajo el supuesto de que solo ese remitente tiene la posesión de la clave.