警告

This document is not updated for ESP32C5 yet, so some of the content may not be correct.

This warning was automatically inserted due to the source file being in the add_warnings_pages list.

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-C5 支持独立模式下的 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_console 演示如何使用 NAN 协议发现附近的服务、建立数据路径，并在设备之间进行通信，无需互联网或 AP 连接。它提供了配置 NAN 服务、发布或订阅服务、发送消息以及启动或终止数据路径的控制台命令。

  • wifi/wifi_aware/nan_publisher 演示如何使用 NAN 协议发布服务，将服务广播给附近的其他设备，以及如何响应订阅该服务的设备。

  • wifi/wifi_aware/nan_subscriber 演示如何使用 NAN 协议发现附近发布所需服务的其他设备，并通过发送消息或启动数据路径与它们进行通信。

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

此文档对您有帮助吗？