氦氪HEKR嵌入式API文档

v1.0.12 by fwj@hekr.me 2015/11/25 19:08:05

关键词

SEXP: S表达式，又称lambdaTM代码。SEXP既是代码也是数据，是API交互的基本格式
可选参数：当参数类型为可选参数时，若不需要该参数，则直接留空
必选参数：当参数类型为必选参数时，若不需要该参数，通常情况下用""占位
Device token: 设备授权识别码,获取方式参考云端API文档
E1: UART API（E1为编号，方便沟通时定位相关内容）
E2: UDP API
E3: WEB API
E4：Lisp通用接口

文档说明

本文档内容基于v3.0.0的固件版本编写，低于该版本的固件部分接口表现可能不一致。

E1 UART接口说明

UART默认参数为9600-8-N-1，通常情况下UART口数据会直接透传到终端(见E1-3)，透传相关协议参考Hekr V1.1模块数据透传说明文档。

E1-1 dev-test 出厂测试指令

API格式

(dev-test)

API功能

进入出厂测试模式

出厂测试说明

模块重启进入出厂测试模式
连接SSID为hekr-test 密码HEKR12345678的Wi-Fi热点
连接出厂测试服务器factorytest.hekr.me
等待服务器发送测试命令

E1-2 getall 获取模块信息

API格式

(getall)

API功能

获取模块信息，例如设备状态，型号id，厂家id，分类id，软AP密码，固件版本，固件版本类型等

返回值示例：

（quote ((state) (detail "mname" "UNIVERSAL_FW_M01" "tid" "ESP_2M_18FE3498A9DD" "mid" 93 "pid" 56 "cid" 75 "host" "device.hekr.me" "testflag" 0 "softapkey" "" "binver" "3.0.61.2" "bintype" "A" "rebootreason" 6)))

返回值说明：

mname 型号名称
mid Model ID 定义该产品型号
cid Category ID 定义该产品类型
pid Provider ID 定义产品提供商
host Host 定义产品连接的云服务器域名
binver 固件版本
bintype 启动分区(目前使用的固件所在分区)
rebootreason 设备上电信息

E1-3 数据透传

透传数据格式参考透传协议

当模块正常连接到云端时,数据通过云端以onmessage透传至终端格式如下：

(onmessage "907c0e62f1736eb318c4185e12747fc6" "ESP_2M_1AFE349C3D1F" "state" "uartdata" "480E02010201000000000000005C" )

当模块连接到路由器但无法连接到云端时,除特殊别说明的消息帧外,数据通过局域网UDP端口10000广播，格式如下：

(lanmsg "tid" "uartdata" "480E02010201000000000000005C")

E2 UDP接口说明

UDP端口为10000,通信内容格式采用S表达式。APP接收模块返回消息也同样采用UDP端口10000。

E2-1 discover 发现设备

发送(discover "tid")

tid - 设备标识码，必选参数，可留空，例如 (discover "" )

返回(device "tid" "mid" "mac")

tid - 设备标识码
mid - 设备类型码
mac - 设备MAC地址

E2-2 ak 设备授权

该接口与E4-1 ak一致，用于局域网配置设备ak，因为支持局域网直接调用（非通过lancall），特此重新说明。

发送(ak "device_token" "tid")

device_token - 设备授权码，通过云端接口获取
tid - 设备标识码，可选参数

返回(deviceACK "tid" "mid" "mac" "device_token" "result")

tid - 设备标识码
mid - 设备类型码
mac - 设备MAC地址
device_token - 设备授权码
result - 操作应答，0表示成功

通过局域网发送ak指令仅当设备未被授权或处于配置模式时有效。若设备已被授权，需先取消授权，否则不响应该指令。

E2-3 lancall 局域网控制

API格式

(lancall "tid" (quote (lispSEXP)) "lock key" "return ip")

API功能

局域网广播调用Lisp通用接口,除了特殊声明指令外，均支持通过该方式调用。

API参数

tid - 设备tid
lispSEXP - lisp表达式参考E4
lock key - 可选参数，当设备上锁后需要lock key才可正常执行否则返回中result为#f
return ip - 必选参数，API返回目标IP地址，默认255.255.255.255，建议使用APP当前IP

API示例

(lancall "RT5350F_8F_ccd29be70139" 
(quote (uartdata "EF6E6F")) "lock key" "192.168.1.102")

API返回

(lanmsg "dev-tid" result)

result根据表达式执行结果返回，参考E4相关指令说明。

E3 WEB接口说明

E3接口主要用于Wi-Fi模块SoftAP模式下配置模块相关信息，在终端连接到Hekr_xxxxxx无线信号后使用。

E3接口对应APP SDK中M1-6、M1-7、M1-8等接口，可以直接通过APP SDK调用。

E3-1 设置Device token（ak）

GET http://192.168.10.1/t/set_ak?ak=device_token

请求参数

ak - 设备授权码(device_token)

返回值

code - 返回代码，0表示设置成功
msg - 返回信息
tid - 模块唯一标识

E3-2 扫描无线网络

GET http://192.168.10.1/t/get_aplist

请求参数

返回内容

[
    {
        "auth_suites":"AUTH_WPA_WPA2_PSK",
        "ssid":"hekr-test",
        "signal":-82,
        "channel":13,
        "bssid": "6C:59:40:73:4A:16"
    },
    {
        ...
    }
]

auth_suites - Wi-Fi加密方式取值：AUTH_OPEN / AUTH_WEP / AUTH_WPA_PSK / AUTH_WPA_WPA2_PSK
ssid - SSID
signal - 信号强度
channel - Wi-Fi信道
bssid - 信号BSSID

E3-3 设置AP信息

GET http://192.168.10.1/t/set_bridge?ssid=v_ssid&bssid=v_bssid&encryption=v_encryption&channel=v_channel&key=v_key

请求参数

ssid - SSID
key - Wi-Fi密码
channel - Wi-Fi信道
bssid - 信号BSSID
encryption - 加密方式，注意需要转化取值0：无密码 1：WEP 2：PSK2 3：EAP,默认值2
tid - 模块唯一标识

返回值

code - 返回代码，0表示设置成功
msg - 返回信息

E4 Lisp通用接口

Lisp相关信息参考IoTSS。

API调用方中以D(Device)、C(Cloud)、U(User)标示，例如:

C-D链路表示云端调用设备上的接口
U-D链路表示用户直接通过局域网调用设备上的接口
U-C-D链路表示用户通过云端调用设备上的接口

E4-1 ak

API格式

(ak "accesskey" "tid")

API功能

设置产品access key(授权用户识别)

API调用方

C-D链路、U-C-D链路、U-D链路（参考E2-2）

API使用说明

若不带accesskey参数则为查询当前ak 例如:(ak)
若accesskey为空则为清除当前ak 例如：（ak ""） （U-D链路不支持该方式调用）
tid为可选参数

API调用示例

(ak "azArbWZMQ215NHJ3MzhXL3RwUllmazZzMENkQ2tVQmJTZzlYai84MzI0b05xSnNhZGpqbGRra3A2Z0ZY00000000" "ESP_2M_1AFE00000000")

参数说明

accesskey Access Key 授权用户识别
tid Terminal ID 终端唯一标识码

API返回

(deviceACK "tid" mid "accesskey" result) ，result为0表示成功，同时向调用方以及云端返回

若tid不匹配则返回#f

E4-2 setParam

API格式

(setParam "mid" xxx "cid" xxx "pid" xxx "host" "xxx")

API功能

设置通用固件出厂时相关信息修改。

API调用方

C-D链路

API使用说明

参数需成对，key-value形式

API调用示例

(setParam "mid" 2 "cid" 1 "pid" 1 "host" "device.hekr.me")

参数说明

mid Model ID 定义该产品型号
cid Category ID 定义该产品类型
pid Provider ID 定义产品提供商
host Host 定义产品连接的云服务器域名，通常为与厂家相关的三级域名以便于后期私有云切换。

API返回

成功 #t
失败 #f

E4-3 setTimer 设置预约任务

API格式

(setTimer taskid code delaytime count looptime )

API功能

设置定时任务

API调用方

C-D链路

API使用说明

一个下发周期内最多设置10条taskid

API调用示例

(setTimer 1 (quote (uartdata "48xxxxxx"))   400  1  0)

参数说明

taskid 预约任务编号,int32
code 执行代码
delaytime 延时时间,单位秒(s),最大3600s
count 循环执行次数，1表示执行一次、n表示执行n次(间隔为looptime)
looptime 循环时间间隔，单位秒(s)

API返回

成功 #t
失败 #f

E4-4 delTimer 删除预约任务

API格式

(delTimer taskid )

API功能

删除预约任务

参数说明

taskid 预约任务编号,int32

API返回

成功 #t
失败 #f

E4-5 dev.upgrade

API格式

(dev.upgrade tid URL MD5 type)

API功能

设备升级

API使用说明

若url等参数留空，模块会自动通过C2-4获取新固件地址。
升级过程中，模块会通过mcastFormatMsgs广播升级进度(mcastFormatMsgs "upgradeprogress" 10 "upgradestate" 1)
upgradeprogress 升级进度(0~100)
upgradestate 升级状态： 0"成功" 、1"下载中" 、 2"固件校验失败" 、 3"超时" 、4"连接失败"

参数说明

tid 模块唯一标识
URL 新固件的URL(仅支持http)
MD5 新固件的32位MD5校验码
type 固件类型

API返回

成功：0
TID错误： 1
固件类型错误： 2
升级中： 3

API调用示例

指定下载固件`http://update.hekr.me/firmware/xxxx.bin` ：

(dev.upgrade "ESP_2M_1AFE349C3DF2" "http://update.hekr.me/firmware/xxxx.bin" "ab6469e59ba1d11c037d67b8d0a67930" "A")

向HEKR SOC服务器获取最新固件：

(dev.upgrade "ESP_2M_1AFE349C3DF2" "" "" "")

E4-6 setExtParam

API格式

(setExtParam "ExtParamString" )

API功能

设置产品出厂信息

API调用方

C-D链路（仅在出厂测试时生产测试服务器使用）

API调用示例

(setExtParam " \"mk\" \"swGi3o2v0CYjDui15OTHKJ/XmyffSF6B\"")

参数说明

ExtParamString 扩展参数，会被加在detail末尾上报云端
tid 设备识别码，可选

API返回

成功返回#t 失败则返回#f

E4-7 getTimerList

API格式

(getTimerList taskid )

API功能

获取预约列表

API调用方

C-D链路

API使用说明

taskid可选参数，不带则返回当前所有预约

API调用示例

(getTimerList 1 )

API返回

(quote (timerList (taskid code delaytime count looptime) (taskid code delaytime count looptime)))

返回参数说明

taskid 预约任务编号,int32
code 执行代码
delaytime 剩余延时时间,单位秒(s)
count 剩余循环执行次数，1表示执行一次、n表示执行n次(间隔为looptime)
looptime 循环时间间隔，单位秒(s)

接口更新历史

v1.0.12

1.追加(dev.upgrade tid "" "" "")说明

v1.0.11

1. discover去掉目前不支持的参数: option
1. 补充(getall)接口说明
1. 更新(dev-test)接口说明

v1.0.9

1.添加E4-8 getTimerList

v1.0.9

1.添加E4-8 getTimerList

v1.0.8

1.修改E4-6 dev.upgrade ：添加upgradestate字段

v1.0.7

1.修改E4-6 dev.upgrade ：添加type字段

v1.0.6

1.修改getall ："binver" "bintype"字段，追加 "state" "mk" "testflag"

v1.0.5

1.修改E4-6 dev.upgrade 添加MD5
2.修改E4-6 dev.upgrade 参数说明，URL可留空

v1.0.4

1.修改E4-7 ek指令为setExtParam
2.修改E4-6 dev.upgrade参数为url

v1.0.3

E3-1、E3-3 返回参数添加tid字段

v1.0.2

1.添加E4-8 ek-企业识别码设置接口
2.添加E1-3 数据透传，添加局域网广播透传说明
3.添加E2-3 lancall-局域网控制

v1.0.1

添加E4 Lisp通用接口

v1.0.0

初始化版本，E1、E2、E3接口说明

最新版文档请访问在线文档 http://docs.hekr.me

氦氪HEKR嵌入式API文档

关键词

文档说明

E1 UART接口说明

E1-1 dev-test 出厂测试指令

API格式

API功能

出厂测试说明

E1-2 getall 获取模块信息

API格式

API功能

E1-3 数据透传

E2 UDP接口说明

E2-1 discover 发现设备

E2-2 ak 设备授权

E2-3 lancall 局域网控制

API格式

API功能

API参数

API示例

API返回

E3 WEB接口说明

E3-1 设置Device token（ak）

E3-2 扫描无线网络

E3-3 设置AP信息

E4 Lisp通用接口

E4-1 ak

API格式

API功能

API调用方

API使用说明

API调用示例

参数说明

API返回

E4-2 setParam

API格式

API功能

API调用方

API使用说明

API调用示例

参数说明

API返回

E4-3 setTimer 设置预约任务

API格式

API功能

API调用方

API使用说明

API调用示例

参数说明

API返回

E4-4 delTimer 删除预约任务

API格式

API功能

参数说明

API返回

E4-5 dev.upgrade

API格式

API功能

API使用说明

参数说明

API返回

API调用示例

指定下载固件http://update.hekr.me/firmware/xxxx.bin ：

向HEKR SOC服务器获取最新固件：

E4-6 setExtParam

API格式

API功能

API调用方

API调用示例

参数说明

API返回

E4-7 getTimerList

API格式

API功能

API调用方

API使用说明

API调用示例

API返回

返回参数说明

接口更新历史

指定下载固件`http://update.hekr.me/firmware/xxxx.bin` ：