氦氪云端API文档(C3)

v1.0.0 by honghu.hu@hekr.me 7/20/2015 9:18:13 PM

氦氪云端 TCP & WEBSOCKET 原生API 文档

关键词

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使用说明
  1. 终端接入云端时,需先调用login,调用成功后,终端方能后续操作
  2. 终端调用login成功之前,云端不会响应任何其他API的调用
  3. 使用tcp长连接通信方式时,需要显式调用login;而采用websocket长连接通信方式时,不要显式调用login,而是通过如下地址访问: ws://device.hekr.me:8080/websocket/t/<tid>/<channel>/<accesskey>/<type>
  4. 当accessKey为空字符串时,type必须为"DEVICE",该终端被认为是设备无宿主
API调用示例
(login "RT5350F_8F_ccd29be70139" "code" "user_3200999" "DEVICE")\n
(login "AppTid_ccxxx" "code" "accesskey" "USER")\n
参数说明
API返回
组播消息格式
(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
参数说明
API返回

C3-3 getTermDetail

API格式
(getTermDetail <tid>)\n
API功能

从云端获取非格式化的终端明细、厂家信息等

API调用方

用户终端

API使用说明

调用终端只能是用户终端,能获取调用终端自己的信息、同宿主用户下所有设备终端及所有被授权的设备终端信息

API调用示例
(getTermDetail "RT5350F_8F_ccd29be70139")\n
参数说明
API返回
"(<data1> ... <dataN>)"
形如:"(\"pid\" \"1\" \"mid\" \"2\" \"cid\" \"1\" \"provider\" \"LSA\" \"category\" \"yuba\" \"model\" \"phone\" \"400-800-999\")"

C3-4 getTermFormatDetail

API格式
(getTermFormatDetail <tid>)\n
API功能

从云端获取格式化的终端明细、厂家信息等

API调用方

用户终端

API使用说明

调用终端只能是用户终端,能获取调用终端自己的信息、同宿主用户下所有设备终端及所有被授权的设备终端信息

API调用示例
(getTermFormatDetail "RT5350F_8F_ccd29be70139")\n
参数说明
API返回
(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")

C3-5 setTermState

API格式
(setTermState <data1> ... <dataN>)\n
API功能

终端向云端上报状态

API调用方

设备终端、用户终端

API使用说明

API调用示例
(setTermState "power" 2)\n
参数说明
API返回

C3-6 mcastTermFormatState

API格式
(mcastTermFormatState <data1> ... <dataN>)\n
API功能

终端向云端上报状态,并最大组播一个格式化消息,该消息包含状态

API调用方

设备终端、用户终端

API使用说明

API调用示例
(mcastTermFormatState "power" 2)\n
参数说明
API返回
组播消息格式
(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
参数说明
API返回
"(<data1> ... <dataN>)"
形如:"(\"power\" 2)"

C3-8 getTermFormatState

API格式
(getTermFormatState <tid>)\n
API功能

从云端获取格式化的终端状态

API调用方

用户终端

API使用说明

调用终端只能是用户终端,能获取调用终端自己的状态、同宿主用户下所有设备终端及所有被授权的设备终端状态

API调用示例
(getTermFormatState "RT5350F_8F_ccd29be70139")\n
参数说明
API返回
(onmessage <调用终端宿主uid> <tid> "state" <data1> ... <dataN>)
形如:(onmessage "user_3200999" "RT5350F_8F_ccd29be70139" "state" "power" 2)

C3-9 @devcall主控

API格式
(@devcall <tid> <code> <callback>)\n
API功能

用户终端以主控方式控制设备终端。调用该API后,云端会立即返回,如果返回成功,云端会再充当代理远程调用设备终端

API调用方

用户终端

API使用说明
  1. 用户终端 -> 设备终端 两终端必须同宿主或有授权关系
  2. 其他情况 均不允许调用
API调用示例
(@devcall "RT5350F_8F_ccd29be70139" (+ 1 2) (lambda x x))\n
参数说明
API返回
远程调用格式:
(rc <调用终端宿主tid> <code> <callback>)

设备终端监听此调用,就可以响应用户终端的远程调用

C3-10 @devcall透传

API格式
(@devcall <tid> (uartdata <ud>) <callback>)\n
API功能

用户终端以透传方式控制设备终端。调用该API后,云端会立即返回,如果返回成功,云端会充当代理远程调用设备终端

API调用方

用户终端

API使用说明
  1. 用户终端 -> 设备终端 两终端必须同宿主或有授权关系
  2. 其他情况 均不允许调用
API调用示例
(@devcall "RT5350F_8F_ccd29be70139" (uartdata "480f0201020001000000000000005d") (lambda x x))\n
参数说明
API返回
远程调用格式
(rc <调用终端宿主tid> (uartdata <ud>) <callback>)

设备终端监听此调用,就可以响应用户终端的远程控制

C3-11 ucastMsg

API格式
(ucastMsg <tid> <msg>)\n
API功能

单播消息,且消息不格式化。调用此API时,云端会立即返回,如果返回成功,云端会再充当代理单播消息

API调用方

设备终端、用户终端

API使用说明
  1. 设备终端 -> 用户终端 两个终端必须是同宿主或有授权关系
  2. 用户终端 -> 用户终端 两个终端必须是同宿主
  3. 其他情况 均不允许发送
API调用示例
(ucastMsg "RT5350F_8F_ccd29be70139" 20150904)\n
(ucastMsg "RT5350F_8F_ccd29be70139" "hello world")\n
(ucastMsg "RT5350F_8F_ccd29be70139" ((lambda x x) 100))\n
参数说明
API返回
单播消息格式,即msg执行的结果
20150904
"helloworld"
100

C3-12 mcastFormatMsgs

API格式
(mcastFormatMsgs <msg1> ... <msgN>)\n
API功能

最大组播消息,且消息格式化。调用此API时,云端会立即返回,如果返回成功,云端会再充当代理组播消息

API调用方

设备终端、用户终端

API使用说明
  1. 设备终端 -> 多个用户终端 即终端设备最大组播
  2. 用户终端 -> 多个用户终端 即用户终端最大组播
  3. 其他情况 均不允许发送
API调用示例
(mcastFormatMsgs 1 2 3)\n
(mcastFormatMsgs "china" "usa" "uk")\n
(mcastFormatMsgs 1 2 ((lambda x x) 100))\n
参数说明
API返回
多播消息格式,即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
参数说明
API返回
组播消息格式
(onmessage <调用终端宿主uid> <调用终端tid> "state" <ud>)

用户终端监听此消息,就能实现数据的透传

C3-15 refresh

API格式
(refresh)\n
API功能

设备终端不断线刷新其在云端所处上下文环境

API调用方

设备终端

API使用说明

无宿主设备认领时使用

API调用示例
(refresh)\n
参数说明

API返回

新老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

上述文档中,出现getallrconmessage这3个关键词,其实可以把它们理解成为终端API

3.1 getall

API格式
(getall)
API功能

获取终端所有信息,包括终端细节、厂家信息、状态。标准实现是:终端获取自己的信息、状态之后,连续调用云端的setTermDetail、mcastTermFormatState上报

API调用方

云端

API使用说明

API调用示例
(getall)
参数说明

API返回
图解

暂无

3.2 rc

API格式
(rc <tid> <code> <callback>)
API功能

接受云端的远程调用。标准实现是:执行code,并将code的执行结果作为callback的参数,一起再ucastMsg给云端

API调用方

云端

API使用说明

API调用示例
(rc "35110987899784367" (+ 1 2) (lambda x x))
参数说明
API返回
图解

暂无

3.3 onmessage

API格式
(onmessage <uid> <tid> <msg1> … <msgN>)
API功能

接收云端转发来的消息。本函数通常被SDK用来实现监听,例如JavaScript API J1-3就是基于此API包装而成

API调用方

云端

API使用说明

API调用示例

请搜索本文中所有onmessge关键字

参数说明
API返回

更新历史

v1.0.0

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