ESP-IDF

https://docs.espressif.com/projects/esp-idf/en/latest/
Admin
ESP-IDF is the official development framework for Espressif's ESP32 and related SoC series,...
Tokens:3,168
Snippets:23
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### Start DPP Listening (C)

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_dpp

Starts listening on the channels specified during the `esp_supp_dpp_bootstrap_gen` call. It listens on each channel for a predefined duration. Returns ESP_OK on success, or an error code if the state is invalid or memory allocation fails.

```c
esp_err_t esp_supp_dpp_start_listen(void);
```

--------------------------------

### Wi-Fi Easy Connect (DPP) Listening Operations

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_dpp

APIs for starting and stopping listening for DPP provisioning requests.

```APIDOC
## esp_supp_dpp_start_listen

### Description
Starts listening on the channels provided during `esp_supp_dpp_bootstrap_gen`. The device listens on every channel from the channel list for a predefined wait time.

### Method
`esp_err_t esp_supp_dpp_start_listen(void)`

### Return Values
* **ESP_OK**: Success
* **ESP_FAIL**: Generic failure.
* **ESP_ERR_INVALID_STATE**: ROC attempted before Wi-Fi is started.
* **ESP_ERR_NO_MEM**: Memory allocation failed while posting ROC request.

---

## esp_supp_dpp_stop_listen

### Description
Stops listening on channels and cancels the ongoing listen operation.

### Method
`esp_err_t esp_supp_dpp_stop_listen(void)`

### Return Values
* **ESP_OK**: Success
* **ESP_FAIL**: Failure.
```

--------------------------------

### Wi-Fi Easy Connect (DPP) Initialization and Deinitialization

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_dpp

APIs for initializing and de-initializing the DPP Supplicant.

```APIDOC
## esp_supp_dpp_init

### Description
Initializes the DPP Supplicant and related data structures.

### Method
`esp_err_t esp_supp_dpp_init(esp_supp_dpp_event_cb_t evt_cb)`

### Parameters
* **evt_cb** (esp_supp_dpp_event_cb_t) - Deprecated: Callback function to receive DPP related events. This parameter is ignored in future IDF versions. Directly register for WiFi events to get DPP events.

### Return Values
* **ESP_OK**: Success
* **ESP_FAIL**: Failure

---

## esp_supp_dpp_deinit

### Description
De-initializes the DPP Supplicant and frees memory from DPP Supplicant Data Structures.

### Method
`esp_err_t esp_supp_dpp_deinit(void)`

### Return Values
* **ESP_OK**: Success
* **ESP_FAIL**: Failure
```

--------------------------------

### Wi-Fi Easy Connect (DPP) Bootstrap Generation

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_dpp

API for generating bootstrap information as an Enrollee.

```APIDOC
## esp_supp_dpp_bootstrap_gen

### Description
Generates Out Of Band Bootstrap information as an Enrollee, which can be used by a DPP Configurator to provision the Enrollee. This method supports the QR Code provisioning method.

### Method
`esp_err_t esp_supp_dpp_bootstrap_gen(const char *chan_list, esp_supp_dpp_bootstrap_t type, const char *key, const char *info)`

### Parameters
* **chan_list** (const char *) - List of channels the device will be available on for listening.
* **type** (esp_supp_dpp_bootstrap_t) - Bootstrap method type. Only the QR Code method is supported.
* **key** (const char *) - Optional: 32-byte Raw Private Key for generating a Bootstrapping Public Key.
* **info** (const char *) - Optional: Ancillary Device Information like Serial Number.

### Return Values
* **ESP_OK**: Success
* **ESP_ERR_DPP_INVALID_LIST**: Channel list is not valid.
* **ESP_FAIL**: Generic failure.
```

--------------------------------

### DPP Enumerations

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_dpp

Lists the enumerations for DPP bootstrap types and events.

```APIDOC
## DPP Enumerations

### Description
Provides enumerations for DPP bootstrap methods and supplicant events.

### Enumerations

- **dpp_bootstrap_type**
  - Description: Types of Bootstrap Methods for DPP.
  - Values:
    - **DPP_BOOTSTRAP_QR_CODE**: QR Code Method
    - **DPP_BOOTSTRAP_PKEX**: Proof of Knowledge Method
    - **DPP_BOOTSTRAP_NFC_URI**: NFC URI record Method

- **esp_supp_dpp_event_t**
  - Description: Types of Callback Events received from DPP Supplicant.
  - Values:
    - **ESP_SUPP_DPP_URI_READY**: URI is ready through Bootstrapping
    - **ESP_SUPP_DPP_CFG_RECVD**: Config received via DPP Authentication
    - **ESP_SUPP_DPP_PDR_RECVD**: Peer Discovery Response is received
    - **ESP_SUPP_DPP_FAIL**: DPP Authentication failure
```

--------------------------------

### Initialize DPP Supplicant (C)

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_dpp

Initializes the DPP Supplicant and its associated data structures. The `evt_cb` parameter is deprecated and will be ignored in future versions; events should be registered directly.

```c
esp_err_t esp_supp_dpp_init(esp_supp_dpp_event_cb_t evt_cb);
```

--------------------------------

### ESP-IDF DPP Bootstrap Methods Enumeration

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_dpp

Enumerates the different methods that can be used for DPP bootstrapping. These include the QR Code Method, Proof of Knowledge Method, and NFC URI record Method.

```c
enum dpp_bootstrap_type {
    DPP_BOOTSTRAP_QR_CODE,
    DPP_BOOTSTRAP_PKEX,
    DPP_BOOTSTRAP_NFC_URI
};
```

--------------------------------

### DPP Type Definitions

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_dpp

Defines the data types and callback functions used in the DPP API.

```APIDOC
## DPP Type Definitions

### Description
Defines key data structures and callback function signatures for DPP interactions.

### Type Definitions

- **esp_supp_dpp_bootstrap_t** (enum dpp_bootstrap_type)
  - Description: Types of Bootstrap Methods for DPP.

- **esp_supp_dpp_event_cb_t** (callback function)
  - Description: Callback function for receiving DPP Events from Supplicant.
  - Parameters:
    - **evt**: (esp_supp_dpp_event_t) - DPP event ID
    - **data**: (void *) - Event data payload
```

--------------------------------

### Generate DPP Bootstrap Information (C)

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_dpp

Generates Out-Of-Band bootstrap information as an Enrollee, which can be used by a DPP Configurator for provisioning. Supports QR Code as the bootstrap method and allows optional private key and ancillary information.

```c
esp_err_t esp_supp_dpp_bootstrap_gen(const char *chan_list, esp_supp_dpp_bootstrap_t type, const char *key, const char *info);
```

--------------------------------

### Declare Dependency on wpa_supplicant (CMakeLists.txt)

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_dpp

This snippet demonstrates how to declare a component's dependency on the 'wpa_supplicant' component in a CMakeLists.txt file. This is required to use DPP functionalities provided by the component.

```cmake
REQUIRES wpa_supplicant
```

```cmake
PRIV_REQUIRES wpa_supplicant
```

--------------------------------

### DPP Error Codes

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_dpp

This section lists the various error codes associated with DPP operations.

```APIDOC
## DPP Error Codes

### Description
Provides a list of error codes that can occur during DPP operations.

### Error Codes

- **ESP_ERR_DPP_FAILURE**
  - Description: Generic failure during DPP Operation

- **ESP_ERR_DPP_TX_FAILURE**
  - Description: DPP Frame Tx failed OR not Acked

- **ESP_ERR_DPP_INVALID_ATTR**
  - Description: Encountered invalid DPP Attribute

- **ESP_ERR_DPP_AUTH_TIMEOUT**
  - Description: DPP Auth response was not received in time

- **ESP_ERR_DPP_INVALID_LIST**
  - Description: Channel list given in esp_supp_dpp_bootstrap_gen() is not valid or too big

- **ESP_ERR_DPP_CONF_TIMEOUT**
  - Description: DPP Configuration was not received in time
```

--------------------------------

### De-initialize DPP Supplicant (C)

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_dpp

Frees memory allocated for the DPP Supplicant's data structures, effectively de-initializing the DPP functionality. Returns ESP_OK on success.

```c
esp_err_t esp_supp_dpp_deinit(void);
```

--------------------------------

### Include ESP-IDF DPP Header

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_dpp

This C code snippet shows how to include the necessary header file for Wi-Fi Easy ConnectTM (DPP) functionalities within the ESP-IDF framework. It is part of the wpa_supplicant component.

```c
#include "esp_dpp.h"
```

--------------------------------

### Stop DPP Listening (C)

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_dpp

Stops any ongoing listening operation for DPP bootstrap information and cancels the listen process. Returns ESP_OK on success.

```c
esp_err_t esp_supp_dpp_stop_listen(void);
```

--------------------------------

### ESP-IDF DPP Supplicant Event Types Enumeration

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_dpp

Enumerates the various callback events that can be received from the DPP Supplicant. These events signal different stages or outcomes of DPP operations, such as URI readiness, configuration reception, peer discovery response, and authentication failures.

```c
enum esp_supp_dpp_event_t {
    ESP_SUPP_DPP_URI_READY,
    ESP_SUPP_DPP_CFG_RECVD,
    ESP_SUPP_DPP_PDR_RECVD,
    ESP_SUPP_DPP_FAIL
};
```

--------------------------------

### ESP-IDF DPP Bootstrap and Event Type Definitions

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_dpp

Defines the types of bootstrap methods available for DPP and the callback function signature for receiving DPP events. The bootstrap types include QR Code, Proof of Knowledge, and NFC URI methods. The event callback receives event IDs and associated data.

```c
typedef enum dpp_bootstrap_type esp_supp_dpp_bootstrap_t;
typedef void (*esp_supp_dpp_event_cb_t)(esp_supp_dpp_event_t evt, void *data);
```

--------------------------------

### ESP-IDF DPP Error Codes

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_dpp

Defines various error codes encountered during DPP operations, indicating specific failure points such as general failures, transmission issues, invalid attributes, authentication timeouts, invalid channel lists, and configuration timeouts.

```c
#define ESP_ERR_DPP_FAILURE 0x2A00
#define ESP_ERR_DPP_TX_FAILURE 0x2A01
#define ESP_ERR_DPP_INVALID_ATTR 0x2A02
#define ESP_ERR_DPP_AUTH_TIMEOUT 0x2A03
#define ESP_ERR_DPP_INVALID_LIST 0x2A04
#define ESP_ERR_DPP_CONF_TIMEOUT 0x2A05
```

--------------------------------

### Include NimBLE HCI Header File

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/bluetooth/nimble/index

This snippet shows how to include the necessary header file for the NimBLE HCI layer in your C/C++ project. It also demonstrates how to declare a dependency on the 'bt' component in your CMakeLists.txt file.

```c
#include "esp_nimble_hci.h"
```

```cmake
REQUIRES bt
```

```cmake
PRIV_REQUIRES bt
```

--------------------------------

### Initialize NimBLE Host

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/bluetooth/nimble/index

Initializes the VHCI transport layer between the NimBLE Host and the ESP Bluetooth controller. This function sets up the necessary transport buffers and registers host callbacks with the controller.

```APIDOC
## esp_nimble_hci_init()

### Description
Initializes the VHCI transport layer between NimBLE Host and ESP Bluetooth controller. This function initializes the transport buffers to be exchanged between NimBLE host and ESP controller. It also registers required host callbacks with the controller.

### Method
`esp_err_t esp_nimble_hci_init(void)`

### Endpoint
N/A (Function Call)

### Parameters
None

### Request Example
```c
#include "esp_nimble_hci.h"

// ... application code ...

if (esp_nimble_hci_init() != ESP_OK) {
    // Handle initialization error
}

// ... rest of the application ...
```

### Response
#### Success Response (ESP_OK)
`ESP_OK` indicating successful initialization.

#### Response Example
`ESP_OK`
```

--------------------------------

### Initialize NimBLE HCI Transport Layer

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/bluetooth/nimble/index

This C function initializes the VHCI transport layer between the NimBLE Host and the ESP Bluetooth controller. It sets up transport buffers and registers host callbacks with the controller. The function returns ESP_OK on success or an appropriate error code on failure.

```c
esp_err_t esp_nimble_hci_init(void)
```

--------------------------------

### NimBLE Macros

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/bluetooth/nimble/index

Provides definitions for NimBLE HCI UART H4 protocol types.

```APIDOC
## NimBLE HCI UART H4 Macros

### Description
These macros define different types for the HCI UART H4 protocol used in NimBLE.

### Macros
- `BLE_HCI_UART_H4_NONE`: Represents no H4 packet type.
- `BLE_HCI_UART_H4_CMD`: Represents an H4 command packet.
- `BLE_HCI_UART_H4_ACL`: Represents an H4 ACL data packet.
- `BLE_HCI_UART_H4_SCO`: Represents an H4 SCO data packet.
- `BLE_HCI_UART_H4_EVT`: Represents an H4 event packet.

### Usage Example
```c
// Example usage (conceptual)
int packet_type = BLE_HCI_UART_H4_EVT;

if (packet_type == BLE_HCI_UART_H4_CMD) {
    // Handle command packet
}
```
```

--------------------------------

### Deinitialize NimBLE Host

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/bluetooth/nimble/index

Deinitializes the VHCI transport layer between the NimBLE Host and the ESP Bluetooth controller. This function should be called after the NimBLE host has been deinitialized.

```APIDOC
## esp_nimble_hci_deinit()

### Description
Deinitializes the VHCI transport layer between NimBLE Host and ESP Bluetooth controller. This function should be called after the NimBLE host is deinitialized.

### Method
`esp_err_t esp_nimble_hci_deinit(void)`

### Endpoint
N/A (Function Call)

### Parameters
None

### Request Example
```c
#include "esp_nimble_hci.h"

// ... application code after NimBLE host deinitialization ...

if (esp_nimble_hci_deinit() != ESP_OK) {
    // Handle deinitialization error
}

// ... rest of the application ...
```

### Response
#### Success Response (ESP_OK)
`ESP_OK` indicating successful deinitialization.

#### Response Example
`ESP_OK`
```

--------------------------------

### Deinitialize NimBLE HCI Transport Layer

Source: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/bluetooth/nimble/index

This C function deinitializes the VHCI transport layer between the NimBLE Host and the ESP Bluetooth controller. It's important to call this function after the NimBLE host has been deinitialized. It returns ESP_OK on success or an appropriate error code on failure.

```c
esp_err_t esp_nimble_hci_deinit(void)
```
Tokens:
Raw