# EVCamera 启动过程及运行时行为、接口

## 启动过程概览

```flow
st=>start: PowerOn
loadcfg=>operation: Load Local Configuration
videostream=>operation: Init SDK & Frame Callback
qr=>operation: start QR thread
checktime=>operation: Update NTP Time
gottime=>condition: Yes or No?
mqtt=>operation: Connect MQTT
mqttOK=>condition: OK?
ptz=>operation: relocate PTZ position
pusher=>operation: create pusher svc
record=>operation: create record svc
uploader=>operation: create upload svc
smart=>operation: create smart detection svc
watchdog=>operation: enable watchdog and feeding every 20s forever(33s deadline)

st->loadcfg->videostream->qr->checktime->gottime
mqtt->mqttOK->ptz->pusher->record->uploader->smart->watchdog
gottime(no)->checktime
gottime(yes)->mqtt
mqttOK(no)->mqtt
mqttOK(yes)->ptz

```

## 启动过程的可用的事实

- 在获取到NTP时间及连上MQTT Broker之前, PTZ重定位功能不会启动

安装、操作、维护人员可以根据重新上电后摄像头有没有转动判断是否联网.

* 没有联网之前QR识别功能是启用的

安装、操作、维护人员可以利用此事实进行离线配置WIFI、SN、MQTT





## 运行时行为和接口

### 机制

```mermaid
sequenceDiagram
	participant EVCamera
	participant Broker
	participant CloudSvc
	
	EVCamera ->> Broker: power_on: pub online
	EVCamera ->> Broker: sub: /evcamera/v1.0/request/<SN>
	CloudSvc ->> Broker: pub: cmd = config|status|upload_video|ptz|get_config|qr
	Broker ->> EVCamera: notify: request {"rid":"<RID>", "cmd": "<x>", ...}
	EVCamera ->> EVCamera: [Handle cmd]
	EVCamera ->> Broker: pub /evcamera/v1.0/response/<RID>
	EVCamera ->> Broker: pub /evcamera/v1.0/report
```

#### MQTT Broker topics

- 下发: /evcamera/v1.0/request/<SN>
- 请求响应: /evcamera/v1.0/response/<RID>
- 请求异常响应或主动上报: /evcamera/v1.0/report


#### 问题: 什么时候通过response topic 上报以及通过report topic 上报

#### 回答:

#### 1. 请求消息可能被从response topic 回复, 也可能被从report topic回复

其区别在于: 是否有效识别出来请求的内容及RID, 如果能识别出来则前者, 否则后者. 

下面就是一个因请求内容不合法导致的异常, 能且只能响应到report topic上. (因无法识别出RID, 所以无法从response topic 响应)

 ```json
{
   "category":"",
   "code":2,
   "msg":"exception: Unexpected non-whitespace character after JSON text at line 1 and column 10, \"time\": 1567669674, \"cmd\": \"status\", \"rid\": \"001231554A20\", \"data\": {} }",
   "rid":"",
   "sn":"012345678901",
   "time":1592281836453,
   "type":"report"
}
 ```

#### 2. 所有的主动上报都通过report topic



### 上线消息: 上电启动后(连接MQTT成功)自动发送

```json
topic: /evcamera/v1.0/report
payload:
{
   "category":"online",
   "code":0,
   "data":{
   },
   "msg":"I'M ONLINE",
   "rid":"",
   "sn":"<SN>",
   "time":1592276971163,
   "type":"report"
}
```



### 实时状态查询接口

#### 请求:

```json
topic: /evcamera/v1.0/request/<SN>
payload:
{
  "time": 1567669674,
  "cmd": "status",
  "rid": "<RID>",
  "data": {}
}
```

#### 响应:

```
topic: /evcamera/v1.0/response/<RID>
payload:
{
   "category":"status",
   "code":0,
   "data":{
      "pusher":{
         "msg":[
         ],
         "val":0
      },
      "record":{
         "capacity":4363,
         "first":1592200334048,
         "last":1592282028135,
         "num":448
      },
      "sd":{
         "MBTotal":29604,
         "MBfree":27877
      }
   },
   "msg":"OK",
   "rid":"001231554A20",
   "sn":"012345678901",
   "time":1592282131155,
   "type":"response"
}
```

##### 响应解读

1. data.pusher.val: pusher状态标志. 0: 正常, 比特0: 内部使用, 比特1置位: 连接视频网关VGW失败,  比特2置位: pusher未启用, 其他比特: 未定义
2. data.puser.msg = []: 当有异常时, 对应的异常可读字符描述
3. data.sd: 为空时说明未检测到SD卡;
4. data.sd.MBTotal: SD卡存储大小
5. data.sd.MBfree: 可用的SD卡存储大小
6. data.record.capacity: 以当前配置估算的可存储视频文件数目
7. data.record.first: 最旧的录像文件时间戳
8. data.record.last:最新的录像文件时间戳
9. data.record.num: 当前录像文件数目

##### 可利用的特性

平台或其他相关者可利用此接口返回超时, 判断摄像头是否在线 (建议超时时间: 2s)



### 配置接口

#### 请求

```
topic: /evcamera/v1.0/request/<SN>
{
  "time": 1567669674,
  "cmd": "config",
  "rid": "<RID>",
  "data": {
    "sn": "A000000Z",
    "vgw": "evcloudsvc.ilabservice.cloud:7123",
    "mqtt": "admin:password@evcloudsvc.ilabservice.cloud:11883",
    "upload": "evcloudsvc.ilabservice.cloud:10009",
    "features": {
      "push": 1, 
      "motion": {
        "enabled": 1,
        "region": {
          "maxX": 1,
          "maxY": 1,
          "minX": 0,
          "minY": 0
        },
        "level": 3
      },
      "recordLen": 30,
      "ai":{
        "enabled": 1,
        "faceThresh": 0.75,
        "humanThresh": 0.63,
        "region": {
          "maxX": 1,
          "maxY": 1,
          "minX": 0,
          "minY": 0
        }
      }
    }
  }
}
```



#### 响应

- 正常响应:

```
topic: /evcamera/v1.0/response/<RID>
{
  "time": ts,
  "rid": "<RID>",
  "type": "response",
  "category": "config",
  "sn": "<SN>",
  "code": 0,
  "msg": "OK",
  "data": {
    "vgw": "evcloudsvc.ilabservice.cloud:7123",
    "mqtt": "admin:password@evcloudsvc.ilabservice.cloud:11883",
    "upload": "evcloudsvc.ilabservice.cloud:10009",
    "features": {
      "push": 0,
      "motion": {
        "enabled": 1,
        "region": {
          "maxX": 1,
          "maxY": 1,
          "minX": 0,
          "minY": 0
        },
        "level": 3  // 1 - 6
      },
      "recordLen": 30,    // seconds of one slice of local recording
      "ai":{
        "enabled": 1,
        "faceThresh": 0.75,  // 0 - 1
        "humanThresh": 0.63,  // 0 - 1
        "region": {
          "maxX": 1,
          "maxY": 1,
          "minX": 0,  
          "minY": 0
        }
      }
    }
  }
}
```

- 异常响应:



### 获取视频接口

- 请求

```json
topic: /evcamera/v1.0/request/<SN>
{
  "time": 1567669674,
  "cmd": "upload_video",
  "rid": "<RID>",
  "data": {
      "start": 1567669674,
      "end": 1567668000,
      "type": 6
    }
}
```

- 响应

```json
topic: /evcamera/v1.0/response/<RID>
{
  "time": 1567669674,
  "type": "response",
  "rid": "<RID>",
  "cata": "upload_video",
  "sn": "<SN>",
  "code": 1,
  "msg": "failed to upload video: file not exist",
  "data":{
    // empty
  }
}
```



### 云台移动接口 PTZ

- 请求

```json
topic: /evcamera/v1.0/request/<SN>
{
   "time":1567669674,
   "cmd":"ptz",
   "rid":"<RID>",
   "data":{
      "action":"left",
      "degree":10
   }
}
```

- 响应

```json
topic: /evcamera/v1.0/response/<RID>
{
    "category": "ptz",
    "code": 0,
    "data": {
        "horizontal": 149,
        "vertical": 0
    },
    "msg": "OK",
    "rid": "<RID>",
    "sn": "<SN>",
    "time": 1592284592684,
    "type": "response"
}
```



### QR识别

- 请求

```
topic: /evcamera/v1.0/request/<SN>
{
   "time":1567669674,
   "cmd":"ptz",
   "rid":"<RID>",
   "data":{
   		"duration": 10
   }
}
```



##### 解读

data.duration: 启用识别的最大时常, 单位为秒

退出QR识别状态的条件:

1. 识别超时

2. 当在duration时间内有任意一次识别成功



当设置duration = -1时, QR识别一直启动. 不建议开启(会影响其他任务)

当设置duration=0时, QR识别停止.

- 响应

命令本身无响应

