氦氪云端API文档(C3)
v1.0.0 by honghu.hu@hekr.me 7/20/2015 9:18:13 PM
氦氪云端 TCP & WEBSOCKET 原生API 文档
关键词
S表达式
:即SEXP
,准确地说是lambdaTM
代码,SEXP既是代码也是数据,这对于理解指令和后续描述的一些场景非常重要lambdaTM
:氦氪自主开发的一种Lisp方言请求参数
:请求中所带参数单播
:unicast,点对点发送组播
:multicast,点对多发送终端
:连接到云端的客户端,分为设备终端
、用户终端
设备终端
:通常是指被动接受控制的终端,例如智能家电等用户终端
:通常是指主动发出控制的终端,例如智能APP、网页、DEBUG控制台等最大组播
:分为设备终端最大组播
、用户终端最大组播
设备终端最大组播
:设备终端组播消息到同宿主用户及授权用户下的所有用户终端用户终端最大组播
:用户终端组播消息到同宿主用户的所有用户终端格式化
:专指氦氪云端将消息或数据包装成(onmessage uid tid data1 ... dataN)的格式主控模式
:硬件模块通过本身的硬件接口(GPIO、I2C、SPI等)直接连接继电器、传感器等硬件模块以完成客户需要的产品功能透传模式
:硬件模块通过本身的UART(串行通信)接口和客户产品中的MCU(单片机)连接,通信协议遵循氦氪模块数据透传说明设备无宿主
:设备未被认领,通常是由于设备处环境不便,或者其他特殊原因,导致用户不能在现场直接和设备绑定
C3 TCP & WEBSOCKET 原生API 说明
下文列举的API都是非常底层的原始云端接口,基于此说明,不依赖于SDK,就能使用氦氪云服务。如果希望快速开发,建议直接使用SDK。
tcp 服务地址 device.hekr.me:9999
websocket 服务地址 device.hekr.me:8080
C3-1 login
API格式
(login <tid> <channel> <accessKey> <type>)\n
API功能
终端登录云端。如果是设备终端登录,且成功后,会设备终端最大组播
一个登陆成功的格式化消息
API调用方
设备终端、用户终端
API使用说明
- 终端接入云端时,需先调用login,调用成功后,终端方能后续操作
- 终端调用login成功之前,云端不会响应任何其他API的调用
- 使用tcp长连接通信方式时,需要显式调用login;而采用websocket长连接通信方式时,不要显式调用login,而是通过如下地址访问:
ws://device.hekr.me:8080/websocket/t/<tid>/<channel>/<accesskey>/<type>
- 当accessKey为空字符串时,type必须为"DEVICE",该终端被认为是
设备无宿主
API调用示例
(login "RT5350F_8F_ccd29be70139" "code" "user_3200999" "DEVICE")\n
(login "AppTid_ccxxx" "code" "accesskey" "USER")\n
参数说明
tid
终端Id,字符串(注意这里当type是USER的时候,tid是对应app的终端tid,apptid绝对不能与设备tid一样)channel
通信频道,字符串,可选["code"]accessKey
授权Key,字符串,获取方法请参考API C1-2type
终端类型,字符串,可选["DEVICE", "USER"],分别对应设备终端、用户终端
API返回
成功
云端对本终端的getall
回调失败
云端会直接关闭连接
组播消息格式
(onmessage <调用终端宿主uid> <tid> "login")
用户终端监听此消息,就可以实现对设备终端的上/下线监控
C3-2 setTermDetail
API格式
(setTermDetail <data1> ... <dataN>)\n
API功能
终端向云端上报终端明细、厂家信息等
API调用方
设备终端、用户终端
API使用说明
无
API调用示例
(setTermDetail "pid" "1" "mid" "2" "cid" "1" "provider" "LSA" "category" "yuba" "model" "phone" "400-800-999")\n
参数说明
data1 ... dataN
终端明细、厂家信息,字符串/数值
API返回
成功
#t失败
#f
C3-3 getTermDetail
API格式
(getTermDetail <tid>)\n
API功能
从云端获取非格式化的终端明细、厂家信息等
API调用方
用户终端
API使用说明
调用终端只能是用户终端,能获取调用终端自己的信息、同宿主用户下所有设备终端及所有被授权的设备终端信息
API调用示例
(getTermDetail "RT5350F_8F_ccd29be70139")\n
参数说明
tid
终端Id,字符串,API使用说明中指定了该值的设定范围
API返回
成功
setTermDetail时填入的那些参数
"(<data1> ... <dataN>)"
形如:"(\"pid\" \"1\" \"mid\" \"2\" \"cid\" \"1\" \"provider\" \"LSA\" \"category\" \"yuba\" \"model\" \"phone\" \"400-800-999\")"
失败
#nil
C3-4 getTermFormatDetail
API格式
(getTermFormatDetail <tid>)\n
API功能
从云端获取格式化的终端明细、厂家信息等
API调用方
用户终端
API使用说明
调用终端只能是用户终端,能获取调用终端自己的信息、同宿主用户下所有设备终端及所有被授权的设备终端信息
API调用示例
(getTermFormatDetail "RT5350F_8F_ccd29be70139")\n
参数说明
tid
终端Id,字符串,API使用说明中指定了该值的设定范围
API返回
成功
setTermDetail时填入的那些参数
(onmessage <调用终端宿主uid> <tid> "detail" <data1> ... <dataN>)
形如:(onmessage "user_3200999" "RT5350F_8F_ccd29be70139" "detail" "pid" "1" "mid" "2" "cid" "1" "provider" "LSA" "category" "yuba" "model" "phone" "400-800-999")
失败
#nil
C3-5 setTermState
API格式
(setTermState <data1> ... <dataN>)\n
API功能
终端向云端上报状态
API调用方
设备终端、用户终端
API使用说明
无
API调用示例
(setTermState "power" 2)\n
参数说明
data1 ... dataN
状态值,字符串/数值
API返回
成功
#t失败
#f
C3-6 mcastTermFormatState
API格式
(mcastTermFormatState <data1> ... <dataN>)\n
API功能
终端向云端上报状态,并最大组播
一个格式化消息,该消息包含状态
API调用方
设备终端、用户终端
API使用说明
无
API调用示例
(mcastTermFormatState "power" 2)\n
参数说明
data1 ... dataN
状态值,字符串/数值
API返回
成功
#t失败
#f
组播消息格式
(onmessage <调用终端宿主uid> <tid> "state" <data1> ... <dataN>)
形如:(onmessage "user_3200999" "RT5350F_8F_ccd29be70139" "state" "power" 2)
用户终端监听此消息,就可以实现对终端的状态监控
C3-7 getTermState
API格式
(getTermState <tid>)\n
API功能
从云端获取非格式化的终端状态
API调用方
用户终端
API使用说明
调用终端只能是用户终端,能获取调用终端自己的状态、同宿主用户下所有设备终端及所有被授权的设备终端状态
API调用示例
(getTermState "RT5350F_8F_ccd29be70139")\n
参数说明
tid
终端Id,字符串,API使用说明中指定了该值的设定范围
API返回
成功
setTermState时填入的那些参数
"(<data1> ... <dataN>)"
形如:"(\"power\" 2)"
失败
#nil
C3-8 getTermFormatState
API格式
(getTermFormatState <tid>)\n
API功能
从云端获取格式化的终端状态
API调用方
用户终端
API使用说明
调用终端只能是用户终端,能获取调用终端自己的状态、同宿主用户下所有设备终端及所有被授权的设备终端状态
API调用示例
(getTermFormatState "RT5350F_8F_ccd29be70139")\n
参数说明
tid
终端Id,字符串,API使用说明中指定了该值的设定范围
API返回
成功
setTermState时填入的那些参数:
(onmessage <调用终端宿主uid> <tid> "state" <data1> ... <dataN>)
形如:(onmessage "user_3200999" "RT5350F_8F_ccd29be70139" "state" "power" 2)
失败
#nil
C3-9 @devcall主控
API格式
(@devcall <tid> <code> <callback>)\n
API功能
用户终端以主控方式控制设备终端。调用该API后,云端会立即返回,如果返回成功,云端会再充当代理远程调用设备终端
API调用方
用户终端
API使用说明
- 用户终端 -> 设备终端 两终端必须同宿主或有授权关系
- 其他情况 均不允许调用
API调用示例
(@devcall "RT5350F_8F_ccd29be70139" (+ 1 2) (lambda x x))\n
参数说明
tid
被控制设备终端Id,字符串,API使用说明中指定了该值的设定范围code
操作代码,SEXPcallback
回调代码,SEXP,这个参数不为#nil时,表示希望被控制设备终端能在code执行完毕时,将code执行结果作为callback的参数,再次调用APIucastMsg
发送到云端,这个过程是强制
的;当这个参数为#nil时,则没有上面过程
API返回
成功
#t失败
#f
远程调用格式:
(rc <调用终端宿主tid> <code> <callback>)
设备终端监听此调用,就可以响应用户终端的远程调用
C3-10 @devcall透传
API格式
(@devcall <tid> (uartdata <ud>) <callback>)\n
API功能
用户终端以透传方式控制设备终端。调用该API后,云端会立即返回,如果返回成功,云端会充当代理远程调用设备终端
API调用方
用户终端
API使用说明
- 用户终端 -> 设备终端 两终端必须同宿主或有授权关系
- 其他情况 均不允许调用
API调用示例
(@devcall "RT5350F_8F_ccd29be70139" (uartdata "480f0201020001000000000000005d") (lambda x x))\n
参数说明
tid
被操作设备终端Id,字符串,API使用说明中指定了该值的设定范围ud
透传数据callback
回调代码,SEXP,这个参数不为#nil时,表示希望被控制设备终端能在code执行完毕时,将code执行结果作为callback的参数,再次调用APIucastMsg
发送到云端,这个过程是强制
的;当这个参数为#nil时,则没有上面过程
API返回
成功
#t失败
#f
远程调用格式
(rc <调用终端宿主tid> (uartdata <ud>) <callback>)
设备终端监听此调用,就可以响应用户终端的远程控制
C3-11 ucastMsg
API格式
(ucastMsg <tid> <msg>)\n
API功能
单播消息,且消息不格式化。调用此API时,云端会立即返回,如果返回成功,云端会再充当代理单播消息
API调用方
设备终端、用户终端
API使用说明
- 设备终端 -> 用户终端 两个终端必须是同宿主或有授权关系
- 用户终端 -> 用户终端 两个终端必须是同宿主
- 其他情况 均不允许发送
API调用示例
(ucastMsg "RT5350F_8F_ccd29be70139" 20150904)\n
(ucastMsg "RT5350F_8F_ccd29be70139" "hello world")\n
(ucastMsg "RT5350F_8F_ccd29be70139" ((lambda x x) 100))\n
参数说明
tid
终端Id,字符串,API使用说明中指定了该值的设定范围msg
消息,字符串/数值/SEXP
API返回
成功
#t失败
#f
单播消息格式,即msg
执行的结果
20150904
"helloworld"
100
C3-12 mcastFormatMsgs
API格式
(mcastFormatMsgs <msg1> ... <msgN>)\n
API功能
最大组播消息
,且消息格式化。调用此API时,云端会立即返回,如果返回成功,云端会再充当代理组播消息
API调用方
设备终端、用户终端
API使用说明
- 设备终端 -> 多个用户终端
即
终端设备最大组播
- 用户终端 -> 多个用户终端
即
用户终端最大组播
- 其他情况 均不允许发送
API调用示例
(mcastFormatMsgs 1 2 3)\n
(mcastFormatMsgs "china" "usa" "uk")\n
(mcastFormatMsgs 1 2 ((lambda x x) 100))\n
参数说明
msg1 ... msgN
消息,字符串/数值/SEXP
API返回
成功
#t失败
#f
多播消息格式,即msg1 ... msgN
执行的结果
(onmessage <调用终端宿主uid> <调用终端tid> 1 2 3)
(onmessage <调用终端宿主uid> <调用终端tid> "china" "usa" "japan")
(onmessage <调用终端宿主uid> <调用终端tid> 1 2 100)
用户终端监听此消息,就能实现多播消息的接收
C3-13 ping
API格式
(ping)\n
API功能
心跳保活
API调用方
设备终端、用户终端
API使用说明
云端如果60s内没有接收到任何数据,包括心跳包,会主动断开与终端的连接
API调用示例
(ping)\n
参数说明
无
API返回
(pong)
C3-14 mcastFormatUartdata
API简称
如果该API调用次数比较频繁,为了节省流量,建议使用简称uartdata
API格式
(mcastFormatUartdata <ud> <mid>)\n
(uartdata <ud> <mid>)\n
API功能
设备终端最大组播
透传数据,调用此API时,云端会立即返回,如果返回成功,云端会充当代理进行组播
API调用方
设备终端
API使用说明
无
API调用示例
(mcastFormatUartdata "6F6EEF" 90)\n
(uartdata "6F6EEF" 90)\n
参数说明
ud
透传数据,字符串,十六进制mid
产品型号,整数
API返回
成功
#t失败
#f
组播消息格式
(onmessage <调用终端宿主uid> <调用终端tid> "state" <ud>)
用户终端监听此消息,就能实现数据的透传
C3-15 refresh
API格式
(refresh)\n
API功能
设备终端不断线刷新其在云端所处上下文环境
API调用方
设备终端
API使用说明
无宿主设备认领时使用
API调用示例
(refresh)\n
参数说明
无
API返回
成功
#t失败
#f
新老API对照表
API V0,云端会持续支持,但建议开发者使用API V1,新API名称比较规范。
节数 | API V0 | API V1 | 备注 |
---|---|---|---|
1.1 | login | login | |
1.2 | setdetail、detail | setTermDetail | |
1.3 | getdetail | getTermDetail | |
1.4 | get-detail | getTermFormatDetail | |
1.5 | setstate | setTermState | |
1.6 | state | mcastTermFormatState | 如果调用频繁,基于流量考虑,也可使用state |
1.7 | getstate | getTermState | |
1.8 | get-state | getTermFormatState | |
1.9 | @devcall | @devcall | |
1.10 | @devcall | @devcall | |
1.11 | send | ucastMsg | |
1.12 | message | mcastFormatMsgs | |
1.13 | ping | ping | |
1.14 | uartdata | mcastFormatUartdata | 如果调用频繁,基于流量考虑,也可使用uartdata |
1.15 | refresh | refresh |
终端API
上述文档中,出现getall
、rc
、onmessage
这3个关键词,其实可以把它们理解成为终端API
3.1 getall
API格式
(getall)
API功能
获取终端所有信息,包括终端细节、厂家信息、状态。标准实现
是:终端获取自己的信息、状态之后,连续调用云端的setTermDetail、mcastTermFormatState上报
API调用方
云端
API使用说明
无
API调用示例
(getall)
参数说明
无
API返回
成功
对云端的连续setTermDetail、mcastTermFormatState调用失败
无
图解
暂无
3.2 rc
API格式
(rc <tid> <code> <callback>)
API功能
接受云端的远程调用。标准实现
是:执行code,并将code的执行结果作为callback的参数,一起再ucastMsg
给云端
API调用方
云端
API使用说明
无
API调用示例
(rc "35110987899784367" (+ 1 2) (lambda x x))
参数说明
tid
发起远程调用的用户终端Id,要理解的是:云端只是充当该用户终端的调用代理而已code
操作代码,SEXP,等同于@devcall里的code
callback
希望回调云端的代码,SEXP,等同于@devcall里的callback
API返回
成功
对云端的ucastMsg
调用失败
无
图解
暂无
3.3 onmessage
API格式
(onmessage <uid> <tid> <msg1> … <msgN>)
API功能
接收云端转发来的消息。本函数通常被SDK用来实现监听,例如JavaScript API J1-3就是基于此API包装而成
API调用方
云端
API使用说明
无
API调用示例
请搜索本文中所有onmessge关键字
参数说明
uid
发送消息的终端宿主uid,要理解的是:云端只是充当此终端的代理转发消息而已tid
发送消息的终端Idmsg ... msgN
消息
API返回
成功
取决于开发者自己的实现失败
无
更新历史
v1.0.0
- 初始化版本,C3接口说明。
最新版文档请访问 在线文档 http://docs.hekr.me