ESP8266_RTOS_SDK v1.4.0

- Main Page
- Modules
- Data Structures
- Files

Typedefs | Enumerations | Functions
ESP-NOW APIs

ESP-NOW APIs. More...

## Typedefs
typedef void(* | esp_now_recv_cb_t) (uint8 *mac_addr, uint8 *data, uint8 len)
| ESP-NOW send callback. More...
typedef void(* | esp_now_send_cb_t) (uint8 *mac_addr, uint8 status)
| ESP-NOW send callback. More...

## Enumerations
enum | esp_now_role { ESP_NOW_ROLE_IDLE = 0, ESP_NOW_ROLE_CONTROLLER, ESP_NOW_ROLE_SLAVE, ESP_NOW_ROLE_MAX }

## Functions
sint32 | esp_now_init (void)
| ESP-NOW initialization. More...
sint32 | esp_now_deinit (void)
| Deinitialize ESP-NOW. More...
sint32 | esp_now_register_send_cb (esp_now_send_cb_t cb)
| Register ESP-NOW send callback. More...
sint32 | esp_now_unregister_send_cb (void)
| Unregister ESP-NOW send callback. More...
sint32 | esp_now_register_recv_cb (esp_now_recv_cb_t cb)
| Register ESP-NOW receive callback. More...
sint32 | esp_now_unregister_recv_cb (void)
| Unregister ESP-NOW receive callback. More...
sint32 | esp_now_send (uint8 *da, uint8 *data, uint8 len)
| Send ESP-NOW packet. More...
sint32 | esp_now_add_peer (uint8 *mac_addr, uint8 role, uint8 channel, uint8 *key, uint8 key_len)
| Add an ESP-NOW peer, store MAC address of target device into ESP-NOW MAC list. More...
sint32 | esp_now_del_peer (uint8 *mac_addr)
| Delete an ESP-NOW peer, delete MAC address of the device from ESP-NOW MAC list. More...
sint32 | esp_now_set_self_role (uint8 role)
| Set ESP-NOW role of device itself. More...
sint32 | esp_now_get_self_role (void)
| Get ESP-NOW role of device itself. More...
sint32 | esp_now_set_peer_role (uint8 *mac_addr, uint8 role)
| Set ESP-NOW role for a target device. If it is set multiple times, new role will cover the old one. More...
sint32 | esp_now_get_peer_role (uint8 *mac_addr)
| Get ESP-NOW role of a target device. More...
sint32 | esp_now_set_peer_channel (uint8 *mac_addr, uint8 channel)
| Record channel information of a ESP-NOW device. More...
sint32 | esp_now_get_peer_channel (uint8 *mac_addr)
| Get channel information of a ESP-NOW device. More...
sint32 | esp_now_set_peer_key (uint8 *mac_addr, uint8 *key, uint8 key_len)
| Set ESP-NOW key for a target device. More...
sint32 | esp_now_get_peer_key (uint8 *mac_addr, uint8 *key, uint8 *key_len)
| Get ESP-NOW key of a target device. More...
uint8 * | esp_now_fetch_peer (bool restart)
| Get MAC address of ESP-NOW device. More...
sint32 | esp_now_is_peer_exist (uint8 *mac_addr)
| Check if target device exists or not. More...
sint32 | esp_now_get_cnt_info (uint8 *all_cnt, uint8 *encrypt_cnt)
| Get the total number of ESP-NOW devices which are associated, and the number count of encrypted devices. More...
sint32 | esp_now_set_kok (uint8 *key, uint8 len)
| Set the encrypt key of communication key. More...

## Detailed Description

ESP-NOW APIs.

Attention
  1. ESP-NOW do not support broadcast and multicast.
  2. ESP-NOW is targeted to Smart-Light project, so it is suggested that slave role corresponding to soft-AP or soft-AP+station mode, controller role corresponding to station mode.
  3. When ESP8266 is in soft-AP+station mode, it will communicate through station interface if it is in slave role, and communicate through soft-AP interface if it is in controller role.
  4. ESP-NOW can not wake ESP8266 up from sleep, so if the target ESP8266 station is in sleep, ESP-NOW communication will fail.
  5. In station mode, ESP8266 supports 10 encrypt ESP-NOW peers at most, with the unencrypted peers, it can be 20 peers in total at most.
  6. In the soft-AP mode or soft-AP + station mode, the ESP8266 supports 6 encrypt ESP-NOW peers at most, with the unencrypted peers, it can be 20 peers in total at most.

## Typedef Documentation

typedef void(* esp_now_recv_cb_t) (uint8 *mac_addr, uint8 *data, uint8 len)

ESP-NOW send callback.

Attention
  The status will be OK, if ESP-NOW send packet successfully. But users need to make sure by themselves that key of communication is correct.

Parameters

  uint8 | *mac_addr : MAC address of target device
  uint8 | *data : data received
  uint8 | len : data length

Returns
  null

typedef void(* esp_now_send_cb_t) (uint8 *mac_addr, uint8 status)

ESP-NOW send callback.

Attention
  The status will be OK, if ESP-NOW send packet successfully. But users need to make sure by themselves that key of communication is correct.

Parameters

  uint8 | *mac_addr : MAC address of target device
  uint8 | status : status of ESP-NOW sending packet, 0, OK; 1, fail.

Returns
  null

## Function Documentation

sint32 esp_now_add_peer | ( | uint8 * | mac_addr,
|  | uint8 | role,
|  | uint8 | channel,
|  | uint8 * | key,
|  | uint8 | key_len
| ) |  |

Add an ESP-NOW peer, store MAC address of target device into ESP-NOW MAC list.

Parameters

  uint8 | *mac_addr : MAC address of device
  uint8 | role : role type of device, enum esp_now_role
  uint8 | channel : channel of device
  uint8 | *key : 16 bytes key which is needed for ESP-NOW communication
  uint8 | key_len : length of key, has to be 16 bytes now

Returns
  0 : succeed
  Non-0 : fail

sint32 esp_now_deinit | ( | void |  | ) |

Deinitialize ESP-NOW.

Parameters

  null |

Returns
  0 : succeed
  Non-0 : fail

sint32 esp_now_del_peer | ( | uint8 * | mac_addr | ) |

Delete an ESP-NOW peer, delete MAC address of the device from ESP-NOW MAC list.

Parameters

  u8 | *mac_addr : MAC address of device

Returns
  0 : succeed
  Non-0 : fail

uint8* esp_now_fetch_peer | ( | bool | restart | ) |

Get MAC address of ESP-NOW device.

Get MAC address of ESP-NOW device which is pointed now, and move the pointer to next one in ESP-NOW MAC list or move the pointer to the first one in ESP-NOW MAC list.

Attention
  1. This API can not re-entry
  2. Parameter has to be true when you call it the first time.

Parameters

  bool | restart : true, move pointer to the first one in ESP-NOW MAC list; false, move pointer to the next one in ESP-NOW MAC list

Returns
  NULL, no ESP-NOW devices exist
  Otherwise, MAC address of ESP-NOW device which is pointed now

sint32 esp_now_get_cnt_info | ( | uint8 * | all_cnt,
|  | uint8 * | encrypt_cnt
| ) |  |

Get the total number of ESP-NOW devices which are associated, and the number count of encrypted devices.

Parameters

  uint8 | *all_cnt : total number of ESP-NOW devices which are associated.
  uint8 | *encryp_cnt : number count of encrypted devices

Returns
  0 : succeed
  Non-0 : fail

sint32 esp_now_get_peer_channel | ( | uint8 * | mac_addr | ) |

Get channel information of a ESP-NOW device.

Attention
  ESP-NOW communication needs to be at the same channel.

Parameters

  uint8 | *mac_addr : MAC address of target device.

Returns
  1 ~ 13 (some area may get 14) : channel number
  Non-0 : fail

sint32 esp_now_get_peer_key | ( | uint8 * | mac_addr,
|  | uint8 * | key,
|  | uint8 * | key_len
| ) |  |

Get ESP-NOW key of a target device.

If it is set multiple times, new key will cover the old one.

Parameters

  uint8 | *mac_addr : MAC address of target device.
  uint8 | *key : pointer of key, buffer size has to be 16 bytes at least
  uint8 | key_len : key length

Returns
  0 : succeed
  > 0 : find target device but can't get key
  < 0 : fail

sint32 esp_now_get_peer_role | ( | uint8 * | mac_addr | ) |

Get ESP-NOW role of a target device.

Parameters

  uint8 | *mac_addr : MAC address of device.

Returns
  ESP_NOW_ROLE_CONTROLLER, role type : controller
  ESP_NOW_ROLE_SLAVE, role type : slave
  otherwise : fail

sint32 esp_now_get_self_role | ( | void |  | ) |

Get ESP-NOW role of device itself.

Parameters

  uint8 | role : role type of device, enum esp_now_role.

Returns
  0 : succeed
  Non-0 : fail

sint32 esp_now_init | ( | void |  | ) |

ESP-NOW initialization.

Parameters

  null |

Returns
  0 : succeed
  Non-0 : fail

sint32 esp_now_is_peer_exist | ( | uint8 * | mac_addr | ) |

Check if target device exists or not.

Parameters

  uint8 | *mac_addr : MAC address of target device.

Returns
  0 : device does not exist
  < 0 : error occur, check fail
  > 0 : device exists

sint32 esp_now_register_recv_cb | ( | esp_now_recv_cb_t | cb | ) |

Register ESP-NOW receive callback.

Parameters

  esp_now_recv_cb_t | cb : receive callback

Returns
  0 : succeed
  Non-0 : fail

sint32 esp_now_register_send_cb | ( | esp_now_send_cb_t | cb | ) |

Register ESP-NOW send callback.

Parameters

  esp_now_send_cb_t | cb : send callback

Returns
  0 : succeed
  Non-0 : fail

sint32 esp_now_send | ( | uint8 * | da,
|  | uint8 * | data,
|  | uint8 | len
| ) |  |

Send ESP-NOW packet.

Parameters

  uint8 | *da : destination MAC address. If it's NULL, send packet to all MAC addresses recorded by ESP-NOW; otherwise, send packet to target MAC address.
  uint8 | *data : data need to send
  uint8 | len : data length

Returns
  0 : succeed
  Non-0 : fail

sint32 esp_now_set_kok | ( | uint8 * | key,
|  | uint8 | len
| ) |  |

Set the encrypt key of communication key.

All ESP-NOW devices share the same encrypt key. If users do not set the encrypt key, ESP-NOW communication key will be encrypted by a default key.

Parameters

  uint8 | *key : pointer of encrypt key.
  uint8 | len : key length, has to be 16 bytes now.

Returns
  0 : succeed
  Non-0 : fail

sint32 esp_now_set_peer_channel | ( | uint8 * | mac_addr,
|  | uint8 | channel
| ) |  |

Record channel information of a ESP-NOW device.

When communicate with this device,

- call esp_now_get_peer_channel to get its channel first,
- then call wifi_set_channel to be in the same channel and do communication.

Parameters

  uint8 | *mac_addr : MAC address of target device.
  uint8 | channel : channel, usually to be 1 ~ 13, some area may use channel 14.

Returns
  0 : succeed
  Non-0 : fail

sint32 esp_now_set_peer_key | ( | uint8 * | mac_addr,
|  | uint8 * | key,
|  | uint8 | key_len
| ) |  |

Set ESP-NOW key for a target device.

If it is set multiple times, new key will cover the old one.

Parameters

  uint8 | *mac_addr : MAC address of target device.
  uint8 | *key : 16 bytes key which is needed for ESP-NOW communication, if it is NULL, current key will be reset to be none.
  uint8 | key_len : key length, has to be 16 bytes now

Returns
  0 : succeed
  Non-0 : fail

sint32 esp_now_set_peer_role | ( | uint8 * | mac_addr,
|  | uint8 | role
| ) |  |

Set ESP-NOW role for a target device. If it is set multiple times, new role will cover the old one.

Parameters

  uint8 | *mac_addr : MAC address of device.
  uint8 | role : role type, enum esp_now_role.

Returns
  0 : succeed
  Non-0 : fail

sint32 esp_now_set_self_role | ( | uint8 | role | ) |

Set ESP-NOW role of device itself.

Parameters

  uint8 | role : role type of device, enum esp_now_role.

Returns
  0 : succeed
  Non-0 : fail

sint32 esp_now_unregister_recv_cb | ( | void |  | ) |

Unregister ESP-NOW receive callback.

Parameters

  null |

Returns
  0 : succeed
  Non-0 : fail

sint32 esp_now_unregister_send_cb | ( | void |  | ) |

Unregister ESP-NOW send callback.

Parameters

  null |

Returns
  0 : succeed
  Non-0 : fail