2025-06-17(Rev345) 通用状态应答/呼入相关接口变动
1. 通用状态应答扩展
之前规定的通用错误应答只能携带一个4字节的错误状态码。现在约定，可以在原来应答结构后扩展应用层数据:
|--------------------------------|
| 1 | 错误应答命令码(4 Bytes)
|--------------------------------|
| 8 + N | 长度(4 Bytes)
|--------------------------------|
| cmd | 命令码(4 Bytes)
|--------------------------------|
| error | 错误码(4 Bytes)
|--------------------------------|
| N-Bytes | 扩展数据(N-bytes)
这种扩展机制并不作为一种普遍的应答数据传输方式使用，而是用于 “命令最初只定义了通用应答，但后来增加了应答数据并且需要与之前保持兼容” 这一特殊场景。当预先知道命令应答有数据时，应使用特定命令应答结构。
通过此方式发送数据，命令定义中必须要有明确约定。
2. 呼入相关接口变动
2025-02-14(Rev323) 选择卡回放通道
更新了以下命令和结构的描述，以支持选择回放
要支持选择回放，需要在能力 ExtInstructions 里加入 selchn
2024-10-31(Rev312) 获取和传递配网参数
2024-09-19(Rev220) 在P2P连接上发送通知
设备可以使用 TciSendRtMsg() 在p2p连接的命令通道上向App推送数据(Rev85开始已经支持在视频流中通过 TciSendLiveMessage() 插入通知. 参见 流事件)。 此接口的好处是只要有连接就可以发送。
设备使用命令值 2 向App发送数据包。数据包有一个固定长度的包头
unsigned int data1
消息类型相关数据1
unsigned int type
消息类型。 RTMTYPE
unsigned int data2
消息类型相关数据2
如果还有额外数据，紧接在这个头之后。
这个结构携带的有效数据与 TciSendLiveMessage() 可以携带的有效数据是一样的。也就是说通知可以在两个通道上发送，最终选择取决于消息类型是不是与视频流强耦合。参考 RTMTYPE, 里面有说明。
应用使用 RTM_USER 类型来发送自定义数据。
2024-06-28(Rev207)
1. 设备无视频的描述
Profile 增加 NoVideo 键
无音频使用
2. 对2024-05-14(rev193)的更新
查看 2024-05-14(rev193)
2.1 添加能力描述
2.2 结构更新
能耗模式中的定时器结构 TIMEPLAN 增加 enabled 开关
2024-06-11(Rev204) 喂食器&事件替换
1. 喂食器
1.1 配置和命令
新增的P2P命令接口定义参见头文件 TgCloudCmd_sp.h 的 喂食器 部分。
1.2 喂食事件及其参数
喂食记录以自定义事件上报,:
"x:feed" 自动喂食"x:feedm" 手动喂食
参数格式：
事件上报请求的数据举例:
{
"uuid":"1801057CIF4I","ossid":"11","ossid_video":"11","is_pay":0,
"tag":"x:feed",
"start_time":1717764429,"end_time":1717764429,"image_path":"2024/06/07/20/47-09.jpg",
"data":{"is_manually":1,"n_serving":5},
"user_id":"30","sdkver":203
}
1.3 设备上报喂食事件
SDK 为上报喂食事件提供了一个专用封装 TcuSendFeedingEvent() 以简化调用。这个接口申明在 tgutil.h 中。
如果不能满足需要可以按下例重新封装。
{
return snprintf(obuf, size, "{\"n_serving\":%d}", nServings);
}
{
char evt_data[128];
memset(&evtp, 0, sizeof(evtp));
return TciSendEventEx(&evtp);
}
int MKEVTDATA_Feeding(int nServings, char *obuf, int size)
生成喂食事件的数据
int TcuSendFeedingEvent(int isManually, int nServing, void *pic, int pic_len)
上报喂食事件
#define EPF_RELEASE_PIC_IN_SDK
由sdk释放图片内存
@ ECEVENT_USER_DEFINED
自定义事件。使用方式见文档 EventSet, Cap-AI
ECEVENT event
事件类型. 参数(evt_data)见事件的说明
char * jpg_pic
图片指针。没有图片时为NULL
int cbSize
本结构大小, =sizeof(EVENTPARAM)。调用者要设置此成员。用于以后结构变化
const char * x_event_name
[2024/3/25添加] 如果event为 ECEVENT_USER_DEFINED, 这里为自定义事件名.
int status
1:事件开始; 0:事件结束(暂不支持)
2. 事件替换
新的事件覆盖旧事件需要在调用 TciSetEventEx() 时显性指定，平台不支持仅根据时间戳去自动覆盖。为此, EVENTPARAM 中增加两个参数 EVENTPARAM::evtToReplace/ EVENTPARAM::tPrevEvent, 分别给出旧事件的类型和发生时间。如果没有要替换的动作，这两个参数要设为0.
2024-05-14(rev193)SD卡相关&信号强度上报&低功耗工作模式
下面的内容在 2024-06-28(Rev207) 中有订正
1.获取录像日期
新增指令 TCI_CMD_LIST_RECORDDAYS, 用于获取SD卡上存在录像的日期。返回 Tcis_DaysList 包含一个日期数组
2.低功耗设备的耗能工作模式
增加指令 TCI_CMD_SET_POWER_STRATEGY/ TCI_CMD_GET_POWER_STRATEGY, 用于管理电源工作模式。本指令代替 TCI_CMD_SET_MAX_AWAKE_TIME/ TCI_CMD_GET_MAX_AWAKE_TIME
3. 录像列表的修改
TCI_CMD_LISTEVENT_REQ 的应答结构 Tcis_ExListEventResp 作如下调整。
旧:
unsigned char reserved[1];
unsigned char index
ignored
unsigned int channel
Camera Index: 0~
unsigned char endflag
为1是表示是最后一个包
unsigned char count
本包包含中的事件数
新：
union {
};
unsigned char estype
0:录像记录为SAvExEvent数组; 1:录像记录为SAvEvent2数组
当estype为1时，返回带事件时间戳的录像条目。App根据estype的值来兼容旧的设备。
4. 新增SD卡状态: 正在初始化
TCI_CMD_GET_EXTERNAL_STORAGE_REQ 命令的应答结构 Tcis_SDCapResp::total 增加了一个 “正在初始化" 的状态表示
@subsection autotoc_md23 5. 上报信号强度(接口变动)
@ref TciSetWakeupReason() 增加了一个参数，用于上传当前 Wifi/4G信号强度
@section autotoc_md24 2024-04-17(rev190) 4G能力描述和接口变动
* @ref Feature_4G 能力增加 <tt>“simtype" 键用于描述SIM卡类型
2024-03-26(rev185) 自定义事件支持/接口变动
1. 自定义事件
自定义事件的标识符要先在平台注册，然后在设备的 EventSet 里打开支持。该能力的语法有更新。
上报自定义事件使用 TciSetEventEx(EVENTPARAM *); EVETNPARAM 结构增加了一个 char *x_event_name; 成员。对自定义事件，设置 EVENTPARAM::event = ECEVENT_USER_DEFINED; EVENTPARAM::x_event_name 为 注册的事件tag
2. 接口变动
2023-11-28 (rev171) 多呼叫键支持及带屏IPC的屏幕配置
1. 多呼叫键
新增事件类型 ECEVENT_CALL2(门铃事件 ECEVENT_DOORBELL(仍可用) 倾向于改名为呼叫事件 ECEVENT_CALL ), 用于第二个按键的呼叫。其它逻辑不变
2. 屏幕配置
新增指令 TCI_CMD_SET_SCREEN_DISPLAY/ TCI_CMD_GET_SCREEN_DISPLAY, 设备有 Screen 能力时必须支持
2023-10-30(rev166) 多(>2)通道设备支持
设备
在 MultiChannels 能力上报通道数（例如3目画中画为 3-composed），这一规则不变。
App
因为p2p连接上的逻辑通道数有限，新的SDK支持在同一个逻辑通道上传输多路视频/音频数据。在发送请求视频的命令(TCI_CMD_VIDEOSTART=0x1ff)时，参数 Tcis_AVStream中的不同channel可以共享相同的avIndex.
typedef struct {
unsigned int avIndex;
unsigned int channel;
TCI_CMD_VIDEOSTART = 0x01FF, TCI_CMD_VIDEOSTOP = 0x02FF, TCI_CMD_AUDIOSTART = 0x0300,...
相应的，实时帧头(FRAMEINFO_t)中的codec_id的高8位，同回放一样，用作区分不同的channel
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;
旧的2路的画中画设备不支持共用**逻辑传输通路** avIndex，App需要对此作兼容性处理：或者只在>2路的设备上使用共用**通路**，或者在SDK 166以上共用。
平台
SDK上报给平台的 category 为基类型(例如ipc)，在 abilities 中上报 MultiChannels 表达设备的通道数。
以前画中画设备上报的category的 ipc-2ch的表示作为旧值保留，新的SDK采用 category + abilities::MultiChannels 的方式表达。
2023-10-14(rev164)
1. 回放接口参数更新
TCIC_RECORD_PLAY_START 命令的参数中的 Param 成员以前未使用，现在增加如下含义:
@ TCIC_RECORD_PLAY_START
开始回放session。这是回放过程收到的第一个命令.
单文件模式用于事件回放。
设备端在放完事件录像后，调用 TciSendPbEndOfEvent() 向App发送 RTM_END_OF_EVENT 通知。 App可能会用此通知来给出提示或更新UI。(2023/10/19)
2. 增加用户自定义能力 UDF
能力 UDF 用于方便第三方App开发者一次性取回(在App获取能力集时)设备能力。App的SDK 要透传该描述给应用
3. ExtFlags 能力
能力 ExtFlags 增加标志描述，用于对SD卡录像列表中的事件类型兼容处理
2023-08-17 (rev159)服务配置Profile
新增服务能力描述 Profile, 用于描述或限定设备支持的服务集合
2023-08-07 (rev158) 报警音定时功能
2022-12-22 (Rev140) 庭院灯
庭院灯功能可视为在普通白光灯功能上加上强度控制、定时等功能。其基本工作模式(关、常开、自动)的控制方式与普通白光灯一样。
- 在 DoubleLight 新增选项
Dim,Timer
- 新增通用定时任务配置指令 TCI_CMD_GET_TIMER_TASK/ TCI_CMD_SET_TIMER_TASK
2022-12-10 (Rev139) 云存和后备存储选项
增加 TCOPT_BACKSTORE_SAVEDAYS 选项，控制后备存储文件保存天数 增加 TCOPT_MAX_DATAFILE_SIZE 选项，控制云存文件大小
2022-10-30 手动调焦
2022-10-24 停车监控总开关/清晰度符号和显示名字
停车监控总开关
新增停车监控功能总开关指令 TCI_CMD_SET_PARKING_MONITOR / TCI_CMD_GET_PARKING_MONITOR . 影响以下子功能:
G-Sensor 取值'scene'时的用途有变化
G-Sensor 为scene 时，场景变量Tcis_GsensorSetting::scene 不再取 GSENSOR_SCENE_PARKING(1)
更新清晰度符号和对应的名字
统一一下符号和名字。参见 Resolutions
2022-10-11(Rev131) 摔倒检测
检测的区域设置复用移动侦测区域设置结构 Tcis_SetMotionDetect, 但作两处与旧结构兼容的调整。
调整前：
typedef struct Tcis_SetMotionDetect
{
unsigned int channel;
unsigned short enabled;
unsigned short flags;
unsigned int sensitivity;
unsigned short hasZone;
...
调整后：
typedef struct Tcis_SetMotionDetect
{
unsigned int channel;
unsigned short enabled;
unsigned short flags;
unsigned int sensitivity;
unsigned char hasZone;
unsigned char excludeZone;
...
Tcis_SetMotionDetect::flags 侦测区域表示标志
2022-09-23(Rev130) 停车监控更新
代替 2022-07-25(rev117) 停车震动检测
2022-08-16(rev125)云台图片内定位(或枪球联动)
2022-08-11(rev123)
2022-08-01(rev121)
接听应答和呼叫状态广播
设备与App之间，以及App与App之间缺省一种呼叫状态同步机制，可能会导致以下现象：
- 设备端已经产生未接事件，App还在等待用户操作
- 呼叫已经挂断，设备准备休眠，另一个用户还试图点接听
为了有更好的用户体验，增加以下机制：
- 接听时(命令 TCI_CMD_ANSWERTOCALL, Tcis_AnswerToCall::state = CALLSTATE_ANSWERED) 设备会返回状态码，告诉APP是否正常接听
- 呼叫状态变化时，会在视频流里通过 流事件 (RTMSGHEAD_t::type = RTM_UPDATE_CALL_STATE) 的方式通知当前连接
提示音开关
新增指令用于控制提示音状态 TCI_CMD_SET_VOICE_PROMPT_STATUS/ TCI_CMD_GET_VOICE_PROMPT_STATUS
要支持本功能，需要在能力 ExtInstructions 能力里包含 voice-prompt
2022-07-25 (rev117)
缩时录像
- 能力 RecordConf 要包含 ”time-lapse"
* 支持指令 @ref TCI_CMD_SET_TIMELAPSE_RECORD, @ref TCI_CMD_GET_TIMELAPSE_RECORD
@subsection parking_det_20220725 停车震动检测
<span style="color:red">deprecated</span> by <a href="#parking_det_2022_09_23">2022-09-23(Rev130)</a>
* 设备的 @ref Feature_G-Sensor 能力要为 “scene"
指令
停车震动检测通过g-sensor实现，配置接口也放利用g-sensor现有命令 TCI_CMD_SET_GSENSOR/ TCI_CMD_GET_GSENSOR, 但请求和返回参数作如下变动。
以前没有请求参数，现在使用参数 Tcis_GetGsensorReq, 使用scene来区分检测场景（行车还是停车）
};
int scene
场景 GSENSORSCENE 如果 G-Sensor 能力不为 "scene", 则 scene 只能为0.
设置时的参数和请求时的应答采用以下结构
};
int scene
场景 GSENSORSCENE 如果 G-Sensor 能力不为 "scene", 则 scene 只能为0.
int sensitivity
灵敏度: 0-关闭; 1-低; 2-中; 3-高
说明
对讲仲裁(通用) – for APP
当有多个用户发起对讲请求时，只有一个用户能被允许。为此，将从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) 命令
2022-07-12 多版本(rev116)
版本上报
设备在 TciCB::get_state 回调里，对 "version"查询返回一个 json 数组格式的字符串。数组从第一个元素开始，分别对应 主版本号，MCU1版本，MCU2版本, ...
例如，设备有一个主控和一个MCU，主控程序版本为1.0.2.8, MCU程序版本为1.0.0.2，上报格式为：
versions = ["01000208", "01000002"]
OTA升级时的 firmware_id
对多版本设备，布署到平台的固件包需要指定适配哪一个CPU/MCU。
假如设备在 TciCB::get_info 回调里返回的 firmware_id 为 "TG_LPIPC_001",
| 固件标识 | 升级包内容 |
| TG_LPIPC_001 | 包含所有cpu/mcu的完整升级包 |
| TG_LPIPC_001.0 | 仅包含主控的固件 |
| TG_LPIPC_001.1 | mcu1的升级包 |
2022-07-01 EventSet 能力和录像状态(rev112)
EventSet 能力
增加 EventSet 能力项用于描述额外启用或禁止的事件集
录像状态
状态查询
新增通用运行时状态查询指令 TCI_CMD_GET_RUNTIME_STATE 。目前用于查询设备当前是否在录像。
设备端不支持该指令返回 TCI_E_UNSUPPORTED_CMD, 不支持指定的状态返回 TCI_E_INVALID_PARAM 。
实时录像状态更新
在实时**视频帧**的帧头第5个字节的最低位，会用作是否在录像的标志
typedef struct FRAMEINFO_t
{
unsigned short codec_id;
unsigned char flags;
unsigned char cam_index;
unsigned char rt_flags;
unsigned char seq_no[3];
unsigned int frame_size;
unsigned int timestamp;
} FRAMEINFO_t;
2022-06-13 通用的(台灯)提示音设置(rev107)
新增通用指令用于设置设备端提示音。设置操作类似 TCI_CMD_SET_ALARMTONE, 在设置前要调用 TCI_CMD_GET_ALARMTONE_CAP 查询设备端支持的音频格式。忽略查询结果中的 Tcis_GetAlarmToneCap_Resp::idAlarmTone
2022-06-07 坐姿检测(rev105)
2022-06-01 巡航
要支持巡航，SupportPTZ 需要包含 Cruise 和 PresetPos 属性。
SupportPTZ = "Relative,PresetPos,Cruise"
APP 调用：
2022-05-19 音频采样格式表示
设备端
- TciSendFrame()/TciSendFrameEx()/TciSendPbFrame()/TciUduPutFrame() 的最一个参数，以前是 关键帧标志
isKeyFrame，对音频应固定为0。现更名为 uFrameFlags, 当数据为音频时，为音频采样格式，取值见 音频采样格式常数
- 增加能力名 AudioFmt, 用于描述设备支持音频格式
APP端
实时和回放的声音包头 FRAMEINFO_t 的第3个字节，云录像帧头McFrameTransformHeader(网络字节顺序)的第4个字节，当帧内容为声音时，取值参见 音频采样格式
typedef struct FRAMEINFO_t
{
unsigned short codec_id;
unsigned char flags;
unsigned char cam_index;
unsigned char onlineNum;
unsigned char seq_no[3];
unsigned int frame_size;
unsigned int timestamp;
} FRAMEINFO_t;
typedef struct {
uint16_t mediaType;
uint16_t keyFrame;
uint32_t length;
uint32_t timestamp;
uint32_t flags;
} __attribute__((__packed__)) McFrameTransformHeader;
2022-05-07(SDK Rev.98) 哭声事件和不支持本地录像的表示
2022-03-19(SDK Rev.94)台灯，门锁图像旋转
台灯
设备能力描述 增加了 多(扩展)属性的表达和解析 说明，APP端要注意看一下。
门锁图像旋转标志
RotateVideo 新增取值 CW90/CW180/CW270, 用于描述设备端的图像旋转角度，需要APP做反向旋转
2022-03-07(SDK rev.93)
2022-02-22(SDK rev.92)
低功耗休眠逻辑微调(设备)
以前sdk通过 TciCB::on_status()回调发出 status_code STATUS_IDLE通知前，会停止p2p/云存等相关服务。现改为如下逻辑：
如果应用层返回0，sdk内部会进入服务清理过程
手动控制电源模式(设备端)
微功耗设备的表述有歧议，在本文中用"手动控制电源模式"代替
手动控制电源模式
手动控制电源类型设备的能力描述
BatteryCam 增加可取值 Solar
AI功能内置
AI服务的请求逻辑现在内置到sdk，应用只需要处理移动侦测事件即可。不要再联接原来的libaiclient.a。
追踪的特定模式支持
能力 Cap-AI ，对硬件追踪类能力，增加 bit2-特写功能标志
2022-01-20 门锁相关
- 门锁设备类型：
"LockBell"
- 开锁指令 TCI_CMD_UNLOCK
- 获取门锁状态 TCI_CMD_GET_LOCK_STATE
2021-12-07 双目摄像机“远景"/"近景"按钮 & 低功耗主动唤醒时间设置
双目摄像机“远景"/"近景"按钮隐藏与显示
Cap-Zoom 增加 "no-shortcut"属性，用来隐藏"远景"/"近景"按钮
低功耗主动唤醒时间设置
新增指令 TCI_CMD_GET_AWAKE_TIME TCI_CMD_SET_AWAKE_TIME ，用来获取和设置低功能设备的主动唤醒时间段
要支持此功能，需要 BatteryCam 能力有 timed-wakeup属性
2021-11-24 SDK Rev86/87
2021-11-02 流事件和设置云台位置命令参数更新
1. 流事件
在实时和回放流中，每帧数据有一个帧头 FRAMEINFO_t , 帧数据类型 FRAMEINFO_t::codec_id 的有效值大于0.
通过在传输流中插入的类型(codec_id)为0的帧，来对流打标签，或通知APP与流相关的事件。codec_id为0时对应的帧头结构为 RTMSGHEAD_t ，其中包含流事件类型 RTMYPE 和事件对应的参数。
在设备端，使用API TciSendLiveMessage() 和 TciSendPbMessage() ，或者针对事件类型专门定义的宏 例如 TciSendLiveMsg_ReachPsp() / TciSendPbSyncFrame() / 等 ..., 分别在实时流(视频)和回放流中插入事件帧。
详见 RTMSGHEAD_t
2. 设置云台位置命令参数更新
设置云台位置命令 TCI_CMD_SET_PTZ_POS 的请求参数 Tcis_SetPtzPosReq ，之前只含有位置信息 PtzPos 。
设置云台位置 TCI_CMD_SET_PTZ_POS = 0x0408
现修改如下
int psp_num
如果是要转到预置位，此为预置位编号，否则为0 [2021.11.2]
当调用预置位时，要传递预置位号。这样云台转到位后，可以流事件时以此编号向APP发送 RTM_REACH_PSP 通知。
2021-20-22 温湿度传感器设置
能力 ExtInstructions 增加 termper和humidity，分别对应温度和湿度传感器
**设备端**：温度/湿度报警需要携带报警时的当前温/湿度值，这个额外参数是一个json格式的字符串，可以使用 MKEVTDATA_Temerature()/MKEVTDATA_Humidity() 来生成。要调用 TciSendEventEx(EVENTPARAM *) 来上报，并将 EVENTPARAM::evt_data 设置为这个字符串。
char sj[128];
memset(¶m, 0, sizeof(param));
param.pass_ownership = 1;
MKEVTDATA_Temerature(
TEMP_C, 50.5, sj,
sizeof(sj));
ep.evt_data = sj;
TciSendEventEx(&ep);
@ ECEVENT_TEMPERATURE_H
[tempH] temperature high(=7). 参数: MKEVTDATA_Temperatur()
2021-10-13 能力和新增指令
禁用或使能报警事件
增加下面两条指令，用于单独禁用或全能报警事件。事件是否有效要同时参考本命令中状态和布/撤防设置。
要支持这两条命令，设备需要在Cap-Defence 能力里报告报警源可以分开布撤防("0xNNN[:0xMMM]" 或 ["0xNNN", "0xMMM"]格式)
云台守望位
给人形人脸等加边框
2021-09-17 SDK rev84
设备AI能力 Cap-AI 描述方式更新
设备自身具有的AI能力，默认要通过购买服务来开启。现增加新的标志，来描述默认开启（不需要购买服务）的情形。Cap-AI
延时摄影
设备如果支持延时摄影，RecordConf 的返回内容中要包含time-lapse
停车监控
行车记录仪要支持停车监控能力，需要在 G-Sensor 里返回 "scene"
实时图像上叠加侦测区域
能力 MD-Capabilities 要有 VisibleZone
2021-08-13 变焦能力描述更新和双目镜头切换标志
能力 Cap-Zoom , 变焦设备(Cap-Zoom="times:xxx")变倍能力描述
双目摄像机镜头切换时在流中插入标志帧 双目摄像机(Cap-Zoom="2lenses")的控制
2021-08-09 布撤防能力描述更新
能力 Cap-Defence
指令 TCI_CMD_GET_DEFENCE_REQ
2021-08-04(sdk>81)多通道设备以及白光红外联动的能力描述
采用JSON格式
多通道设备，每个通道可能有不一样的能力。例如有的通道有云台，其余通道没有。针对这种情况，需要对每个通道单独描述。此时的描述内容是一个数组。
为简化解析，在今后的能力 描述中，引入 json来表示复杂和多通道的能力。
APP要继续兼容之前的格式。
格式说明
- 设备在能力查询中返回一个合法的 json 值表达式（字符串、数组、json对象）
- 设备具有的通道数在
MultiChannels属性中返回。
固件在能力描述中返回一个json数组，数组的第n项对应通道n的属性。对单通道设备，或者所有通道具有相同配置，设备可以返回一个字符串。
举例 : 对一个2通道的设备的 DoubleLight 属性，固件返回 "Yes"意味两个通道都有白光灯。等同于 ["Yes", "Yes"]。如果返回 ["Yes", "No"]则表示仅在第一个通道上有白光灯。
- 复杂描述项可以打散为json格式，例如
Cap-AI能力“bd,fd,mt”可以返回数组["bd", "fd", "mt"]。此部分见具体能力说明。
参考
多通道设备的控制
现有指令集，部分带有channel参数，部分没有（不需要或遗漏）。对遗漏的指令，目前APP和设备可作合理推导。
例如 TCI_CMD_SET_PTZ_POS 指令没有channel参数，对画中画设备不能指定转哪一个镜头对应的云台。但因为实际设备只有一个云台，实际操作就可以忽略channel。
今后有新的设备形态加入需要扩充指令内容时再另行规定。
2021-07-20(Rev81)
直连模式下APP传时区设置
直连模式下在原 Tcis_ExPassWordReq 结构后追加时区字符串。字符串要以NULL结尾。
#define TCI_CMD_PASSWORD_REQ 0X8002
{
unsigned char password[48];
unsigned char reserved[4];
char timezone[0]
结构长度大于60时存在timezone成员。以'\0'结尾
STimeDay livetime
配网时清0. AP直连时设为手机的时间
SD卡回放手动跳转时中途(middle-way)数据处理
SD回放中，用户在APP上重新定位，设备收到PLAY_START指令跳到新的文件位置开始发送。此时网络上还有先前已经发送但APP尚未收到的帧。网络延时越高，中途帧越多，这些帧中还可能有自动跳到下一个文件时发的时间同步帧。如果APP不能区分middle-way帧和新的开始播放的帧，绘制时间轴时可能出现跳动（从新定位点跳回旧播放位置又再次返回新定位点）。为了区分新旧位置的帧。现对时间同步帧作如下规定：
APP
设备端
回放中发生时间跳转 调用 TciSendPbSyncFrame ( handle, utc_ime, is_response_to_PLAY_START) 发送时间同步帧。
#define TciSendPbSyncFrame(handle, utc_ime, is_response_to_PLAY_START) TciSendPbFrame(handle, 0, NULL, 0, utc_time, is_response_to_PLAY_START)
如果是响应用户操作，将 is_response_to_PLAY_START设为1，否则设为0
2021-07-13(Rev80)能力更新：IP配置/红外灯控制
2021-06-24 移动侦测区域设置扩展
移动侦测区域现在增加多边形区域的描述。考虑到设备并不能直接解析多边形，实现上APP会用多很小的矩形来逼近多边形，同时要求设备保存多边形的表示。
Tcis_SetMotionDetect
typedef struct Tcis_SetMotionDetect
{
unsigned int channel;
unsigned short enabled;
unsigned short flags;
unsigned int sensitivity;
unsigned short hasZone;
union {
struct Fake_MdZoneVLA {
unsigned short nZones;
} __PACKED__ mz;
struct Fake_MdPolygonVLA {
unsigned short nPolygons;
} __PACKED__ mp;
struct {
struct Fake_MdZoneVLA mz;
struct Fake_MdPolygonVLA mp;
} __PACKED__ zp;
} u;
Tcis_SetMotionDetectReq Tcis_GetMotionDetectResp
设置移动侦测区域请求和获取移动侦测区域应答的结构(伪).
准备一个 Tcis_SetMotionDetect 的例子:
union {
char buff[1024];
} u;
const MdZone rect = { 0, 0, 5000, 5000 };
const struct {
int nPoints;
POINT points[4];
} polygon = {
4,
{ {0,0}, {5000,0}, {5000,5000}, {0,5000} }
};
memset(&u.resp, 0, sizeof(u.resp));
u.resp.enabled = 1;
u.resp.sensitivity = 1;
u.resp.hasZone = 1;
u.resp.u.zp.mz.nZones = 1;
u.resp.u.zp.mz.zones[0] = rect;
struct Fake_MdPolygonVLA *o = (struct Fake_MdPolygonVLA*)(&u.resp.u.zp.mz.zones[0] + 1);
o->nPolygons = 1;
memcpy(&o->polygons[0], &polygon, sizeof(polygon));
#define MD_AT_RECTSWITHPOLYGON
区域用多个矩形逼近多边形，同时后面有多边形坐标
int TciSendCmdResp(p2phandle_t handle, unsigned int cmd, const void *data, int dataSize)
发送p2p命令应答
#define TCI_CMD_GETMOTIONDETECT_REQ
获取移动侦测配置请求 Tcis_GetMotionDetectReq
2021-06-16 OSD & 预置位 & 变倍能力描述 & AP模式口令 & IP配置 (rev77)
1. OSD
新增指令:
App要先调用 TCI_CMD_GET_OSD_REQ 命令，从设备获取OSD能力和当前osd设置
使用 TCI_CMD_SET_OSD_REQ 可以一次设置/修改/删除一条或多条OSD条目
2. 预置位
2.1 获取预置位
2021-04-23 获取预置位的请求结构 的 flags 取值作如下扩展定义:
应答结构体 Tcis_GetPresetPointsResp 作如下调整：
- 原结构被改名为 PresetPointArray
- Tcis_GetPresetPointsResp 有如下新的定义：
typedef struct {
union {
struct psp_cap {
uint32_t cbSize;
uint16_t max_psp;
uint16_t type;
int flags;
} __PACKED__ psp_cap;
};
2.2 设置预置位
新增指令
3. 变倍能力描述修改
之前的变倍能力描述方式在步数上的描述太过粗略，本次修改提供一种更精细的步数描述方式。
变焦设备(Cap-Zoom=’times:xxx‘)变倍能力描述
4. AP模式口令
- 设备：在 TciCB::on_apmode_login() 回调里 验证默认口令（忽略account参数。如果不修改的话，默认口令是"12345"）
- APP：使用 TCI_CMD_SETPASSWORD_REQ(0x8004) 命令来修改默认口令。这一指令在SDK内部处理
5. IP配置
本接口仅用于华视安邦定制设备，不需要设备能力协商
2021-04-23 双目+变焦 支持
1. 变焦能力 Cap-Zoom 描述更新
Cap-Zoom
变焦设备(Cap-Zoom="times:xxx")操作控制指令说明
2. 双目+变焦
有变焦功能的双目摄像机，其设备能力描述为“双目”和”变焦“摄像机能力的组合（ Cap-Zoom)。操作逻辑和新增指令见 双目+变焦摄像机的控制。
【远景】【近景】按钮对应的位置 PtzPos 不再是仅”双目“设备的 {-1.0, -1.0, 0.0} 和 {-1.0, -1.0, 1.0},而是要通过 TCI_CMD_GET_PSP 获取。
预置位有两种表示方式：
- 传统球机用编号表示的预置位。编号对应的具体位置保存在球机内，对外是黑盒。 本命令中用 struct psp_by_no 表示.
- 用位置表示的预置位。 本命令中用 struct psp_by_pos 表示.
一个预置位可以对应云台的某个朝向、镜头的某个变焦倍数，或二者组合。 如果仅包含变焦信息，flags 应设置 PSP_F_ZOOMONLY。
对仅包含变焦信息的预置位，应该放在数组的最前面，并按变焦倍数从小到大的顺序排列。这样APP容易根据排序决定UI。
例如，对双目+变焦摄像机，返回两个预置位（同时设置PSP_F_ZOOMONLY和PSP_F_SHORTCUT标志），第一个位置将对应[近景]按钮， 第二个对应[远景]按扭。或者，对返回多个预置位的情形，APP在一个滑动轴上，按变倍值单向排列并对每个预置位置描一个驻点。
#define TCI_CMD_GET_PSP 0x0452
#define PSP_BY_NO 1
#define PSP_BY_POS 2
#define PSP_F_ZOOMONLY 0x01
#define PSP_F_SHORTCUT 0x02
uint16_t n_psp;
uint16_t type;
union {
struct psp_by_no {
uint16_t flags;
uint16_t num;
char name[32];
} pspn[0];
struct psp_by_pos {
uint32_t flags;
char name[32];
} pspp[0];
};
2021-04-13 门铃
门铃设备
能力描述
| 能力名 | 能力说明 | 取值 | 取值说明 |
| DeviceType | 设备类型 | "IPC" | 普通网络摄像机 |
| "DriveRec" | 行车记录仪 |
| "DoorBell" | 门铃 |
门铃事件
门铃事件细分为以下类型：
O - Optinal M - Mandatory
前3个事件需要固件调用接口 TciSetEventEx()/TciSetEventHandleOver2()/... 通知sdk。后3个事件由sdk内部产生。这些事件都会通知到平台。
接听/拒接/未接
门铃呼叫最终会被接听、拒接或未接。接听或拒接由APP端使用 TCI_CMD_ANSWERTOCALL 命令显式通知设备端。
#define TCI_CMD_ANSWERTOCALL 0x450
int reserved;
typedef enum {
int state
高16位用作应答源类型: 0-App对门铃事件的响应; 1-自微信小程序; 2-来自App的呼叫连接 低16位为呼叫应答状态.
ECALLSTATE
Doorbell call state
@ CALLSTATE_ANSWERED
已接。TCI_CMD_ANSWERTOCALL
@ CALLSTATE_MISSED
未接. 门铃呼叫由sdk内部定时. wxvoip呼叫代理会通过 TCI_CMD_ANSWERTOCALL 通知设备
@ CALLSTATE_REJECTED
拒接。TCI_CMD_ANSWERTOCALL
2021-03-29(SDK Rev.70) 关闭麦克风
1. 关闭麦克风 – 能力和指令
<2021-03-10(SDK Rev.68) > 中的 第3和第4小节作废
能力名 Microphone 的取值描述更新如下：
关闭麦克风后：
- 实时无音频
- SD卡录像不录声音
- 云存储不录声音
- 无声音报警
第2点需要固件处理， 其余情形SDK内部会处理。
2021-03-10(SDK Rev.68)
1. 三码流支持
此处码流的概念，定义为某种质量的图像输出。选择一种码流，即是选择一种不同的图像质量（分辨率/fps/bitrate等的不同）。
双码流设备支持同时输出两种不同质量的码流。
三码流设备可以输出3种不同质量的码流，但不一定有能力同时输出。当不能同时输出时，靠切换某一路码流的质量实现。
1.1 码流描述
本说明代替 2020-12-02 新增图像分辨率 里
| 能力名 | 能力说明 | 取值
|
| Resolutions | 设备支持的图像质量组合。默认 0HD+1SD | 见表后 |
1.2 码流描述详解
质量组合 ::=质量描述项1[+质量描述项2[+质量描述项3...]]
质量描述项按质量从高到低的顺序，用‘’+'`连接.
质量描述项 ::= {码流编号}{质量描述符}
码流编号 ::= 0|1|2|...，低的编号对应更高的分辨率
质量描述符::= SD|HD|FHD|UHD|...
SD -- 标清(流畅)
HD -- 高清
FHD -- 全高清
UHD -- 超高清
xxx -- XXX
质量描述符不一定限于分辨率。例如可能是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。
1.3 码流选择命令接口
1.3.1 当前双码流设备的码流选择逻辑
当前的码流选择逻辑在APP与SDK内部实现，不需要固件的应用层参与
- APP发送
TCI_CMD_SETSTREAMCTRL_REQ 命令，在命令请求里携带质量参数quality。取值TCIC_QUALITY_MAX(1)或TCIC_QUALITY_MIN(5), 分别对应设备的高分辨率(0)和低分辨率码流(1)
- 设备SDK内部处理此请求（不通知固件应用层），对高分请求发送码流0的数据，低分请求发送码流1数据
1.3.2 修改后的逻辑
修改后的逻辑，固件逻辑见 【1.3.2.4 设备行为】。APP与SDK端【1.3.2.1~1.3.2.3小节】使用之前同样的命令和quality 质量常数 参数，但quality的取值规则有调整。
1.3.2.1 质量常数
为了兼容旧实现，保留原有的图像质量常数定义。
typedef enum
{
TCIC_QUALITY_HIGH = 0x02,
TCIC_QUALITY_MIDDLE = 0x03,
TCIC_QUALITY_LOW = 0x04,
ENUM_QUALITY_LEVEL
doxygen 里匿名变量的占位符。定义为空，仅为了生成文档用
暂时最多支持5种质量。质量常数与码流的对应关系，要看设备的Resolutions能力。
1.3.2.2 质量常数 和 质量描述项 的对应关系
使用索引来引用质量描述项是最简单的。但为了兼容，需要使用一种更复杂的映射方式。如下。
下表中的数字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种质量。
1.3.2.3 APP行为
APP收到设备的Resolutions能力后，忽略质量描述项前面的数字（注意：可能存在旧的固件没有数字）。
将描述符转成文字在UI上显示
根据描述项数目，确定每个描述项对应的质量常数(如前表)
用户在UI选择 高清/标清/... 时，APP在 TCI_CMD_SETSTREAMCTRL_REQ 命令的quality中传入相应的质量常数
1.3.2.4 设备行为
SDK收到质量选择命令，如果请求的质量对应的码流下有多个质量设置，则将质量常数转换为质量描述项， 调用应用的 TciCB::switch_quality(int channel, int stream, const char *qstr) 回调。
参数 stream/qstr对应Resolutions中某一项的值。例如 "0FHD"对应stream=0, qstr="FHD".
设备检查对应码流的质量设置是否与请求一致，如果不一致则修改之。
1.3.3 举例
设备能力: 0FHD+1HD+1SD
质量常数和设备端对应的码流/质量：
| 质量描述项 | 质量常数 | APP显示 | 当前设置 |
| 0FHD | TCIC_QUALITY_MAX | 全高清 | * |
| 1HD | TCIC_QUALITY_MIDDLE | 高清 | * |
| 1SD | TCIC_QUALITY_MIN | 标清（或流畅） | |
假设设备当前设置为：
用户打开APP时，默认请求的高清图像。
- 现在用户在APP上选择【流畅】, APP在
TCI_CMD_SETSTREAMCTRL_REQ 命令的 quality参数中传入 TCIC_QUALITY_MIN。
TCIC_QUALITY_MIN对应的质量描述项为1SD(码流为1，支持HD和SD两种质量)。SDK调用 TciCB::switch_quality(0, 1, "SD")，固件知道当前质量为高清，因此将码流1的质量设为标清。- SDK将码流1的数据传给APP。
- 如果用户选择【全高清】。因为对应的码流0只支持一种质量，SDK不会将此命令传给固件，而是直接传送码流0的数据给APP。
2. 行车记录仪休眠模式开关指令
#define TCI_CMD_SET_ENABLE_DORMANCY 0x044A
#define TCI_CMD_GET_ENABLE_DORMANCY 0x044C
int reserved;
休眠状态 TCI_CMD_SET_ENABLE_DORMANCY = 0x0432 TCI_CMD_GET_ENABLE_DORMANCY = 0x0434
3. 杂项能力描述Misc
新增一个杂项("Misc")能力描述，用于一些很琐屑的功能开关。
| 名称 | 解释 | 取值 | 说明 |
| Misc | 杂项。整数值的16进制的字符串表示，以"0x"开始，例如"0x1234"。,该整数值的每一位表示一个功能开关 | bit0 | 禁止SD卡录像时录制声音 |
4. SD卡录像声音开关
SD卡录像设置里增加一个是否录声音的选项。
{
unsigned char recordStream
SD卡录像清晰度:0-高清，1-标清. 要求 RecordConf = "res"
unsigned char flags
not used (2021-9-18)
unsigned char reserved[2]
0
unsigned int recordType
Refer to ENUM_RECORD_TYPE
unsigned int channel
Camera Index:0~N-1
Tcis_SetRecord Tcis_SetRecordReq
2021-01-22(SDK Rev.64)
1.设备端新增报警上报接口 TciSetEventEx
新增 TciSetEventEx() 接口，允许上报事件附带参数。例如：行车记录仪的碰撞事件带严重程度参数。当事件严重时，会给关连手机发送短信。
#define EVTDATA_SERIOUS_COLLISION (void*)1
int pass_ownership;
int TciSetEventEx(EVENTPARAM *evtp)
上报事件。本版本允许附带事件特定参数.
2020-12-14
1. SD卡状态值定义更新
sd容量应答结构中的 total(总容量) 增加只读状态定义
unsigned char reserved[8];
int free
Free space size of sdcard (MBytes)
2. 通用AI功能开关指令的能力描述
| Key | Value |
| "Extlnstructions" | 支持的指令列表。多条指令间用分号隔开:
-
close-device –开关设备
-
alarm-bell –警铃配置(本能力仅当"AlertSound"为"YES"才有效)
-
pbrate –支持回放倍速设置
-
alarmtone –支持报警音设置.需要支持
-
TCI_CMD_GET_ALARMTONE_CAP
-
TCI_CMD_SET_ALARMTONE
-
TCI_CMD_PLAY_ALARMTONE
-
status-led –支持开启和关闭状态灯.需要支持:
-
TCI_CMD_SET_LED_STATUS
-
TCI_CMD_GET_LED_STATUS
-
close-plan –设备关闭计划。需要同时支持“close-device”能力。需要支持以下命令:
-
TCI_CMD_SET_CLOSE_PLAN
-
TCI_CMD_GET_CLOSE_PLAN
-
ai-switch – AI功能打开关闭。需要支持指令：
-
TCI_CMD_SET_AI
-
TCI_CMD_GET_AI
|
3. 通用AI功能开关指令
可代替 TCI_CMD_SET_ENABLE_BT/ TCI_CMD_GET_ENABLE_BT
#define TCI_CMD_SET_AI 0x032C
#define TCI_CMD_GET_AI 0x032E
#define AITM_BODY_DET 0x00000001
#define AITM_BODY_TRACE 0x00000002
#define AITM_FACE_DET 0x00000004
#define AITM_FACE_RECO 0x00000008
unsigned char reserved[8];
unsigned int ait_mask
AI类型掩码 的组合。 获取时为当前支持的AI功能; 设置时为要修改状态的AI功能
unsigned int ai_flags
对应位为1表示使能
2020-12-02(Rev.61)
1. 低功耗产品休眠条件更新（APP和固件）
本更新代替 《2020-09-23 低功耗产品在APP进入设置页面时的约定》
1.1 APP
原来的设计：
APP在进入设置页面时发送 TCI_CMD_GET_MAX_AWAKE_TIME 。在设置页面没有任何操作一段时间(例如30")后，设备进入休眠。
现在更新为：
APP在结束实时流和SD卡回放，进入其它操作界面(云回放或设置页面)时， 发送 TCI_CMD_ENTER_SETUP，退出界面时发送 TCI_CMD_LEAVE_SETUP.
- 设备收到 TCI_CMD_ENTER_SETUP 后，不会进入休眠状态，直到收到TCI_CMD_LEAVE_SETUP或连接断开。
- 如果APP在打开时对低功耗设备执行了预连接，但不做任何操作，设备会很快返回休眠，预连是没有效果的。
1.1.1 新增的指令
#define TCI_CMD_ENTER_SETUP 0x0338
#define TCI_CMD_LEAVE_SETUP 0x0336
1.2 固件
固件在调用 TciStart() 后，在 on_status() 回调里收到 STATUS_IDLE 进入休眠状态。在调用TciStart()前，自行决定何时休眠。不用再判断是否在回放和设置无操作倒计时等。
更多说明参见sdk文档 《低功耗设备开发》
2. 新增图像分辨率能力描述
[Depracated] by Resolutions 2020-01-26
| 能力名 | 能力说明 | 取值 | 取值说明 | 相关指令 |
| Resolutions | 设备的主/辅码流图像分辨率 | HD+SD | 高清+标清 | |
| FHD+SD | 全高清+标清 |
| UHD+SD | 超高清+标清 |
2020-11-04(Rev.59)
APP设置连接模式口令
用户可以修改直连模式下的默认口令
#define TCI_CMD_SETPASSWORD_REQ 0x8004
typedef struct
{
char oldpasswd[32];
char newpasswd[32];
该指令在sdk内部处理，固件不需要响应。
2020-10-24(Rev.57)
设备sdk变动
TciCB::on_status() 新增 STATUS_SDER 通知，并且现在要有返回值。ECEVENT_POWEROFF/ECEVENT_POWERON事件被 ECEVENT_PARK/ECEVENT_SETOFF事件代替，设备在响应 STATUS_SDER 通知时上传。
2020-10-17(Rev.56)
设备SDK接口变动
- 新增接口:
TciSetEvent2()TciSetEventHandleOver2()EyeCloudReportError()
- 修改接口:
TciUduBegin()去掉事件时间和图片参数- TciSetEvent() 和 变为宏
2020-10-12(Rev.54)
1. 新增报警灯和PIR能力
| 能力名 | 能力说明 | 取值 | 取值说明 | 相关指令
|
| AlarmLight | 是否支持报警灯 | No | 不支持 | TCI_CMD_SET_ALARMLIGHT
TCI_CMD_GET_ALARMLIGHT |
| Yes | 支持 |
| PIR | 是否支持PIR(灵敏度设置) | No | 不支持 | TCI_CMD_SET_PIR
TCI_CMD_GET_PIR |
| Yes | 支持 |
2. 新增报警灯和PIR控制指令
#define TCI_CMD_SET_ALARMLIGHT 0x442
#define TCI_CMD_GET_ALARMLIGHT 0x444
#define TCI_CMD_SET_PIR 0x446
#define TCI_CMD_GET_PIR 0x448
int channel
id of light: 0
int sens
0:关闭; 1:低; 2:中; 3:高
int state
0:关; 1:开; 2:自动; 3:按定时设置
Tcis_PirSens Tcis_SetPirSensReq
Tcis_GetAlarmLightStateResp Tcis_SetAlarmLightStateReq
Tcis_PirSens Tcis_GetPirSensResp
Tcis_AlarmLightState Tcis_GetAlarmLightStateResp
2020-09-23
1. 低功耗产品在APP进入设置页面时的约定
进入设置面时，APP向设备查询唤醒后工作时长（或称唤醒后录像时长）(0x042C) . 【查看定义】
#define TCI_CMD_GET_MAX_AWAKE_TIME
设备以此命令作为进入设置状态的标志，内部设置新的休眠倒计时初值（例如30“内无操作则设备进入休眠）
2020-09-15(sdk rev51)
1. (行车记录仪)基于SD卡录像的云录像补录API
云存储补录
2020-09-07(sdk rev50)
1. 画中画SD卡录像和云录像回放功能
参见 录像与回放
2020-08-26(sdk rev48)
1. g-sensor和画面旋转能力
| 能力名 | 能力说明 | 取值 | 取值说明 | 相关指令
|
| G- Sensor | 是否支持g-sensor | No | 不支持(非行车记录仪默认不支持) | |
| Yes | 支持(行车记录仪默认支持) |
| RotateVideo | 是否支持画面翻转 | No | 不支持 | |
| Yes | 支持(默认) |
2. 画中画主画面查询和更新
app在请求画中画主画面时，调用GET命令向设备查询当前主画面设置。
app在切换主画面时，向设备SET命令
#define TCI_CMD_SET_PRIMARY_VIEW 0x43E
#define TCI_CMD_GET_PRIMARY_VIEW 0x440
int channel
主画面通道: 0|1. GET 请求时忽略
Tcis_PrimaryView Tcis_GetPrimaryViewResp
Tcis_PrimaryView Tcis_GetPrimaryViewReq
Tcis_PrimaryView Tcis_SetPrimaryViewReq
2020-08-17(sdk rev47)
1. api接口
1.1 电池状态上报 TciReportBatteryStatus()
int TciReportBatteryStatus(int qoe, int qoe_low, int charging)
上报电池状态
1.2 网络传输统计回调 trans_stat
TciCB增加成员 trans_stat() 回调
};
...
};
void(* trans_stat)(const struct TransStatUser *_stat)
网络传输统计回调
int msStatInterval
统计周期(单位: ms)
int nBytesInBuff
位于发送缓冲区的字节数
short is_igop
1:统计间隔为一个I帧间隔; 0:周期约为~1s
int nBytesThrow
丢掉的字节数。丢包会持续到到一个I帧，这期间即使网络恢复也会丢，所以其值只能作为参考, 不能用于计算网速
1.3 休眠接口TciPrepareAuthString()
进入休眠需要先与休眠服务器建立连接认证，并在主控下电后一直保持连接并发送心跳。
TciPrepareHiberation() 适用于主控建立连接，主控下电后网络模块继承该连接属性的情形。
TciPrepareAuthString()适用于网络模块建立连接的情形。
int TciGetWakeupServers(Ipv4Addr servers[3])
获取唤醒服务器ip地址
const uint8_t * TciPrepareAuthString(const char *randKey, int *len_of_authstring)
生成唤醒服务器登录命令.
unsigned short port
port, network byte-order
unsigned int ip
ip, network byte-order
2. 新增指令
设备喇叭音量设置(能力Speaker:TuneVol)
#define TCI_CMD_SET_VOLUME 0x436
#define TCI_CMD_GET_VOLUME 0x438
}Tcis_SetVolumeReq，Tcis_GetVolumeResp;
int flags
0: 音量调节范围不可知，1：音量调节范围可知
喇叭音量 TCI_CMD_SET_VOLUME = 0x436 TCI_CMD_GET_VOLUME = 0x438
设备拾音灵敏度设置(能力Microphone:TuneVol)
#define TCI_CMD_SET_MIC_LEVEL 0x43A
#define TCI_CMD_GET_MIC_LEVEL 0x43C
unsigned char reserved[4];
int sensitivity
灵敏度：[0-100]
MIC 灵敏度 TCI_CMD_SET_MIC_LEVEL = 0x43A TCI_CMD_GET_MIC_LEVEL = 0x43C
Tcis_SetMicLevel Tcis_SetMicLevelReq
Tcis_SetMicLevel Tcis_GetMicLevelResp
2020-07-25(SDK rev.46)
设置G-Sensor(DeviceType:DriveRec)
#define TCI_CMD_SET_GSENSOR 0x432
#define TCI_CMD_GET_GSENSOR 0x434
typedef struct Tcis_SetGsensor {
int sensitivity;
unsigned char reserved[4];
} Tcis_SetGsensorReq, Tcis_GetGsensorResp;
2020-07-06（SDK rev.40）
获取GPS信息(能力Gps:Yes)
#define TCI_CMD_GETGPSINFO_REQ 0x0334
};
#define TCI_CMD_GETGPSINFO_RESP 0x0335
int avIndex
flags==1时为流式发送的p2p通道
uint32_t signal_strength
0-未知; 1-弱; 2-一般; 3-强
int flags
0: Request/Answer方式取一次, 忽略avIndex; 1: 流式，在avIndex通道上发送.
GPS 能力
| 能力名 | 能力说明 | 取值 | 取值说明 | 相关指令
|
| Gps | 是否支持Gps | No | 不支持 | |
| Yes | 支持 |
2020-04-09(SDK rev.32)
1. 新增接口
针对低功耗摄像机增加如下接口
int TciAllocCloudBuffer(unsigned int uCloudBuffSize)
预分配云存储帧缓存空间.
2020-03-18(SDK rev.30)
1. 新增状态on_status回调参数
低功耗摄像在进入休眠要检查当前是否有人操作。判断【没人操作】要满足以下条件：
- 没人访问实时视频
- 没人在回放sd卡录像
- N秒内没有收新的命令
其中第一条，访问实时流的操作在SDK内部处理了，应用层并不知道。现对 on_status 回调增加一个新的事件取值： STATUS_STREAMING
void on_status(int event, const void *pData, int len);
2020-03-16 （SDK rev.29）
1. 新增指令
1.1 状态灯开关
enum {
}
typedef struct Tcis_SetCameraStatus {
int status;
char resvered[4];
} Tcis_SetLedStatus, Tcis_GetLedStatus;
#define TCI_CMD_SET_LED_STATUS
设置状态灯的模式 req: Tcis_SetLedStatusReq; resp: generic. 能力: ExtInstructions包含status-led
#define TCI_CMD_GET_LED_STATUS
获取状态灯的模式 req: none; resp: Tcis_GetLedStatusResp
1.2 SD卡录像相关设置
设置SD卡录像模式(TCI_CMD_SETRECORD_REQ)的请求结构做如下更改：
typedef struct {
unsigned int channel;
unsigned int recordType;
unsigned char recordStream;
unsigned char reserved[3];
TCI_CMD_GETRECORD_REQ = 0x0312,
1.3 电池电量和供电模式
仅电池摄像机使用
enum {
};
typedef struct{
int batteryMode;
int batteryPower;
#define TCI_CMD_GET_BATTERY_STATUS
获取电池电量 see Tcis_GetBatteryStatusResp
1.4 获取WIFI/4G信号强度
enum {
};
typedef struct{
int activeNetIntf;
int signalLevel;
#define TCI_CMD_GET_WIFI_SIGNALLEVEL
获取WiFi/4G信号强度 see Tcis_GetWifiLevelResp
1.5 被动唤醒后无操作最大工作时长
在超出此时间后，设备重新进入休眠状态
enum {
};
typedef struct {
int max_awake_time;
int reserved;
#define TCI_CMD_SET_MAX_AWAKE_TIME
2020-02-17（SDK rev.27)
1. 能力描述（自定义报警音）
| Key | Value |
| "ExtInstructions" | 支持的指令列表。多条指令间用分号隔开:
-
close-device – 开关设备
-
alarm-bell – 警铃配置(本能力仅当"AlertSound"为"YES"才有效)
-
pbrate – 支持回放倍速设置
-
alarmtone – 支持报警音设置.需要支持
-
TCI_CMD_GET_ALARMTONE_CAP
-
TCI_CMD_SET_ALARMTONE
-
TCI_CMD_PLAY_ALARMTONE
|
2. 新增指令（报警音设置）
enum {
};
typedef struct {
unsigned short nSamplePerSec;
unsigned char nBitsPerSample;
unsigned char nChannels;
unsigned int nExpectedFileFormats;
unsigned char ExpectedFileFormats[8];
unsigned int nSupportedAudioCodecs;
unsigned char SupportedAudioCodecs[8];
unsigned int idAlarmTone;
typedef struct {
unsigned int id;
unsigned short type;
unsigned char af_fmt;
unsigned char a_codec;
int data_len;
char data[0];
TCI_CMD_SET_ALARMTONE = 0x041E, //设置报警音频 TCI_CMD_PLAY_AUDIO = 0x0356 //播放语音不保存
#define TCI_CMD_SET_ALARMTONE
设置报警音频 see Tcis_SetAlarmTone_Req
#define TCI_CMD_GET_ALARMTONE_CAP
获取报警音频文件格式信息 see Tcis_GetAlarmToneCap_Resp
#define TCI_CMD_PLAY_ALARMTONE
播放报警音
2020-02-10
1. 回放控制参数语义扩展
回放控制命令TCI_CMD_RECORD_PLAYCONTROL(0x031A)请求体结构如下：
typedef struct
{
unsigned int channel;
unsigned int command;
unsigned int Param;
unsigned char reserved[4];
command取值 为ENUM_PLAYCONTROL:
typedef enum
{
TCIC_RECORD_PLAY_STEPFORWARD = 0x02,
TCIC_RECORD_PLAY_STEPBACKWARD = 0x03,
TCIC_RECORD_PLAY_FORWARD = 0x04,
TCIC_RECORD_PLAY_BACKWARD = 0x05,
TCIC_RECORD_PLAY_SEEKTIME = 0x06,
TCIC_RECORD_PLAY_END = 0x07,
ENUM_PLAYCONTROL
SD卡回放控制指令
@ TCIC_RECORD_PLAY_PAUSE
暂停
@ TCIC_RECORD_PLAY_STOP
结束回放或停止某路视频.
现启用TCIC_RECORD_PLAY_FORWARD(0x04)值作为倍速插放控制命令。相应的Param为速度倍数:
0,1: 1倍速；2: 2倍速; ...
2. 回放倍速能力
ExtInstructions 增加 pbrate
| Key | Value |
| "ExtInstructions" | 支持的指令列表。多条指令间用分号隔开:
-
close-device – 开关设备
-
alarm-bell – 警铃配置(本能力仅当"AlertSound"为"YES"才有效)
-
pbrate – 支持回放倍速设置 ...以后会添加更多...
|
2019-12-18
1. 指令能力(警铃)
增加alarm_bell
| Key | Value |
| "ExtInstructions" | 支持的指令列表。多条指令间用分号隔开:
-
close-device – 开关设备
-
alarm-bell – 警铃配置(本能力仅当"AlertSound"为"YES"才有效) ...以后会添加更多...
|
2. 新增指令(警铃配置)
"ExtInstructions" 包含 "alarm-bell"时，设备支持以下指令：
enum {
TCI_CMD_SET_ALARMBELL = 0x0418,
TCI_CMD_GET_ALARMBELL = 0x041A,
};
typedef struct Tcis_SetAlarmBell {
uint8_t version;
uint8_t reserved[3];
uint32_t event_mask;
uint32_t event_mask2;
Tcis_SetAlarmBellReq Tcis_GetAlarmBellResp
设置设备警铃命令和获取设备警铃设置命令的参数结构体.
2019-12-04(SDK rev.16)
1.新增能力描述
1.1 通用简单能力开关
| Key | Value |
| "ExtInstructions" | 支持的指令列表。多条指令间用分号隔开:
-
close-device – 开关设备 ...以后会添加更多...
|
2.新增和更新接口
2.1 设备开关
enum {
TCL_CMD_SET_CAMERA_STATUS = 0x0414,
TCL_CMD_GET_CAMERA_STATUS = 0x0416
}
typedef struct Tcis_SetCameraStatus {
int status;
char resvered[4];
} Tcis_SetCameraStatus, Tcis_GetCameraStatus;
APP向设备查询Features时，设备使用”DeviceStatus“名称在”setting“里向APP返回当前状态。
2019-11-09(SDK rev.12)
2. 新增和更新接口
2.1 人形追踪开关
enum {
}
char resvered[4];
Tcis_SetEnableBT Tcis_SetEnableBtReq
Tcis_SetEnableBT Tcis_GetEnableBtResp
#define TCI_CMD_SET_ENABLE_BT
设置人形跟踪开关 see Tcis_SetEnableBtReq
#define TCI_CMD_GET_ENABLE_BT
获取人形跟踪开关状态 see Tcis_GetEnableBtResp
2019-09-19
1. 几条指令的返回值更正
下列命令设备端当前实现在成功时返回1，失败返回0.
- APP：对这几条指令，如果设备能力支持，可以忽略返回值，有返回即认为操作成功
- IPC：修改返回值，成功时返回0，失败返回1
SET_BUZZER_REQ
SET_DOUBLELIGHT_REQ
SET_DAYNIGHT_REQ
SET_MOTION_TRACKER_REQ
SET_MICROPHONE_REQ
DEV_REBOOT_REQ
SET_CLOUD_VIDEO_QUALITY_REQ
2. Feature和Setting名字更新
Feature和setting里的"Buzzer"更名为"AlertSound"
APP：为兼容旧设备，取settings时, 以"Buzzer"和"AlertSound"两个名字查询设备状态，使用有返回的那个作为当前设置
2019-09-17
1. SD卡回放时设备与APP绝对时间同步
设备在以下情形，向app报告下一帧数据的真实时间[1]
- 收到
PLAY_START命令，执行了文件定位，开始发送数据时
- 当前文件播放结束，自动跑步到下一个文件开始播放时
- 其它原因导致时间戳不连续，app无法推算帧的正确发生时间时
报告方式为，设备向app发送一个帧, codec_id和frame_size都为0, timestamp 为下一个音频或视频帧的真实utc时间
typedef struct _FRAMEINFO
{
unsigned short codec_id;
unsigned char flags;
unsigned char cam_index;
unsigned char onlineNum;
unsigned char reserve1[3];
unsigned int frame_size;
unsigned int timestamp;
} FRAMEINFO_t;
[1] 设备端使用 TciSendPbFrame(handle, (TCMIDIA)0, NULL, 0, timestamp, 0) 调用来发送时间同步帧
2. SD卡回放事件类型
在LISTEVENT_REQ命令返回的列表项，SAvEvent的event域取值定义如下(在ec_const.h里定义):
typedef enum {
ECEVENT_NONE = 0,
ECEVENT_MOTION_DETECTED,
ECEVENT_HUMAN_BODY,
ECEVENT_SOUND,
ECEVENT_PIR,
ECEVENT_SMOKE,
ECEVENT_TEMPERATURE_L,
ECEVENT_TEMPERATURE_H,
ECEVENT_HUMIDITY_L,
ECEVENT_HUMIDITY_H,
ECEVENT_GENERIC_SENSOR, //通用传感器类消息
ECEVENT_MAX
} ECEVENT;
3. 错误应答
目前的协议，错误返回方式不一致或缺失。有的错误域在命令相关的应答数据结构里， 有的应答结构没有定义错误域。如果设备不支持某条命令，没有相应的报错机制。 下面定义一种与当前协议兼容的错误应答机制：
|--------------------------------|
| 1 | 错误应答命令码
|--------------------------------|
| 8 | 长度
|--------------------------------|
| cmd | 命令码
|--------------------------------|
| error | 错误码
|--------------------------------|
其中，
| Field | Note |
| 1 | 专用于错误应答的命令码 |
| 8 | 数据长度 |
| cmd | 从app收到命令请求码 |
| error | 通用错误码(见下表) |
通用错误码
| Value | Note |
| 0 | 成功 |
| 1 | 命令处理中，请等待 |
| 2 | 包头错（不支持的协议头） – 这个错误码保留以后使用 |
| 3 | 命令不支持 |
| 4 | 参数错误 |
| 5 | 资源不足 |
| 6 | 内部错误 |
4. 命令码取值规范
当前的命令码，如果命令有响应的，都同时定义了REQ和RESP，并且满足
今后新的命令都遵循这两条规则，响应码不再单独定义。
由于历史原因，存在少数几条值为奇数的请求码，但这些命令都不需要响应，所以对APP不影响。设备端会对这几条指令作特殊处理。
| 命令范围 | 说明 |
| 1 | 错误应答 |
| 0x180~0x400 | IPC命令 |
| 0x8000~0x8100 | IPC命令 |
| 0x1000~0x1100 | IPC |
| 其余 | 保留不要使用 |
1.12.0