/* * ESPRSSIF MIT License * * Copyright (c) 2015 * * Permission is hereby granted for use on ESPRESSIF SYSTEMS ESP8266 only, in which case, * it is free of charge, to any person obtaining a copy of this software and associated * documentation files (the "Software"), to deal in the Software without restriction, including * without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, * and/or sell copies of the Software, and to permit persons to whom the Software is furnished * to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included in all copies or * substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. * */ #ifndef __ESPNOW_H__ #define __ESPNOW_H__ #ifdef __cplusplus extern "C" { #endif /** \defgroup ESPNow_APIs ESP-NOW APIs * @brief ESP-NOW APIs * * @attention 1. ESP-NOW do not support broadcast and multicast. * @attention 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. * @attention 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. * @attention 4. ESP-NOW can not wake ESP8266 up from sleep, so if the target ESP8266 * station is in sleep, ESP-NOW communication will fail. * @attention 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. * @attention 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. * */ /** @addtogroup ESPNow_APIs * @{ */ enum esp_now_role { ESP_NOW_ROLE_IDLE = 0, ESP_NOW_ROLE_CONTROLLER, ESP_NOW_ROLE_SLAVE, ESP_NOW_ROLE_MAX, }; /** * @brief 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. * * @param uint8 *mac_addr : MAC address of target device * @param uint8 *data : data received * @param uint8 len : data length * * @return null */ typedef void (*esp_now_recv_cb_t)(uint8 *mac_addr, uint8 *data, uint8 len); /** * @brief 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. * * @param uint8 *mac_addr : MAC address of target device * @param uint8 status : status of ESP-NOW sending packet, 0, OK; 1, fail. * * @return null */ typedef void (*esp_now_send_cb_t)(uint8 *mac_addr, uint8 status); /** * @brief ESP-NOW initialization. * * @param null * * @return 0 : succeed * @return Non-0 : fail */ sint32 esp_now_init(void); /** * @brief Deinitialize ESP-NOW. * * @param null * * @return 0 : succeed * @return Non-0 : fail */ sint32 esp_now_deinit(void); /** * @brief Register ESP-NOW send callback. * * @param esp_now_send_cb_t cb : send callback * * @return 0 : succeed * @return Non-0 : fail */ sint32 esp_now_register_send_cb(esp_now_send_cb_t cb); /** * @brief Unregister ESP-NOW send callback. * * @param null * * @return 0 : succeed * @return Non-0 : fail */ sint32 esp_now_unregister_send_cb(void); /** * @brief Register ESP-NOW receive callback. * * @param esp_now_recv_cb_t cb : receive callback * * @return 0 : succeed * @return Non-0 : fail */ sint32 esp_now_register_recv_cb(esp_now_recv_cb_t cb); /** * @brief Unregister ESP-NOW receive callback. * * @param null * * @return 0 : succeed * @return Non-0 : fail */ sint32 esp_now_unregister_recv_cb(void); /** * @brief Send ESP-NOW packet. * * @param 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. * @param uint8 *data : data need to send * @param uint8 len : data length * * @return 0 : succeed * @return Non-0 : fail */ sint32 esp_now_send(uint8 *da, uint8 *data, uint8 len); /** * @brief Add an ESP-NOW peer, store MAC address of target device into ESP-NOW MAC list. * * @param uint8 *mac_addr : MAC address of device * @param uint8 role : role type of device, enum esp_now_role * @param uint8 channel : channel of device * @param uint8 *key : 16 bytes key which is needed for ESP-NOW communication * @param uint8 key_len : length of key, has to be 16 bytes now * * @return 0 : succeed * @return Non-0 : fail */ sint32 esp_now_add_peer(uint8 *mac_addr, uint8 role, uint8 channel, uint8 *key, uint8 key_len); /** * @brief Delete an ESP-NOW peer, delete MAC address of the device from ESP-NOW MAC list. * * @param u8 *mac_addr : MAC address of device * * @return 0 : succeed * @return Non-0 : fail */ sint32 esp_now_del_peer(uint8 *mac_addr); /** * @brief Set ESP-NOW role of device itself. * * @param uint8 role : role type of device, enum esp_now_role. * * @return 0 : succeed * @return Non-0 : fail */ sint32 esp_now_set_self_role(uint8 role); /** * @brief Get ESP-NOW role of device itself. * * @param uint8 role : role type of device, enum esp_now_role. * * @return 0 : succeed * @return Non-0 : fail */ sint32 esp_now_get_self_role(void); /** * @brief Set ESP-NOW role for a target device. If it is set multiple times, * new role will cover the old one. * * @param uint8 *mac_addr : MAC address of device. * @param uint8 role : role type, enum esp_now_role. * * @return 0 : succeed * @return Non-0 : fail */ sint32 esp_now_set_peer_role(uint8 *mac_addr, uint8 role); /** * @brief Get ESP-NOW role of a target device. * * @param uint8 *mac_addr : MAC address of device. * * @return ESP_NOW_ROLE_CONTROLLER, role type : controller * @return ESP_NOW_ROLE_SLAVE, role type : slave * @return otherwise : fail */ sint32 esp_now_get_peer_role(uint8 *mac_addr); /** * @brief 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. * * @param uint8 *mac_addr : MAC address of target device. * @param uint8 channel : channel, usually to be 1 ~ 13, some area may use channel 14. * * @return 0 : succeed * @return Non-0 : fail */ sint32 esp_now_set_peer_channel(uint8 *mac_addr, uint8 channel); /** * @brief Get channel information of a ESP-NOW device. * * @attention ESP-NOW communication needs to be at the same channel. * * @param uint8 *mac_addr : MAC address of target device. * * @return 1 ~ 13 (some area may get 14) : channel number * @return Non-0 : fail */ sint32 esp_now_get_peer_channel(uint8 *mac_addr); /** * @brief Set ESP-NOW key for a target device. * * If it is set multiple times, new key will cover the old one. * * @param uint8 *mac_addr : MAC address of target device. * @param uint8 *key : 16 bytes key which is needed for ESP-NOW communication, * if it is NULL, current key will be reset to be none. * @param uint8 key_len : key length, has to be 16 bytes now * * @return 0 : succeed * @return Non-0 : fail */ sint32 esp_now_set_peer_key(uint8 *mac_addr, uint8 *key, uint8 key_len); /** * @brief Get ESP-NOW key of a target device. * * If it is set multiple times, new key will cover the old one. * * @param uint8 *mac_addr : MAC address of target device. * @param uint8 *key : pointer of key, buffer size has to be 16 bytes at least * @param uint8 key_len : key length * * @return 0 : succeed * @return > 0 : find target device but can't get key * @return < 0 : fail */ sint32 esp_now_get_peer_key(uint8 *mac_addr, uint8 *key, uint8 *key_len); /** * @brief 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 * @attention 2. Parameter has to be true when you call it the first time. * * @param 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 * * @return NULL, no ESP-NOW devices exist * @return Otherwise, MAC address of ESP-NOW device which is pointed now */ uint8 *esp_now_fetch_peer(bool restart); /** * @brief Check if target device exists or not. * * @param uint8 *mac_addr : MAC address of target device. * * @return 0 : device does not exist * @return < 0 : error occur, check fail * @return > 0 : device exists */ sint32 esp_now_is_peer_exist(uint8 *mac_addr); /** * @brief Get the total number of ESP-NOW devices which are associated, and the * number count of encrypted devices. * * @param uint8 *all_cnt : total number of ESP-NOW devices which are associated. * @param uint8 *encryp_cnt : number count of encrypted devices * * @return 0 : succeed * @return Non-0 : fail */ sint32 esp_now_get_cnt_info(uint8 *all_cnt, uint8 *encrypt_cnt); /** * @brief 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. * * @param uint8 *key : pointer of encrypt key. * @param uint8 len : key length, has to be 16 bytes now. * * @return 0 : succeed * @return Non-0 : fail */ sint32 esp_now_set_kok(uint8 *key, uint8 len); /** * @} */ #ifdef __cplusplus } #endif #endif