# Wi-Fi AwareTM (NAN)

[English]

Wi-Fi AwareTM，也可称为 NAN (Neighbor Awareness Networking) 协议，其支持 Wi-Fi 设备发现附近的其他服务。通常情况下，基于位置的服务需通过服务器查询环境信息，并通过 GPS 或其他位置推算技术获取定位。不过，NAN 无需与服务器、GPS 或其他地理位置服务保持实时连接，即可支持设备之间通过 Wi-Fi 直接连接来交换信息。NAN 能够在 Wi-Fi 密集的环境中高效扩展，并通过提供附近人员和服务的信息来完善 Wi-Fi 连接性。

多个邻近的 NAN 设备组成一个 NAN 集群，集群中的设备能够相互通信。NAN 设备还可通过 NAN 服务发现协议，通过发布或订阅功能，在所处集群内提供或查找服务。通过服务名称可以完成服务匹配，一旦找到匹配，设备就可以发送信息，或与匹配到的设备间建立 IPv6 数据路径。

ESP32-S2 支持独立模式下的 Wi-Fi Aware，同时支持服务发现协议和数据路径。Wi-Fi Aware 协议仍在改进中，如需了解更多信息，请前往 Wi-Fi Alliance 官网的 Wi-Fi Aware 页面。大多数 Android 8 及更高版本的 Android 智能手机都支持 Wi-Fi Aware。如需了解更多信息，请参阅 Android 的开发者指南 Wi-Fi Aware。

## 应用示例

如需查看发布者和订阅者示例，请前往 wifi/wifi_aware/nan_publisher 和 wifi/wifi_aware/nan_subscriber。如需探索 Wi-Fi Aware 的全部功能，请参考用户交互界面控制台示例 wifi/wifi_aware/nan_console。如需了解更多信息，请参考对应示例目录中的 README 文档。

## API 参考

### Header File

- components/esp_wifi/wifi_apps/nan_app/include/esp_nan.h

- This header file can be included with:

  >     #include "esp_nan.h"

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

  >     REQUIRES esp_wifi

  > or

  >     PRIV_REQUIRES esp_wifi

### Functions

esp_err_t esp_wifi_nan_start(const wifi_nan_config_t *nan_cfg)

  Start NAN Discovery with provided configuration.

  Attention

    This API should be called after esp_wifi_init().

  参数:

    nan_cfg -- NAN related parameters to be configured.

  返回:

    - ESP_OK: succeed

    - others: failed

esp_err_t esp_wifi_nan_stop(void)

  Stop NAN Discovery, end NAN Services and Datapaths.

  返回:

    - ESP_OK: succeed

    - others: failed

uint8_t esp_wifi_nan_publish_service(const wifi_nan_publish_cfg_t *publish_cfg, bool ndp_resp_needed)

  Start Publishing a service to the NAN Peers in vicinity.

  Attention

    This API should be called after esp_wifi_nan_start().

  参数:

    - publish_cfg -- Configuration parameters for publishing a service.

    - ndp_resp_needed -- Setting this true will require user response for every NDP Req using esp_wifi_nan_datapath_resp API.

  返回:

    - non-zero: Publish service identifier

    - zero: failed

uint8_t esp_wifi_nan_subscribe_service(const wifi_nan_subscribe_cfg_t *subscribe_cfg)

  Subscribe for a service within the NAN cluster.

  Attention

    This API should be called after esp_wifi_nan_start().

  参数:

    subscribe_cfg -- Configuration parameters for subscribing for a service.

  返回:

    - non-zero: Subscribe service identifier

    - zero: failed

esp_err_t esp_wifi_nan_send_message(wifi_nan_followup_params_t *fup_params)

  Send a follow-up message to the NAN Peer with matched service.

  Attention

    This API should be called after a NAN service is discovered due to a match.

  参数:

    fup_params -- Configuration parameters for sending a Follow-up message.

  返回:

    - ESP_OK: succeed

    - others: failed

esp_err_t esp_wifi_nan_cancel_service(uint8_t service_id)

  Cancel a NAN service.

  参数:

    service_id -- Publish/Subscribe service id to be cancelled.

  返回:

    - ESP_OK: succeed

    - others: failed

uint8_t esp_wifi_nan_datapath_req(wifi_nan_datapath_req_t *req)

  Send NAN Datapath Request to a NAN Publisher with matched service.

  Attention

    This API should be called by the Subscriber after a match occurs with a Publisher.

  参数:

    req -- NAN Datapath Request parameters.

  返回:

    - non-zero NAN Datapath identifier: If NAN datapath req was accepted by publisher

    - zero: If NAN datapath req was rejected by publisher or a timeout occurs

esp_err_t esp_wifi_nan_datapath_resp(wifi_nan_datapath_resp_t *resp)

  Respond to a NAN Datapath request with Accept or Reject.

  Attention

    This API should be called if ndp_resp_needed is set True by the Publisher and a WIFI_EVENT_NDP_INDICATION event is received due to an incoming NDP request.

  参数:

    resp -- NAN Datapath Response parameters.

  返回:

    - ESP_OK: succeed

    - others: failed

esp_err_t esp_wifi_nan_datapath_end(wifi_nan_datapath_end_req_t *req)

  Terminate a NAN Datapath.

  参数:

    req -- NAN Datapath end request parameters.

  返回:

    - ESP_OK: succeed

    - others: failed

void esp_wifi_nan_get_ipv6_linklocal_from_mac(ip6_addr_t *ip6, uint8_t *mac_addr)

  Get IPv6 Link Local address using MAC address.

  参数:

    - ip6 -- [out] Derived IPv6 Link Local address.

    - mac_addr -- [in] Input MAC Address.

esp_err_t esp_wifi_nan_get_own_svc_info(uint8_t *own_svc_id, char *svc_name, int *num_peer_records)

  brief Get own Service information from Service ID OR Name.

  Attention

    If service information is to be fetched from service name, set own_svc_id as zero.

  参数:

    - own_svc_id -- [inout] As input, it indicates Service ID to search for. As output, it indicates Service ID of the service found using Service Name.

    - svc_name -- [inout] As input, it indicates Service Name to search for. As output, it indicates Service Name of the service found using Service ID.

    - num_peer_records -- [out] Number of peers discovered by corresponding service.

  返回:

    - ESP_OK: succeed

    - ESP_FAIL: failed

esp_err_t esp_wifi_nan_get_peer_records(int *num_peer_records, uint8_t own_svc_id, struct nan_peer_record *peer_record)

  brief Get a list of Peers discovered by the given Service.

  参数:

    - num_peer_records -- [inout] As input param, it stores max peers peer_record can hold. As output param, it specifies the actual number of peers this API returns.

    - own_svc_id -- Service ID of own service.

    - peer_record -- [out] Pointer to first peer record.

  返回:

    - ESP_OK: succeed

    - ESP_FAIL: failed

esp_err_t esp_wifi_nan_get_peer_info(char *svc_name, uint8_t *peer_mac, struct nan_peer_record *peer_info)

  brief Find Peer's Service information using Peer MAC and optionally Service Name.

  参数:

    - svc_name -- Service Name of the published/subscribed service.

    - peer_mac -- Peer's NAN Management Interface MAC address.

    - peer_info -- [out] Peer's service information structure.

  返回:

    - ESP_OK: succeed

    - ESP_FAIL: failed

### Structures

struct nan_peer_record

  Parameters of a peer service record

  Public Members

  uint8_t peer_svc_id

    Identifier of Peer's service

  uint8_t own_svc_id

    Identifier of own service associated with Peer

  uint8_t peer_nmi[6]

    Peer's NAN Management Interface address

  uint8_t peer_svc_type

    Peer's service type (Publish/Subscribe)

  uint8_t ndp_id

    Specifies if the peer has any active datapath

  uint8_t peer_ndi[6]

    Peer's NAN Data Interface address, only valid when ndp_id is non-zero

### Macros

WIFI_NAN_CONFIG_DEFAULT()

NDP_STATUS_ACCEPTED

NDP_STATUS_REJECTED

NAN_MAX_PEERS_RECORD

ESP_NAN_PUBLISH

ESP_NAN_SUBSCRIBE

提供有关此文档的反馈