全系列模组购买请戳:安信可官方淘宝店

OneNET AT指令

概述

描述 WIFI 模组的扩展指令集功能以及使用方法。

扩展指令集主要应用在和中国移动物联网 OneNet 开放平台实现设备数据上传和命令控

制功能,模块原有 AT 命令、Wifi 功能 AT 命令、TCP/IP 工具箱 AT 命令等保持不变。

模组扩展指令功能需求

 模组扩展指令设计简介

模组扩展指令的设计旨在实现终端设备和平台服务器之间数据通讯,其中终端设备主要

由 WIFI 模组及 MCU 主控模块组成,模组扩展指令的功能主要是将平台接入协议(Http 协议

和 EDP 协议)植入 WIFI 模组,然后进行封装,给用户提供开放的指令接口,用户使用这些

指令就可以轻松实现终端设备和平台服务器之间的数据通讯,平台服务器、WIFI 模组及 MCU

主控模块三者之间的关系如下图所示。

图 1 平台服务器、WIFI 模组及 MCU 主控模块关系图

 模组扩展指令设计思路

模组扩展指令的设计主要围绕终端设备和平台之间的数据通讯进行设计,主要包括以下过程和步骤。

  • 步骤 1:主 Apikey 参数固化—终端设备开发商在 OneNET 平台注册公司管理用户账户,

并在该账号下新建一个项目,一个项目对应平台上的一个 MasterKey(也称主 Apikey),将平台申请到的主 Apikey 通过串口工具或者 MCU 上的程序代码发送给 WIFI 模组,WIFI 模组将该参数烧录在固定地址空间。

  • 步骤 2:平台设备定义—WIFI 模组利用在主 Apikey 在平台申请该设备的设备 ID 和设备 Apikey,同时也将申请成功的参数进行保存,后续 WIFI 模组就可以利用自身保存的设备

ID 及设备 Apikey 同平台服务器完成数据通讯。

  • 步骤 3:建立设备连接—WIFI 模组的数据通讯是采用的 EDP 协议,EDP 协议是建立在

TCP/IP 基础上,所以要完成设备连接,先得确保 WIFI 模组连上可用的 AP,然后 WIFI 模组和平台服务器建立 TCP 连接,最后利用设备 ID 及设备 Apikey 封装成 EDP 连接报文建立设备连接。

  • 步骤 4:数据上传—WIFI 模组接收主控 MCU 的数据,然后封装成 EDP 报文,发送至平台服务器。
  • 步骤 5:命令控制—WIFI 模组接收到平台服务器的 EDP 命令控制报文,解析报文内容,然后发送给主控 MCU。

平台服务器、WIFI 模组及 MCU 主控模块三者之间的数据流程如下图所示。

图 2 平台服务器、WIFI 模组及 MCU 主控模块数据流程图

模组扩展指令命名规则及使用说明

扩展指令保持原 AT 指令命名风格,采用 AT+CIOT的方式。

 模组扩展指令所实现的主要功能及分类

模组扩展指令暂时设计为 18 条,后续可扩展更丰富的功能。

  • 基本参数查询设置功能
  • 平台业务定义功能(利用 HTTP 协议的 RESTful API)
  • 平台设备连接功能(利用平台提供的 EDPSDK)
  • 平台数据上传功能(利用平台提供的 EDPSDK)
  • 平台命令控制功能(利用平台提供的 EDPSDK)

 WIFI模组扩展指令详细说明

 WIFI模组扩展指令一览表

WIFI 模组扩展 AT 指令  
命令 描述
AT+CIOT 查询固化参数;
AT+CIOTMKEY 查询主 Apikey;
AT+CIOTMKEYA 设置主 Apikey;
AT+CIOTINIT 启动参数创建;
AT+CIOTID 查询设备操作命令;
AT+CIOTIDC 删除设备操作命令;
AT+CIOTKEY 查询设备 Apikey 操作命令;
AT+CIOTKEYC 删除设备 Apikey 操作命令;
AT+CIOTSTATUS 查询 WIFI 模组和物联网平台的连接状态;
AT+CIOTSTART 启动向物联网平台数据发送;
AT+CIOTDAT 向物联网平台传送小数据;
AT+CIOTBINSET 设置二进制文件上传的信息;
AT+CIOTBINSEND 发送二进制文件内容;
AT+CIOTBINEND 结束二进制文件;
AT+CIOTQUIT 停止向物联网平台数据传送;
AT+CIOTSEND 单次向物联网平台传送小数据;
AT+CIOTPING 心跳指令;
+IOTCMD 物联网平台发送的控制命令;

该页AT指令版本为v1.3,请下载onenet_at_v1.3固件。

AT指令版本v1.4的改动了一些指令,删除了部分AT指令,增加了新的AT指令。

onenet_at_v1.4固件指令修改 onenet_at_command_v1.4.pdf

 错误码定义

错误码说明 错误码
WLAN 错误 -100
网络错误 -101
没有 master key -102
没有设备 ID -103
没有设备 key -104
设备不在线 -105
无效的操作 -106
文件发送错误 -107
参数错误 -108
设备连接失败 -109
数据发送失败 -110
设备连接断开失败 -111
设备参数初始化失败 -112

 指令格式说明

(1) 格式说明

<>:表示必须包含的部分
[]:表示可选的部分

(2) 命令消息格式

AT+<CMD>[op][para-1,para-2,para-3,......]<CR>
a) AT+:命令消息前缀
b) CMD:命令字符串
c) [op]:命令操作符,挃定是参数设置或查询。可以是:1、"=":表示参数设置2、"无":表示参数查询
d) [para-n]:参数设置时的输入,查询命令时为"?"
e) <CR>:结束符,回车,ASCII 码 0x0d

(3) 回应消息格式

+<RSP>=[para-1,para-2,para-3,......]<CR><LF>
a) +:响应消息前缀
b) RSP:相应字符串,包括:
  1. "OK":表示成功
  2. "ERR":表示失败
c) [para-n]:查询时返回的参数,或者出错时的错误码
d) <CR>: ASCII 码 0x0d
e) <LF>: ASCII 码 0x0a

 AT指令

 AT+CIOT

说明:查询 WIFI 模块的主 APIKEY,设备 ID 及设备 APIKEY 是否已经固化存在。

功能:查询参数是否存在
查询指令格式: 正确响应:
AT+CIOT?<CR> +OK<CR><LF>
错误响应分三种情况:
+ERR=-102<CR><LF>
+ERR=-103<CR><LF>
+ERR=-104<CR><LF>
参数:无

注:模块需要固化主APIKEY,设备ID及设备APIKEY三个参数,目前APIKEY的长度为28个

字节长度,但后续有扩展的可能;设备 ID 长度也是扩展的。

 AT+CIOTMKEY

说明:查询 WIFI 模块的主 APIKEY 是否已经固化存在。

功能:查询 master key 是否存在
查询指令格式: 正确响应:
AT+CIOTMKEY?<CR> +OK<CR><LF>
错误响应:
+ERR=-102<CR><LF>
参数:无

 AT+CIOTMKEYA

说明:设置 WIFI 模块的主 APIKEY 参数。如果本地已经存在主 APIKEY,执行此条指令会覆盖

已有的主 APIKEY,同时删除原有主 APIKEY 创建的设备 ID 和设备 APIKEY。

功能:设置并固化 master key
指令格式: 正确响应:
AT+CIOTMKEYA=[mkey]<CR> +OK=[mkey]<CR><LF>
错误响应:
+ERR<CR><LF>
参数:mkey 为主 APIKEY

 AT+CIOTINIT

说明:AT+CIOTINIT 用来启动设备 ID 和设备 Apikey 参数的创建或者参数的有效性验证,创

建参数前,必须已经固化了主 Apikey,WIFI 模块使用主 Apikey 向平台服务器申请设备 ID

的创建,然后再进行设备 Apikey 的创建。参数创建成功后,WIFI 模组都需要将创建成功的

参数固化在自身的参数存储区。

如果本地主 Apikey,设备 ID 和设备 Apikey 都存在,则只需要去平台服务器查询设备 ID 和

设备 Apikey 是否存在。(平台查询参数是确保平台上对应的设备没有被删除),如果平台查

询失败,则必须清除设备 ID 和设备 APIKEY,然后使用主 APIKEY 在平台重新创建设备,获

取新的设备 ID 和设备 APIKEY,再进行固化。

功能:启动参数创建
指令格式: 正确响应:
AT+CIOTINIT<CR> +OK<CR><LF>
错误响应:
+ERR=-100<CR><LF>
+ERR=-101<CR><LF>
+ERR=-102<CR><LF>
+ERR=-112<CR><LF>
参数:无

 AT+CIOTID

说明:查询设备 ID

功能:查询设备 ID 是否存在
查询指令格式: 正确响应:
AT+CIOTID?<CR> +OK=[dev_id]<CR><LF>
错误响应:
+ERR=-103<CR><LF>
参数:dev_id

 AT+CIOTIDC

说明:删除设备 ID,必须删除对应的设备 APIKEY。

功能:删除设备 ID
指令格式: 正确响应:
AT+CIOTIDC<CR> +OK<CR><LF>
错误响应:
+ERR<CR><LF>
参数:无

 AT+CIOTKEY

说明:查询设备 APIKEY

功能:查询设备 apikey
查询指令格式: 正确响应:
AT+CIOTKEY?<CR> +OK=[apikey]<CR><LF>
正确响应:
+ERR=-104<CR><LF>
参数:apikey  设备 APIKEY

 AT+CIOTKEYC

说明:删除设备 APIKEY,不必删除设备 ID。

功能:删除设备 APIKEY
指令格式: 正确响应:
AT+CIOTKEYC<CR> +OK<CR><LF>
错误响应:
+ERR<CR><LF>
参数:无

 AT+CIOTSTATUS

说明:指令功能是查询设备的连接状态。

功能:查询设备连接状态
指令格式: 响应:
AT+CIOTSTATUS<CR> +OK=state<CR><LF>
参数:state
²  device_up,设备登录
²  Device_down,设备未登录

 AT+CIOTSTART

说明:指令功能是建立设备连接,启动数据发送。

功能:建立设备连接,启动数据发送
指令格式: 正确响应:
AT+CIOTSTART=[encrypt]<CR> +OK<CR><LF>
错误响应:
+ERR=-108<CR><LF>
+ERR=-109<CR><LF>
参数:encrypt
0,不使用加密
1,使用加密

 AT+CIOTDAT

说明:指令功能是长传小数据

功能:发送数据
指令格式: 正确响应:
AT+CIOTDAT=[num,key_1,time_1,value_1…key_n,time_n,value_n]<CR> +OK<CR><LF>
错误响应:
+ERR=-108<CR><LF>
+ERR=-110<CR><LF>
参数:
Num:数据记录数量
key:数据采样名称
time:数据采样时间
value:数据采样值
说明:
时间格式:如 2016-01-01 00:00:00 年月日用’-’分隔 时分秒用’:’分隔
如没有采样时间,则时间项不填,格式为 AT+CIOTSTART=[kay,,value]<CR>

AT+CIOTBINSET

说明:设置二进制文件发送的头部信息,由于数据缓冲大小的限制,一般在进行二进制文件

上传的时候,先将 EDP 头部传给服务器,然后将二进制文件数据分片上传的方式来进行二

进制文件上传。(AT+CIOTBINSET,AT+CIOTBINSEND 及 AT+CIOTBINEND 组合使用)

功能:设置二进制文件
指令格式: 正确响应:
AT+CIOTDATBINSET=[des,bin_lens]<CR> +OK<CR><LF>
错误响应:
+ERR=-108<CR><LF>
参数:
des:二进制文件的数据流 ID
bin_lens:文件总长度
说明:  

AT+CIOTBINSEND

说明:发送二进制文件的数据,在参数检查的时候,只需要判断当前长度和数据个数相等即可。

功能:发送二进制文件
指令格式: 正确响应:
AT+CIOTBINSEND=[bin_len,bin_data]<CR> +OK<CR><LF>
错误响应:
+ERR=-108<CR><LF>
参数:
bin_len:当次发送数据长度
bin_data:数据(数据形式为 16 进制格式,如 01AA55 表示数据 OX01,OXAA,OX55)

说明:正确响应+OK 表示 WIFI 将本次的数据网络发送成功。

 AT+CIOTBINEND

说明:设置二进制文件发送的结束标记,返回文件发送的状态。

功能:结束二进制文件
指令格式: 正确响应:
AT+CIOTBINEND<CR> +OK=<CR><LF>
错误响应:
+ERR=-107<CR><LF>
参数:无

 AT+CIOTQUIT

说明:指令实现的功能为断开设备连接,停止数据发送。

功能:断开设备连接
指令格式: 正确响应:
AT+CIOTQUIT<CR> +OK<CR><LF>
错误响应:
+ERR=-111<CR><LF>
参数:无

注:EDP 协议没有断开设备连接请求的报文,AT+CIOTQUIT 要实现断开设备连接的功能,直接断开和服务器的 TCP 连接,可以达到断开设备连接的目的。

 AT+CIOTSEND

说明:发送小数据,功能等同于指令集(AT+CIOTSTART;AT+CIOTDAT;AT+CIOTQUIT)指令

内部执行流程如下:

功能:发送采样数据
指令格式: 正确响应:
AT+CIOTDAT=[encrypt,num,kay_1,time_1,value_1…kay_n,time_n,value_n]<CR> +OK<CR><LF>
错误响应:
+ERR=-108<CR><LF>
+ERR=-109<CR><LF>
+ERR=-110<CR><LF>
+ERR=-111<CR><LF>
参数:
encrypt:是否加密
num: 数据记录数
0,不加密
1,加密
key:数据采样名称
time:数据采样时间
value:数据采样值
说明:
时间格式:如 2016-01-01 00:00:00年月日用’-’分隔 时分秒用’:’分隔, 如没有采样时间,则时间项不填,格式为 AT+CIOTSEND=[encrypt,kay,,value]<CR>

 AT+CIOTPING

功能:心跳
指令格式: 正确响应:
AT+CIOTPING<CR> +OK<CR><LF>
错误响应:
+ERR<CR><LF>
参数:无

 +IOTCMD

说明:此指令是 WIFI 模组主动发送给 MCU,当 WIFI 模组接收到物联网平台发送的控制命令

时,向串口发送“+IOTCMD=[datalen,data]”其中“+IOTCMD:”仅仅是给 MCU 标识符,表示

这是平台下发的控制命令。

平台服务器向设备发送控制命令
事件格式: 参数:
+IOTCMD=[datalen,data]<CR><LF> datalen:控制命令的数据长度
data: 控制命令内容

指令使用实例

 单次上传小数据

(1) AT+CIOT?    //查询主 APIKEY 存在
(2) AT+CIOTINIT //创建设备参数,平台查询设备参数—即参数的有效性验证
(3) AT+CIOTSEND //单次上传一条数据

 循环上传小数据

(1) AT+CIOT?     //查询主 APIKEY 存在
(2) AT+CIOTINIT  //创建设备参数,平台查询设备参数—即参数的有效性验证
(3) AT+CIOTSTART //启动数据发送
(4) AT+CIOTDAT   //上传小数据
......
(5) AT+CIOTDAT   //上传小数据
(6) AT+CIOTQUIT  //停止数据发送

 上传二进制文件

(1) AT+CIOT?     //查询主 APIKEY 存在
(2) AT+CIOTINIT  //创建设备参数,平台查询设备参数—即参数的有效性验证
(3) AT+CIOTSTART //启动数据发送
// 上传第一个文件
(4) AT+CIOTBINSET  //设置二进制文件
(4) AT+CIOTBINSEND //发送二进制文件
(5) AT+CIOTBINEND  //结束二进制文件
//上传第 N 个文件
//上传第一个文件
(6) AT+CIOTBINSET  //设置二进制文件
(7) AT+CIOTBINSEND //发送二进制文件
(8) AT+CIOTBINEND  //结束二进制文件
(9) AT+CIOTQUIT    //停止数据发送