# 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.