Cloud Of Things API

来自Jack's Lab
跳转到： 导航, 搜索

本页面为设计初稿


目录

1 User ID

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


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

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

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


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

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

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



2 Devices

2.1 创建设备


URL http://api.easyhomelink.org/v1/devices
Formats JSON
Methods POST
Returns 设备 ID


例子：

data.txt: 

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
  }
}

cat data.txt | netcat api.easyhomelink.org 80


返回数据 (JSON): 

{
  "DEV_ID": 2
}



2.2 查看设备


URL http://api.easyhomelink.org/v1/device/DEV_ID
Formats JSON
Methods GET
Returns 设备信息


例子： 

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

返回 JSON 格式数据： 

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



2.3 编辑设备


URL http://api.easyhomelink.org/v1/device/DEV_ID
Formats JSON
Methods PUT
Returns 无


例子： 

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

data.txt (JSON): 

{
  "name":"Home Enviroment",
  "description":"Home",
  "tags":["temperature","Home"],
  "location":{
    "local":"Nanjing",
    "latitude":32.071852,
    "longitude":118.793551,
  }
}



2.4 删除设备


URL http://api.easyhomelink.org/v1/device/DEV_ID
Formats JSON
Methods DELETE
Returns 无

例子： 

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




2.5 罗列设备

罗列 UID 用户的所有设备


URL http://api.easyhomelink.org/v1/devices
Formats JSON
Methods PUT
Returns 当前用户的所有设备概要描述

例子： 

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

返回 JSON 格式数据： 

[
  {
    "id": 1,
    "name": "Home",
    "about": "Home enviroment"
  },
  {
    "id": 2,
    "name": "Outdoor",
    "about": "Outdoor enviroment"
  }
]




3 Sensors

3.1 Create


URL http://api.easyhomelink.org/v1/device/DEV_ID/sensors
Formats JSON
Methods POST
Returns Sensor ID


例子： 

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

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

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

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

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


返回值： 

{
  "id": 1
}




3.2 View


URL http://api.easyhomelink.org/v1/device/DEV_ID/sensor/SEN_ID
Formats JSON
Methods GET
Returns 设备信息


例子： 

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


返回值： 

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



3.3 Update


URL http://api.easyhomelink.org/v1/device/DEV_ID/sensor/SEN_ID
Formats JSON
Methods PUT
Returns 无


例子： 

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


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

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



3.4 Delete


URL http://api.easyhomelink.org/v1/device/DEV_ID/sensor/SEN_ID
Formats JSON
Methods DELETE
Returns 无


例子： 

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



4 Datapoints

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

4.1 Create


URL http://api.easyhomelink.org/v1/device/DEV_ID/sensors/SEN_ID/datapoints
Formats JSON
Methods POST
Returns 无


例子：

data.txt 

POST /v1/device/1/sensor/1/datapoints HTTP/1.1
Accept: */*
x-key: asdf1234
Content-Length:	15
Content-Type: text/html

{"value":17.2}


或者 data.txt 

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}

cat req.txt | nc easyhomelink.org 3000



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


数值型传感器 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}
}


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

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}]




4.2 View


URL http://api.easyhomelink.org/v1/device/DEV_ID/sensor/SEN_ID/datapoint/KEY
Formats JSON
Methods GET
Returns 设备信息


返回传感器的最新数据：

data.txt (最后一行是空行) 

GET /v1/device/1/sensor/1/datapoint HTTP 1.1
Accept: */*
x-key: asdf1234
Content-Length: 0
Content-Type: text/html


  cat data.txt | netcat easyhomelink.org 3000



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


返回传感器的所有数据：

data.txt 

GET /v1/device/1/sensor/1/datapoints HTTP/1.1
Accept: */*
x-chart: 1
x-key: asdf1234
Content-Length: 0
Content-Type: text/html


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


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

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



4.3 Update


URL http://api.easyhomelink.org/v1/device/DEV_ID/sensor/SEN_ID/datapoint/KEY
Formats JSON
Methods PUT
Returns 无



4.4 Delete


URL http://api.easyhomelink.org/v1/device/DEV_ID/sensor/SEN_ID/datapoint/KEY
Formats 无
Methods DELETE
Returns 无



5 Controllers

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

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

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

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

5.1 Create


URL http://api.easyhomelink.org/v1/device/DEV_ID/controllers
Formats JSON
Methods POST
Returns 无



5.2 View


URL http://api.easyhomelink.org/v1/device/DEV_ID/controller/CRTL_ID
Formats JSON
Methods GET
Returns 设备信息



6 Users

6.1 Create 

{
    "username":"login2",
    "password":"abc123_md5sum",
    "email":"api@jackslab.org"
}



6.2 Edit



6.3 View



6.4 Delete







来自“http://wiki.jackslab.org/index.php?title=Cloud_Of_Things_API&oldid=3348”
个人工具
名字空间

变换
操作
导航
工具箱