蓝牙^® PAN API

概述

PAN（Personal Area Networking，个人区域网络）通过 BNEP（Bluetooth Network Encapsulation Protocol，蓝牙网络封装协议）在经典蓝牙上实现 IP 组网。设备可作为 PAN 用户（PANU）、组网中心（GN）或网络接入点（NAP），使对端设备能够交换以太网帧并获得网络访问。

应用示例

bluetooth/bluedroid/classic_bt/bt_pan_nap 演示如何使用 PAN 网络接入点（NAP）角色，使 PANU 对端可通过 ESP 设备的 Wi-Fi STA 上行链路访问互联网。
bluetooth/bluedroid/classic_bt/bt_pan_panu 演示如何使用 PAN 用户（PANU）角色连接 NAP（例如 bt_pan_nap 或开启蓝牙网络共享的手机），并验证 IP 连通性。
bluetooth/bluedroid/classic_bt/bt_pan_gn 演示如何使用 PAN 组网（GN）角色作为中枢，桥接多个 PANU 客户端，使其能在同一子网内通信。

API 参考

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.

参数:

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

返回:

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.

参数:

cfg -- [in] PAN initialization configuration.

返回:

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.

返回:

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().

备注

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.

参数:

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.

返回:

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.

参数:

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

返回:

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.

备注

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.

参数:

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.

返回:

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.

参数:

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.

返回:

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.

参数:

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.

返回:

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.

此文档对您有帮助吗？

反馈已收到，谢谢！
如果您有其他意见，欢迎填写乐鑫文档反馈表。

我们重视您的反馈。
您可以填写乐鑫文档反馈表告诉我们如何改进该文档。

蓝牙® PAN API

概述

应用示例

API 参考

Header File

Functions

Unions

Structures

Macros

Type Definitions

Enumerations

蓝牙^® PAN API