Accueil Explorer Aide
Connexion
RT-Thread-packages
/
esp-idf
miroir de https://github-proxy.rt-thread.io/RT-Thread-packages/esp-idf.git
2
0
Fork 0
Fichiers Tickets 0 Wiki
Aborescence: v3.3.6
Branches Tags
esp-idf
/
docs
/
en
/
api-reference
/
network
/
esp_now.rst

esp_now.rst 6.1 KB
Lien permanent Historique Raw

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103 
  1. ESP-NOW
    2. 

  2. =======
    3. 

  3. 

  4. Overview
    5. 

  5. --------
    6. 

  6. 

  7. ESP-NOW is a kind of connectionless WiFi communication protocol which is defined by Espressif. In ESP-NOW, application data is 
    8. 

  8. encapsulated in vendor-specific action frame and then transmitted from one WiFi device to another without connection. 
    9. 

  9. CTR with CBC-MAC Protocol(CCMP) is used to protect the action frame for security. ESP-NOW is widely used in smart light, remote 
    10. 

  10. controlling, sensor, etc.
    11. 

  11. 

  12. Frame Format
    13. 

  13. ------------
    14. 

  14. 

  15. ESP-NOW uses vendor-specific action frame to transmit ESP-NOW data. The format of vendor-specific action frame is as follows:
    16. 

  16. 

  17. .. highlight:: none
    18. 

  18. 

  19. ::
    20. 

  20. 

  21.     ----------------------------------------------------------------------------------------
    22. 

  22.     | MAC Header | Category Code | Organization Identifier | Vendor Specific Content | FCS |
    23. 

  23.     ----------------------------------------------------------------------------------------
    24. 

  24.                        1 byte              3 bytes                  7~255 bytes
    25. 

  25. 

  26. - Category Code: The Category field is set to the value(127) indicating the vendor-specific category.
    27. 

  27. - Organization Identifier: The Organization Identifier contains a unique identifier(0x18fe34) which is the first three bytes 
    28. 

  28.                            of MAC address applied by Espressif.
    29. 

  29. - Vendor Specific Content: The Vendor Specific Content contains vendor-specific field as follows:
    30. 

  30. 

  31. .. highlight:: none
    32. 

  32. 

  33. ::
    34. 

  34. 

  35.     -------------------------------------------------------------------------------
    36. 

  36.     | Element ID | Length | Organization Identifier | Type | Version |    Body    |
    37. 

  37.     -------------------------------------------------------------------------------
    38. 

  38.         1 byte     1 byte            3 bytes         1 byte   1 byte   0~250 bytes
    39. 

  39.     
    40. 

  40. - Element ID: The Element ID field is set to the value(221) indicating the vendor-specific element.
    41. 

  41. - Length: The length is the total length of Organization Identifier, Type, Version and Body.
    42. 

  42. - Organization Identifier: The Organization Identifier contains a unique identifier(0x18fe34) which is the first three bytes 
    43. 

  43.                            of MAC address applied by Espressif.
    44. 

  44. - Type: The Type field is set to the value(4) indicating ESP-NOW.
    45. 

  45. - Version: The Version field is set to the version of ESP-NOW.
    46. 

  46. - Body: The Body contains the ESP-NOW data.
    47. 

  47. 

  48. As ESP-NOW is connectionless, the MAC header is a little different from that of standard frames. The FromDS and ToDS bits of 
    49. 

  49. FrameControl field are both 0. The first address field is set to the destination address. The second address field is set to 
    50. 

  50. the source address. The third address field is set to broadcast address(0xff:0xff:0xff:0xff:0xff:0xff).
    51. 

  51. 

  52. Security
    53. 

  53. --------
    54. 

  54. 

  55. ESP-NOW use CCMP method which can be referenced in IEEE Std. 802.11-2012 to protect the vendor-specific action frame. The WiFi 
    56. 

  56. device maintains a Primary Master Key(PMK) and several Local Master Keys(LMK). The lengths of them are 16 bytes. PMK is used 
    57. 

  57. to encrypt LMK with AES-128 algorithm. Call ``esp_now_set_pmk()`` to set PMK. If PMK is not set, a default PMK will be used. 
    58. 

  58. If LMK of the paired device is set, it will be used to encrypt the vendor-specific action frame with CCMP method. The maximum 
    59. 

  59. number of different LMKs is six. Do not support encrypting multicast vendor-specific action frame. 
    60. 

  60. 

  61. Initialization and De-initialization
    62. 

  62. ------------------------------------
    63. 

  63. 

  64. Call ``esp_now_init()`` to initialize ESP-NOW and ``esp_now_deinit()`` to de-initialize ESP-NOW. ESP-NOW data must be transmitted
    65. 

  65. after WiFi is started, so it is recommended to start WiFi before initializing ESP-NOW and stop WiFi after de-initializing ESP-NOW.
    66. 

  66. When ``esp_now_deinit()`` is called, all of the information of paired devices will be deleted.
    67. 

  67. 

  68. Add Paired Device
    69. 

  69. -----------------
    70. 

  70. 

  71. Before sending data to other device, call ``esp_now_add_peer()`` to add it to the paired device list first. The maximum number of 
    72. 

  72. paired devices is twenty. If security is enabled, the LMK must be set. ESP-NOW data can be sent from station or softap interface. 
    73. 

  73. Make sure that the interface is enabled before sending ESP-NOW data. A device with broadcast MAC address must be added before 
    74. 

  74. sending broadcast data. The range of the channel of paired device is from 0 to 14. If the channel is set to 0, data will be sent 
    75. 

  75. on the current channel. Otherwise, the channel must be set as the channel that the local device is on.
    76. 

  76. 

  77. Send ESP-NOW Data
    78. 

  78. -----------------
    79. 

  79. 

  80. Call ``esp_now_send()`` to send ESP-NOW data and ``esp_now_register_send_cb`` to register sending callback function. It will return 
    81. 

  81. `ESP_NOW_SEND_SUCCESS` in sending callback function if the data is received successfully on MAC layer. Otherwise, it will return 
    82. 

  82. `ESP_NOW_SEND_FAIL`. There are several reasons failing to send ESP-NOW data, for example, the destination device doesn't exist, the 
    83. 

  83. channels of the devices are not the same, the action frame is lost when transmiting on the air, etc. It is not guaranteed that 
    84. 

  84. application layer can receive the data. If necessary, send back ack data when receiving ESP-NOW data. If receiving ack data timeout 
    85. 

  85. happens, retransmit the ESP-NOW data. A sequence number can also be assigned to ESP-NOW data to drop the duplicated data.
    86. 

  86. 

  87. If there is a lot of ESP-NOW data to send, call ``esp_now_send()`` to send less than or equal to 250 bytes of data once a time. 
    88. 

  88. Note that too short interval between sending two ESP-NOW datas may lead to disorder of sending callback function. So, it is 
    89. 

  89. recommended that sending the next ESP-NOW data after the sending callback function of previous sending has returned. The sending 
    90. 

  90. callback function runs from a high-priority WiFi task. So, do not do lengthy operations in the callback function. Instead, post 
    91. 

  91. necessary data to a queue and handle it from a lower priority task.
    92. 

  92. 

  93. Receiving ESP-NOW Data
    94. 

  94. ----------------------
    95. 

  95. 

  96. Call ``esp_now_register_recv_cb`` to register receiving callback function. When receiving ESP-NOW data, receiving callback function 
    97. 

  97. is called. The receiving callback function also runs from WiFi task. So, do not do lengthy operations in the callback function. 
    98. 

  98. Instead, post necessary data to a queue and handle it from a lower priority task.
    99. 

  99. 

  100. API Reference
    101. 

  101. -------------
    102. 

  102. 

  103. .. include:: /_build/inc/esp_now.inc
    104.