 |
Tange Cloud for Device
Rev.366 |
|
Tange Cloud for Device
Rev.366 |
例如：对一个2通道的设备的 DoubleLight 属性，固件返回 "Yes"意味两个通道都有白光灯。等同于 ["Yes", "Yes"]。如果返回 ["Yes", "No"]则表示仅在第一个通道上有白光灯。
多(扩展)属性表达与解析 能力可能有多个属性， 如果属性值是字符串格式，多个属性间用分隔符隔开。
分隔符可以是','或';'。之前的文档里，有的指定';'，有的指定','，一般情况下这两者在功效上并没有区别。因此，除特殊情况(目前是Cap-Zoom)，APP要能兼容这两种分隔符.
因为多属性的存在，除了No值以外，APP端要避免直接字符串比较。而是要先用 ','和';'分割，再在分割得到数组中搜索。
多属性情形，属性间可能存在依赖关系。为方便解析，规定主属性在前。
是否支持4G [2024/4/17 rev.190 更新支持simtype]
其中 simtype是可选的，取值：
是否支持报警灯
是否有蜂鸣器
当设备支持蜂鸣器时，还可以有以下扩展属性(用','分隔)。能力值中具有扩展属性时，Yes可省略。
支持的对讲音频格式: “音频编码:采样频率:采样位宽:声道数”
如果没有此描述，默认为 "g711a:8000:16:1"。或者在收到实时音频后取与之相同的配置。
是否支持自动追踪
电池摄像机能力
扩展属性用';'分隔，追加到主能力后面。
对 Dormant类型摄像机，定义如下扩展属性：
呼叫的时间配置。
时间单位为秒，计时从触发呼叫那一刻开始（对app来说是呼叫事件的时间）。
呼叫超时时间: 超时无人接听，设备呼叫终止，事件状态为missed。
超时后设备端的默认行为是下电（否则设置标志），APP应退出接听界面或不再尝试连接。
门锁的默认值是60", 其余设备类型为30"。
最大持续时间: 如果非0，接听在到达最大存在时间时强行中止。
设备端强行中止时要调用 TciForceSleeping(), app会在视频通道上收到 RTM_GOINGTO_SLEEP 通知。
APP端收到通知，或倒计时到0，都要断开连接。
30“呼叫超时后，设备下电；拒接或挂断后设备立即下电；用户接听后可以一直通话。
30"呼叫超时后，设备下电；拒接或挂断后设备立即下电；用户接听到180"(从呼叫开始计时)强制关断设备下电。
30"呼叫超时后，设备和app端停止振铃；在180”内用户可以任意接听、挂断、重新连接和退出；180"时强制下电。
AI能力分硬AI（设备设备硬件的AI能力，hw_ai）和软AI（通过AI服务器获取的AI能力，'sw_ai'）两种. 设备在此描述中分别描述这两种能力.
上报格式为一个json数组，格式见例子。
NOTE – 见后面的说明 ！！！
* fd – 人脸检测 (face detection) * fr – 人脸识别 (face recognition) * mt – 移动跟踪 (movement tracking) * ot – 物体跟踪 (object tracking)
下面两种取值不再有效，要合并并改为 body [Rev217, 2024/8/29]
表示设备有如下软AI能力： [软AI "sw_ai" 已废弃]
* 移动跟踪(mt): 要购买服务 ----— 软AI都要通过购买猎取
硬AI能力:
为保持兼容，APP要支持旧的"用逗号隔开的一种或多种ai能力字符串"格式(形如："body,fd,mt")，对这种描述，其标志值按=0处理, 即要购买服务。
新增AI类型，这个类型的名字会以平台注册，但在SDK不会再添加一个对应事件类型的枚举类型(例如 ECEVENT_CRY)。对这类事件，固件要采用自定义事件标签的方式上报(EVENTPARAM::event = ECEVENT_USER_DEFINED)，事件的名字与AI类型的名字一致。
有对应的事件枚举定义的，可以继续使用特定枚举的方式。
在此处描述的ai类型，其对应事件不用在 EventSet 里再描述一次。
布撤防能力
0xNNN/0xMMM: 都是数值的16进制 字符串 表示。转成数值后位n如果为1，表示事件n被设置。事件n取值见 ECEVENT 。
0xNNN: 为支持独立配置的报警类型。
0xMMM: 为不支持独立（合并在一起）配置的报警类型。如果缺省，表示其余类型不支持布/撤防。
设备支持布撤防时，要支持指令: TCI_CMD_GET_DEFENCE_REQ / TCI_CMD_SET_DEFENCE_REQ
支持独立设置的报警源，还要支持指令: TCI_CMD_SET_EVENT_STATE / TCI_CMD_GET_EVENT_STATE
如果设备支持 移动侦测、人形检测、声音三种报警, 并且声音报警可以单独开关。三种报警类型常数为
于是：
最后，得到能力描述为 "0x08:0x06"或 ["0x08", "0x06"]。
如果设备返回 "0x08", 则意味着仅可以对声音报警进行布撤防设置。
设备报告支持独立设置，APP在实现上也可能选择一起配置。固件要能处理这种情况
以上面的能力描述为例。设备报告声音侦测支持独立设置，但APP实现还是采用的统一布撤防。固件在收到的 TCI_CMD_SET_DEFENCE_REQ 命令的请求中 Tcis_SetDefence::items[0].event_mask 值为 ECEVENT_ALL 或 0x0e，那么声音侦测的布撤防采用本处的统一设置。
之后APP升级，对声音采用单独布撤防设置，event_mast取值为 0x08, 那么声音侦测要采用新的的配置，原来的统一设置中要排除声音侦测。
APP调用 TCI_CMD_GET_DEFENCE_REQ 获取配置时，如果能力为 "bundle", 命令参数被忽略。否则要使用以下参数结构:
以前面的配置为例，需要在进入声音的布撤防界面前，以
请求声音布撤防配置。在进入另一个对其它项的配置界面前，以 req.event = 0获取其它报警类型共用的布撤防配置。
设备的变倍(焦)参数及相关属性描述
| "times:DESC,DESC[,TOTAL]" "times:DESC[,,TOTAL]" | 变焦能力描述 | TCI_CMD_SET_PTZ_POS TCI_CMD_PTZ_LONG_COMMAND 变焦操作控制指令说明 |
| "times:unknown" | 支持，但是变焦倍数未知. APP上只有Z+/Z-按钮 | |
| "2lenses" | 双目摄像机 | TCI_CMD_SET_PTZ_POS 双目摄像机的控制 云台配置 |
| "2lenses;times:xxx" | 双目+变焦. 双目和变焦描述的组合，用一个';'隔开 | TCI_CMD_SET_PTZ_POS TCI_CMD_PTZ_LONG_COMMAND TCI_CMD_GET_PSP 双目+变焦摄像机的控制 |
| 其它 | 不支持 |
扩展属性用 ';'与其它发生隔开
是否支持日夜切换
| 白光灯配置 (Tcis_GetWhiteLightResp::mode) | 白光灯规则 | 红外灯状态 |
|---|---|---|
| 开 | 白天灭，夜间亮 | 灭 |
| 关 | 灭 | 白天灭，晚上亮 |
| 自动 | 白天灭。晚上触发移动侦测时亮 | 白天灭，晚上亮。有移动侦测时灭，并触发白光灯 |
设备类型。
设备类型规定了设备主要的行为模式。但相关能力配置仍然需要准确描述。例如台灯类别默认有灯、灯光可调、支持定时器，这些能力仍然需要在DoubleLight里配置。
是否支持白光灯。（实际应叫 WhiteLight, 从历史）
Yes - 支持。TCI_CMD_GET_DOUBLELIGHT_REQ / TCI_CMD_SET_DOUBLELIGHT_RESP.
当设备支持白光灯时，还可以有以下扩展属性(用','分隔)。能力值中具有扩展属性时，Yes可省略。
Dim - 可调节。在Yes属性的基础上，支持 TCI_CMD_GET_LIGHT / TCI_CMD_SET_LIGHT.
设备支持调节的功能项在TCI_CMD_GET_LIGHT 命令的 Tcis_LightState::fMask 中返回。
例如返回 SETLIGHT_F_INTENSITY | SETLIGHT_F_ONOFF, 表示支持调光强度和开关
扩展功能的位标识
该能力的值为一个无限位整数的16进制字符串表示。这个字符串表示的数值可以超出本机可以表示的最大整数值。
| 位 | 功能 | 说明 |
|---|---|---|
| 0 | 为1时表示设备端正确支持了SD卡录像列表中的事件类型 SAvExEvent::event | 以前的 iCam365/WeCAM App没有检查设备SD卡录像列表中事件类型成员 SAvExEvent::event, 导致旧的固件中没有正确返回的这个值。新 iCam365/WeCAM APP 的 UI 将要显示使用这个成员。为了与旧的固件作区分，如果固件正确设置了 SAvExEvent::event, 则设置此标志，App按返回值显示具体事件类型；否则只区分是否为事件。 客户自己开发设备和App的，可以忽略此标志或自行约定 |
更长的例子
假设应用能处理的最大整数类型是uint32，这个字符串表示的值已经溢出。应用要把它解析成3个32位整数的数组:
标志的第N位，在数组中对应 vals[N/32] 的 位 (N%32)
设备额外支持或屏蔽的事件集合。
设备按类型，参考硬件配置，会被赋予有一个默认允许的事件集合。集合外的事件会被过滤掉。如果要支持或屏蔽额外的事件，需要在此处报告。
自定义事件需要在此处报告
EventSet的是一个2元或4元素的数组，每两个元素组为一对，每一对的第一个元素表示要开启的事件，第二个元素表示要屏蔽的事件（或者表述为：下标0、2的表示开启，下标1、3的元素表示禁止）。
元素类型可以是一个整数(用第N位表示事件N)，也可以是一个字符串(内容为逗号','或分号';'分割的事件名列表)，还可以是另一个JSON数组(事件名)。
整数用来表达SDK预定义事件，因为SDK只对外提供了事件的数值符号，没有公开名称。
字符串或 JSON 字符串数组用来表达用户扩展的事件。
扩展事件以 "`x:`" 开头，仍然需要先在平台注册
门铃设备默认支持呼叫事件 ECEVENT_DOORBELL，如果要额外支持pir和人形事件，禁用移动侦测(假设。实际门铃默认不支持移动侦测)。要开启和屏蔽的标志：
SDK将EventSet上报给平台时会把掩码转成tag数组。例如:
在前例基础上，假设用户定义并注册了两个扩展事件 "`x:earthquake`" 和 "`x:volcano_erpt`", 下面的表达都是有效的
SDK通知给平台的内容
(最后更新于 2024-06-28 rev207)
支持的扩展指令集。格式为分号';'（APP端要允许逗号','分隔）隔开的指令名，或者是一个 JSON 数组。
示例：
是否支持G-Sensor
【2022/10/24】
如果只支持灵敏度设置，可以设置G-Sensor为"scene"，并处理 scene=1(GSENSORSCENE::GSENSOR_SCENE_PARKING) 的情形
但推荐使用新的能力值: 在 ExtInstructions 中包含 "parking-mon"
是否支持Gps
移动侦测能力
支持时要实现的指令：TCI_CMD_SETMOTIONDETECT_REQ, TCI_CMD_GETMOTIONDETECT_REQ
如果区域可显示(VisibleZone), 需要支持TCI_CMD_GET_MDAREA_STATE, TCI_CMD_SET_MDAREA_STATE
多通道设备(例如画中画)，如果只对某一个通道进行设置，配置要写成数组形式。例如
表示要在通道1上进行移动侦测设置
是否有麦克风。默认为有，但不能控制。下面的值要明确指定。
附加属性以','隔开追加在主属性后面
2023-04-07:
多路图像
{relation}为:
"composed"： 多路视频一路音频
"independ": 多路独立音视频
是否支持PIR(灵敏度设置)
用于选择设备支持的服务。内容分公共属性和特定属性。
特定属性同设备类型相关，同时具体内容取决于需求文档的约定。
Profile的值是一个json字符串(2024/04/28) ，不再使用非格式化的字符串表示(App要保留对旧的设备的支持，目前只有"EyeplusEU"一种无格式取值)
ExtFuncSet – 扩展功能集(Extended Function Set), 其值是一个json数组。
例子: Profile = { "ExtFuncSet":["KLM"] }
DeviceType = DriveRec
这种配置用公共属性 'NoRemoteLiveAccess'代替
DeviceType = IPC
LightSens - Sensor感光能力
Black – 黑光级
例子: Profile={"LightSens": "Black"}
(是否支持)SD卡录像配置
多个开关值用','隔开，或写成json数组格式。例如: "res,time-lapse"或 ["res", "time-lpase"]
是否支持画面旋转
设备支持的图像质量
图像质量描述项的组合.默认 0HD+1SD. 参见 多码流支持
设备屏显描述
"mjpg:320x240:0:cw90" 要求App抓取320*240的jpeg图片，并且把图像顺时针旋转90度.
"h264:1280x720:1" App可以视网络情况传输 1280*720 或 640*360(或别的分辨率) 的h264图像，图像的长宽比应基本一致。
扬声器属性
是否支持云台, 以及云台控制方式和其它属性
要支持云台，设备必须在属性中返回 "Yes", "Relative", "Absolute", "Hybrid" 中的一个值("Yes"和"Relative"是等效的)【2023-03-31】
如果设备支持云台，能力描述中可以追加其它属性。追加属性放在后面，用','隔开。
PresetPos - 预置位。
例: "Relative,PresetPos".
需要支持命令:
WatchPos - 守望位.
例："Absolute,WatchPos". 支持守望位就一定支持预置位，需要响应命令
Reset - 支持云台复位。
有此属性要响应命令 TCI_CMD_PTZ_LONG_COMMAND 的Tcis_PtzCmd::control 参数取值 TCIC_MOTOR_RESET_POSITION (=35)。并在复位完成后给一个应答
HorzOnly | VertOnly - 仅支持水平或垂直方向控制。
默认为同时支持水平和垂直
Cruise - 支持巡航和线扫。
编辑巡航轨迹使用 TCI_CMD_GET_PTZ_TRACK / TCI_CMD_SET_PTZ_TRACK . 调用巡航轨迹使用 TCI_CMD_PTZ_LONG_COMMAND(设置 Tcis_PtzCmd::control 为 TCIC_PTZ_CALL_TRACK(=10), 或 TCIC_PTZ_AUTO_SCAN(=9))
LocInPic - 图片内定位（枪球联动）。
有此属性的通道，APP可以允许用户选择该路图像中一个位置并通过 TCI_CMD_LOCATE_IN_PIC 命令回传给设备，设备驱动本通道（如果本通道没有云台，则是另一路有云台的通道（联动））云台指向选中的位置。
有或没有云台的通道都可以有此属性。
举例:
【多枪一球的产品，约定有云台的这一路为通道0】
品字形布局、双枪并列的机器，当球与两路枪联动时，如果不另加说明，App默认将两路枪的图像按在数组中出现的顺序左右排列，并将两路图像从逻辑上视为合为一路(一枪)。发送 `TCI_CMD_LOCATE_IN_PIC` 时，x取值基于合成的后的图像。
Y：计算方式不变。
X：X' = 先按原来的方式计算相对原始图像(通道1或通道2)宽度的比例除以2。对通道1，X=X'; 对通道2，X=X'+0.5
参数中的channel忽略(可传0，即带云台这一路的通道号)
传统摄像机，一路视频就对应一个镜头、一路音频、0或一个云台等。命令中用到的channel参数，就意味这样一套实体的组合。
双目和画中画摄像机，存在独立或共享云台(可能还有别的硬件)情形，在描述上会有一些特殊的地方。
如果两个镜头不是随动(独立)的，要用一个长度为2的数组来描述哪一个镜头下可以操纵云台。
数组元素0和1分别对应画中画设备的通道0、1，双目摄像机的远景和近景。
云台控制命令中channel取0或1，对应数组下标。
以 SupportPTZ = ["No", "Yes"]为例：
| SupportPTZ | 元素0(No) | 元素1(Yes) |
|---|---|---|
| 画中画 | 通道0: 不支持云台 | 通道1 支持云台 |
| 双目摄像机 | 远景: 不支持云台 | 近景 支持云台 |
设备不支持 PresetPos
预置位功能完全在APP端实现。APP调用 TCI_CMD_GET_PTZ_POS 获取当前位置并保存为一个预置位，以后调用 TCI_CMD_SET_PTZ_POS 来恢复到预定位置
设备支持PresetPos
这种配置是为了让APP保存预置位时，调用 TCI_CMD_SET_PSP 通知设备，以便于设备连接第三方控制器(NVR)时预置位信息可以在APP和第三方间保持同步。
用户自定义Feature
这个值用于第三方开发者扩展自己的属性。获取能力集时，这个值透传给App端，App的SDK再返回给应用自行处理。
UDF的值是一个json对象的字符串表示。例如 {"feat1":"value1", "feat2":"value2"}
如果对象中含有一个名为 ext_attrs 的属性，这个属性值会传给平台并在平台端保存。在获取设备列表时可以在 ext_attrs::udf 里得到这个值。从rev320起设备端取消ext_attrs。UDF的所有内容都上报到平台
在App从设备获取能力集时，可以在 "UDF" 下拿到上面的值:
从平台拉取列表时，可以得到:
本语法用来描述设备所具有的变倍能力的类型（光学/电子放大）、放大倍数和控制方式。
下面公式中的 '+', 空格，[], 引号 是用来表示连接、分隔和常量字符串，不是最终能力字符中一部分
times:4,1.5
4倍光学/1.5倍电子，6.0步调整(默认)
times:4,2,5
4倍光学/2倍电子，5步调整。这种步数的描述太粗略，应该采用下面的形式
times:L4@(1:1.5:2:3:4),E2/9
4倍光学变倍，可以分5步控制(在 1x/1.5x/2x/3x/4x 时停下来)
2倍光学变倍，可以细分9步,每步间隔 (倍数2 - 1)/(步数9 - 1)。 本例中每步分别对应 1x, 1.125x, 1.25x, 1.375x, 1.5x, 1.625x, 1.75x, 1.875x, 2x.
times:S4,,
这个是要求在APP端模拟4倍电子变焦。步数为默认的4步。因为只有一种变焦方式，所以第2个{DESC}为空
2lenses;times:S1.5F3,S4
这个是双目摄像机，两个镜头各自在APP端模拟1.5倍和4倍电子放大。并且，近景镜头放大到1.5倍时，APP会定位显示到3 -— 这个看效果！！！
变焦控制指令使用现有的云台操作命令，请求结构体不变，但参数增加新的语义。
APP端的UI可能有不同设计，因而操作方式也不一样：
双目摄像机（Cap-Zoom = "2lenses"），两个镜头的切换，视为2倍变焦摄像机在1x和2x间做变倍操作。
使用 TCI_CMD_SET_PTZ_POS 指令，参数 PtzPos 的 z取 0.0和 1.0，分别对应APP界面上的两个快捷按钮【近景】和【远景】。
切换镜头时，要在新的镜头的第一帧前调用 TciSendLensSwitchFlag() 插入一个标志帧。
在APP端会收到一个 FRAMEINFO_t结构，其成员 flags = 1，其余皆为0.
【双目+变焦】 摄像机，可以有两种控制UI：
APP上只有变焦界面，对用户隐藏双目切换操作。
设备按普通变焦像机上报能力（Cap-Zoom="times:xxx"）和响应 TCI_CMD_SET_PTZ_POS 指令
APP上有变焦和远/近景切换界面。
设备要上报能力 Cap-Zoom="2lenses;times:xxxx"(双目和变焦能力的组合，用';'隔开)，响应 TCI_CMD_SET_PTZ_POS 指令
远/近景按钮对应的变倍位置z不再是固定的0.0和1.0，而是通过指令 TCI_CMD_GET_PSP 获取
此处码流的概念，定义为某种质量的图像输出。选择一种码流，即是选择一种不同的图像质量（分辨率/fps/bitrate等的不同）。 双码流设备支持同时输出两种不同质量的码流。 三码流设备可以输出3种不同质量的码流，但不一定有能力同时输出。当不能同时输出时，靠切换某一路码流的质量实现。
质量描述符不一定限于分辨率。例如可能是HD12fps，HD30fps，Prefer等任意字符串。其意义由固件自行解释，并与APP约定在UI上提示的方式。
质量描述项举例：
质量组合举例:
0HD+1SD: 设备只支持双码流，在码流0上输出高清，码流1上输出标清 0FHD+1HD+2SD: 设备支持3路码流同时编码, 分别在码流0/1/2上输出全高清/高清/标清图像 0FHD+1HD+1SD: 设备支持3种质量，但同时只能编码两路图像。它的码流0固定为FHD，码流1可以为SD或HD。 auto+0HD+1SD: 设备支持双码流(可手动选择)，同时支持自适应码流
修改后的逻辑使用同样的命令和quality参数。但quality的值会映射到质量描述项而不是码流。
为了兼容旧实现，保留原有的图像质量常数定义。
暂时最多支持5种质量。质量常数与码流的对应关系，要看设备的Resolutions能力。
使用索引来引用质量描述项是最简单的。但为了兼容，需要使用一种更复杂的映射方式：
| 质量常数 | 含义 | 设备支持的码流(质量)数 |
|---|---|---|
| TCIC_QUALITY_MAX | 最高质量 | 2,3,4,5 |
| TCIC_QUALITY_HIGH | 4,5 | |
| TCIC_QUALITY_MIDDLE | 中等质量 | 3,4,5 |
| TCIC_QUALITY_LOW | 5 | |
| TCIC_QUALITY_MIN | 最低质量 | 2,3,4,5 |
例如，设备支持3种质量(码流)，则会用到3种质量常数TCIC_QUALITY_MAX/TCIC_QUALITY_MIDDLE/TCIC_QUALITY_MIN，分别对应设备上报的Resolutions中的第1/2/3种质量。
APP收到设备的Resolutions能力后，忽略质量描述项前面的数字（注意：可能存在旧的固件没有数字）。
将描述符转成文字在UI上显示
根据描述项数目，确定每个描述项对应的质量常数(如前表)
用户在UI选择 高清/标清/... 时，APP在 TCI_CMD_SETSTREAMCTRL_REQ 命令的quality中传入相应的质量常数
SDK收到质量选择命令，如果请求的质量对应的码流下有多个质量设置，则将质量常数转换为质量描述项， 调用应用的TciCB::switch_quality(int channel, int stream, const char *qstr) 回调。
参数 stream/qstr对应Resolutions中某一项的值。例如 "0FHD"对应stream=0, qstr="FHD".
设备检查对应码流的质量设置是否与请求一致，如果不一致则修改之。
设备能力: 0FHD+1HD+1SD
质量常数和设备端对应的码流/质量：
| 质量描述项 | 质量常数 | APP显示 | 当前设置 |
|---|---|---|---|
| 0FHD | TCIC_QUALITY_MAX | 全高清 | * |
| 1HD | TCIC_QUALITY_MIDDLE | 高清 | * |
| 1SD | TCIC_QUALITY_MIN | 标清（或流畅） |
假设设备当前设置为：
用户打开APP时，默认请求的高清图像。
1.15.0