Comcat：以“本页面为设计初稿 == User ID == 是一个 UUID 字符串，用于用户身份的验证和识别，唯一，可重新生成（未来应默认使用 https）...”为内容创建页面

2014-12-11T17:19:49Z

以“本页面为设计初稿 == User ID == 是一个 UUID 字符串，用于用户身份的验证和识别，唯一，可重新生成（未来应默认使用 https）...”为内容创建页面

新页面

本页面为设计初稿

== User ID ==

是一个 UUID 字符串，用于用户身份的验证和识别，唯一，可重新生成（未来应默认使用 https）

一个用户下可有多个设备，每个设备下可有多个传感器（感知端）和控制器（控制端）。传感器和控制器可以被多个设备使用。一个设备相当于一个感知端、控制端以及控制策略（触发器，类似 IF-THEN）的集合

设备、感知端、控制端之间的关系为松耦合，即：一个设备可以只有一个感知端（只作数据呈现），或者只有一个控制端（只接受控制指令）；一个感知端可用于多个设备，一个控制端也可为多个设备所用；

因此，设备是上接用户 (UI) 下承硬件交互的桥梁

简单如一个体重监测设备，可作为只有一个传感器的设备

一个家庭灯光设备，可以有多个环境光强传感器，声控传感器（亦可作为其他设备的输入，比如窗帘控制设备），甚至手势传感器，控制器则对应各房间灯的开关

对于一个家庭成员追踪设备，则各人智能手机为感知端（定时上传 GPS/GSM 数据），加一些虚拟控制器，比如 weibo 推发器

 

== Devices ==

=== 创建设备 ===

 
{| border="0" width=500 cellspacing="1" cellpadding="8" align="left" bgcolor=#1b74c2
| style="background:#dee7ec" width=80| URL
| style="background:#ffffff" | http://api.easyhomelink.org/v1/devices
|-
| style="background:#dee7ec" | Formats
| style="background:#ffffff" | JSON
|-
| style="background:#dee7ec" | Methods
| style="background:#ffffff" | POST
|-
| style="background:#dee7ec" | Returns
| style="background:#ffffff" | 设备 ID
|}

例子：

data.txt:
<pre>
POST /v1/devices HTTP/1.1
Accept: */*
x-key: YOUR_X-KEY
Content-Length: 177
Content-Type: text/html

{
"name":"Home Enviroment",
"description":"Home",
"tags":["temperature","Home"],
"location":{
"local":"Nanjing",
"latitude":24.123,
"longitude":34.456
}
}
</pre>

<pre>
cat data.txt | netcat api.easyhomelink.org 80
</pre>

返回数据 (JSON):
<pre>
{
"DEV_ID": 2
}
</pre>

 

=== 查看设备 ===

 
{| border="0" width=500 cellspacing="1" cellpadding="8" align="left" bgcolor=#1b74c2
| style="background:#dee7ec" width=80| URL
| style="background:#ffffff" | http://api.easyhomelink.org/v1/device/DEV_ID
|-
| style="background:#dee7ec" | Formats
| style="background:#ffffff" | JSON
|-
| style="background:#dee7ec" | Methods
| style="background:#ffffff" | GET
|-
| style="background:#dee7ec" | Returns
| style="background:#ffffff" | 设备信息
|}

例子：

<pre>
curl --request GET --header "UID: YOUR_UUID" http://api.easyhomelink.org/v1/device/DEV_ID
</pre>

返回 JSON 格式数据：

<pre>
{
"name":"Home Enviroment",
"description":"Home",
"tags":["temperature","Home"],
"location":{
"local":"Nanjing",
"latitude":24.123,
"longitude":34.456
}
}
</pre>

 

=== 编辑设备 ===

 
{| border="0" width=500 cellspacing="1" cellpadding="8" align="left" bgcolor=#1b74c2
| style="background:#dee7ec" width=80| URL
| style="background:#ffffff" | http://api.easyhomelink.org/v1/device/DEV_ID
|-
| style="background:#dee7ec" | Formats
| style="background:#ffffff" | JSON
|-
| style="background:#dee7ec" | Methods
| style="background:#ffffff" | PUT
|-
| style="background:#dee7ec" | Returns
| style="background:#ffffff" | 无
|}

例子：

<pre>
curl --request PUT --data-binary @data.txt --header "UID: YOUR_UUID" http://api.easyhomelink.org/v1/device/DEV_ID
</pre>

data.txt (JSON):
<pre>
{
"name":"Home Enviroment",
"description":"Home",
"tags":["temperature","Home"],
"location":{
"local":"Nanjing",
"latitude":32.071852,
"longitude":118.793551,
}
}
</pre>

 

=== 删除设备 ===

 
{| border="0" width=500 cellspacing="1" cellpadding="8" align="left" bgcolor=#1b74c2
| style="background:#dee7ec" width=80| URL
| style="background:#ffffff" | http://api.easyhomelink.org/v1/device/DEV_ID
|-
| style="background:#dee7ec" | Formats
| style="background:#ffffff" | JSON
|-
| style="background:#dee7ec" | Methods
| style="background:#ffffff" | DELETE
|-
| style="background:#dee7ec" | Returns
| style="background:#ffffff" | 无
|}

例子：

<pre>
curl --request DELETE --data-binary @data.txt --header "UID: YOUR_UUID" http://api.easyhomelink.org/v1/device/DEV_ID
</pre>

 

=== 罗列设备 ===

罗列 UID 用户的所有设备

 
{| border="0" width=500 cellspacing="1" cellpadding="8" align="left" bgcolor=#1b74c2
| style="background:#dee7ec" width=80| URL
| style="background:#ffffff" | http://api.easyhomelink.org/v1/devices
|-
| style="background:#dee7ec" | Formats
| style="background:#ffffff" | JSON
|-
| style="background:#dee7ec" | Methods
| style="background:#ffffff" | PUT
|-
| style="background:#dee7ec" | Returns
| style="background:#ffffff" | 当前用户的所有设备概要描述
|}

例子：

<pre>
curl --request GET --header "UID: YOUR_UUID" http://api.easyhomelink.org/v1/devices
</pre>

返回 JSON 格式数据：
<pre>
[
{
"id": 1,
"name": "Home",
"about": "Home enviroment"
},
{
"id": 2,
"name": "Outdoor",
"about": "Outdoor enviroment"
}
]
</pre>

 

== Sensors ==

=== Create ===

 
{| border="0" width=600 cellspacing="1" cellpadding="8" align="left" bgcolor=#1b74c2
| style="background:#dee7ec" width=80| URL
| style="background:#ffffff" | http://api.easyhomelink.org/v1/device/DEV_ID/sensors
|-
| style="background:#dee7ec" | Formats
| style="background:#ffffff" | JSON
|-
| style="background:#dee7ec" | Methods
| style="background:#ffffff" | POST
|-
| style="background:#dee7ec" | Returns
| style="background:#ffffff" | Sensor ID
|}

例子：

<pre>
curl --request POST --data-binary @data.txt --header "UID: YOUR_UUID" http://api.easyhomelink.org/v1/device/5/sensors
</pre>

POST 的数据存放于文件 data.txt 中：

<pre>
{
"name":"datastream",
"tags":["tag1","tag2"],
"unit": {
"name": "humidity",
"symbol": "%"
}
}
</pre>

这是一个常见的通用型数据流型传感器，比如温度传感器、湿度传感器、PM2.5 传感器、煤气浓度传感器、门磁传感器 ...

现在硬件集成度很高，一个芯片带多个传感器的模块很多，比如现在温度和湿度常常在一个模块上，我们建议对这样一个模块 Create 两个 Sensor，因为其随时间有两个数据流

返回值：

<pre>
{
"id": 1
}
</pre>

 

=== View ===

 
{| border="0" width=600 cellspacing="1" cellpadding="8" align="left" bgcolor=#1b74c2
| style="background:#dee7ec" width=80| URL
| style="background:#ffffff" | http://api.easyhomelink.org/v1/device/DEV_ID/sensor/SEN_ID
|-
| style="background:#dee7ec" | Formats
| style="background:#ffffff" | JSON
|-
| style="background:#dee7ec" | Methods
| style="background:#ffffff" | GET
|-
| style="background:#dee7ec" | Returns
| style="background:#ffffff" | 设备信息
|}

例子：

<pre>
curl --request GET --header "UID: YOUR_UUID" http://api.easyhomelink.org/v1/device/5/sensor/1
</pre>

返回值：

<pre>
{
"name":"datastream",
"tags":["tag1","tag2"],
"unit": {
"name": "humidity",
"symbol": "%"
}
}
</pre>

 

=== Update ===

 
{| border="0" width=600 cellspacing="1" cellpadding="8" align="left" bgcolor=#1b74c2
| style="background:#dee7ec" width=80| URL
| style="background:#ffffff" | http://api.easyhomelink.org/v1/device/DEV_ID/sensor/SEN_ID
|-
| style="background:#dee7ec" | Formats
| style="background:#ffffff" | JSON
|-
| style="background:#dee7ec" | Methods
| style="background:#ffffff" | PUT
|-
| style="background:#dee7ec" | Returns
| style="background:#ffffff" | 无
|}

例子：

<pre>
curl --request PUT --data-binary @data.txt --header "UID: YOUR_UUID" http://api.easyhomelink.org/v1/device/5/sensor/1
</pre>

上传的数据位于文件 data.txt：

<pre>
{
"name":"datastream",
"tags":["living room"],
"unit": {
"name": "humidity",
"symbol": "%"
}
}
</pre>

 

=== Delete ===

 
{| border="0" width=600 cellspacing="1" cellpadding="8" align="left" bgcolor=#1b74c2
| style="background:#dee7ec" width=80| URL
| style="background:#ffffff" | http://api.easyhomelink.org/v1/device/DEV_ID/sensor/SEN_ID
|-
| style="background:#dee7ec" | Formats
| style="background:#ffffff" | JSON
|-
| style="background:#dee7ec" | Methods
| style="background:#ffffff" | DELETE
|-
| style="background:#dee7ec" | Returns
| style="background:#ffffff" | 无
|}

例子：

<pre>
curl --request DELETE --header "UID: YOUR_UUID" http://api.easyhomelink.org/v1/device/5/sensor/1
</pre>

 

== Datapoints ==

对应一个特定的传感器，属传感器的数据

=== Create ===

 
{| border="0" width=650 cellspacing="1" cellpadding="8" align="left" bgcolor=#1b74c2
| style="background:#dee7ec" width=80| URL
| style="background:#ffffff" | http://api.easyhomelink.org/v1/device/DEV_ID/sensors/SEN_ID/datapoints
|-
| style="background:#dee7ec" | Formats
| style="background:#ffffff" | JSON
|-
| style="background:#dee7ec" | Methods
| style="background:#ffffff" | POST
|-
| style="background:#dee7ec" | Returns
| style="background:#ffffff" | 无
|}

例子：

data.txt
<pre>
POST /v1/device/1/sensor/1/datapoints HTTP/1.1
Accept: */*
x-key: asdf1234
Content-Length: 15
Content-Type: text/html

{"value":17.2}
</pre>

或者 data.txt
<pre>
POST /v1/device/1/sensor/1/datapoints HTTP/1.1
Accept: */*
x-key: asdf1234
Content-Length: 49
Content-Type: text/html

{"timestamp":"2013-01-09T13:23:20", "value":17.2}
</pre>

<pre>
cat req.txt | nc easyhomelink.org 3000
</pre>

系统支持数值型传感器和地理位置型传感器（GPS、北斗、伽利略、GLONASS等导航系统终端模块）：

<pre>

数值型传感器 data.txt 格式如下:
{
"timestamp":"2012-03-15T16:13:14",
"value":294.34
}

地理位置型传感器 data.txt 格式如下:
{
"timestamp":"2012-03-15T16:13:14",
"value":{"lat":40.0207,"lng":115.2614,"alt":2000}
}
</pre>

一个设备的所有传感器数据批量上传：

<pre>
POST /v1/device/1/datapoints HTTP/1.1
Accept: */*
x-key: asdf1234
Content-Length: 125
Content-Type: text/html

[{"sensor_id":1,"value":17.2},{"sensor_id":2,"value":{"lat":40.0207,"lng":115.2614,"alt":2000},{"sensor_id":3,"value":19.2}]
</pre>

 

=== View ===

 
{| border="0" width=650 cellspacing="1" cellpadding="8" align="left" bgcolor=#1b74c2
| style="background:#dee7ec" width=80| URL
| style="background:#ffffff" | http://api.easyhomelink.org/v1/device/DEV_ID/sensor/SEN_ID/datapoint/KEY
|-
| style="background:#dee7ec" | Formats
| style="background:#ffffff" | JSON
|-
| style="background:#dee7ec" | Methods
| style="background:#ffffff" | GET
|-
| style="background:#dee7ec" | Returns
| style="background:#ffffff" | 设备信息
|}

返回传感器的最新数据：

data.txt (最后一行是空行)
<pre>
GET /v1/device/1/sensor/1/datapoint HTTP 1.1
Accept: */*
x-key: asdf1234
Content-Length: 0
Content-Type: text/html

</pre>

<pre>
cat data.txt | netcat easyhomelink.org 3000
</pre>

<pre>
curl --request GET --header "x-key: YOUR_UUID" http://api.easyhomelink.org/v1/device/1/sensor/1/datapoint
</pre>

返回传感器的所有数据：

data.txt
<pre>
GET /v1/device/1/sensor/1/datapoints HTTP/1.1
Accept: */*
x-chart: 1
x-key: asdf1234
Content-Length: 0
Content-Type: text/html

</pre>

<pre>
curl --request GET --header "x-key: YOUR_UUID" http://api.easyhomelink.org/v1/device/1/sensor/1/datapoints
</pre>

返回传感器 20120712T11:30:20 时的数据：

<pre>
curl --request GET --header "x-key: YOUR_UUID" http://api.easyhomelink.org/v1/device/1/sensor/1/datapoint/20120712T11:30:20
</pre>

 

=== Update ===

 
{| border="0" width=650 cellspacing="1" cellpadding="8" align="left" bgcolor=#1b74c2
| style="background:#dee7ec" width=80| URL
| style="background:#ffffff" | http://api.easyhomelink.org/v1/device/DEV_ID/sensor/SEN_ID/datapoint/KEY
|-
| style="background:#dee7ec" | Formats
| style="background:#ffffff" | JSON
|-
| style="background:#dee7ec" | Methods
| style="background:#ffffff" | PUT
|-
| style="background:#dee7ec" | Returns
| style="background:#ffffff" | 无
|}

 

=== Delete ===

 
{| border="0" width=650 cellspacing="1" cellpadding="8" align="left" bgcolor=#1b74c2
| style="background:#dee7ec" width=80| URL
| style="background:#ffffff" | http://api.easyhomelink.org/v1/device/DEV_ID/sensor/SEN_ID/datapoint/KEY
|-
| style="background:#dee7ec" | Formats
| style="background:#ffffff" | 无
|-
| style="background:#dee7ec" | Methods
| style="background:#ffffff" | DELETE
|-
| style="background:#dee7ec" | Returns
| style="background:#ffffff" | 无
|}

 

== Controllers ==

控制器没有数据流，只有状态，可用一个整数描述

对于常用的家用灯光开关，1 表示开，0 表示关

对于一个室内用于浇花的水泵，1 为运行，0 为停止

对于一个电动的窗帘，可用 0 - 10 表示开启的大小

=== Create ===

 
{| border="0" width=650 cellspacing="1" cellpadding="8" align="left" bgcolor=#1b74c2
| style="background:#dee7ec" width=80| URL
| style="background:#ffffff" | http://api.easyhomelink.org/v1/device/DEV_ID/controllers
|-
| style="background:#dee7ec" | Formats
| style="background:#ffffff" | JSON
|-
| style="background:#dee7ec" | Methods
| style="background:#ffffff" | POST
|-
| style="background:#dee7ec" | Returns
| style="background:#ffffff" | 无
|}

 

=== View ===

 
{| border="0" width=600 cellspacing="1" cellpadding="8" align="left" bgcolor=#1b74c2
| style="background:#dee7ec" width=80| URL
| style="background:#ffffff" | http://api.easyhomelink.org/v1/device/DEV_ID/controller/CRTL_ID
|-
| style="background:#dee7ec" | Formats
| style="background:#ffffff" | JSON
|-
| style="background:#dee7ec" | Methods
| style="background:#ffffff" | GET
|-
| style="background:#dee7ec" | Returns
| style="background:#ffffff" | 设备信息
|}

 

== Users ==

=== Create ===

<pre>
{
"username":"login2",
"password":"abc123_md5sum",
"email":"api@jackslab.org"
}
</pre>

 

=== Edit ===

 

=== View ===

 

=== Delete ===

Cloud Of Things API - 版本历史

Comcat：以“本页面为设计初稿 == User ID == 是一个 UUID 字符串，用于用户身份的验证和识别，唯一，可重新生成（未来应默认使用 https）...”为内容创建页面