©️版权声明
本协议是 瞳赋® Tofu Intelligence® 独家财产,受版权法和条约的保护,未经授权不得转载或复制他用。
协议提供对接测试客户端与源码,方便客户快速应用。
TJSON测试软件说明:
部分功能说明:
🟢图像抓拍: 点选“显示抓拍图像”,并启动“抓拍上传开”后抓拍图像存储到软件所在目录中,如下图所示。
🟢保存数据: 开始接收/发送数据后点选“保存数据”,数据将保存到软件所在目标 log文件夹下,可查看数据发送/接收的16进制原始数据。
🟢数据透传: 透传数据包括PELCO_D,VISCA,VISCA_IR三种模式,分别对应云台、可见光相机、热红外相机通道,详细说明请查看本页4.2.2章节。
支持数据循环发送。
本协议规定了AI端与操控端、AI端与吊舱之间的通信方式和协议。
⚠️注意,本协议中所指的吊舱专指Tofu型号吊舱,其他吊舱与云台不适用PV协议通信方式。
本协议适用于任何操作系统,可用于客户端软件的二次开发。
(非吊舱用户请忽略此部分🔻)
AI端在运行过程中直接控制云台和镜头。AI端作为服务器端(Server端),吊舱与镜头控制端作为客户端(Client端),AI端口号为8090。采用PelcoD协议与VISCA协议,以下简称PV协议。控制与查询周期默认为200ms一次。若您使用云台相机,此部分可忽略,只需要使用JSON协议即可,网络通信全部基于TCP/IP方式。
(非吊舱用户请忽略此部分🔺)
操控端中支持AI端的算法模式切换与参数配置;识别、跟踪过程中信息接收;云台与镜头的手动控制,AI端作为服务器端(Server端),操控端作为客户端(Client端),AI端口号为8089。采用JSON协议。所有JSON数据上下帧间隔不得小于100毫秒。
AI端采用 RTSP 协议传输视频,视频默认采用H.264编码(可通过T-JSON协议控制修改为H.265),端口号为554。当AI相机节点开机时即启动RTSP Server等待视频点播。操控终端需要查看视频时,通过 RTSP URL 的形式点播视频。T-JSON协议不包含视频流部分,视频流解析请自行使用RTSP视频解析方式,暂不提供此部分相关代码与技术支持。
网络链路中,所有连接到AI端的设备都必须遵循心跳帧规则。
(非吊舱用户请忽略此节)
AI端与吊舱采用PV协议通信,其中云台运动与查询相关指令采用PelcoD协议,镜头变倍、聚焦、查询相关指令采用VISCA协议。
通信不包含其他指令之外的数据,直接通过网络端口发送接收即可。此处列举几个常用协议指令,完整协议请参考 PelcoD云台控制与VISCA镜头控制协议文档。若您使用云台相机,此部分可忽略,只需要使用JSON协议即可。
T-JSON通信协议适用于客户端与AI端之间的通信,用于控制和配置AI端,获取AI端的状态消息,以及手动控制云台和镜头,获取目标截图。
T-JSON协议分为JSON指令协议与图像抓拍协议,均通过同一个8089端口进行通信。
以下数据帧说明中,Tofu产品代表服务器端,客户端软件/平台软件代表客户端。
🟢 JSON指令 协议格式:
标识码1 | 标识码2 | 帧类型 | 帧长度 | 帧内容 |
---|---|---|---|---|
1Byte | 1Byte | 1Byte | 4Byte | N |
0xEC | 0x91 | 见帧类型表 | 帧内容长度N | JSON |
帧类型表:
帧类型 | 类型名 | 格式 |
---|---|---|
0x01(设备到客户端) | 状态帧 | JSON |
0x03(客户端到设备) | 控制指令 | JSON |
0x04(设备到客户端) | 图像抓拍,协议见图像抓拍协议格式 | JPEG Socket |
0x05(客户端到设备) | 图像信息查询 | JSON |
0x06(客户端到设备) | 设置目标检测区域 | JSON |
0x07(客户端到设备) | 设置显示模式 | JSON |
0x08(客户端到设备) | 设置算法模型 | JSON |
0x09(客户端到设备) | 设置目标截图状态 | JSON |
0x11(双向) | 心跳 | Socket |
0x12(双向) | ACK | Socket |
🟢 图像抓拍 协议格式:
开启图像抓拍(目标截图)功能后,识别后的目标区域截图会以Socket方式与JSON同一个端口实时发送。 目标图像抓拍为每个目标单独组包,发送周期为300ms。例如,图像中有3个目标,协议将发送三个独立的Socket包。
标识码1 | 标识码2 | 帧类型 | 帧长度 | 位置信息 | 帧内容 | 帧校验 | 帧尾标识1 | 帧尾标识2 |
---|---|---|---|---|---|---|---|---|
1Byte | 1Byte | 1Byte | 4Byte | 8Byte | N Byte | 1Byte | 1Byte | 1Byte |
0xEB | 0x92 | 0x04 | JPEG Size | Location | JPEG | Sum | 0xFB | 0x92 |
位置信息: 截取图像在原始图像中的坐标位置,其中按顺序包括左X-coordinate(2Byte)、上Y-coordinate(2Byte),截取图像的宽Width(2Byte)、高Height(2Byte)。Coordinate坐标原点在画面的左上角,为(X=1,Y=1)。
帧长度: JPEG图像数据的Byte数量,对应上表的 N。
帧校验: 0xEB+0x92+0x04+帧长度 的7Byte 合校验。
AI运行过程信息推送包括算法信息与设备状态信息。
算法信息数据结构说明:
Key | Disp. | Value | Type |
---|---|---|---|
ControlType | 控制类型 | AIInfo | String |
WorkMode | 工作模式 | 0x00:关闭AI 0x01:识别 0x02:自动跟踪 0x03:点选跟踪 0x04:波门/框选跟踪🪄 |
Int |
ObjectCount | 目标总数 | N | Int |
Object | 目标信息 | 见下表 | JSON |
🪄
波门跟踪是固定尺寸大小正方形区域的框选跟踪。
Object格式说明:
Key | Disp. | Value | Type |
---|---|---|---|
Class | 目标类型🪄 | 0xA1:人/飞机,0xA2:车/直升机, 0xA3:船/鸟,0xA4:无人机, 0xB1:跟踪正常, 0xB2:跟踪丢失 |
Int |
Point | 位置信息✏️ | Left:左X, Top:上Y, Right:右X, Bottom:下Y |
Int |
Distance | 距离信息 | N | Double |
🪄
目标类型最多为4个类,编号对应名称根据选择的模型变化。
✏️
Point目标框的位置,左上角为零点0,0。
取值范围:
可见光:Left、Right 0-1919;Top、Bottom 0-1079。
热红外:Left、Right 0-719;Top、Bottom 0-575。
当跟踪状态时只推送跟踪目标的坐标,当跟踪丢失时坐标均为0,0,0,0。
⚠️非所有设备具备Distacne信息,若有,单位为 m(米)。
JSON示例:
{
"ControlType": "AIInfo", // 控制类型,表示这是一个 AI 算法信息推送
"WorkMode": 1, // 工作模式,0x01 表示识别模式
"ObjectCount": 2, // 目标总数,表示当前检测到的目标数量
"Object": { // 目标信息集合,每个目标用一个唯一的 ID 标识
"01": { // 目标 ID 为 "01"
"Class": 161, // 目标类型,0xA1 表示人
"Points": { // 目标在图像中的位置信息(坐标框)
"Left": 100, // 目标框左上角的 X 坐标
"Top": 100, // 目标框左上角的 Y 坐标
"Right": 200, // 目标框右下角的 X 坐标
"Bottom": 200 // 目标框右下角的 Y 坐标
},
"Distance": 1066.0 // 目标距离(单位:米)
},
"02": { // 目标 ID 为 "02"
"Class": 162, // 目标类型,0xA2 表示车
"Points": { // 目标在图像中的位置信息(坐标框)
"Left": 300, // 目标框左上角的 X 坐标
"Top": 100, // 目标框左上角的 Y 坐标
"Right": 400, // 目标框右下角的 X 坐标
"Bottom": 200 // 目标框右下角的 Y 坐标
},
"Distance": 1182.0 // 目标距离(单位:米)
}
}
}
在跟踪过程中JSON示例:
{
"ControlType": "AIInfo", // 控制类型,表示这是一个 AI 算法信息推送
"WorkMode": 2, // 工作模式,0x02 表示自动跟踪模式
"ObjectCount": 1, // 目标总数,表示当前检测到的目标数量为 1
"Object": { // 目标信息集合,包含每个检测到的目标的详细信息
"01": { // 目标 ID 为 "01",表示第一个目标
"Class": 177, // 目标类型,0xB1 表示跟踪正常(具体分类需根据实际定义)
"Points": { // 目标在图像中的位置信息(坐标框)
"Left": 220, // 目标框左上角的 X 坐标
"Top": 450, // 目标框左上角的 Y 坐标
"Right": 250, // 目标框右下角的 X 坐标
"Bottom": 490 // 目标框右下角的 Y 坐标
},
"Distance": 1055.0 // 目标距离(单位:米),表示目标距离相机的距离
}
}
}
设备状态信息数据结构说明:
Key | Name | Value | Type | Disp. |
---|---|---|---|---|
ControlType | 控制类型 | ZoomInfo | String | |
ZoomInfo | 镜头倍率 | 精确到小数点后一位/两位 | Double | |
ZoomInfoIR | 热红外镜头倍率 | 精确到小数点后一位/两位 | Double | 非双光输入设备,无此项 |
PTZInfoH | 云台横向角度 | 精确到小数点后一位/两位 | Double | 需串口服务器 |
PTZInfoV | 云台垂直角度 | 精确到小数点后一位/两位 | Double | 需串口服务器 |
LaserRange | 测距 | 精确到小数点后一位 | Double | 部分设备支持 |
CamShowMode | 相机显示模式 | 0:彩色;1:黑白 | Int | 部分设备支持 |
Latitude | 纬度 | 精确到小数点后六位 | String | 部分设备支持 |
Longitude | 经度 | 精确到小数点后六位 | String | 部分设备支持 |
Height | 测距 | 精确到小数点后一位 | Double | 部分设备支持 |
JSON示例:
{
"ControlType": "ZoomInfo", // 控制类型,表示这是一个设备状态信息推送
"ZoomInfo": 3.6, // 镜头倍率
"ZoomInfoIR": 1.5, // 热红外镜头倍率,非双光输入无此项
"PTZInfoH": -50.3, // 云台横向角度
"PTZInfoV": 16.4, // 云台垂直角度
"LaserRange": 810.0, // 测距信息,表示激光测距的结果,单位为米
"CamShowMode": 0, // 相机显示模式,0 表示彩色模式
"Latitude": "39.836502N", // 纬度信息,N 表示北纬
"Longitude": "116.287451E",// 经度信息,E 表示东经
"Height": 888.0 // 高度信息
}
包含工作模式配置与数据透传。
工作模式配置指令格式:
Key | Disp. | Value | Type |
---|---|---|---|
ControlType | 控制类型 | SetWorkMode | String |
SetWorkMode | 工作模式 | 0x00:关闭AI 0x01:识别 0x02:自动跟踪 0x03:点选跟踪 0x04:波门/框选跟踪 0x05:自动变焦开🪄 0x06:自动变焦关 |
Int |
P2Track | 配置 | 下表说明 | Int |
🪄
自动变焦功能是指跟踪过程中随目标大小自动变焦的功能。
P2Track配置在点选跟踪、波门/框选跟踪时需要。具体说明如下表。
Key | Disp. | Value | Type |
---|---|---|---|
Center | 🪄中心点 | X:横坐标,Y:纵坐标 | Int |
Distance | 搜索范围/区域大小 | N | Int |
DistanceX | 搜索范围/区域大小 | N | Int |
DistanceY | 搜索范围/区域大小 | N | Int |
🪄
画面左上为1,1源点;Center对应目标中心点坐标。
点选跟踪模式下默认Distacne=30;
波门/框选跟踪模式下可使用Distance(跟踪框为正方形)或DistanceX/Y(跟踪框为任意大小长方形)。
JSON示例:
{
"ControlType": "SetWorkMode", // 控制类型
"SetWorkMode": 1 // 设置的工作模式,0x01 表示识别模式
}
P2Track信息仅在点选跟踪模式与波门跟踪模式下输入,点选跟踪需要提供点击的坐标,Distance默认用30,如果坐标在识别到的目标区域内即会锁定跟踪。
波门跟踪提供的是中心坐标与跟踪框宽度(高度)信息。
点选跟踪JSON示例:
{
"ControlType": "SetWorkMode", // 控制类型
"SetWorkMode": 3, // 设置的工作模式,0x03 表示点选跟踪模式
"P2Track": { // 点选跟踪配置
"Center": { // 目标中心点的坐标
"X": 310, // 目标中心点的 X 坐标
"Y": 660 // 目标中心点的 Y 坐标
},
"Distance": 64 // 搜索范围,表示以中心点为中心的搜索半径
}
}
框选跟踪JSON示例:
{
"ControlType": "SetWorkMode", // 控制类型
"SetWorkMode": 4, // 设置的工作模式,0x04 表示波门/框选跟踪模式
"P2Track": { // 波门/框选跟踪配置
"Center": { // 目标中心点的坐标
"X": 240, // 目标中心点的 X 坐标
"Y": 330 // 目标中心点的 Y 坐标
},
"DistanceX": 36, // 跟踪区域的宽度
"DistanceY": 28 // 跟踪区域的高度
}
}
数据透传指令格式:
Key | Disp. | Value | Type |
---|---|---|---|
ControlType | 控制类型 | SerialControl | String |
SerialType | 串口选择🪄 | PELCO_D VISCA VISCAIR✏️ |
String |
SerialData | 数据 | Lens:数据长度 Data:数据内容 |
Int String |
🪄
可见光设备中SerialType选择PELCO_D则数据会发送至云台,选择VISCA则数据发送至相机。
✏️
在使用Tofu提供的LIR热红外机芯时, 使用 SerialType=VISCA,
实际指令采用PELCO_D协议发送,此时注意发送的PELCO_D协议的 ID号需要改为 0x02。双光单变焦输入的设备中 SerialType=VISCA 则给当前主画面的相机发送透传指令。
双光双变焦输入(Tofu6)的设备中,热红外机芯透传请使用 SerialType=VISCAIR。
Pelco-D与VISCA指令协议详见,[PELCO-D云台控制与VISCA镜头控制协议]。
Pelco-D透传接口也可以用来发送[非标ExPelco-D高精度云台控制协议] (需云台支持)。
JSON示例:
{
"ControlType": "SerialControl", // 控制类型,表示这是一条用于串口通信控制的指令
"SerialType": "PELCO_D", // 串口协议类型,指定使用 PELCO-D 协议
"SerialData": { // 串口数据内容
"Lens": 7, // 数据长度,表示后续数据的字节数
"Data": "FF01000800FF08" // 实际发送的串口数据,以十六进制字符串表示
}
}
/*
指令 FF01000800FF08 的具体含义是:
• 设备地址:0x01
• 操作:向上移动(Up),垂直速度为最大速度,水平速度为停止。
• 校验和:0x08
*/
JSON控制热红外镜头变倍加示例:
{
"ControlType": "SerialControl", // 控制类型,表示这是一条用于串口通信控制的指令
"SerialType": "VISCA", // 串口协议类型,指定使用 VISCA 协议
"SerialData": {
"Lens": 7, // 数据长度,表示后续数据的字节数
"Data": "FF020020000022" // 实际发送的串口数据,以十六进制字符串表示
/*
• FF:同步字节(固定值)。
• 02:设备地址(这里为 0x02)。
• 00:命令类别(控制命令)。
• 20:具体命令(变倍加操作)。
• 22:校验和
*/
}
}
查询帧发送格式如下,长度为7Byte。
标识码 | 帧类型 | 帧内容 |
---|---|---|
0xEC 0x91 | 0x05 | 0x00 0x00 0x00 0x00 |
查询信息反馈:
Key | Name | Value | Type | Disp. |
---|---|---|---|---|
ControlType | 控制类型 | ImageSetting | String | |
ImageSize | 图像分辨率 | 0:1080P 1:720P 2:D1 3:1440P |
int | 请勿使用比实际分辨率更高的分辨率配置 |
ImageBit | 图像码率 | 512~4096 | Int | 单位为Kb/S |
ImageCode | 编码格式 | 0:H264 1:H265 |
int | |
WorkMode | 工作模式 | 0x00:关闭AI 0x01:识别 0x02:自动跟踪 0x03:点选跟踪 0x04:波门/框选跟踪 |
Int | 部分设备支持输出 |
JSON示例:
{
"ControlType": "ImageSetting", // 控制类型,表示这是一条用于设置图像参数的指令
"ImageSize": 0, // 图像分辨率设置,0 表示 1080P (1920x1080)
"ImageBit": 4096, // 图像码率设置,4096 表示码率为 4096 Kb/S
"ImageCode": 0, // 图像编码格式设置,0 表示使用 H.264 编码
"WorkMode": 1 // 当前工作模式,部分设备支持查询输出
}
设置目标检测区域
Key | Disp. | Value | Type |
---|---|---|---|
ControlType | 控制类型 | SetValue | String |
WarnArea | 区域设置🪄 | AreaItem:区域标记 AreaPoint:X、Y坐标 |
Int |
🪄
区域设置时,画面左上角坐标为(1,1),AreaPoint最多为6个。
JSON示例:
1.设置检测区域:
{
"ControlType": "SetAreaDot", // 控制类型,表示这是一条用于设置目标检测区域的指令
"WarnArea": { // 目标检测区域的配置
"AreaItem": 1, // 区域标记,表示这是第一个检测区域
"AreaPoint": [ // 区域的四个顶点坐标,定义一个矩形检测区域
{
"X": 120, // 第一个顶点的 X 坐标
"Y": 100 // 第一个顶点的 Y 坐标
},
{
"X": 310, // 第二个顶点的 X 坐标
"Y": 100 // 第二个顶点的 Y 坐标
},
{
"X": 310, // 第三个顶点的 X 坐标
"Y": 360 // 第三个顶点的 Y 坐标
},
{
"X": 120, // 第四个顶点的 X 坐标
"Y": 360 // 第四个顶点的 Y 坐标
}
]
}
}
2.取消检测区域:
{
"ControlType": "SetAreaDot", // 控制类型,表示这是一条用于设置或取消目标检测区域的指令
"WarnArea": { // 目标检测区域的配置
"AreaItem": 0 // 区域标记,0 表示取消所有检测区域
}
}
Key | Name | Value | Type | Disp. |
---|---|---|---|---|
ControlType | 控制类型 | PipShowSetting | String | |
PipShow | 显示类型 | 0:大图可见光,小图红外 1:红外 2:可见光 3:融合 16:大图红外,小图可见光 |
Int | 非双光设备不支持此协议 |
JSON示例:
{
"ControlType": "PipShowSetting", // 控制类型,表示这是一条用于设置显示模式的指令
"PipShow": 0 // 显示模式设置,0 表示“大图显示可见光,小图显示红外”
}
Key | Name | Value | Type | Disp. |
---|---|---|---|---|
ControlType | 控制类型 | ModelSetting | String | |
Model | 算法模型🪄 | 0:可见光混合模型 1:红外混合模型 2:人车识别 3:船识别 4:无人机识别 5:飞机,直升机识别 6:鸟识别 |
Int |
🪄
1)2,3,4模型为标准提供的模型,0,1,5,6模型为非标准提供的模型,详情请咨询。
2)0,1模型为混合模型,即识别类别为4类或5类,波段与模型不匹配时自动切换成匹配的混合模型。
JSON示例:
{
"ControlType": "ModelSetting", // 控制类型,表示这是一条用于设置算法模型的指令
"Model": 3 // 算法模型设置,3 表示“船识别”模型
}
Key | Name | Value | Type | Disp |
---|---|---|---|---|
ControlType | 控制类型 | ImageUpload | String | |
Upload | 目标截图状态 | 0:目标抓拍关闭 1:目标抓拍开启 |
Int |
JSON示例:
{
"ControlType": "ImageUpload", // 控制类型,表示这是一条用于设置目标截图状态的指令
"Upload": 1 // 目标截图状态设置,1 表示开启目标截图功能
}
标识码 | 标识码 | 帧类型 | 帧长度 | 状态码 |
---|---|---|---|---|
1Byte | 1Byte | 1Byte | 4Byte | 2Byte |
0xEC | 0x91 | 0x12 | 0x00 00 00 02 | 0x00 XX |
状态码类型见下表。
状态码 | 描述 |
---|---|
0x00 00 | 执行正常 |
0x00 01 | 包不完整 |
0x00 02 | 协议内容错误 |
标识码 | 标识码 | 帧类型 | 帧长度 |
---|---|---|---|
1Byte | 1Byte | 1Byte | 4Byte |
0xEC | 0x91 | 0x11 | 0x00 00 00 00 |
客户端在15秒之内需要给服务器端发送心跳帧,当服务器收到客户端心跳帧后,将在1s内回复心跳,若客户端超时未收到回复,客户端需重新发送该帧。
当服务器连续15s内未收到客户端的心跳帧时,服务器将判定客户端已自动离线,将停止数据发送和接收。
当客户端连续15s内未收到服务器回复时,应判定本次连接已被中断,需重新连接。