# FastEspnow

**Repository Path**: chiyoooo/fast-espnow

## Basic Information

- **Project Name**: FastEspnow
- **Description**: 可以一键配对Espnow 设备, 快速建立 一对一, 多对多的连接
- **Primary Language**: Unknown
- **License**: BSD-3-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2023-01-19
- **Last Updated**: 2024-08-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Arduino FastEspnow Library

Esp32 Arduino Espnow 库,用于一对一, 一对多的快速配对

这个库的更改日志可以在 CHANGELOG 中找到。

## 快速使用

### 引入头文

```CPP
#include "FastEspnow.h"
```

### 在 `setup()` 中配置设备识别码

SN 是一个 uint16_t 的识别码, 不同设备间应该具备不同 SN, 以便配对的时候进行识别

```CPP
Espnow.begin(SN);
```

### 注册事件

```CPP

 // 开始扫描回调
Espnow.attach_strat_scan_cb();

// 结束扫描回调
Espnow.attach_stop_scan_cb();

// 设备离线通知, 设备断开连接后触发
Espnow.attach_PeerOffline_cb();

// 设备上线通知, 设备第一次配对后触发
Espnow.attach_peerOnline_cb();

// 设备挂起通知, 当向某设备发送信息失败超过一定次数后,将判定该设备挂起
Espnow.attach_peerSupend_cb();

// 设备激活通知, 设备启动后,将自动向所有节点发送激活指令.
// 如果某设备之前是挂起状态, 向其成功发送数据后, 也将将其视为激活
Espnow.attach_peerActive_cb();

// 数据接收通知
Espnow.attach_RecMessage_cb();
```

## API 使用

### 1.开启配对扫描

开启后, 设备将会在 10s 内持续发送广播, 如果另一个设备也开启扫描, 则两个会配对

```cpp
Espnow.scan();
```

### 2.开启心跳

由于设备的挂让通知需要通过向设备发送信息后的结果来判断, 因此在未发送信息时候,无法准确预知设备是否是离线
因此可以通过开启心跳, 来获得相对准确及时的设备 挂起 / 激活状态变化信息

```cpp
Espnow.openHeartBeat(interval); // 开启心跳
Espnow.closeHeartBeat(interval); // 关闭心跳
```

### 3.发送指令

#### 3.1 指令数据结构 MESSAGE

设备直接的数据是通过 MESSAGE 数据结构来进行发送的, 具备简单的校验功能

```cpp
struct MESSAGE
{
    uint8_t head[2] = {0xFF, 0xFE}; // 帧头.固定为 0xFF, 0xFE
    uint16_t sn;                    // SN 接收设备编号
    uint8_t cmd;                    // 指令
    uint8_t len;                    // 数据长度
    uint8_t data[64];               // 数据内容
    uint8_t sum;                    // 校验和. 构造函数中将自动构建, 不需要手动计算
    uint8_t address[6];             // 发送信息节点地址 不会在ESPNOW发送中被封包
};
```

可以通过提供的几种构造方法来构建 MESSAGE 结构体

```cpp
MESSAGE(const uint8_t *buf);                                       // 使用数组构造，用于数据接收阶段
MESSAGE(uint16_t _sn, uint8_t _cmd, uint8_t _len = 0, ...);        // 用不定参数的指令数据 构造
MESSAGE(uint16_t _sn, uint8_t _cmd, uint8_t _len, uint8_t *_data); // 用指令数据数组 构造
```

#### 3.2 发送函数

```cpp
void sendMessage(const uint8_t *address, MESSAGE msg);                         // ESPNOW 发送函数 信息结构体
void sendMessage(const uint8_t *address, uint8_t _cmd, uint8_t _len = 0, ...); // ESPNOW 发送函数 不定参数
```

### 4.发送挂起 / 激活指令

向所有已经连接的节点发送挂起 / 激活指令, 注意的是, 激活指令会在 Espnow.begin() 中自动发送.
建议设备每次要进入低功耗模式, 或者关机时发送挂起指令

```cpp
Espnow.supend(); // 挂起指令
Espnow.active(); // 激活指令
```

### 5.获取已经配对的节点数据

```cpp
Espnow.getActivePeers(); // 获取已经配对的节点的总数
Espnow.peers[]; // // 获取已经配对的节点的数组
```

### 6.删除某个已配对的设备 / 清空配对

清空之前所有已经配对的设备

```cpp
Espnow.removePeer(Index); // 删除指定序号的设备
Espnow.clearAllPeers();// 清空配对
```

### 7.承诺指令

1. 对于部分一定需要送达但是对时间不敏感的数据, 可以通过 CMD_PROMISE 指令来发送承诺指令
2. 设备接收到 CMD_PROMISE 后会自动发送 CMD_PROMISE_ASK 指令进行应答
3. A 设备向 B 设备,发送承诺数据后,如果 B 设备出于断电或者距离太远导致无法正常接收到,设备 A 会存储该指令内容, 在 B 设备向 A 设备发送数据的时候, 再尝试进行发送, 确保设备 B 能收到数据.
4. 承诺数据一般用于确保配置信息的发送, 比如 A 是一个无线适配器, B 是设备, 当 A 试图修改 B 的配置时,如果 B 正好处于休眠状态或者信号不佳的位置, 在 B 重新链接后, 能确保一定能接收到配置信息.
5. 每个设备暂时只支持一条承诺信息, 再次发送的承诺数据会覆盖掉内存中旧的信息

```cpp
 // 发送承诺指令 数据内容 uint8_t C
Espnow.sendMessage(mac, CMD_PROMISE,1,C);
```

### 7.配置握手信息

某些情况下, 我们希望设备在握手连接或者启动的时候, 发送带有某些数据的指令, 用于设备配置信息等用途
此时可以通过在 Espnow.begin(SN,data,len);中放入一个数组, 该数组数据,将在握手的时候作为附属信息一起被发送
并且在每次激活的时候也将一起发送.