 |
Tange Cloud for Device
Rev.355 |
|
Tange Cloud for Device
Rev.355 |
实现码流自适应需要处理以下几个点：
auto，开启自适应功能之前规定的通用错误应答只能携带一个4字节的错误状态码。现在约定，可以在原来应答结构后扩展应用层数据:
这种扩展机制并不作为一种普遍的应答数据传输方式使用，而是用于 “命令最初只定义了通用应答，但后来增加了应答数据并且需要与之前保持兼容” 这一特殊场景。当预先知道命令应答有数据时，应使用特定命令应答结构。
App端收到扩展数据，按扩展数据的定义解释响应，否则按错误码的定义解释。
通过此方式发送数据，命令定义中必须要有明确约定。
| 旧 | 新 | 变动内容 |
|---|---|---|
| TciAcceptInCall(INCALLINFO * ) TciRejectInCall(INCALLINFO *) | TciAcceptInCall2(ECALLFLAVOR flavor) TciRejectInCall2() | 参数变化 |
| TgVdpAccept(INCALLINFO *) TgVdpReject(INCALLINFO *) | TgVdpAccept2() TgVdpReject2() | 去掉了参数 |
| STATUS_INCALL | STATUS_INCALL2 | 回调参数不再由用户释放 |
更新了以下命令和结构的描述，以支持选择回放
要支持选择回放，需要在能力 ExtInstructions 里加入 selchn
设备可以使用 TciSendRtMsg() 在p2p连接的命令通道上向App推送数据(Rev85开始已经支持在视频流中通过 TciSendLiveMessage() 插入通知. 参见 流事件)。 此接口的好处是只要有连接就可以发送。
设备使用命令值 2 向App发送数据包。数据包有一个固定长度的包头
如果还有额外数据，紧接在这个头之后。
这个结构携带的有效数据与 TciSendLiveMessage() 可以携带的有效数据是一样的。也就是说通知可以在两个通道上发送，最终选择取决于消息类型是不是与视频流强耦合。参考 RTMTYPE, 里面有说明。
应用使用 RTM_USER 类型来发送自定义数据。
Profile 增加 NoVideo 键
无音频使用
pwr-stgyrecdays能耗模式中的定时器结构 TIMEPLAN 增加 enabled 开关
DeviceType 类型 为PetFeeder 。这是新增的值。
在 EventSet 里上报自定义事件类型 x:feed 和x:feedm
新增的P2P命令接口定义参见头文件 TgCloudCmd_sp.h 的 喂食器 部分。
喂食记录以自定义事件上报,:
"x:feed" 自动喂食"x:feedm" 手动喂食参数格式：
"n_serving" : 喂食份数事件上报请求的数据举例:
SDK 为上报喂食事件提供了一个专用封装 TcuSendFeedingEvent() 以简化调用。这个接口申明在 tgutil.h 中。
如果不能满足需要可以按下例重新封装。
新的事件覆盖旧事件需要在调用 TciSetEventEx() 时显性指定，平台不支持仅根据时间戳去自动覆盖。为此, EVENTPARAM 中增加两个参数 EVENTPARAM::evtToReplace / EVENTPARAM::tPrevEvent, 分别给出旧事件的类型和发生时间。如果没有要替换的动作，这两个参数要设为0.
下面的内容在 2024-06-28(Rev207) 中有订正
新增指令 TCI_CMD_LIST_RECORDDAYS, 用于获取SD卡上存在录像的日期。返回 Tcis_DaysList 包含一个日期数组
增加指令 TCI_CMD_SET_POWER_STRATEGY / TCI_CMD_GET_POWER_STRATEGY, 用于管理电源工作模式。本指令代替 TCI_CMD_SET_MAX_AWAKE_TIME / TCI_CMD_GET_MAX_AWAKE_TIME
TCI_CMD_LISTEVENT_REQ 的应答结构 Tcis_ExListEventResp 作如下调整。
旧:
新：
当estype为1时，返回带事件时间戳的录像条目。App根据estype的值来兼容旧的设备。
TCI_CMD_GET_EXTERNAL_STORAGE_REQ 命令的应答结构 Tcis_SDCapResp::total 增加了一个 “正在初始化" 的状态表示
@subsection autotoc_md24 5. 上报信号强度(接口变动)
@ref TciSetWakeupReason() 增加了一个参数，用于上传当前 Wifi/4G信号强度
@section autotoc_md25 2024-04-17(rev190) 4G能力描述和接口变动
* @ref Feature_4G 能力增加 <tt>"simtype"</tt> 键用于描述SIM卡类型
* 用 @ref TciReport4GInfoEx() 代替 @ref TciReport4GInfo(), 后者移除。
* @ref TciSetWakeupReason() 支持上报自定义原因字符串
@section autotoc_md26 2024-03-26(rev185) 自定义事件支持/接口变动
@subsection autotoc_md27 1. 自定义事件
自定义事件的标识符要先在平台注册，然后在设备的 @ref Feature_EventSet 里打开支持。该能力的语法有更新。
上报自定义事件使用 @ref TciSetEventEx(EVENTPARAM *); @ref EVETNPARAM 结构增加了一个 <tt>char *x_event_name;</tt> 成员。对自定义事件，设置 @ref EVENTPARAM::event = @ref ECEVENT_USER_DEFINED; @ref EVENTPARAM::x_event_name 为 注册的事件tag
@subsection autotoc_md28 2. 接口变动
* @ref TciSetBackStore(const char *path, ECBUFFERHINT hint) 的<tt>hint</tt>参数语义有变化
* 新增接口 @ref TciGetSdkState() 可以返回SDK内部模块运行状态。用于低功耗设备是否进入休眠的辅助判断。不能代替 @ref STATUS_IDLE
@section autotoc_md29 2023-11-28 (rev171) 多呼叫键支持及带屏IPC的屏幕配置
@subsection autotoc_md30 1. 多呼叫键
<span style="strike">新增事件类型 @ref ECEVENT_CALL2(门铃事件 @ref ECEVENT_DOORBELL(仍可用) 倾向于改名为呼叫事件 @ref ECEVENT_CALL ), 用于第二个按键的呼叫。其它逻辑不变</span> – 2025/6/20
@subsection autotoc_md31 2. 屏幕配置
新增指令 @ref TCI_CMD_SET_SCREEN_DISPLAY / @ref TCI_CMD_GET_SCREEN_DISPLAY, 设备有 @ref Feature_Screen 能力时必须支持
@section autotoc_md32 2023-10-30(rev166) 多(>2)通道设备支持
* 设备
在 @ref Feature_MultiChannels 能力上报通道数（例如3目画中画为 <tt>3-composed</tt>），这一规则不变。
* App
因为p2p连接上的逻辑通道数有限，新的SDK支持在同一个逻辑通道上传输多路视频/音频数据。在发送请求视频的命令(TCI_CMD_VIDEOSTART=0x1ff)时，参数 <tt>Tcis_AVStream</tt>中的不同<tt>channel</tt>可以共享相同的<tt>avIndex</tt>.
@icode{c}
typedef struct {
unsigned int avIndex; // avIndex
unsigned int channel; // Camera Index
} __PACKED__ Tcis_AVStream;
@endicode
相应的，实时帧头(<tt>FRAMEINFO_t</tt>)中的<tt>codec_id</tt>的高8位，同回放一样，用作区分不同的<tt>channel</tt>
@icode
typedef struct FRAMEINFO_t
{
/* >0时, 低8位为Media codec type defined in @ref ENUM_CODECID, 高8位为视频通道号
=0时，为 RTMSGHEAD_t 结构 */
unsigned short codec_id;
/* For video frame, is of ENUM_FRAMEFLAG.
* for Audio Frame: flags = (samplerate << 2) | (databits << 1) | (channel)
* @ref audio_sample_fmt "音频采样格式" */
unsigned char flags;
unsigned char cam_index; // 0 (>0 may be used in future)
unsigned char rt_flags; // 如果是视频帧, bit0为是否在录像的标志位
unsigned char seq_no[3]; // 1~0xffffff. sequency number for frame, used internally by sdk to detect frame loss.
unsigned int frame_size; // Size of frame
unsigned int timestamp; // Timestamp of the frame, in milliseconds
} FRAMEINFO_t;
@endicode
<span style="color:red">旧的2路的画中画设备不支持共用**逻辑传输通路** avIndex，App需要对此作兼容性处理：或者只在>2路的设备上使用共用**通路**，或者在SDK 166以上共用。
平台
SDK上报给平台的 category 为基类型(例如ipc)，在 abilities 中上报 MultiChannels 表达设备的通道数。
以前画中画设备上报的category的 ipc-2ch的表示作为旧值保留，新的SDK采用 category + abilities::MultiChannels 的方式表达。
TCIC_RECORD_PLAY_START 命令的参数中的 Param 成员以前未使用，现在增加如下含义:
单文件模式用于事件回放。
设备端在放完事件录像后，调用 TciSendPbEndOfEvent() 向App发送 RTM_END_OF_EVENT 通知。 App可能会用此通知来给出提示或更新UI。(2023/10/19)
能力 UDF 用于方便第三方App开发者一次性取回(在App获取能力集时)设备能力。App的SDK 要透传该描述给应用
能力 ExtFlags 增加标志描述，用于对SD卡录像列表中的事件类型兼容处理
新增服务能力描述 Profile, 用于描述或限定设备支持的服务集合
Timer 属性，用于给报警音加时间控制庭院灯功能可视为在普通白光灯功能上加上强度控制、定时等功能。其基本工作模式(关、常开、自动)的控制方式与普通白光灯一样。
Dim,Timer增加 TCOPT_BACKSTORE_SAVEDAYS 选项，控制后备存储文件保存天数 增加 TCOPT_MAX_DATAFILE_SIZE 选项，控制云存文件大小
mfocus 值。表示设备支持手动调焦短按时调焦发送 TCI_CMD_PTZ_SHORT_COMMAND, 参数结构 Tcis_PtzShortCmd 结构增加 focus成员·
新增停车监控功能总开关指令 TCI_CMD_SET_PARKING_MONITOR / TCI_CMD_GET_PARKING_MONITOR . 影响以下子功能:
G-Sensor 为scene 时，场景变量Tcis_GsensorSetting::scene 不再取 GSENSOR_SCENE_PARKING(1)
统一一下符号和名字。参见 Resolutions
"tumble". 设备端应该在 Cap-AI 里上报.检测的区域设置复用移动侦测区域设置结构 Tcis_SetMotionDetect, 但作两处与旧结构兼容的调整。
调整前：
调整后：
Tcis_SetMotionDetect::flags 侦测区域表示标志
"parking-mon"LocInPic属性BirdFeeder 用于喂鸟器设备与App之间，以及App与App之间缺省一种呼叫状态同步机制，可能会导致以下现象：
为了有更好的用户体验，增加以下机制：
新增指令用于控制提示音状态 TCI_CMD_SET_VOICE_PROMPT_STATUS / TCI_CMD_GET_VOICE_PROMPT_STATUS
要支持本功能，需要在能力 ExtInstructions 能力里包含 voice-prompt
停车震动检测通过g-sensor实现，配置接口也放利用g-sensor现有命令 TCI_CMD_SET_GSENSOR / TCI_CMD_GET_GSENSOR, 但请求和返回参数作如下变动。
以前没有请求参数，现在使用参数 Tcis_GetGsensorReq, 使用scene来区分检测场景（行车还是停车）
设置时的参数和请求时的应答采用以下结构
当有多个用户发起对讲请求时，只有一个用户能被允许。为此，将从sdk118开始增加 TCI_CMD_START_TALK(=0x0332) 指令用于代替无返回的 TCI_CMD_SPEAKERSTART(0x350)。 二者有相同的请求参数.
当对讲不被允许时，本指令返回状态码 ，否则返回0
sdk118前的设备不支持 TCI_CMD_START_TALK , 将会返回状态码 TCI_E_UNSUPPORTED_CMD(3)，APP要继续发送旧的TCI_CMD_SPEAKERSTART(0x350) 命令
设备在 TciCB::get_state 回调里，对 "version"查询返回一个 json 数组格式的字符串。数组从第一个元素开始，分别对应 主版本号，MCU1版本，MCU2版本, ...
例如，设备有一个主控和一个MCU，主控程序版本为1.0.2.8, MCU程序版本为1.0.0.2，上报格式为：
对多版本设备，布署到平台的固件包需要指定适配哪一个CPU/MCU。
假如设备在 TciCB::get_info 回调里返回的 firmware_id 为 "TG_LPIPC_001",
| 固件标识 | 升级包内容 |
|---|---|
| TG_LPIPC_001 | 包含所有cpu/mcu的完整升级包 |
| TG_LPIPC_001.0 | 仅包含主控的固件 |
| TG_LPIPC_001.1 | mcu1的升级包 |
增加 EventSet 能力项用于描述额外启用或禁止的事件集
新增通用运行时状态查询指令 TCI_CMD_GET_RUNTIME_STATE 。目前用于查询设备当前是否在录像。
设备端不支持该指令返回 TCI_E_UNSUPPORTED_CMD, 不支持指定的状态返回 TCI_E_INVALID_PARAM 。
在实时**视频帧**的帧头第5个字节的最低位，会用作是否在录像的标志
新增通用指令用于设置设备端提示音。设置操作类似 TCI_CMD_SET_ALARMTONE, 在设置前要调用 TCI_CMD_GET_ALARMTONE_CAP 查询设备端支持的音频格式。忽略查询结果中的 Tcis_GetAlarmToneCap_Resp::idAlarmTone
objects成员表示购买服务允许检测的对象要支持巡航，SupportPTZ 需要包含 Cruise 和 PresetPos 属性。
APP 调用：
isKeyFrame，对音频应固定为0。现更名为 uFrameFlags, 当数据为音频时，为音频采样格式，取值见 音频采样格式常数实时和回放的声音包头 FRAMEINFO_t 的第3个字节，云录像帧头McFrameTransformHeader(网络字节顺序)的第4个字节，当帧内容为声音时，取值参见 音频采样格式
cry) 类型ECEVENT_CRY(参考 ECEVENT )"no-media" 取值，用于表示设备不支持(SD卡)本地录像LampCam类型VertOnly HorzOnly)以表达仅支持水平或垂直方向控制AEC 从属性，表示可以支持全双工对讲设备能力描述 增加了 多(扩展)属性的表达和解析 说明，APP端要注意看一下。
RotateVideo 新增取值 CW90/CW180/CW270, 用于描述设备端的图像旋转角度，需要APP做反向旋转
以前sdk通过 TciCB::on_status()回调发出 STATUS_IDLE 通知前，会停止p2p/云存等相关服务。现改为如下逻辑：
如果应用层返回0，sdk内部会进入服务清理过程
微功耗设备的表述有歧议，在本文中用"手动控制电源模式"代替
BatteryCam 增加可取值 Solar
AI服务的请求逻辑现在内置到sdk，应用只需要处理移动侦测事件即可。不要再联接原来的libaiclient.a。
能力 Cap-AI ，对硬件追踪类能力，增加 bit2-特写功能标志
"LockBell"Cap-Zoom 增加 "no-shortcut"属性，用来隐藏"远景"/"近景"按钮
新增指令 TCI_CMD_GET_AWAKE_TIME TCI_CMD_SET_AWAKE_TIME ，用来获取和设置低功能设备的主动唤醒时间段
要支持此功能，需要 BatteryCam 能力有 timed-wakeup属性
Reset ，参见 SupportPTZ在实时和回放流中，每帧数据有一个帧头 FRAMEINFO_t , 帧数据类型 FRAMEINFO_t::codec_id 的有效值大于0.
通过在传输流中插入的类型(codec_id)为0的帧，来对流打标签，或通知APP与流相关的事件。codec_id为0时对应的帧头结构为 RTMSGHEAD_t ，其中包含流事件类型 RTMTYPE 和事件对应的参数。
在设备端，使用API TciSendLiveMessage() 和 TciSendPbMessage() ，或者针对事件类型专门定义的宏 例如 TciSendLiveMsg_ReachPsp() / TciSendPbSyncFrame() / 等 ..., 分别在实时流(视频)和回放流中插入事件帧。
详见 RTMSGHEAD_t
设置云台位置命令 TCI_CMD_SET_PTZ_POS 的请求参数 Tcis_SetPtzPosReq ，之前只含有位置信息 PtzPos 。
现修改如下
当调用预置位时，要传递预置位号。这样云台转到位后，可以流事件时以此编号向APP发送 RTM_REACH_PSP 通知。
能力 ExtInstructions 增加 termper和humidity，分别对应温度和湿度传感器
**设备端**：温度/湿度报警需要携带报警时的当前温/湿度值，这个额外参数是一个json格式的字符串，可以使用 MKEVTDATA_Temerature()/MKEVTDATA_Humidity() 来生成。要调用 TciSendEventEx(EVENTPARAM *) 来上报，并将 EVENTPARAM::evt_data 设置为这个字符串。
增加下面两条指令，用于单独禁用或全能报警事件。事件是否有效要同时参考本命令中状态和布/撤防设置。
要支持这两条命令，设备需要在Cap-Defence 能力里报告报警源可以分开布撤防("0xNNN[:0xMMM]" 或 ["0xNNN", "0xMMM"]格式)
WatchPos 选项WatchPos选项时要支持指令: TCI_CMD_SET_WATCHPOS / TCI_CMD_GET_WATCHPOS设备自身具有的AI能力，默认要通过购买服务来开启。现增加新的标志，来描述默认开启（不需要购买服务）的情形。Cap-AI
设备如果支持延时摄影，RecordConf 的返回内容中要包含time-lapse
行车记录仪要支持停车监控能力，需要在 G-Sensor 里返回 "scene"
能力 MD-Capabilities 要有 VisibleZone
能力 Cap-Zoom , 变焦设备(Cap-Zoom="times:xxx")变倍能力描述
双目摄像机镜头切换时在流中插入标志帧 双目摄像机(Cap-Zoom="2lenses")的控制
能力 Cap-Defence
多通道设备，每个通道可能有不一样的能力。例如有的通道有云台，其余通道没有。针对这种情况，需要对每个通道单独描述。此时的描述内容是一个数组。
为简化解析，在今后的能力 描述中，引入 json来表示复杂和多通道的能力。
APP要继续兼容之前的格式。
MultiChannels属性中返回。固件在能力描述中返回一个json数组，数组的第n项对应通道n的属性。对单通道设备，或者所有通道具有相同配置，设备可以返回一个字符串。
举例 : 对一个2通道的设备的 DoubleLight 属性，固件返回 "Yes"意味两个通道都有白光灯。等同于 ["Yes", "Yes"]。如果返回 ["Yes", "No"]则表示仅在第一个通道上有白光灯。
Cap-AI能力“bd,fd,mt”可以返回数组["bd", "fd", "mt"]。此部分见具体能力说明。现有指令集，部分带有channel参数，部分没有（不需要或遗漏）。对遗漏的指令，目前APP和设备可作合理推导。
例如 TCI_CMD_SET_PTZ_POS 指令没有channel参数，对画中画设备不能指定转哪一个镜头对应的云台。但因为实际设备只有一个云台，实际操作就可以忽略channel。
今后有新的设备形态加入需要扩充指令内容时再另行规定。
直连模式下在原 Tcis_ExPassWordReq 结构后追加时区字符串。字符串要以NULL结尾。
SD回放中，用户在APP上重新定位，设备收到PLAY_START指令跳到新的文件位置开始发送。此时网络上还有先前已经发送但APP尚未收到的帧。网络延时越高，中途帧越多，这些帧中还可能有自动跳到下一个文件时发的时间同步帧。如果APP不能区分middle-way帧和新的开始播放的帧，绘制时间轴时可能出现跳动（从新定位点跳回旧播放位置又再次返回新定位点）。为了区分新旧位置的帧。现对时间同步帧作如下规定：
frame_size和codec_id都为0，timestamp为下一帧的UTC时间flags设为1，否则为0回放中发生时间跳转 调用 TciSendPbSyncFrame ( handle, utc_ime, is_response_to_PLAY_START) 发送时间同步帧。
如果是响应用户操作，将 is_response_to_PLAY_START设为1，否则设为0
| 能力名 | 能力说明 | 取值 | 取值说明 | 相关指令 |
|---|---|---|---|---|
| DayNight | 是否支持日夜切换 | No | 不支持 | |
| Yes | 支持。独立操控 | TCI_CMD_GET_DAYNIGHT_REQ TCI_CMD_SET_DAYNIGHT_REQ | ||
| Auto | 支持。与白光灯联动 | TCI_CMD_GET_DOUBLELIGHT_REQ TCI_CMD_SET_DOUBLELIGHT_REQ | ||
| ExtInstructions | 支持的扩展指令 | ... ipconfig | TCI_CMD_SET_IPCONFIG TCI_CMD_GET_IPCONFIG |
移动侦测区域现在增加多边形区域的描述。考虑到设备并不能直接解析多边形，实现上APP会用多很小的矩形来逼近多边形，同时要求设备保存多边形的表示。
Tcis_SetMotionDetect
准备一个 Tcis_SetMotionDetect 的例子:
新增指令:
App要先调用 TCI_CMD_GET_OSD_REQ 命令，从设备获取OSD能力和当前osd设置
使用 TCI_CMD_SET_OSD_REQ 可以一次设置/修改/删除一条或多条OSD条目
2021-04-23 获取预置位的请求结构 的 flags 取值作如下扩展定义:
应答结构体 Tcis_GetPresetPointsResp 作如下调整：
新增指令
之前的变倍能力描述方式在步数上的描述太过粗略，本次修改提供一种更精细的步数描述方式。
变焦设备(Cap-Zoom=’times:xxx‘)变倍能力描述
本接口仅用于华视安邦定制设备，不需要设备能力协商
变焦设备(Cap-Zoom="times:xxx")操作控制指令说明
有变焦功能的双目摄像机，其设备能力描述为“双目”和”变焦“摄像机能力的组合（ Cap-Zoom)。操作逻辑和新增指令见 双目+变焦摄像机的控制。
【远景】【近景】按钮对应的位置 PtzPos 不再是仅”双目“设备的 {-1.0, -1.0, 0.0} 和 {-1.0, -1.0, 1.0},而是要通过 TCI_CMD_GET_PSP 获取。
预置位有两种表示方式：
一个预置位可以对应云台的某个朝向、镜头的某个变焦倍数，或二者组合。 如果仅包含变焦信息，flags 应设置 PSP_F_ZOOMONLY。
对仅包含变焦信息的预置位，应该放在数组的最前面，并按变焦倍数从小到大的顺序排列。这样APP容易根据排序决定UI。
例如，对双目+变焦摄像机，返回两个预置位（同时设置PSP_F_ZOOMONLY和PSP_F_SHORTCUT标志），第一个位置将对应[近景]按钮， 第二个对应[远景]按扭。或者，对返回多个预置位的情形，APP在一个滑动轴上，按变倍值单向排列并对每个预置位置描一个驻点。
| 能力名 | 能力说明 | 取值 | 取值说明 |
|---|---|---|---|
| DeviceType | 设备类型 | "IPC" | 普通网络摄像机 |
| "DriveRec" | 行车记录仪 | ||
| "DoorBell" | 门铃 |
门铃事件细分为以下类型：
| 事件 | 标签(平台和APP) | 常数(设备端) | O/M |
|---|---|---|---|
| 人经过 | passby | ECEVENT_PASSBY | O |
| 人停留 | stay | ECEVENT_STAY | O |
| 按下门铃 | doorbell | ECEVENT_DOORBELL | M |
| 未接 | missed | ||
| 接听 | answered | ||
| 拒接 | rejected |
O - Optinal M - Mandatory
前3个事件需要固件调用接口 TciSetEventEx()/TciSetEventHandleOver2()/... 通知sdk。后3个事件由sdk内部产生。这些事件都会通知到平台。
门铃呼叫最终会被接听、拒接或未接。接听或拒接由APP端使用 TCI_CMD_ANSWERTOCALL 命令显式通知设备端。
<2021-03-10(SDK Rev.68) > 中的 第3和第4小节作废
能力名 Microphone 的取值描述更新如下：
| 能力名 | 能力说明 | 取值 | 取值说明 | 相关指令 |
|---|---|---|---|---|
| Microphone | 是否有麦克风 | No | 不支持 | |
| Yes | 支持 | |||
| Muteable | 支持静音 | TCI_CMD_SET_MICROPHONE_REQ TCI_CMD_GET_MICROPHONE_REQ | ||
| TuneVol | 音量可调 | TCI_CMD_SET_MICROPHONE_REQ TCI_CMD_GET_MICROPHONE_REQ TCI_CMD_SET_MIC_LEVEL TCI_CMD_GET_MIC_LEVEL |
关闭麦克风后：
第2点需要固件处理， 其余情形SDK内部会处理。
此处码流的概念，定义为某种质量的图像输出。选择一种码流，即是选择一种不同的图像质量（分辨率/fps/bitrate等的不同）。
双码流设备支持同时输出两种不同质量的码流。
三码流设备可以输出3种不同质量的码流，但不一定有能力同时输出。当不能同时输出时，靠切换某一路码流的质量实现。
本说明代替 2020-12-02 新增图像分辨率 里
| 能力名 | 能力说明 | 取值 |
|---|---|---|
| Resolutions | 设备支持的图像质量组合。默认 0HD+1SD | 见表后 |
质量组合 ::=质量描述项1[+质量描述项2[+质量描述项3...]]
质量描述项按质量从高到低的顺序，用‘’+'`连接.
质量描述项 ::= {码流编号}{质量描述符}
码流编号 ::= 0|1|2|...，低的编号对应更高的分辨率
质量描述符::= SD|HD|FHD|UHD|...
质量描述符不一定限于分辨率。例如可能是HD12fps，HD30fps，Prefer等任意字符串。其意义由固件自行解释，并与APP约定在UI上提示的方式。
质量描述项举例：
0HD: 表示码流0上的高清图像1SD: 表示码流1上的标清图像质量组合举例:
0HD+1SD: 设备只支持双码流，在码流0上输出高清，码流1上输出标清。这个是默认行为
0FHD+1HD+2SD: 设备支持3路码流同时编码, 分别在码流0/1/2上输出全高清/高清/标清图像
0FHD+1HD+1SD: 设备支持3种质量，但同时只能编码两路图像。它的码流0固定为FHD，码流1可以为SD或HD。
当前的码流选择逻辑在APP与SDK内部实现，不需要固件的应用层参与
TCI_CMD_SETSTREAMCTRL_REQ 命令，在命令请求里携带质量参数quality。取值TCIC_QUALITY_MAX(1)或TCIC_QUALITY_MIN(5), 分别对应设备的高分辨率(0)和低分辨率码流(1)修改后的逻辑，固件逻辑见 【1.3.2.4 设备行为】。APP与SDK端【1.3.2.1~1.3.2.3小节】使用之前同样的命令和quality 质量常数 参数，但quality的取值规则有调整。
为了兼容旧实现，保留原有的图像质量常数定义。
暂时最多支持5种质量。质量常数与码流的对应关系，要看设备的Resolutions能力。
使用索引来引用质量描述项是最简单的。但为了兼容，需要使用一种更复杂的映射方式。如下。
下表中的数字N，表示设备支持N种质量时，其对应的质量常数会被用来标识N种质量中的一种。
| 质量常数 | 含义 | 设备支持的码流(质量)数 | |||
|---|---|---|---|---|---|
| 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时，默认请求的高清图像。
TCI_CMD_SETSTREAMCTRL_REQ 命令的 quality参数中传入 TCIC_QUALITY_MIN。TCIC_QUALITY_MIN对应的质量描述项为1SD(码流为1，支持HD和SD两种质量)。SDK调用 TciCB::switch_quality(0, 1, "SD")，固件知道当前质量为高清，因此将码流1的质量设为标清。新增一个杂项("Misc")能力描述，用于一些很琐屑的功能开关。
| 名称 | 解释 | 取值 | 说明 |
|---|---|---|---|
| Misc | 杂项。整数值的16进制的字符串表示，以"0x"开始，例如"0x1234"。,该整数值的每一位表示一个功能开关 | bit0 | 禁止SD卡录像时录制声音 |
SD卡录像设置里增加一个是否录声音的选项。
新增 TciSetEventEx() 接口，允许上报事件附带参数。例如：行车记录仪的碰撞事件带严重程度参数。当事件严重时，会给关连手机发送短信。
sd容量应答结构中的 total(总容量) 增加只读状态定义
| Key | Value |
|---|---|
| "Extlnstructions" | 支持的指令列表。多条指令间用分号隔开:
|
可代替 TCI_CMD_SET_ENABLE_BT/ TCI_CMD_GET_ENABLE_BT
本更新代替 《2020-09-23 低功耗产品在APP进入设置页面时的约定》
原来的设计：
APP在进入设置页面时发送 TCI_CMD_GET_MAX_AWAKE_TIME 。在设置页面没有任何操作一段时间(例如30")后，设备进入休眠。
现在更新为：
APP在结束实时流和SD卡回放，进入其它操作界面(云回放或设置页面)时， 发送 TCI_CMD_ENTER_SETUP，退出界面时发送 TCI_CMD_LEAVE_SETUP.
固件在调用 TciStart() 后，在 on_status() 回调里收到 STATUS_IDLE 进入休眠状态。在调用TciStart()前，自行决定何时休眠。不用再判断是否在回放和设置无操作倒计时等。
更多说明参见sdk文档 《低功耗设备开发》
[Depracated] by Resolutions 2020-01-26
| 能力名 | 能力说明 | 取值 | 取值说明 | 相关指令 |
|---|---|---|---|---|
| Resolutions | 设备的主/辅码流图像分辨率 | HD+SD | 高清+标清 | |
| FHD+SD | 全高清+标清 | |||
| UHD+SD | 超高清+标清 |
用户可以修改直连模式下的默认口令
该指令在sdk内部处理，固件不需要响应。
TciCB::on_status() 新增 STATUS_SDER 通知，并且现在要有返回值。ECEVENT_POWEROFF/ECEVENT_POWERON事件被 ECEVENT_PARK/ECEVENT_SETOFF事件代替，设备在响应 STATUS_SDER 通知时上传。TciSetEvent2()TciSetEventHandleOver2()EyeCloudReportError()TciUduBegin()去掉事件时间和图片参数| 能力名 | 能力说明 | 取值 | 取值说明 | 相关指令 |
|---|---|---|---|---|
| AlarmLight | 是否支持报警灯 | No | 不支持 | TCI_CMD_SET_ALARMLIGHT TCI_CMD_GET_ALARMLIGHT |
| Yes | 支持 | |||
| PIR | 是否支持PIR(灵敏度设置) | No | 不支持 | TCI_CMD_SET_PIR TCI_CMD_GET_PIR |
| Yes | 支持 |
进入设置面时，APP向设备查询唤醒后工作时长（或称唤醒后录像时长）(0x042C) . 【查看定义】
设备以此命令作为进入设置状态的标志，内部设置新的休眠倒计时初值（例如30“内无操作则设备进入休眠）
参见 录像与回放
| 能力名 | 能力说明 | 取值 | 取值说明 | 相关指令 |
|---|---|---|---|---|
| G- Sensor | 是否支持g-sensor | No | 不支持(非行车记录仪默认不支持) | |
| Yes | 支持(行车记录仪默认支持) | |||
| RotateVideo | 是否支持画面翻转 | No | 不支持 | |
| Yes | 支持(默认) |
app在请求画中画主画面时，调用GET命令向设备查询当前主画面设置。
app在切换主画面时，向设备SET命令
TciCB增加成员 trans_stat() 回调
进入休眠需要先与休眠服务器建立连接认证，并在主控下电后一直保持连接并发送心跳。
TciPrepareHiberation() 适用于主控建立连接，主控下电后网络模块继承该连接属性的情形。
TciPrepareAuthString()适用于网络模块建立连接的情形。
| 能力名 | 能力说明 | 取值 | 取值说明 | 相关指令 |
|---|---|---|---|---|
| Gps | 是否支持Gps | No | 不支持 | |
| Yes | 支持 |
针对低功耗摄像机增加如下接口
低功耗摄像在进入休眠要检查当前是否有人操作。判断【没人操作】要满足以下条件：
其中第一条，访问实时流的操作在SDK内部处理了，应用层并不知道。现对 on_status 回调增加一个新的事件取值： STATUS_STREAMING
设置SD卡录像模式(TCI_CMD_SETRECORD_REQ)的请求结构做如下更改：
仅电池摄像机使用
在超出此时间后，设备重新进入休眠状态
| Key | Value |
|---|---|
| "ExtInstructions" | 支持的指令列表。多条指令间用分号隔开:
|
回放控制命令TCI_CMD_RECORD_PLAYCONTROL(0x031A)请求体结构如下：
command取值 为ENUM_PLAYCONTROL:
现启用TCIC_RECORD_PLAY_FORWARD(0x04)值作为倍速插放控制命令。相应的Param为速度倍数:
0,1: 1倍速；2: 2倍速; ...
ExtInstructions 增加 pbrate
| Key | Value |
|---|---|
| "ExtInstructions" | 支持的指令列表。多条指令间用分号隔开:
|
增加alarm_bell
| Key | Value |
|---|---|
| "ExtInstructions" | 支持的指令列表。多条指令间用分号隔开:
|
"ExtInstructions" 包含 "alarm-bell"时，设备支持以下指令：
| Key | Value |
|---|---|
| "ExtInstructions" | 支持的指令列表。多条指令间用分号隔开:
|
APP向设备查询Features时，设备使用”DeviceStatus“名称在”setting“里向APP返回当前状态。
下列命令设备端当前实现在成功时返回1，失败返回0.
Feature和setting里的"Buzzer"更名为"AlertSound"
APP：为兼容旧设备，取settings时, 以"Buzzer"和"AlertSound"两个名字查询设备状态，使用有返回的那个作为当前设置
设备在以下情形，向app报告下一帧数据的真实时间[1]
PLAY_START命令，执行了文件定位，开始发送数据时报告方式为，设备向app发送一个帧, codec_id和frame_size都为0, timestamp 为下一个音频或视频帧的真实utc时间
[1] 设备端使用 TciSendPbFrame(handle, (TCMIDIA)0, NULL, 0, timestamp, 0) 调用来发送时间同步帧
在LISTEVENT_REQ命令返回的列表项，SAvEvent的event域取值定义如下(在ec_const.h里定义):
目前的协议，错误返回方式不一致或缺失。有的错误域在命令相关的应答数据结构里， 有的应答结构没有定义错误域。如果设备不支持某条命令，没有相应的报错机制。 下面定义一种与当前协议兼容的错误应答机制：
其中，
| Field | Note |
|---|---|
| 1 | 专用于错误应答的命令码 |
| 8 | 数据长度 |
| cmd | 从app收到命令请求码 |
| error | 通用错误码(见下表) |
| Value | Note |
|---|---|
| 0 | 成功 |
| 1 | 命令处理中，请等待 |
| 2 | 包头错（不支持的协议头） – 这个错误码保留以后使用 |
| 3 | 命令不支持 |
| 4 | 参数错误 |
| 5 | 资源不足 |
| 6 | 内部错误 |
当前的命令码，如果命令有响应的，都同时定义了REQ和RESP，并且满足
今后新的命令都遵循这两条规则，响应码不再单独定义。
由于历史原因，存在少数几条值为奇数的请求码，但这些命令都不需要响应，所以对APP不影响。设备端会对这几条指令作特殊处理。
| 命令范围 | 说明 |
|---|---|
| 1 | 错误应答 |
| 0x180~0x400 | IPC命令 |
| 0x8000~0x8100 | IPC命令 |
| 0x1000~0x1100 | IPC |
| 其余 | 保留不要使用 |
1.12.0