Bluetooth® PAN API

[中文]

Overview

PAN (Personal Area Networking) enables IP networking over Classic Bluetooth using BNEP (Bluetooth Network Encapsulation Protocol). Devices can act as a PAN User (PANU), Group Network (GN) hub, or Network Access Point (NAP) so peers can exchange Ethernet frames and obtain network access.

Application Examples

• bluetooth/bluedroid/classic_bt/bt_pan_nap demonstrates how to use the PAN Network Access Point (NAP) role so that PANU peers can reach the Internet through the ESP device's Wi-Fi STA uplink.

• bluetooth/bluedroid/classic_bt/bt_pan_panu demonstrates how to use the PAN User (PANU) role to connect to a NAP (for example bt_pan_nap or a phone with Bluetooth tethering) and verify IP connectivity.

• bluetooth/bluedroid/classic_bt/bt_pan_gn demonstrates how to use the PAN Group Network (GN) role as a hub that bridges multiple PANU clients so they can communicate on the same subnet.

API Reference

Header File

• components/bt/host/bluedroid/api/include/api/esp_pan_api.h

• This header file can be included with:

  #include "esp_pan_api.h"
  

• This header file is a part of the API provided by the bt component. To declare that your component depends on bt, add the following to your CMakeLists.txt:

  REQUIRES bt
  

  or

  PRIV_REQUIRES bt
  

Functions

esp_err_t esp_pan_register_callback(esp_pan_cb_t callback)

This function is called to register callbacks with the PAN module.

Parameters:

callback -- [in] Pointer to the callback function.

Returns:

• ESP_OK: success

• other: failed

esp_err_t esp_pan_init(const esp_pan_cfg_t *cfg)

This function is called to initialize the PAN module.

         When the operation is completed, the callback function will be called with ESP_PAN_INIT_EVT.
         After initialization succeeds, ESP_PAN_SET_ROLE_EVT is reported for the registered roles.
         This function should be called after esp_bluedroid_enable() completes successfully.

Parameters:

cfg -- [in] PAN initialization configuration.

Returns:

• ESP_OK: success

• other: failed

esp_err_t esp_pan_deinit(void)

This function is called to deinitialize the PAN module.

         Active PAN connections are closed first. For each closed connection, ESP_PAN_CLOSE_EVT is reported.
         When deinitialization completes, ESP_PAN_DEINIT_EVT is reported.
         This function must be called after esp_pan_init() succeeds and before calling esp_pan_init() again.

Returns:

• ESP_OK: success

• other: failed

esp_err_t esp_pan_connect(esp_bd_addr_t remote_bda, esp_pan_role_t local_role, esp_pan_role_t peer_role)

This function makes a PAN connection to a remote Bluetooth device.

         When the connection is established or fails, the callback function will be called with ESP_PAN_OPEN_EVT.
         For an incoming connection, ESP_PAN_OPENING_EVT is reported before ESP_PAN_OPEN_EVT.
         This function must be called after esp_pan_init() succeeds and before esp_pan_deinit().

Note

Valid outgoing role pairs include PANU->NAP, PANU->GN, and GN->GN. A PANU device can only maintain one PANU-role connection at a time.

Parameters:

• remote_bda -- [in] Remote Bluetooth device address.

• local_role -- [in] Local PAN role for this connection. One of ESP_PAN_ROLE_PANU, ESP_PAN_ROLE_GN, ESP_PAN_ROLE_NAP.

• peer_role -- [in] Expected peer PAN role for this connection.

Returns:

• ESP_OK: success

• other: failed

esp_err_t esp_pan_disconnect(uint16_t handle)

This function closes a PAN connection.

         When the operation is completed, the callback function will be called with ESP_PAN_CLOSE_EVT.
         This function must be called after a valid connection handle is obtained from ESP_PAN_OPEN_EVT.

Parameters:

handle -- [in] Connection handle obtained from ESP_PAN_OPEN_EVT.

Returns:

• ESP_OK: success

• other: failed

esp_err_t esp_pan_write(uint16_t handle, const uint8_t *dst, const uint8_t *src, uint16_t protocol, uint16_t len, const uint8_t *data, bool ext)

This function sends Ethernet payload data over a PAN connection.

         The data is encapsulated by BNEP and transmitted to the peer device.
         When the write request is accepted or rejected, ESP_PAN_WRITE_EVT is reported.
         This function must be called after a valid connection handle is obtained from ESP_PAN_OPEN_EVT.

Note

dst and src are 6-byte Ethernet MAC addresses, not Bluetooth device addresses. When integrated with esp_netif, use the Ethernet frame header generated by the TCP/IP stack. Pause transmission when ESP_PAN_CONG_EVT reports congestion. len greater than ESP_PAN_MAX_WRITE_LEN is rejected with ESP_ERR_INVALID_ARG.

Parameters:

• handle -- [in] Connection handle obtained from ESP_PAN_OPEN_EVT.

• dst -- [in] Destination Ethernet MAC address. Use broadcast address for ARP requests.

• src -- [in] Source Ethernet MAC address. Usually the local PAN netif MAC address.

• protocol -- [in] Ethernet protocol type, e.g. ESP_PAN_PROTO_IP or ESP_PAN_PROTO_ARP.

• len -- [in] Length of the payload pointed to by data. Must be in the range [1, ESP_PAN_MAX_WRITE_LEN].

• data -- [in] Pointer to L3 payload. Ethernet header is not included.

• ext -- [in] TRUE if forwarded BNEP extension headers are present.

Returns:

• ESP_OK: success

• ESP_ERR_INVALID_ARG: invalid handle, NULL pointer, zero or oversized len

• other: failed

esp_err_t esp_pan_set_protocol_filters(uint16_t handle, uint16_t num_filters, const uint16_t *start_array, const uint16_t *end_array)

This function sets protocol filters on the peer device.

         Only Ethernet frames whose protocol type falls into one of the configured ranges are accepted.
         When the operation completes or a peer indication is received, ESP_PAN_PFILTER_EVT is reported.

Parameters:

• handle -- [in] Connection handle obtained from ESP_PAN_OPEN_EVT.

• num_filters -- [in] Number of protocol filter ranges (0 to ESP_PAN_MAX_PROTOCOL_FILTERS). Pass 0 with NULL arrays to clear filters.

• start_array -- [in] Array of range start protocol values. Ignored when num_filters is 0.

• end_array -- [in] Array of range end protocol values. Ignored when num_filters is 0.

Returns:

• ESP_OK: success

• ESP_ERR_INVALID_ARG: invalid handle, NULL arrays when num_filters > 0, or too many filters

• other: failed

esp_err_t esp_pan_set_multicast_filters(uint16_t handle, uint16_t num_filters, const esp_bd_addr_t *start_array, const esp_bd_addr_t *end_array)

This function sets multicast filters on the peer device.

         Only multicast Ethernet frames whose destination MAC falls into one of the configured ranges
         are accepted. When the operation completes or a peer indication is received,
         ESP_PAN_MFILTER_EVT is reported.

Parameters:

• handle -- [in] Connection handle obtained from ESP_PAN_OPEN_EVT.

• num_filters -- [in] Number of multicast filter ranges (0 to ESP_PAN_MAX_MULTICAST_FILTERS). Pass 0 with NULL arrays to clear filters.

• start_array -- [in] Array of range start MAC addresses (esp_bd_addr_t elements). Ignored when num_filters is 0.

• end_array -- [in] Array of range end MAC addresses (esp_bd_addr_t elements). Ignored when num_filters is 0.

Returns:

• ESP_OK: success

• ESP_ERR_INVALID_ARG: invalid handle, NULL arrays when num_filters > 0, or too many filters

• other: failed

Unions

union esp_pan_cb_param_t

#include <esp_pan_api.h>

PAN callback parameters union.

Public Members

struct esp_pan_cb_param_t::pan_init_evt_param init

PAN callback param of ESP_PAN_INIT_EVT

struct esp_pan_cb_param_t::pan_deinit_evt_param deinit

PAN callback param of ESP_PAN_DEINIT_EVT

struct esp_pan_cb_param_t::pan_set_role_evt_param set_role

PAN callback param of ESP_PAN_SET_ROLE_EVT

struct esp_pan_cb_param_t::pan_opening_evt_param opening

PAN callback param of ESP_PAN_OPENING_EVT

struct esp_pan_cb_param_t::pan_open_evt_param open

PAN callback param of ESP_PAN_OPEN_EVT

struct esp_pan_cb_param_t::pan_close_evt_param close

PAN callback param of ESP_PAN_CLOSE_EVT

struct esp_pan_cb_param_t::pan_data_ind_evt_param data_ind

PAN callback param of ESP_PAN_DATA_IND_EVT

struct esp_pan_cb_param_t::pan_cong_evt_param cong

PAN callback param of ESP_PAN_CONG_EVT

struct esp_pan_cb_param_t::pan_pfilter_evt_param pfilter

PAN callback param of ESP_PAN_PFILTER_EVT

struct esp_pan_cb_param_t::pan_mfilter_evt_param mfilter

PAN callback param of ESP_PAN_MFILTER_EVT

struct esp_pan_cb_param_t::pan_write_evt_param write

PAN callback param of ESP_PAN_WRITE_EVT

struct pan_close_evt_param

#include <esp_pan_api.h>

ESP_PAN_CLOSE_EVT.

Public Members

uint16_t handle

Connection handle of the closed link.

struct pan_cong_evt_param

#include <esp_pan_api.h>

ESP_PAN_CONG_EVT.

Public Members

uint16_t handle

Connection handle whose congestion status changed.

bool cong

TRUE, congested. FALSE, uncongested. Pause esp_pan_write() when TRUE.

struct pan_data_ind_evt_param

#include <esp_pan_api.h>

ESP_PAN_DATA_IND_EVT.

Public Members

uint16_t handle

Connection handle on which data was received.

uint8_t src[ESP_BD_ADDR_LEN]

Source Ethernet MAC address of the received frame.

uint8_t dst[ESP_BD_ADDR_LEN]

Destination Ethernet MAC address of the received frame.

uint16_t protocol

Ethernet protocol type, e.g. ESP_PAN_PROTO_IP or ESP_PAN_PROTO_ARP.

uint16_t len

Length of the payload pointed to by data.

uint8_t *data

Pointer to L3 payload. Ethernet header is not included.

bool ext

TRUE if BNEP extension headers are present.

bool forward

TRUE if the frame is forwarded by GN/NAP.

struct pan_deinit_evt_param

#include <esp_pan_api.h>

ESP_PAN_DEINIT_EVT.

Public Members

esp_pan_status_t status

Deinitialization status.

struct pan_init_evt_param

#include <esp_pan_api.h>

ESP_PAN_INIT_EVT.

Public Members

esp_pan_status_t status

Initialization status.

struct pan_mfilter_evt_param

#include <esp_pan_api.h>

ESP_PAN_MFILTER_EVT.

Public Members

uint16_t handle

Connection handle related to the filter event.

bool indication

TRUE if this is an indication from peer. FALSE if this is a local operation result.

esp_pan_status_t status

Operation status.

uint16_t len

Length of the filters buffer in bytes.

uint8_t *filters

Pointer to multicast filter data. Valid only in callback context.

struct pan_open_evt_param

#include <esp_pan_api.h>

ESP_PAN_OPEN_EVT.

Public Members

esp_pan_status_t status

Connection open status.

esp_bd_addr_t remote_bda

Remote Bluetooth device address.

uint16_t handle

Connection handle assigned by PAN stack.

esp_pan_role_t local_role

Local role used for this connection.

esp_pan_role_t peer_role

Peer role used for this connection.

struct pan_opening_evt_param

#include <esp_pan_api.h>

ESP_PAN_OPENING_EVT.

Public Members

esp_bd_addr_t remote_bda

Remote Bluetooth device address.

uint16_t handle

Connection handle assigned by PAN stack.

struct pan_pfilter_evt_param

#include <esp_pan_api.h>

ESP_PAN_PFILTER_EVT.

Public Members

uint16_t handle

Connection handle related to the filter event.

bool indication

TRUE if this is an indication from peer. FALSE if this is a local operation result.

esp_pan_status_t status

Operation status.

uint16_t len

Length of the filters buffer in bytes.

uint8_t *filters

Pointer to protocol filter data. Valid only in callback context.

struct pan_set_role_evt_param

#include <esp_pan_api.h>

ESP_PAN_SET_ROLE_EVT.

Public Members

esp_pan_status_t status

Role registration status.

esp_pan_role_mask_t role

Registered local role bitmap.

struct pan_write_evt_param

#include <esp_pan_api.h>

ESP_PAN_WRITE_EVT.

Public Members

esp_pan_status_t status

Write operation status.

uint16_t handle

Connection handle on which data was written.

Structures

struct esp_pan_cfg_t

PAN initialization configuration parameters.

Public Members

esp_pan_role_mask_t role

Local PAN roles to register. Bitmap of esp_pan_role_t values.

esp_pan_sec_t panu_sec

Security mask for PANU role registration.

esp_pan_sec_t gn_sec

Security mask for GN role registration.

esp_pan_sec_t nap_sec

Security mask for NAP role registration.

const char *panu_service_name

SDP service name for PANU. Set NULL to use the default name.

const char *gn_service_name

SDP service name for GN. Set NULL to use the default name.

const char *nap_service_name

SDP service name for NAP. Set NULL to use the default name.

Macros

ESP_PAN_INVALID_HANDLE

Invalid PAN connection handle.

Returned when a connection is not established. This value must not be passed to PAN API functions that require a valid handle.

ESP_PAN_MAX_WRITE_LEN

Maximum Ethernet payload length accepted by esp_pan_write().

Matches the fixed PAN write buffer capacity after BT_HDR and protocol header overhead: PAN_BUF_SIZE(4112) - sizeof(BT_HDR)(8) - PAN_MINIMUM_OFFSET(28).

ESP_PAN_MAX_PROTOCOL_FILTERS

Maximum number of protocol filter ranges accepted by esp_pan_set_protocol_filters().

Must match BNEP_MAX_PROT_FILTERS.

ESP_PAN_MAX_MULTICAST_FILTERS

Maximum number of multicast filter ranges accepted by esp_pan_set_multicast_filters().

Must match BNEP_MAX_MULTI_FILTERS.

ESP_PAN_PROTO_IP

Ethernet protocol type for IPv4 over PAN/BNEP.

ESP_PAN_PROTO_ARP

Ethernet protocol type for ARP over PAN/BNEP.

ESP_PAN_SEC_NONE

No security.

ESP_PAN_SEC_AUTHENTICATE

Authentication required.

ESP_PAN_SEC_ENCRYPT

Encryption required.

ESP_PAN_DEFAULT_CONFIG()

PAN default configuration.

Registers PANU role only with authentication and encryption enabled.

Type Definitions

typedef uint8_t esp_pan_role_mask_t

Bitmap of esp_pan_role_t values for local role registration.

typedef uint16_t esp_pan_sec_t

PAN security type.

typedef void (*esp_pan_cb_t)(esp_pan_cb_event_t event, esp_pan_cb_param_t *param)

PAN callback function type.

         When handling ESP_PAN_DATA_IND_EVT, it is strongly recommended to cache incoming data and
         process it in another lower priority application task rather than performing heavy work directly
         in this callback.

Param event:

Event type.

Param param:

Pointer to callback parameter, currently union type.

Enumerations

enum esp_pan_role_t

PAN role type.

Each role is a single bit. Combine values with bitwise OR into an esp_pan_role_mask_t when registering multiple local roles at initialization.

Typical connection role pairs:

• PANU (client) -> NAP (server)

• PANU (client) -> GN (server)

• GN (client) -> GN (server)

• NAP (server) <- PANU (client, incoming connection)

Values:

enumerator ESP_PAN_ROLE_PANU

PAN User role. Connects to NAP or GN for network access.

enumerator ESP_PAN_ROLE_GN

Group Network role. Bridges multiple PAN devices in a subnet.

enumerator ESP_PAN_ROLE_NAP

Network Access Point role. Provides network access to PANU peers.

enum esp_pan_status_t

PAN status type.

Values:

enumerator ESP_PAN_SUCCESS

Successful operation.

enumerator ESP_PAN_FAILURE

Generic failure.

enumerator ESP_PAN_BUSY

Temporarily cannot handle this request.

enumerator ESP_PAN_NO_RESOURCE

No more resources.

enumerator ESP_PAN_NEED_INIT

PAN module shall init first.

enumerator ESP_PAN_NEED_DEINIT

PAN module shall deinit first.

enumerator ESP_PAN_NO_CONNECTION

Connection may have been closed.

enum esp_pan_cb_event_t

PAN callback function events.

Values:

enumerator ESP_PAN_INIT_EVT

When PAN is initialized, the event comes.

enumerator ESP_PAN_DEINIT_EVT

When PAN is deinitialized, the event comes.

enumerator ESP_PAN_SET_ROLE_EVT

When PAN role registration completes, the event comes.

enumerator ESP_PAN_OPENING_EVT

When an incoming PAN connection is being established, the event comes.

enumerator ESP_PAN_OPEN_EVT

When a PAN connection is opened, the event comes.

enumerator ESP_PAN_CLOSE_EVT

When a PAN connection is closed, the event comes.

enumerator ESP_PAN_DATA_IND_EVT

When PAN connection received data, the event comes.

enumerator ESP_PAN_CONG_EVT

When PAN connection congestion status changed, the event comes.

enumerator ESP_PAN_PFILTER_EVT

When protocol filter indication/result is available, the event comes.

enumerator ESP_PAN_MFILTER_EVT

When multicast filter indication/result is available, the event comes.

enumerator ESP_PAN_WRITE_EVT

When PAN write operation completes, the event comes.

---

Was this page helpful?

• Thank you! We received your feedback.
• If you have any comments, fill in Espressif Documentation Feedback Form.

• We value your feedback.
• Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.