add gateway api doc

product/gateway.md

@@ -0,0 +1,882 @@
+# 网关前后端交互协议
+
+## 调试地址
+
+http://gzq.myqnapcloud.com:8090
+
+## 区域(Area)
+
+#### 获取区域列表
+
+GET /api/area
+
+#### 新增area项(ID自动生成)
+
+POST /api/area
+
+#### 根据ID查询area项
+
+GET /api/area/{id}
+
+#### 根据ID修改area项
+
+PUT /api/area/{id}
+
+#### 根据ID删除area项
+
+DELETE /api/area/{id}
+### area item json数据格式
+
+
+~~~json
+{
+  "id": 1,//区域ID
+  "name": "会议室",//区域名字
+}
+~~~
+
+### area list json数据格式
+
+~~~json
+{
+    "type": "areaListResult",
+    "size": 2,
+    "items": [
+        {
+            "id": 1,
+            "name": "会议室",
+        },
+        {
+            "id": 3,
+            "name": "茶水间",
+        },
+    ]
+}
+~~~
+## 设备(Device)
+
+### 设备http接口
+
+#### 获取设备列表
+
+GET /api/device
+
+#### 新增设备
+
+POST /api/device
+
+#### 删除设备
+
+DELETE /api/device/{id}
+
+#### 修改设备信息
+PUT /api/device/{id}
+
+#### 获取设备信息
+
+GET /api/device/{id}
+
+### 设备项json数据格式
+
+#### configDesc设备配置描述（不同设备的属性，是以下属性的子集）
+
+~~~ json
+[{
+	"name": "device_addr", //设备地址
+	"value": 12,
+	"type": "INTEGER"
+}, {
+	"name": "device_port", //设备端口
+	"value": 3,
+	"type": "INTEGER"
+}, {
+	"name": "control_addr", //控制地址
+	"value": 3,
+	"type": "INTEGER"
+}, {
+	"name": "control_type", //控制类型
+	"value": 3,
+	"type": "INTEGER"
+}, {
+	"name": "temperature_addr", //温湿度传感器地址
+	"value": 3,
+	"type": "INTEGER"
+}, {
+	"name": "temperature_type", //温湿度传感器类型
+	"value": "wired",
+	"type": "STRING"
+}, {
+	"name": "broadcast", //是否跨网关控制
+	"value": true,
+	"type": "BOOL"
+}, {
+	"name": "modlist", //模式列表
+	"value": "low,normal,high,auto",
+	"type": "STRING"
+}, {
+	"name": "speedlist", //风速列表
+	"value":"fan,cool,heat",
+	"type": "STRING"
+}{
+	"name": "temp", //温度
+	"value":"0",
+	"type": "INTEGER"
+}]
+~~~
+
+
+
+#### 灯设备configDesc数据格式
+
+~~~json
+[
+  {
+    "name": "device_addr",
+    "value": 12,
+    "type": "INTEGER"
+  },
+  {
+    "name": "device_port",
+    "value": 3,
+    "type": "INTEGER"
+  },
+  {
+    "name": "broadcast",
+    "value": true,
+    "type": "BOOL"
+  }
+]
+~~~
+
+#### 干接点设备configDesc数据格式
+
+~~~json
+[
+  {
+    "name": "device_addr",
+    "value": 12
+  },
+  {
+    "name": "device_port",
+    "value": 3
+  },
+  {
+    "name": "control_type",
+    "value": "click"
+  },
+  {
+    "name": "associated_scene",
+    "value": [
+      1,
+      2,
+      3
+    ]
+  }
+]
+~~~
+
+### 设备列表数据格式
+
+~~~json
+{
+  "type": "deviceListResult",
+  "size": 2,
+  "items": [
+    {
+      "id": 1,
+      "name": "0001",
+      "displayName": "吸顶灯",
+      "type": "light",
+      "subtype":	"light_bar",
+      "attachType":	"canbus",
+      "areaId": 1,
+      "gatewayId":	1,
+      "configDesc": ""
+    },
+    {
+      "id": 3,
+      "name": "003",
+      "displayName": "吸顶灯",
+      "type": "curtain",
+      "subtype":	"light_bar",
+      "attachType":	"canbus",
+      "areaId": 2,
+      "gatewayId":	1,
+      "configDesc": ""
+    }
+  ]
+  
+}
+~~~
+
+## 面板(Panel)
+
+### 面板类型：
+
+canbus(can总线面板) network(普通网络面板) networkExt(附带设备的网络面板)
+
+### 面板http接口
+
+#### 获取面板列表
+
+GET /api/panel
+
+#### 新增面板
+
+POST /api/panel
+
+#### 删除设备
+
+DELETE /api/panel/{id}
+
+#### 修改面板信息
+PUT /api/panel/{id}
+
+#### 获取面板信息
+
+GET /api/panel/{id}
+
+#### 面板列表数据格式
+
+~~~json
+{
+  "type": "panelListResult",
+  "size": 2,
+  "items": [
+    {
+      "id": 1,
+      "name": "2001",
+      "displayName": "面板1",
+      "type": "panel",
+      "subtype": "canbus",
+      "areaId": 1,
+      "configDesc": "",
+    },
+    {
+      "id": 3,
+      "name": "2003",
+      "displayName": "面板2",
+      "type": "panel",
+      "subtype": "canbus",
+      "areaId": 2,
+      "configDesc": "",
+    }
+  ]
+}
+~~~
+
+面板configDesc
+
+
+~~~json
+{
+  "canId":1,
+  "broadcast":false,
+  "display_device":[
+    {
+      "name":"0001",
+      "lock":false
+    }
+  ],
+  "display_scene":[
+    {
+      "name":"1003",
+      "lock":false
+    }
+  ],
+  "attached_device":[],
+  "background":"",
+  "lock_weekday":[
+    1,
+    2,
+    3,
+    4,
+    5
+  ],
+  "lock_start_time":{
+    "hour":"00",
+    "minute":"00",
+    "second":"00"
+  },
+    
+  "lock_end_time":{
+    "hour":"23",
+    "minute":"59",
+    "second":"59"
+  }
+}
+
+~~~
+
+
+## 场景(Scene)
+
+### scene http接口
+
+#### 获取scene列表
+GET /api/scene
+
+#### 新增scene项(ID自动生成)
+POST /api/scene
+
+#### 根据ID查询scene项
+GET /api/scene/{id}
+
+#### 根据ID修改scene项
+PUT /api/scene/{id}
+
+#### 根据ID删除scene项
+DELETE /api/scene/{id}
+
+### actionDesc场景动作描述
+
+~~~json
+[{
+	"id": 1,
+	"channels": [{
+		"value": "on",
+		"name": "action",
+		"type": "STRING"
+	}],
+	"subtype": "default",
+	"type": "curtain",
+}, {
+	"subtype": "default",
+	"type": "curtain",
+	"id": 2,
+	"channels": [{
+		"value": "on",
+		"type": "STRING",
+		"name": "action"
+	}]
+}, {
+	"id": 3,
+	"channels": [{
+		"name": "action",
+		"value": "on",
+		"type": "STRING"
+	}],
+	"subtype": "default",
+	"type": "curtain"
+}, {
+	"id": 4,
+	"channels": [{
+		"name": "action",
+		"type": "STRING",
+		"value": "on"
+	}],
+	"subtype": "default",
+	"type": "light",
+}]
+~~~
+
+### scene item json数据格式
+
+
+~~~json
+{
+  "id": 4,
+  "name": "1004",
+  "displayName": "test_scene_4",
+  "areaId": 1,
+  "type": "sleep",
+  "subtype": "",
+  "actionDesc": "...",
+  "enable": true
+}
+~~~
+
+### scene list json数据格式
+
+~~~json
+{
+  "type": "sceneListResult",
+  "size": 2,
+  "items": [
+    {
+      "id": 1,
+      "name": "test_scene_1",
+      "type": "exit",
+      //"description": "close all device when exit",
+      "actionDesc": ""
+    },
+    {
+      "id": 3,
+      "name": "test_scene_3",
+      "type": "work",
+      //"description": "open all device when at work",
+      "actionDesc": ""
+    }
+  ]
+}
+~~~
+
+## 定时触发(Schedule)
+
+#### 定时事件触发：
+
+时间：星期+小时+分钟+秒，可设置多个
+举例:
+周一周二周三周四周五，08:30:00，自动开启工作模式
+周一周二周三周四周五，13:00:00，自动开启休息模式
+周一周二周三周四周五，14:00:00，自动开启工作模式
+
+### schedule http接口
+
+#### 获取时间表(schedule)列表
+GET /api/schedule
+
+#### 修改时间表
+PUT /api/schedule
+
+#### 新增时间表项(ID自动生成)
+POST /api/schedule/
+
+#### 根据ID删除时间表项
+DELETE /api/schedule/{id}
+
+#### 根据ID修改时间表项
+PUT /api/schedule/{id}
+
+#### 根据ID查询时间表项
+GET /api/schedule/{id}
+
+### 时间表项(schedule)数据格式
+
+~~~ json
+{
+  "id": 1,
+  "name": "上班定时开启工作模式",
+  "time": "{\"hour\":12,\"minute\":12,\"second\":12,\"weekday\":[1,3,5]}",
+  "sceneId": 1,
+  "enable": true
+}
+~~~
+
+### 时间触发表(schedule)列表数据格式
+
+~~~json
+{
+  "enable": true,
+  "items": [
+    {
+      "id": 1,
+      "name": "上班开启工作模式",
+      "time": "{\"hour\":8,\"minute\":30,\"second\":0,\"weekday\":[1,2,3,4,5]}",
+      "sceneId": 1,
+      "enable": true
+    },
+    {
+      "id": 2,
+      "name": "下班开启离开模式",
+      "time": "{\"hour\":20,\"minute\":0,\"second\":0,\"weekday\":[1,2,3,4,5]}",
+      "sceneId": 2,
+      "enable": true
+    }
+  ]
+}
+~~~
+
+## 事件触发(Trigger)
+
+时间：开始时间(星期+小时+分钟+秒)+结束时间(星期+小时+分钟+秒)，可设置多个
+设备事件：门禁、各种传感器等
+举例:
+开始时间（周一周二周三周四周五，08:00:00）结束时间（周一周二周三周四周五，09:30:00），该时间段检测到门禁刷卡数据，自动开启工作模式
+开始时间（周一周二周三周四周五，08:00:00）结束时间（周一周二周三周四周五，21:30:00），该时间段检测到人体感应，自动开启茶水间灯光
+
+设备事件细分，可以叠加多个条件，与或非
+
+### http接口
+
+#### 获取触发列表
+GET /api/trigger
+
+#### 修改触发
+PUT /api/trigger
+
+#### 新增触发表项(ID自动生成)
+POST /api/trigger/
+
+#### 根据ID删除触发表项
+DELETE /api/trigger/{id}
+
+#### 根据ID修改触发表项
+PUT /api/trigger/{id}
+
+#### 根据ID查询触发表项
+GET /api/trigger/{id}
+
+### 触发表项数据格式
+
+~~~json
+{
+  "id": 1,
+  "name": "test",
+  "enableTime": {
+    "startTime": {
+      "hour": 8,
+      "minute": 30,
+      "second": 0
+    },
+    "endTime": {
+      "hour": 21,
+      "minute": 0,
+      "second": 0
+    },
+    "weekday": [
+      1,
+      3,
+      5
+    ]
+  },
+  "condition": {
+    "devId": 15,
+    "devType": "humiture",
+    "logicType": "and",
+    "data": [
+      {
+        "name": "temp",
+        "compare": "equal",
+        "value": 20
+      },
+      {
+        "name": "humidity",
+        "compare": "greater",
+        "value": 40
+      }
+    ]
+  },
+  "sceneId": 1,
+  "enable": true
+}
+~~~
+
+### 触发表列表数据格式
+
+~~~json
+{
+  "items": [
+    {
+      "id": 1,
+      "name": "卫生间有人自动开灯",
+      "enableTime": {
+        
+      },
+      "condition": {
+        
+      },
+      "sceneId": 1,
+      "enable": true
+    },
+    {
+      "id": 2,
+      "name": "卫生间无人自动关灯",
+      "enableTime": {
+        
+      },
+      "condition": {
+        
+      },
+      "sceneId": 2,
+      "enable": true
+    }
+  ]
+}
+~~~
+## 文件管理(File Manager)
+
+### http接口
+
+#### 获取文件列表(path:background(背景图片))
+
+GET /api/file/{path}
+
+#### 上传文件
+POST /api/file/{path}?name=bg1.jpg
+
+#### 下载文件
+GET /api/file/{path}?name=bg1.jpg
+
+#### 删除文件
+DELETE/api/file/{path}?name=bg1.jpg
+
+### 文件项数据格式
+
+~~~json
+{
+  "name": "bg1.jpg",
+  "size": "1M"
+}
+~~~
+
+### 文件列表数据格式
+
+~~~json
+{
+  "items": [
+    {
+      "name": "bg1.jpg",
+      "size": "1M"
+    },
+    {
+      "name": "bg2.jpg",
+      "size": "1M"
+    },
+    {
+      "name": "bg3.jpg",
+      "size": "1M"
+    }
+  ]
+}
+~~~
+
+## 其他操作接口
+
+### 获取系统信息
+
+GET /api/system/sysinfo
+
+#### 数据格式
+
+~~~json
+{
+	"uptime": 2223, /* Seconds since boot */
+	"memTotal": 1009660,//单位kb
+	"memFree": 919732,
+	//"memAvailable": 948204,
+	"cpu": "Amlogic",
+	"storageTotal": "2G",
+	"storageAvailable": "1.8G",
+	"storageUsed": "136.6M",
+	"serialNumber": "",
+	"hardwareVersion": "",
+	"softwareVersion": ""
+}
+~~~
+
+### 以太网信息
+
+#### 获取以太网信息
+
+GET /api/system/network
+
+#### 修改以太网信息
+
+PUT /api/system/network
+
+#### 数据格式
+
+~~~json
+{
+	"dhcp": false,
+	"ip": "192.168.1.2",
+	"netmask": "255.255.255.0",
+	"geteway": "192.168.1.1",
+	"mac": "01:02:03:04:05:06" //只能获取，不能修改
+}
+~~~
+
+### 网关配置信息
+
+#### 获取配置信息
+GET /api/config
+
+#### 设置配置信息
+PUT /api/config
+
+#### 导入配置文件
+POST /api/config/export
+
+#### 导出配置文件
+GET /api/config/devlist
+
+#### 导入设备列表(上传配置文件)
+POST /api/config/devlist
+
+#### 导出设备列表(下载配置文件)
+GET /api/config/devlist
+
+#### 数据格式
+
+~~~
+{
+    "basic": {
+        "platform": "zhiju",
+        "canType": "uart2can",
+        "canId": 32,
+        "gatewayId": 1,
+		"send_log_to_server": 1,
+		"ntp_server": "",
+		"workMode": "master" //master或slave
+    },
+    "remote": {
+        "brokerAddress": "tcp://www.izhiju.cn:1883",
+        "username": "mqttgateway",
+        "password": "Iottest8@h2018"
+    },
+    "local": {
+        "brokerAddress": "tcp://localhost:1883",
+        "username": "",
+        "password": ""
+    }
+}
+~~~
+
+### 获取系统时间
+GET /api/system/time
+
+### 修改系统时间
+PUT /api/system/time
+
+### 数据格式
+~~~json
+{
+	"rawTime":	1632981788, //1970年1月1日起的秒数
+	"ntp_time":	true,
+	"ntp_server":	["0.pool.ntp.org", "1.pool.ntp.org", "2.pool.ntp.org", "3.pool.ntp.org", "time.android.com"]
+}
+~~~
+### 系统操作命令
+
+POST /api/system/cmd
+
+~~~json
+{
+  "cmd": "cmd_name" //reboot重启,factory_reset恢复出厂
+}
+~~~
+
+### 修改密码
+
+PUT /api/system/reset_passwd
+
+#### 数据格式
+
+~~~
+{
+	"passwd_current": "",
+	"passwd_new": ""
+}
+~~~
+
+### 浏览器上传固件升级
+POST /api/system/upload_firmware
+
+### 检测固件版本
+GET /api/system/update/latest
+
+### OTA升级固件
+POST /api/system/update
+#### 数据格式
+{
+	"latest": "1.0.1"
+	"path": "http://www.test.com/iot_gateway.img"
+}
+
+### 网关日志
+
+#### 获取网关日志
+GET /api/system/log
+
+#### 浏览器发送数据
+
+~~~json
+{
+	"date_begin": "2021-09-02 00:00:00",//查询日志开始时间
+	"date_end": "2021-09-02 23:59:59",//查询日志结束时间
+	"level": 7, //查询日志级别info:1 warn:2 error:3 7=1+2+3
+	"page": 2, //查询第几页
+	"offset": 50,//从第几条日志开始查询
+	"limit": 50//返回日志条数
+}
+~~~
+
+#### 网关返回数据
+
+~~~json
+{
+  "data": [
+    {
+      "id": 1004,
+      "level": 1,//info:1 warn:2 error:3
+      "date": "2021-08-28", //日志产生日期
+      "time": "03:01:58", //日志产生时间
+      "ip": "127.0.0.1",
+      "user": "admin",
+      "message": "open area1 light1", //日志信息内容
+      "message_id": "1" //日志ID
+    },
+	{
+      "id": 1003,
+      "level": 1,
+      "date": "2021-08-28",
+      "time": "03:01:58",
+      "ip": "127.0.0.1",
+      "user": "admin",
+      "message": "open area2 curtain",
+      "message_id": "2"
+    },
+    {
+      "id": 1002,
+      "level": 2,
+      "date": "2021-08-28",
+      "time": "03:00:26",
+      "ip": "127.0.0.1",
+      "user": "admin",
+      "message": "",
+      "message_id": "3"
+    },
+    {
+      "id": 1001,
+      "level": 3,
+      "date": "2021-08-28",
+      "time": "03:00:05",
+      "ip": "127.0.0.1",
+      "user": "admin",
+      "message": "send canbus data error",
+      "message_id": "4"
+    }
+  ],
+  "total": 3,
+  "severity": {//相应级别日志条数
+    "info": 2,
+    "warn": 1,
+    "error": 1
+  },
+  "error_code": 0,
+  "error_message": ""
+}
+~~~
+
+#### 导出日志文件
+GET /api/system/log_export
+
+
+
+### 网关地区配置信息
+
+#### 获取配置信息
+GET /api/config/city
+
+#### 设置配置信息
+POST /api/config/city
+
+~~~json
+{
+	"location_id": 101010100,                            //城市ID
+	"location_name_en": "Beijing",                       //本地城市英文
+	"location_name_zn": "北京",                          //本地城市中文
+	"iso_3166_1": "CN",                                  //国家编码
+	"country_region_en": "China",                        //国家英文
+	"country_region_zh": "中国",                         //国家中文
+  "adm1_name_en": "Beijing",                           //省级英文
+  "adm1_name_zh": "北京市",                             //省级中文
+  "adm2_name_en": "Beijing",                           //市级英文
+  "adm2_name_zh": "北京市",                             //市级中文
+  "timezone": "Asia/Shanghai",                          //时区
+  "latitude": "39.904987",                              //纬度    
+  "longitude": "116.405289",                            //经度
+  "adcode":110000                                      //城市编码   
+}
+~~~