1总体说明
1.1 基本约定和配置说明
Wifi模块对外的数据传输采用串口通信，所有传输消息都是4字节对齐，采用大端方式。 Wifi模块的串口配置如下：
| 配置项 | 说明 |
|---|---|
| Baud Rate | 115200 |
| Data Bits | 8 |
| Parity | None |
| Stop Bites | 1 |
| Flow Control | 无 |
Wifi模块的输出有两类消息，一类是wifi日志消息，一类是接口控制消息。 以下文档涉及到消息格式定义时，采用C语言的结构体表示。其中u8表示1个字节，u16表示2个字节，u32表示4个字节。
所有消息都采用同步机制，都需要有对应的回应消息。
1.2 接口消息格式
总的消息格式如下，按字节序依次排布：
| 字段名称 | 说明 |
|---|---|
| MagicFlag | 日志消息和控制消息的区分标示，总共四个字节,其中:0x01020304：标示日志消息；0x02030405：控制和数据消息 |
| Payload | Payload结构定义参见以下章节 |
1.2.1 日志消息
日志消息是一个字符串信息，无其他特殊约定。
1.2.2 控制和数据消息
格式如下，按字节序依次排布： |AC_MessageHead||AC_MessageOptHead||AC_MessageOption|.......|AC_MessagePayload| 说明如下：
| 名称 | 作用 |
|---|---|
| AC_MessageHead | 公共消息头，所有消息都要包含此头 |
| AC_MessageOptHead | 可选消息控制头（Option项），提供扩展定义功能，此头是可选存在项，是否存在由AC_MessageHead中的OptNum字段指示。 |
| AC_MessageOption | 可选消息控制体，用以提供可选消息的具体内容，和AC_MessageOptHead配对出现。 |
| AC_MessagePayload | 具体的消息内容 |
所有数据控制消息都有一个AC_MessageHead，然后是存在若干对AC_MessageOptHead和AC_MessageOption，具体的数目通过AC_MessageHead中的OptNum字段指示。Option项主要用以用户的定制化需求和扩展功能。AC_MessagePayload是实际消息内容，具体内容参见以下章节。
1.3 消息头的详细说明
1.3.1 AC_MessageHead格式说明
AC_MessageHead的格式定义如下所示：
typedef struct
{
u8 Version;
u8 MsgId; //消息ID
u8 MsgCode; //消息类型
u8 OptNum;
u16 Payloadlen; //msg payload len + opt len + opt head len
u16 TotalMsgCrc;
} AC_MessageHead;
字段说明如下：
| 名称 | 作用 |
|---|---|
| Version | 协议版本 |
| MsgId | 消息序号 |
| MsgCode | 消息类型，所有的消息类型定义 |
| OptNum | 用以指示Option项的个数 |
| Payloadlen | 消息体的总长度，包括AC_MessagePayload，AC_MessageOptHead和AC_MessageOption所有数据的字节长度 |
| TotalMsgCrc | 消息内容的CRC校验和，消息内容包括AC_MessagePayload，AC_MessageOptHead和AC_MessageOption。采用16bit CRC CCITT |
消息类型列表如下：
| 值 | 消息名称 | 说明 |
|---|---|---|
| 0 | AC_CODE_EQ_BEGIN | 设备启动通知 |
| 1 | AC_CODE_EQ_DONE | Wifi回应设备启动通知 |
| 2 | AC_CODE_WIFI_CONNECTED | Wifi链接成功通知 |
| 3 | AC_CODE_WIFI_DISCONNECTED | Wifi断链通知 |
| 4 | AC_CODE_CLOUD_CONNECTED | 云端链接成功通知 |
| 5 | AC_CODE_CLOUD_DISCONNECTED | 云端链接断链通知 |
| 7 | AC_CODE_REGSITER | 注册接入请求 |
| 8 | AC_CODE_REST | 重置wifi密码设置 |
| 15 | AC_CODE_ACK | 回应消息 |
| 16 | AC_CODE_ERR | 错误消息 |
| 17 | AC_CODE_OTA_BEGIN | OTA启动消息 |
| 18 | AC_CODE_OTA_FILE_BEGIN | OTA文件传输消息 |
| 19 | AC_CODE_OTA_FILE_CHUNK | OTA文件传输 |
| 20 | AC_CODE_OTA_FILE_END | OTA文件传输结束 |
| 21 | AC_CODE_OTA_END | OTA结束 |
| 23 | AC_CODE_ZOTA_FILE_BEGIN | Wifi 升级文件传输消息 |
| 24 | AC_CODE_ZOTA_FILE_CHUNK | Wifi 升级文件传输 |
| 25 | AC_CODE_ZOTA_FILE_END | Wifi 升级文件传输结束 |
| 26 | AC_CODE_ZOTA_END | Wifi 升级OTA结束 |
| 35 | AC_CODE_OTA_CONFIRM | OTA确认升级 |
| 64 | AC_EVENT_BASE | 设备自定义控制消息基址 |
| (64,200) | AC_EVENT_CONTROL_AND_RESPONSE | 由服务或APP发给设备的控制消息以及设备的应答消息 |
| [200,255] | AC_EVENT_DEVICE_REPORT | 设备上报信息 |
1.3.2 AC_MessageOption格式说明
AC_MessageHead的格式定义如下所示：
typedef struct
{
u16 OptCode;
u16 OptLen;
}AC_MessageOptHead;
字段说明如下：
| 名称 | 作用 |
|---|---|
| OptCode | 可选Option消息类型 |
| OptLen | 可选Option的消息长度 |
可选类型消息定义：
| 值 | 消息名称 | 说明 |
|---|---|---|
| 0 | AC_OPT_TRANSPORT | 设备ID透传 |
| 1 | AC_OPT_SSESSION | 链接SSESSION |
2 消息定义和说明
2.1 AC_CODE_EQ_BEGIN消息
设备启动消息，无实际消息内容。设备启动后，择机发送该消息，用以探测wifi模块是否启动完成。
2.2 AC_CODE_EQ_DONE消息
wifi启动回应，无实际消息内容。Wifi收到AC_CODE_EQ_BEGIN消息后，回复该消息。
2.3 AC_CODE_WIFI_CONNECTED消息
Wifi链接成功通知回应，无实际消息内容。
2.4 AC_CODE_WIFI_DISCONNECTED消息
Wifi断链通知，无实际消息内容。
2.5 AC_CODE_CLOUD_CONNECTED消息
Wifi链接云端成功通知，无实际消息内容。
2.6 AC_CODE_CLOUD_DISCONNECTED消息
云端断链通知，无实际消息内容。
2.7 AC_CODE_REGSITER消息
设备接入请求消息，用以设备发起接入云端的请求，wifi模块收到后，立即开始云端接入。 消息格式定义如下：
typedef struct
{
u8 u8EqVersion[4];
u8 u8ModuleKey[112];
u8 u8Domain[8];
u8 u8DeviceId[8];
}AC_RegisterReq
字段说明如下：
| 名称 | 作用 |
|---|---|
| u8EqVersion | 设备版本信息，通过此version来确定目前设备版本，用以后续OTA升级。版本信息设备需要自行存储 |
| u8ModuleKey | 设备的秘钥Key，不同设备Key是唯一的 |
| u8Domain | 设备域信息，不同设备类型不一样 |
| u8DeviceId | 设备唯一标示 |
| 以上信息，都是在设备在出厂前进行相关的注册，注册成功后，自行存储。当设备启动后，先发送请求信息给wifi模块，wifi用来进行和云端认证。 |
2.8 AC_CODE_REST消息
Wifi密码重置情况，消息体为空，当局域网的wifi AP更换，或者密码更换后，重置密码。
2.9 AC_CODE_ACK消息
OTA消息的正确回应，msgid要和请求消息一一对应。
2.10 AC_CODE_ERR消息
OTA消息的错误回应。
typedef struct{
u8 ErrorCode;
}AC_ErrorMsg;
2.11 AC_CODE_OTA_BEGIN消息
OTA升级启动请求。其后按照每个文件的顺序，云端依次发送AC_CODE_OTA_FILE_BEGIN消息，若干AC_CODE_OTA_FILE_CHUNK消息，AC_CODE_OTA_FILE_END消息给设备。所有文件升级完成后，云端发送 AC_CODE_OTA_END。 该消息需要给回应AC_CODE_ACK消息，失败回应AC_CODE_ERR消息。 消息格式定义如下：
typedef struct
{
u8 u8FileNum;
u8 u8Pad[3];
//u8 u8FileType[0];
}AC_OtaBeginReq;
字段说明如下：
| 名称 | 作用 |
|---|---|
| u8FileNum | 用以指示本次升级时文件类型和个数。文件类型在该消息体之后，按字节依次排列 |
| u8Pad | 填充位，无意义 |
2.12 AC_CODE_OTA_FILE_BEGIN消息
OTA 文件传输启动请求，该消息需要给回应AC_CODE_ACK消息，失败回应AC_CODE_ERR消息。
typedef struct
{
u8 u8FileType;
u8 u8FileVersion;
u16 u16TotalFileCrc;
u32 u32FileTotalLen;
}AC_OtaFileBeginReq;
字段说明如下：
| 名称 | 作用 |
|---|---|
| u8FileType | 文件类型 |
| u8FileVersion | 文件版本号 |
| u16TotalFileCrc | 整个文件的CRC |
| u32FileTotalLen | 文件长度 |
2.13 AC_CODE_OTA_FILE_CHUNK消息
OTA 文件块传输请求，该消息需要给回应AC_CODE_ACK消息，失败回应AC_CODE_ERR消息。整个升级文件后，会被拆分成若干文件块进行传输。一次升级会有若干文件块。
typedef struct
{
u32 u32Offset;
}AC_OtaFileChunkReq;
字段说明如下：
| 名称 | 作用 |
|---|---|
| u32Offset | 文件偏移 |
2.14 AC_CODE_OTA_FILE_END消息
OTA升级文件传输结束消息，该消息需要给回应AC_CODE_ACK消息，失败回应AC_CODE_ERR消息。无消息体
2.15 AC_CODE_OTA_END消息
OTA升级结束消息，该消息需要给回应AC_CODE_ACK消息，失败回应AC_CODE_ERR消息。
2.16 AC_CODE_OTA_CONFIRM消息
OTA确认升级消息，收到该消息设备侧启动更新固件流程，执行成功需要回应AC_CODE_ACK消息，失败回应AC_CODE_ERR消息。
2.17 AC_CODE_ZOTA_FILE_BEGIN消息
关于wifi模块，目前支持两种方式的wifi模块的升级方式，一种方式是wifi模块和云端直接进行OTA交互，一种方式是设备先和云端进行交互，获得wifi模块的文件，然后再由设备触发wifi模块升级。 该消息用在第二种方式下wifi模块升级。 消息格式同AC_CODE_OTA_FILE_BEGIN。
2.18 AC_CODE_ZOTA_FILE_CHUNK消息
消息格式同AC_CODE_OTA_FILE_CHUNK。
2.19 AC_CODE_ZOTA_FILE_END消息
消息格式同AC_CODE_OTA_FILE_END。
2.20 AC_CODE_ZOTA_END消息
该消息用以wifi OTA升级完成后，通知设备，设备收到后，择机复位wifi模块，建议收到后，尽快断电复位wifi。
2.21 AC_EVENT_BASE消息
除了上述公共控制消息外，设备可以自行定义消息内容，所有消息类型的基址为AC_EVENT_BASE，根据需要进行累加，最多支持到255。
说明
开区间(64,200)内的代码表示由服务或APP发给设备的控制消息以及设备的应答消息, 注意控制消息和应答消息使用不同的消息类型；闭区间[200,255]内的代码表示设备上报信息。
3 可选内容定义和说明
3.1 AC_OPT_TRANSPORT消息
该消息用于将设备ID和消息一并上传，用来进行针对指定设备的控制管理。 消息定义如下：
typedef struct{
u8 u8DeviciId[8];
} AC_TransportInfo;
3.2 AC_OPT_SSESSION消息
在APP和wifi模块直连模式下，会包含此字段，用以区分是链接SSESSION控制。设备收到直连控制消息后，发送对应的回应消息时，也要包含该可选字段。 消息定义如下：
typedef struct{
u32 u32SsessionId;
}AC_SsessionInfo;
4 消息交互流程
4.1 开机交互流程图
说明：
- 厂商在进行设备开发时，需要将设备的ID，设备的秘钥，设备的域信息，设备的版本信息烧制到设备中。
- 当wifi模块通知可以进行云端接入时，设备需要首先发送AC_CODE_REGSITER消息，携带设备的ID，设备的秘钥，设备的域信息，设备的版本信息给wifi模块，wifi模块利用这些信息进行安全接入。
4.2 OTA交互流程图
说明：
- OTA时，云端会把要升级版本划分成若干文件块，依次通过wifi模块发给设备。
- 设备收全版本后，自行选择升级机制。
- 如需升级wifi模块，需要按照上图的wifi模块升级方式进行升级。
5 API接口和移植说明
5.1 API说明
5.1.1API说明和公共结构定义
在开发过程中，用户可以自己根据消息格式开发相关功能，为了简化实现，提供一下基础API库，开发时可以直接利用。 这些API函数，主要封装了协议交互过程，协议组包过程，协议解析过程，使用这些API后，开发者只需关注业务流程，无需考虑具体协议逻辑。
API使用到的公共结构定义如下：
- AC_OptList，可选项结构，用以存储相关可选项。
结构定义
typedef struct
{
AC_TransportInfo *pstruTransportInfo;
AC_SsessionInfo *pstruSsession;
}AC_OptList;
数据成员
| 字段 | 类型 | 说明 |
|---|---|---|
| pstruTransportInfo | AC_TransportInfo * | 透传数据option项 |
| pstruSsession | AC_SsessionInfo * | 链接ssession |
5.1.2 设备启动
函数定义
void AC_SendDeviceStart(AC_OptList *pstruOptList)
参数
| 字段 | 类型 | 说明 |
|---|---|---|
| pstruOptList | AC_OptList * | Option项列表 |
说明
该函数用于通知wifi模块，设备已经启动完毕，可以接收控制命令
设备注册
函数定义
void AC_SendDeviceRegsiter(AC_OptList *pstruOptList, u8 *pu8EqVersion, u8 *pu8ModuleKey, u8 *pu8Domain, u8 *pu8DeviceId)
参数
| 字段 | 类型 | 说明 |
|---|---|---|
| pstruOptList | AC_OptList * | Option项列表 |
| pu8EqVersion | u8 * | 设备当前版本 |
| pu8ModuleKey | u8 * | 设备秘钥 |
| pu8Domain | u8 * | 设备域名 |
| pu8DeviceId | u8 * | 设备ID |
说明
该函数用于请求云端链接注册，调用后，会发送注册给wifi模块，wifi模块收到后，进行云端链接。 注意：当wifi模块每次启动后并链接wifi成功后，并不会主动链接云端，而是主动上报wifi链接成功消息，设备当接收到该消息后，需要自行确认接入云端的时机。如果wifi模块由于异常重启，需要再次发送该命令触发云端接入。
5.1.3 设备密码重置
函数定义
void AC_SendRestMsg(AC_OptList *pstruOptList)
参数
| 字段 | 类型 | 说明 |
|---|---|---|
| pstruOptList | AC_OptList * | Option项列表 |
说明
当wifi密码重置后，需要设备发送该消息，进行wifi密码重置，重新进入smartconfig状态。
5.1.4 ACK回应
函数定义
void AC_SendAckMsg(AC_OptList *pstruOptList, u8 u8MsgId)
参数
| 字段 | 类型 | 说明 |
|---|---|---|
| pstruOptList | AC_OptList * | Option项列表 |
| u8MsgId | u8 | 消息ID |
说明
发送正确响应，其中MSG ID是对应接收消息的MSG ID。
5.1.5 ERROR回应
函数定义
void AC_SendErrMsg(AC_OptList *pstruOptList, u8 u8MsgId, u8 *pu8ErrorMsg, u16 u16DataLen);
参数
| 字段 | 类型 | 说明 |
|---|---|---|
| pstruOptList | AC_OptList * | Option项列表 |
| u8MsgId | u8 | 设备当前版本 |
| pu8ErrorMsg | u8 * | 错误消息内容 |
| u16DataLen | u16 | 设备当前版本 |
说明
发送控制指令的错误回应，其中MSG ID是对应接收消息的MSG ID。
5.1.6 协议消息组包
函数定义
void AC_BuildMessage(u8 u8MsgCode, u8 u8MsgId,
u8 *pu8Payload, u16 u16PayloadLen,
AC_OptList *pstruOptList,
u8 *pu8Msg, u16 *pu16Len);
参数
| 字段 | 类型 | 说明 |
|---|---|---|
| u8MsgCode | u8 | 消息类型 |
| u8MsgId | u8 | 消息ID |
| pu8Payload | u8 | 消息实际内容 |
| u16PayloadLen | u16 | 消息实际长度 |
| pstruOptList | AC_OptList * | Option项列表 |
| pu8Msg | u8 * | 组好的消息数据的存储buffer |
| pu16Len | u8 * | 组好的数据长度 |
说明
组成协议定义的数据二进制码流。
5.1.7 协议消息接收处理入口
函数定义
void AC_RecvMessage(AC_MessageHead *pstruMsg);
参数
| 字段 | 类型 | 说明 |
|---|---|---|
| pstruMsg | AC_MessageHead * | 接收到的协议数据 |
说明
当设备在串口收齐一包协议数据后，调用该接口进行协议数据处理。
5.1.8 协议Option数据组包
函数定义
void AC_BuildOption(AC_OptList *pstruOptList, u8 *pu8OptNum, u8 *pu8Buffer, u16 *pu16Len);
参数
| 字段 | 类型 | 说明 |
|---|---|---|
| pstruOptList | AC_OptList * | Option项列表 |
| pu8OptNum | u8 * | 组好Option项的个数 |
| pu8Buffer | u8 * | 组好Option项的数据存储缓存 |
| pu16Len | u16 * | 组好Option数据缓存长度 |
说明
将option列表组成协议定义的数据二进制码流。
5.1.9 Option项解析处理
函数定义
void AC_ParseOption(AC_MessageHead *pstruMsg, AC_OptList *pstruOptList, u16 *pu16OptLen);
参数
| 字段 | 类型 | 说明 |
|---|---|---|
| pstruMsg | AC_MessageHead * | 数据接收处理入口 |
| pstruOptList | AC_OptList * | 解析好的数据内容 |
| pu16OptLen | u16 * | Option总长度 |
说明
将原始协议数据码流解析成对应的option项结构。
6 平台移植说明
以下是API进行平台移植时，需要用户自己实现的接口功能。以下接口会在API执行过程中，调用。
6.1 串口数据发送接口
函数定义
void AC_SendMessage(u8 *pu8Msg, u16 u16DataLen);
参数
| 字段 | 类型 | 说明 |
|---|---|---|
| pu8Msg | u8 * | 待发送的数据缓存 |
| u16DataLen | u16 | 待发送的数据长度 |
说明
串口数据发送接口，当数据按协议格式组好后，需要使用该接口进行数据发送。
6.2 通知类型消息处理接口
函数定义
void AC_DealNotifyMessage(AC_MessageHead *pstruMsg, AC_OptList *pstruOptList , u8 *pu8Playload);
参数
| 字段 | 类型 | 说明 |
|---|---|---|
| pstruMsg | AC_MessageHead * | 收到的数据 |
| pstruOptList | AC_OptList * | 解析后的option项 |
| pu8Playload | u8 * | 指向Playload数据起始位置 |
说明
当API收到如下消息后，调用该接口：AC_CODE_EQ_DONE, AC_CODE_WIFI_CONNECTED, AC_CODE_WIFI_DISCONNECTED, AC_CODE_CLOUD_CONNECTED,AC_CODE_CLOUD_DISCONNECTED。
6.3 OTA升级处理接口
函数定义
void AC_DealOtaMessage (AC_MessageHead *pstruMsg, AC_OptList *pstruOptList , u8 *pu8Playload);
参数
| 字段 | 类型 | 说明 |
|---|---|---|
| pstruMsg | AC_MessageHead * | 收到的数据 |
| pstruOptList | AC_OptList * | 解析后的option项 |
| pu8Playload | u8 * | 指向Playload数据起始位置 |
说明
当API收到如下消息后，调用该接口：AC_CODE_OTA_BEGIN,AC_CODE_OTA_FILE_BEGIN,AC_CODE_OTA_FILE_CHUNK,AC_CODE_OTA_FILE_END,AC_CODE_OTA_END。
6.4 设备控制消息处理接口
函数定义
void AC_DealEvent(AC_MessageHead *pstruMsg, AC_OptList *pstruOptList , u8 *pu8Playload);
参数
| 字段 | 类型 | 说明 |
|---|---|---|
| pstruMsg | AC_MessageHead * | 收到的数据 |
| pstruOptList | AC_OptList * | 解析后的option项 |
| pu8Playload | u8 * | 指向Playload数据起始位置 |
说明
当API收相关的设备自定义控制消息后，调用该接口。自定义消息必须大于等于AC_EVENT_BASE。